# kb-lib `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](USAGE.md). ## Matrices contractuelles Les matrices actives sont maintenues sous [`../test-fixtures/contract-matrices/`](../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. ## Documents - [Utilisation](USAGE.md) - [Travaux restants](TODO.md) - [Historique de la crate](CHANGELOG.md) - [Architecture générale](../docs/architecture/ARCHITECTURE.md) - [Pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md) - [Matrice des surfaces](../docs/architecture/SURFACE_CRATE_MATRIX.md)