khadhroony-bot3/README.md

Khadhroony Bot3

Khadhroony Bot3 is the consolidated successor workspace to khadhroony-bot2.

Workspace crates

• kb-core: foundation errors and shared primitives.
• kb-config: configuration contracts.
• kb-lib: all decoder, executor and materializer APIs and implementations.
• kb-logging: logging and tracing runtime.
• kb-program-ids: Solana program identifier registry.
• kb-pipeline: ingestion, decoding, materialization and execution orchestration.
• kb-rpc: HTTP and WebSocket Solana transports.
• kb-store: store-neutral contracts and PostgreSQL implementation modules.
• kb-wallet: wallet and signer support.
• kb-app-demo: the only binary retained during the initial migration.

Migration principle

The previous workspace is preserved under migration/khadhroony-bot2-reference. The new workspace compiles independently as a controlled scaffold. Public APIs are ported into kb-lib module by module, with compatibility recorded in migration/module-map.json.

Validation

cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets

État de migration 0.1.0-pre.001

• kb-wallet remplace définitivement le scaffold kb_wallet.
• kb-core conserve l’architecture de kb_core : implémentations dans error.rs et module.rs, façade et réexports dans lib.rs.
• Les prochaines APIs consolidées de kb-lib suivront la même règle : aucun contrat métier ne sera défini directement dans lib.rs.

Contrats consolidés

À partir de 0.1.0-pre.002, kb-lib porte les modèles et contrats fondamentaux autrefois répartis entre kb_model, kb_decoder_api, kb_materializer_api et kb_execution_api. Les implémentations restent dans des modules dédiés ; kb-lib/src/lib.rs ne contient que les déclarations de modules et les réexports publics.

Stockage consolidé

À partir de 0.1.0-pre.003, kb-store remplace le scaffold initial par une implémentation complète :

• contrats store-neutral : DTO, entités, pagination, santé et traits de repository ;
• adaptateur PostgreSQL : connexion, initialisation idempotente, requêtes, diagnostics et replay ;
• façade unique dans kb-store/src/lib.rs ;
• modèle de replay partagé conservé dans kb-lib, sans duplication ;
• options PostgreSQL indépendantes de kb-config, adaptées par la frontière applicative.

Décodeurs consolidés

0.1.0-pre.004 porte le décodeur Solana Core dans kb-lib. 0.1.0-pre.005 ajoute SPL Memo v1, v3 et v4. 0.1.0-pre.006 ajoute le décodeur SPL Token classique avec ses 28 tags publiés, son wire borné, ses formes d’autorité et son Batch structuré. 0.1.0-pre.007 ajoute le programme SPL Associated Token Account avec ses trois instructions, sa forme historique Create vide et la validation canonique des PDA pour SPL Token classique et Token‑2022.

0.1.0-pre.008 porte le décodeur Token‑2022 maximal, son parseur d’états Mint/Account/Multisig et de TLV, ainsi que le programme indépendant du registre ElGamal. Les deux composants gardent des frontières et des targets de tracing distincts. Tous les décodeurs migrés utilisent les mêmes contrats contextualisés, la même façade publique et aucune dépendance inverse vers kb-store.

0.1.0-pre.009 porte le décodeur indépendant Metaplex Token Metadata. Il couvre les 58 discriminateurs d’instructions publiés 0..=57, les 15 variantes de comptes Key 0..=14, les PDA officiels et les layouts courants, expérimentaux et historiques. Les metadata externes Metaplex restent séparées des metadata incorporées de Token‑2022, de Metaplex Core et de Bubblegum.

Matérialisateurs consolidés

0.1.0-pre.010 porte les quatre matérialisateurs Solana natifs dans kb-lib :

• MtLifecycleMaterializer pour les comptes System, nonces, ALT, loaders, Feature Gate, contextes ZK et rapports Slashing ;
• MtAdminMaterializer pour les assignations, configurations et autorités, avec ses projections stateful Token‑2022 et registre ElGamal ;
• MtComplianceAuditMaterializer pour les écritures et copies bornées de bytecode ;
• MtStakingMaterializer pour les transitions Stake et Vote commitées.

Les identités historiques des processors sont conservées pour la compatibilité des replays, tandis que les targets de tracing suivent désormais la hiérarchie kb-lib.materializer.*. Le contrat public MtApiEventMaterializer, ses modèles d’entrée et ses résultats restent réexportés à la racine de kb-lib, afin qu’un futur crate externe puisse fournir un matérialiseur sans dépendre d’une implémentation interne.

0.1.0-pre.011 termine le port des matérialisateurs réellement implémentés dans bot2 :

• MtTransactionAnnotationMaterializer pour les Memo commitées ;
• MtTokenAccountsMaterializer pour les mutations SPL Token, le lifecycle ATA et les snapshots Token‑2022 ;
• MtFeesMaterializer pour les frais publics et confidentiels Token‑2022, sans prétendre déchiffrer les valeurs confidentielles ;
• MtRiskMaterializer pour les faits de risque SPL Token et ATA sans score arbitraire ;
• MtMetadataMaterializer pour les snapshots descriptifs Token‑2022 et Metaplex, sans fetch off-chain.

Les modules de matérialisation sont privés. Tous les contrats, types concrets et helpers destinés aux consommateurs externes sont exposés exclusivement par kb-lib/src/lib.rs. Des tests aval distincts protègent les contrats d’extension DcApiProtocolDecoder, MtApiEventMaterializer et ExApiInstructionExecutor.