khadhroony-bot3/docs/audits/V0_4_6_ALIGNMENT_AUDIT.md

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 :

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 :

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 :

kb-pipeline-demo-scenarios :
- 39 tests de bibliothèque
- 1 test de binaire

kb-app-demo-desktop :
- 117 tests

Audits connus :

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 :

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 démontrés avant passage officiel à 0.4.6

9.1 Desktop et contrat Tauri

Il reste à obtenir une validation explicite et complète de :

1. la synchronisation des adaptateurs Tauri et des payloads TS-RS avec les APIs réutilisables ;
2. la couverture des cycles d’ouverture, fermeture et réouverture des fenêtres concernées.

9.2 Cycle de vie WebSocket

Le code place la session WebSocket dans AppState, distinctement de la fenêtre, et expose des commandes explicites de statut, connexion, désabonnement et déconnexion.

Il reste néanmoins à valider explicitement :

1. que fermer demo_ws ne ferme pas une session active ;
2. que rouvrir demo_ws récupère l’état courant ;
3. que l’arrêt intervient uniquement sur déconnexion explicite, fermeture de l’application ou timeout prévu.

Ces validations doivent être couvertes par des tests ou une campagne reproductible avant retrait des tâches du TODO.

9.3 Validation complète dans le workspace réel

Avant le changement de version, exécuter :

cargo fmt --all
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
cargo test -p kb-pipeline-demo-scenarios
cargo test -p kb-app-demo-desktop

Exécuter également les tests ciblés de toute crate modifiée par les correctifs issus de cet audit.

La validation frontend doit utiliser :

cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

10. Liste fermée des écarts à traiter

Avant 0.4.6, traiter uniquement :

• validation Tauri/TS-RS ;
• validation des cycles de fenêtres ;
• validation du cycle de vie persistant de demo_ws ;
• éventuelles corrections directement révélées par ces validations ;
• exécution finale des commandes de validation du workspace.

Aucun nouvel audit complet des protocoles déjà validés n’est requis.

11. Conclusion

NOT_READY_FOR_0_4_6

Le périmètre fonctionnel historique de bot2 0.4.6 est largement migré et les différences architecturales sont documentées. Le passage officiel reste bloqué par des validations desktop/WebSocket explicites et par la validation finale du workspace réel.

Après clôture de ces points, la conclusion pourra devenir :

READY_WITH_DOCUMENTED_EXCEPTIONS

Les exceptions documentées attendues sont le registre ElGamal non validé sur réseau et les travaux Metaplex Token Metadata réservés à 0.4.7.