# kb-lib `kb-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle fournit les modèles, décodeurs, matérialisateurs, exécuteurs et contrats de sécurité indépendants du transport, du stockage et de l’interface utilisateur. ## Périmètre La crate couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et Metaplex Token Metadata. Elle expose également les modèles wire bornés, les décodeurs de comptes `Buffer` et `Metadata` et le décodeur contextualisé des neuf instructions stables de Solana Program Metadata. Pour Solana Program Metadata, la surface publique fondatrice comprend : - les tailles fixes officielles des headers, seeds et références externes ; - les enums fermées de discriminateur, encodage, compression, format et source ; - le seed brut de 16 octets avec helpers UTF-8 bornés ; - les données directes, URL et références vers un autre compte sans résolution off-chain ; - les cinq erreurs custom officielles et les erreurs de conversion fail-closed ; - les snapshots bornés `Buffer` et `Metadata`, avec validation du propriétaire, des PDA metadata, des longueurs logiques et des trois sources de données ; - une politique explicite où les octets situés après `data_length` sont conservés comme capacité allouée et jamais assimilés au contenu logique ; - les neuf instructions stables `Write`, `Initialize`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim`, `Close`, `Allocate` et `Extend` ; - les formes runtime actuelles non produites par le SDK, notamment `SetData` sans remplacement de données et les suffixes ignorés de `SetImmutable`, `Trim` et `Close` ; - une frontière historique où l’ancien nom pré-stable `WithdrawExcessLamports` du tag `5` reste une provenance de `Trim`, sans dixième entrée de couverture. Pour Metaplex Token Metadata, elle fournit : - le décodage des 58 discriminants et des principales familles de comptes ; - la propriété unique des faits metadata, admin, lifecycle et risk/compliance ; - 20 opérations courantes exécutables ; - 15 opérations obsolètes encore constructibles, exposées comme dépréciées et soumises à une approbation explicite ; - 22 versions remplacées conservées en décodage uniquement et redirigées vers leur remplacement canonique final ; - une frontière explicite avec Bubblegum et avec les metadata incorporées de Token-2022. ## Responsabilités - reconnaître et décoder des instructions contextualisées ; - décoder les comptes on-chain pris en charge ; - produire des observations et diagnostics typés ; - matérialiser les faits stables et prouvés ; - construire des plans d’exécution bornés ; - déclarer les comptes, signers, coûts et confirmations nécessaires ; - appliquer les garde-fous fail-closed avant simulation, signature ou envoi ; - exposer des modèles indépendants du RPC, de PostgreSQL et de Tauri. ## Hors périmètre `kb-lib` ne sélectionne aucun endpoint, ne lit pas directement un RPC, ne persiste aucune donnée, ne gère pas les secrets de wallet et ne soumet aucune transaction. ## Surface publique principale - contrats `DcApi*` et décodeurs concrets `Dc*Decoder` ; - parseurs de comptes et d’états bornés ; - contrats `MtApi*` et matérialisateurs concrets ; - contrats `ExApi*`, politiques de sécurité et exécuteurs `Ex*Executor` ; - `ExMetadataMetaplexTokenMetadataExecutor`, `ExMetaplexTokenMetadataExecutionIntent` et `ExMetaplexTokenMetadataOperation` ; - `DcMetadataSolanaProgramMetadataDecoder`, modèles `DcMetadataSpm*`, constantes `DC_METADATA_SPM_*` et fonctions `decoder_metadata_solana_program_metadata_decode_*_account` pour le contrat Solana Program Metadata ; - modèles canoniques `Md*` réexportés par la façade. Les exemples d’appel et invariants sont documentés dans [USAGE.md](USAGE.md). ## Relations avec le workspace - dépend de `kb-core` et `kb-program-ids` ; - 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`, `kb-pipeline` ni d’une application. ## Statut et limites La surface fonctionnelle Metaplex de la crate est achevée. Les campagnes Devnet restantes relèvent de `kb-pipeline-demo-scenarios` et de `kb-app-demo-desktop`, non d’un manque de builder dans `kb-lib`. Pour Solana Program Metadata, les modèles wire, les décodeurs bornés de comptes et le décodeur contextualisé des neuf instructions stables sont actifs. `Buffer` accepte tout reliquat comme données allouées sans inventer de PDA stable après changement d’autorité ; `Metadata` valide la dérivation canonical ou non-canonical et distingue le contenu logique de la capacité ajoutée par `Extend`. Les variantes qui dépendent de l’état du compte restent des intentions wire jusqu’aux lectures stateful prévues, et aucune forme pré-stable n’est déclarée compatible réseau sans preuve de cluster. Le registre ElGamal n’est pas déclaré validé réellement sur réseau. ## Documentation - [Guide d’utilisation](USAGE.md) - [Travaux restant à réaliser](TODO.md) - [Historique des changements](CHANGELOG.md) - [Matrice contractuelle Metaplex](../test-fixtures/contract-matrices/METAPLEX_TOKEN_METADATA_MATRIX.json) - [Matrice des comptes Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_ACCOUNT_MATRIX.json) - [Matrice des instructions Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_INSTRUCTION_MATRIX.json) - [Audit de l’inventaire et de l’historique des instructions](../docs/audits/V0_4_8_PRE_005_SOLANA_PROGRAM_METADATA_INSTRUCTION_HISTORY_AUDIT.md)