417 lines
15 KiB
Markdown
417 lines
15 KiB
Markdown
<!-- file: docs/audits/V0_4_6_ALIGNMENT_AUDIT.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# Audit ciblé d’alignement `0.4.6`
|
||
|
||
## 1. Objet
|
||
|
||
Cet audit détermine si `khadhroony-bot3` peut être officiellement aligné sur le périmètre fonctionnel de `khadhroony-bot2 0.4.6`.
|
||
|
||
Il ne refait pas les audits protocolaires complets déjà réalisés pour Solana Core, SPL Memo, SPL Token, SPL Associated Token Account, Token-2022 et le registre SPL ElGamal. Il synthétise leur migration, les tests disponibles, les validations Devnet connues et les écarts résiduels démontrés.
|
||
|
||
## 2. Base examinée
|
||
|
||
Base documentaire et source :
|
||
|
||
```text
|
||
khadhroony-bot3 v0.1.0-pre.073
|
||
```
|
||
|
||
Le workspace contient onze crates :
|
||
|
||
1. `kb-core` ;
|
||
2. `kb-config` ;
|
||
3. `kb-lib` ;
|
||
4. `kb-logging` ;
|
||
5. `kb-program-ids` ;
|
||
6. `kb-pipeline` ;
|
||
7. `kb-pipeline-demo-scenarios` ;
|
||
8. `kb-onchain-transport` ;
|
||
9. `kb-store` ;
|
||
10. `kb-wallet` ;
|
||
11. `kb-app-demo-desktop`.
|
||
|
||
Toutes utilisent actuellement la version workspace `0.1.0`. Aucun changement vers `0.4.6` ne doit être effectué avant clôture des blocants de la section 9.
|
||
|
||
## 3. Architecture migrée
|
||
|
||
### 3.1 Consolidations principales
|
||
|
||
| Bot2 | Bot3 | Statut |
|
||
|------------------------------------|------------------------------|-------------------------------------|
|
||
| modèles et contrats répartis | `kb-core` et `kb-lib` | migré et consolidé |
|
||
| décodeurs séparés | modules de `kb-lib` | migré |
|
||
| exécuteurs séparés | modules de `kb-lib` | migré |
|
||
| matérialisateurs séparés | modules de `kb-lib` | migré |
|
||
| stockage core et PostgreSQL séparé | `kb-store` | migré et consolidé |
|
||
| crates RPC et transports | `kb-onchain-transport` | migré et renommé |
|
||
| pipeline historique | `kb-pipeline` | migré |
|
||
| scénarios dépendants du desktop | `kb-pipeline-demo-scenarios` | extraits partiellement |
|
||
| application de démonstration | `kb-app-demo-desktop` | migrée et renommée |
|
||
| wallet temporaire | `kb-wallet` | migré, capacités avancées reportées |
|
||
|
||
La consolidation modifie la structure des crates, mais ne constitue pas en elle-même un écart fonctionnel.
|
||
|
||
### 3.2 Binaires et crates mixtes
|
||
|
||
- `kb-app-demo-desktop` reste une crate mixte bibliothèque et binaire ;
|
||
- `kb-pipeline-demo-scenarios` reste une crate mixte ;
|
||
- sa bibliothèque s’appelle `kb_pipeline_demo_scenarios` ;
|
||
- son binaire explicite s’appelle `kb-pipeline-demo-scenarios-cli` ;
|
||
- `autobins = false` empêche la création d’une cible implicite concurrente.
|
||
|
||
## 4. Documentation et règles
|
||
|
||
### 4.1 Contrat par crate
|
||
|
||
Les onze crates disposent désormais de :
|
||
|
||
```text
|
||
README.md
|
||
TODO.md
|
||
USAGE.md
|
||
CHANGELOG.md
|
||
```
|
||
|
||
Les TODO sont classés par échéance :
|
||
|
||
- blocants avant `0.4.6` ;
|
||
- travaux entre `0.4.6` et `0.4.7` ;
|
||
- versions ultérieures ;
|
||
- reports conditionnels.
|
||
|
||
### 4.2 Documentation transversale
|
||
|
||
Les documents actifs couvrent :
|
||
|
||
- architecture générale et carte des crates ;
|
||
- pipeline et stockage ;
|
||
- configuration et logging ;
|
||
- RPC, backfill et WebSocket ;
|
||
- extraction Core, replay et matérialisation ;
|
||
- PostgreSQL ;
|
||
- validation Devnet ;
|
||
- règles documentaires.
|
||
|
||
Les anciens plans et prompts de migration ont été archivés sous `olddocs/archivekbot3/`.
|
||
|
||
## 5. Capacités fonctionnelles alignées sur bot2 `0.4.6`
|
||
|
||
### 5.1 Fondation et stockage
|
||
|
||
- contrats d’erreur et identités de modules ;
|
||
- configuration typée JSON et schéma embarqué ;
|
||
- logging structuré ;
|
||
- stockage canonique, observations, tables Core et decode/materialization ;
|
||
- migrations PostgreSQL et diagnostics ;
|
||
- pagination et requêtes de replay bornées.
|
||
|
||
### 5.2 Transports et acquisition
|
||
|
||
- JSON-RPC HTTP standard ;
|
||
- WebSocket standard ;
|
||
- pools et rôles d’endpoints ;
|
||
- acquisition de signatures et transactions ;
|
||
- adaptation canonique ;
|
||
- simulation, soumission et confirmation ;
|
||
- backfill HTTP, reprise et annulation coopérative.
|
||
|
||
### 5.3 Pipeline
|
||
|
||
- extraction Core ;
|
||
- decode replay contextualisé ;
|
||
- matérialisation optionnelle et idempotente ;
|
||
- inspections stateful ;
|
||
- corrélations et préflights Token-2022 ;
|
||
- orchestration de preuves et postconditions.
|
||
|
||
### 5.4 Solana Core et SPL
|
||
|
||
Sont migrés jusqu’au périmètre historique de bot2 `0.4.6` :
|
||
|
||
- Solana Core et programmes natifs ;
|
||
- SPL Memo v1, v3 et v4 ;
|
||
- SPL Token classique ;
|
||
- SPL Associated Token Account ;
|
||
- Token-2022 et extensions couvertes ;
|
||
- registre SPL ElGamal dans les couches effectivement implémentées.
|
||
|
||
Memo v1 et v3 restent non exécutables. Memo v4 reste la génération exécutable.
|
||
|
||
## 6. Validations connues
|
||
|
||
### 6.1 Base `pre.062`
|
||
|
||
La base de migration a été déclarée validée avec :
|
||
|
||
```text
|
||
kb-pipeline-demo-scenarios :
|
||
- 39 tests de bibliothèque
|
||
- 1 test de binaire
|
||
|
||
kb-app-demo-desktop :
|
||
- 117 tests
|
||
```
|
||
|
||
Audits connus :
|
||
|
||
```text
|
||
General Rust rule audit: clean
|
||
Rust export completeness audit: 0 candidate(s)
|
||
Khadhroony workspace rule audit: clean
|
||
```
|
||
|
||
### 6.2 Devnet
|
||
|
||
Ont été validés sur Solana Devnet :
|
||
|
||
- System Transfer ;
|
||
- Memo v4 ;
|
||
- ATA classique ;
|
||
- ATA Token-2022 ;
|
||
- SPL Token `TransferChecked` ;
|
||
- Token-2022 :
|
||
- `MintToChecked` ;
|
||
- `TransferChecked` ;
|
||
- `ApproveChecked` ;
|
||
- `Revoke` ;
|
||
- `BurnChecked` ;
|
||
- `FreezeAccount` ;
|
||
- `ThawAccount` ;
|
||
- `CloseAccount`.
|
||
|
||
Les parcours couverts incluent simulation, confirmation opérateur, envoi, confirmation, insertion canonique, extraction Core, replay, matérialisation et idempotence.
|
||
|
||
### 6.3 Validation exécutée pendant cet audit
|
||
|
||
Avec le `Cargo.lock` de référence fourni séparément :
|
||
|
||
```text
|
||
General Rust rule audit: clean
|
||
Rust export completeness audit: 0 candidate(s)
|
||
Khadhroony workspace rule audit: clean
|
||
```
|
||
|
||
Les commandes Cargo n’ont pas pu être réexécutées dans l’environnement de production du delta, car le binaire `cargo` n’y est pas disponible. Les résultats historiques ne sont donc pas présentés comme nouvellement exécutés.
|
||
|
||
## 7. Éléments non bloquants pour `0.4.6`
|
||
|
||
### 7.1 Metaplex Token Metadata
|
||
|
||
Le décodeur a été commencé dans bot2 `0.4.7`, puis migré dans bot3. La matérialisation historique doit être vérifiée et les éléments suivants restent à terminer après l’alignement `0.4.6` :
|
||
|
||
- exécuteur ;
|
||
- complément éventuel de matérialisation ;
|
||
- orchestration pipeline ;
|
||
- scénarios de démonstration ;
|
||
- panneaux desktop ;
|
||
- validations finales.
|
||
|
||
Ces travaux appartiennent à la future version fonctionnelle `0.4.7`.
|
||
|
||
### 7.2 Registre SPL ElGamal
|
||
|
||
Le registre est implémenté dans certaines couches, mais n’est pas déclaré validé sur Devnet ou Mainnet.
|
||
|
||
La validation dépend notamment :
|
||
|
||
- de la confirmation du déploiement réseau ;
|
||
- d’un générateur de preuve `PubkeyValidity` ;
|
||
- d’un compte `Proof Context State` valide ;
|
||
- d’un scénario opérateur fonctionnel.
|
||
|
||
Cette absence de validation réseau ne bloque pas l’alignement sur bot2 `0.4.6`, car bot2 ne disposait pas non plus de cette validation réelle. Elle doit rester explicitement documentée.
|
||
|
||
### 7.3 Capacités planifiées après `0.4.7`
|
||
|
||
Ne bloquent pas `0.4.6` :
|
||
|
||
- split de `kb-config` et configuration logging dédiée en `0.5.x` ;
|
||
- complétion de `kb-wallet` en `0.5.x` ;
|
||
- décodeur générique Anchor et surfaces complémentaires en `0.6.x` ;
|
||
- protocoles Meteora, Raydium, Pump, Orca, Jupiter et autres ;
|
||
- transports streaming avancés en `0.13.x`.
|
||
|
||
## 8. Écarts architecturaux acceptés
|
||
|
||
Les différences suivantes sont des choix bot3 validés, pas des régressions :
|
||
|
||
- fusion des décodeurs, exécuteurs et matérialisateurs dans `kb-lib` ;
|
||
- fusion des contrats et implémentations de stockage dans `kb-store` ;
|
||
- renommage de `kb-rpc` en `kb-onchain-transport` ;
|
||
- séparation des scénarios réutilisables dans `kb-pipeline-demo-scenarios` ;
|
||
- maintien de `kb-app-demo-desktop` comme package mixte ;
|
||
- maintien d’un wallet minimal avant sa complétion en `0.5.x`.
|
||
|
||
## 9. Blocants ou vérifications à clôturer avant passage officiel à `0.4.6`
|
||
|
||
La checklist historique contient encore de nombreuses tâches non cochées. Certaines sont déjà réalisées mais non réconciliées, certaines appartiennent à `0.4.7+`, et d’autres restent réellement à vérifier.
|
||
|
||
La liste suivante remplace la précédente liste trop restrictive.
|
||
|
||
### 9.1 Réconciliation de la checklist historique
|
||
|
||
Avant toute conclusion finale :
|
||
|
||
- confronter chaque tâche non cochée à l’état actuel du code, des tests et de la documentation ;
|
||
- cocher les tâches déjà prouvées ;
|
||
- retirer ou archiver les formulations obsolètes ;
|
||
- transférer vers les TODO ou le ROADMAP les travaux `0.4.7+` ;
|
||
- ne conserver comme blocants `0.4.6` que les écarts encore démontrables.
|
||
|
||
La checklist demande encore un alignement final sur `0.4.7`, ce qui ne correspond plus à la trajectoire décidée : clôture de migration en `0.4.6`, puis reprise séparée de `0.4.7`.
|
||
|
||
### 9.2 Preuves Devnet du périmètre `0.4.6`
|
||
|
||
La validation ATA, SPL Token classique et Token-2022 est documentée comme réalisée dans le prompt de reprise, alors que la checklist historique conserve ces tâches ouvertes.
|
||
|
||
Il faut :
|
||
|
||
- rattacher les preuves disponibles aux tâches correspondantes ;
|
||
- fermer ATA classique, ATA Token-2022, SPL Token classique et les huit opérations Token-2022 réellement validées ;
|
||
- conserver ElGamal comme exception conditionnelle et non comme validation manquante bloquante ;
|
||
- vérifier si le replay System Transfer et Memo v4 après changement de nomenclature a déjà été exécuté ou doit être rejoué.
|
||
|
||
### 9.3 Nomenclature et contrats persistés
|
||
|
||
Vérifier avant alignement :
|
||
|
||
- l’audit empêchant la réintroduction des anciennes identités persistées ;
|
||
- l’état réel de la base Devnet après changement de nomenclature ;
|
||
- l’audit Python final de nomenclature ;
|
||
- la cohérence entre matrices actives et registres compilés pour les surfaces `0.4.6`.
|
||
|
||
La réévaluation complète de chaque matrice lors de futures surfaces n’est pas un blocant global `0.4.6`.
|
||
|
||
### 9.4 Règles et documentation active
|
||
|
||
Clôturer :
|
||
|
||
- la lecture croisée finale des règles ;
|
||
- la suppression des demandes historiques sans valeur normative ;
|
||
- la vérification qu’aucun document actif ne raconte encore la migration comme dépendance conceptuelle nécessaire ;
|
||
- la confirmation que les README et USAGE des onze crates correspondent à l’état actuel ;
|
||
- la documentation de reconstruction PostgreSQL encore explicitement demandée par la checklist.
|
||
|
||
L’inventaire complet Program IDs/IDL peut être traité ultérieurement, après rescan des archives, sauf lorsqu’une source est nécessaire pour valider une surface `0.4.6`.
|
||
|
||
### 9.5 Desktop, Tauri et interface
|
||
|
||
Vérifier explicitement :
|
||
|
||
- synchronisation Tauri/TS-RS ;
|
||
- cycles d’ouverture, fermeture et réouverture ;
|
||
- séparateurs de menu ;
|
||
- absence de contrôles morts ou dupliqués ;
|
||
- correspondance entre options HTML, commandes Tauri et scénarios backend ;
|
||
- contrat de fenêtre pour Decode replay, Exécution Solana Core et Exécution SPL ;
|
||
- absence de logique métier substantielle restante dans `tauri.rs` ;
|
||
- tests unitaires placés dans les modules fonctionnels ;
|
||
- timeout HTTP et arrêt global de l’application.
|
||
|
||
### 9.6 Cycle de vie WebSocket
|
||
|
||
Valider :
|
||
|
||
- fermer `demo_ws` ne ferme pas une session active ;
|
||
- rouvrir `demo_ws` récupère l’état courant ;
|
||
- l’arrêt intervient uniquement sur déconnexion explicite, fermeture de l’application ou timeout prévu ;
|
||
- les diagnostics et contrôles reflètent l’état réel de la session.
|
||
|
||
### 9.7 Configuration, secrets et logging
|
||
|
||
Confirmer :
|
||
|
||
- seul `kb-config` charge `.env` ;
|
||
- ordre de priorité des variables et fichiers ;
|
||
- comportement `${VAR}` et `${VAR:-fallback}` ;
|
||
- absence de fuite de secrets ;
|
||
- résolution réelle de `HELIUS_API_KEY` ;
|
||
- absence de dépendance directe `dotenvy` dans les scénarios ;
|
||
- routes console `local_devnet` et `mainnet` ;
|
||
- targets `kb-lib.decoder.*`, `kb-lib.executor.*`, `kb-lib.materializer.*` ;
|
||
- absence de recréation de répertoires de logs d’anciennes crates.
|
||
|
||
### 9.8 PostgreSQL et fiabilité du pipeline
|
||
|
||
Décider et valider avant alignement :
|
||
|
||
- documentation des tables conservées, dérivées et de leur ordre de reconstruction ;
|
||
- contrôle des index et contraintes après reconstruction ;
|
||
- dimensionnement du pool ou justification du report ;
|
||
- retry borné pour les timeouts transitoires, ou preuve que ce correctif n’est pas requis pour l’équivalence `0.4.6` ;
|
||
- profils `local_devnet` et `mainnet` pendant la campagne finale.
|
||
|
||
### 9.9 Validation des surfaces desktop
|
||
|
||
Vérifier :
|
||
|
||
- Exécution Solana Core ;
|
||
- Exécution SPL ;
|
||
- options réellement exposées ;
|
||
- suppression des options mortes ;
|
||
- statut de `execute_devnet_spl_token_lifecycle` ;
|
||
- simulation, envoi, progression, résumé et diagnostics ;
|
||
- replay et matérialisation post-exécution pour les familles supportées.
|
||
|
||
### 9.10 Documentation opérateur minimale
|
||
|
||
Avant `0.4.6`, confirmer que la documentation active permet au minimum :
|
||
|
||
- création ou sélection du wallet de démonstration ;
|
||
- récupération de la clé publique ;
|
||
- saisie des champs desktop ;
|
||
- exécution des scénarios Solana Core et SPL ;
|
||
- compréhension des préconditions, signers, frais et résultats ;
|
||
- vérification du replay et des projections.
|
||
|
||
Les scénarios Metaplex appartiennent à `0.4.7`.
|
||
|
||
### 9.11 Validation finale du workspace
|
||
|
||
Exécuter dans le workspace réel :
|
||
|
||
```bash
|
||
cargo fmt --all
|
||
cargo test --workspace
|
||
cargo check --workspace
|
||
cargo clippy --all-targets
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
```
|
||
|
||
Exécuter également :
|
||
|
||
- vérification des bindings TS-RS régénérés ;
|
||
- validation runtime de toutes les fenêtres ;
|
||
- validation HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL ;
|
||
- validation Solana Core et SPL sur Devnet ;
|
||
- vérification de l’archive finale et absence de secrets ou artefacts exclus.
|
||
|
||
## 10. Éléments explicitement reportés après `0.4.6`
|
||
|
||
Ne doivent pas bloquer la version :
|
||
|
||
- Metaplex Token Metadata complet, exécuteur et validations, pour `0.4.7` ;
|
||
- Anchor générique, pour `0.6.x` ;
|
||
- registre Program IDs/IDL complet après rescan historique ;
|
||
- workers W1/W2 et applications associées tant que leur version ROADMAP n’est pas décidée ;
|
||
- wallet complet et split de configuration, pour `0.5.x` ;
|
||
- transports streaming avancés, pour `0.13.x` ;
|
||
- ElGamal réseau tant que son déploiement et ses preuves ne sont pas disponibles.
|
||
|
||
## 11. Conclusion
|
||
|
||
```text
|
||
NOT_READY_FOR_0_4_6
|
||
```
|
||
|
||
Le périmètre historique `0.4.6` paraît largement présent, mais la liste de cinq blocants précédemment publiée était incomplète. La checklist doit d’abord être réconciliée et les familles de vérification des sections 9.2 à 9.11 doivent être clôturées ou explicitement reportées avec justification.
|
||
|
||
La conclusion pourra devenir :
|
||
|
||
```text
|
||
READY_WITH_DOCUMENTED_EXCEPTIONS
|
||
```
|
||
|
||
lorsque les vérifications restantes seront prouvées et que les seules exceptions seront explicitement documentées, notamment ElGamal non validé sur réseau et Metaplex réservé à `0.4.7`.
|