kb-lib est la bibliothèque fonctionnelle consolidée de khadhroony-bot3. Elle expose les modèles partagés, les contrats et implémentations de décodage, de matérialisation, d’exécution et de sécurité nécessaires au pipeline Solana.

Périmètre

La crate regroupe quatre familles internes, exposées par la façade kb_lib :

décodeurs et contrats de décodage contextualisé ;
exécuteurs, plans préparés et politiques de sécurité ;
matérialisateurs et projections structurées ;
modèles canoniques utilisés par les autres crates.

Elle couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et le décodeur Metaplex Token Metadata. De nombreux décodeurs et exécuteurs réservés exposent seulement une identité et une compatibilité conservatrice ; ils ne constituent pas une implémentation fonctionnelle.

Responsabilités

reconnaître et décoder une instruction à partir d’un contexte canonique ;
publier des déclarations de couverture déterministes ;
produire des observations et diagnostics typés ;
construire des plans d’exécution bornés et vérifiables ;
appliquer les politiques de sécurité avant simulation, signature ou envoi ;
matérialiser les observations commitées selon des contrats explicites ;
conserver des modèles indépendants du stockage, du transport et de l’interface desktop.

Hors périmètre

kb-lib ne persiste aucune donnée, ne dialogue pas directement avec un RPC, ne sélectionne pas un endpoint et ne gère pas les secrets de wallet. Ces responsabilités appartiennent respectivement à kb-store, kb-onchain-transport, kb-pipeline et kb-wallet.

Surface publique principale

La façade publique est organisée autour de :

DcApiInstructionDecoder, DcApiProtocolDecoder et les types DcApi* ;
les décodeurs concrets DcSolanaCoreDecoder, DcSplMemoDecoder, DcSplTokenDecoder, DcSplAssociatedTokenAccountDecoder, DcSplToken2022Decoder, DcSplElgamalRegistryDecoder et DcMetadataMetaplexTokenMetadataDecoder ;
ExApiTypedInstructionExecutor, ExApiInstructionExecutor, les politiques ExApi* et les exécuteurs concrets Ex*Executor ;
ExSafetyChecker et les décisions de sécurité associées ;
MtApiEventMaterializer, les types MtApi* et les matérialisateurs concrets ;
MdCoreInstructionReplayInput et les modèles canoniques réexportés.

Le catalogue détaillé et les exemples se trouvent dans USAGE.md.

Matrices contractuelles

Les matrices actives sont maintenues sous ../test-fixtures/contract-matrices/. Elles servent à la fois de références documentaires et de fixtures exécutées par des tests. Elles ne sont pas dupliquées dans la documentation de la crate.

Relations

dépend de kb-core pour le contrat d’erreur commun ;
dépend de kb-program-ids pour le registre canonique des programmes ;
est consommée par kb-pipeline, kb-store, kb-onchain-transport, kb-pipeline-demo-scenarios et kb-app-demo-desktop ;
ne dépend jamais de kb-store ni d’une application.

Statut et limites

La migration des surfaces historiques jusqu’à un périmètre proche de bot2 0.4.6 est largement réalisée. Le décodeur et les matérialisations Metaplex Token Metadata sont présents, mais l’exécuteur et la clôture fonctionnelle de cette surface restent à réaliser. Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.

README.md Unescape Escape

kb-lib