khadhroony-bot3/README.md

Khadhroony Bot3

khadhroony-bot3 est le workspace Rust consolidé succédant à khadhroony-bot2 pour l’acquisition, le stockage, le décodage, la matérialisation, la validation et l’exécution contrôlée d’opérations Solana.

Version fonctionnelle

Le workspace est aligné sur le périmètre fonctionnel de khadhroony-bot2 0.4.6 dans la nouvelle architecture bot3. Les différences de structure sont intentionnelles : les modèles, décodeurs, exécuteurs et matérialisateurs sont consolidés dans kb-lib, le stockage dans kb-store et les transports RPC dans kb-onchain-transport.

Exceptions documentées :

• le registre ElGamal est implémenté avec validations synthétiques et garde-fous fail-closed, mais n’est pas déclaré validé réellement sur Devnet ou Mainnet ;
• Metaplex Token Metadata possède déjà ses décodeurs d’instructions et de comptes ainsi qu’une matérialisation substantielle, mais son exécuteur, son orchestration complète et ses démonstrations appartiennent à 0.4.7 ;
• les améliorations structurelles de kb-config, kb-logging et kb-store sont reportées à 0.5.x.

Architecture

Le workspace contient 11 crates :

• kb-core : erreurs et primitives transversales ;
• kb-config : chargement et validation de la configuration ;
• kb-lib : modèles, décodeurs, exécuteurs et matérialisateurs ;
• kb-logging : logging et tracing ;
• kb-program-ids : registre des programmes et comptes Solana connus ;
• kb-pipeline : backfill, extraction Core, replay et orchestration ;
• kb-pipeline-demo-scenarios : bibliothèque de scénarios et CLI ;
• kb-onchain-transport : transports RPC HTTP et WebSocket ;
• kb-store : contrats de stockage et adaptateur PostgreSQL ;
• kb-wallet : frontière de wallet et signataires, encore incomplète ;
• kb-app-demo-desktop : bibliothèque et application Tauri de démonstration.

La vue détaillée est disponible dans :

• docs/architecture/ARCHITECTURE.md ;
• docs/architecture/CRATE_MAP.md ;
• docs/architecture/PIPELINE_ARCHITECTURE.md ;
• docs/architecture/STORAGE_ARCHITECTURE.md ;
• docs/architecture/SURFACE_CRATE_MATRIX.md.

Documentation

L’index actif se trouve dans docs/README.md.

Les règles normatives commencent dans RULES.md. Les règles spécialisées sont placées sous docs/rules/.

Les documents historiques de bot2, bobobot et de la migration bot3 sont conservés sous olddocs/. Ils servent de sources historiques et ne sont pas normatifs.

Validation générale

cargo fmt --all
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
cargo test --workspace

La validation frontend desktop s’effectue uniquement avec :

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