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-onchain-transport: 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.

0.1.0-pre.012 restaure les 98 squelettes de décodeurs réservés sous forme de types Dc*Decoder implémentant DcApiProtocolDecoder. Les 97 surfaces identifiables déclarent leur Program ID exact dans kb-program-ids; Anchor reste volontairement sans identifiant statique. Ces squelettes répondent Maybe sans produire de faux événement et sont exposés uniquement par la façade kb_lib.

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.

0.1.0-pre.013 remplace les 14 dernières frontières temporaires de matérialisation par des squelettes Mt*Materializer. Ils conservent le contrat historique MtMaterializer, implémentent également MtApiEventMaterializer, restent volontairement inactifs et ne produisent aucun faux événement via l’API bot3. Tous les types sont accessibles exclusivement depuis la façade kb_lib.

0.1.0-pre.014 confirme la parité de l’API publique ExApi* avec bot2 et remplace les 104 frontières temporaires d’exécution par des squelettes Ex*Executor. Chaque squelette référence uniquement ses Program IDs enregistrés, annonce Maybe sur sa surface et construit exclusivement un plan réservé à zéro instruction. Les exécuteurs opérationnels seront portés séparément, en commençant par Solana Core puis SPL.

0.1.0-pre.015 rend ExSolanaCoreExecutor fonctionnel. Il construit des plans déterministes pour 109 opérations natives réparties sur 18 surfaces, conserve les refus explicites des programmes historiques non exécutables et expose ses intents sous les préfixes bot3 ExSolanaCore* et EX_SOLANA_CORE_*. Les 103 autres exécuteurs restent réservés jusqu’à leur port fonctionnel.

0.1.0-pre.016 intègre le moteur transversal ExSafetyChecker et rend ExSplMemoExecutor fonctionnel. Memo v4 produit une instruction officielle bornée et soumise à simulation ; les générations historiques v1/v3 restent decode-only. Les 102 autres exécuteurs restent réservés jusqu’à leur port fonctionnel.

Migration pipeline

La tranche 0.1.0-pre.029 migre la planification et l’extraction core de kb-pipeline.

Pipeline migré

kb-pipeline contient désormais l’extraction core et le replay contextuel de décodage avec matérialisation optionnelle.

Backfill HTTP

La tranche 0.1.0-pre.031 ajoute l’orchestration HTTP de backfill : signatures explicites ou historiques par adresse, pagination bornée, hydration via getTransaction, retries, annulation, reprise déterministe et persistance des observations.