88 lines
6.5 KiB
Markdown
88 lines
6.5 KiB
Markdown
<!-- file: kb-lib/README.md -->
|
||
<!-- version: 23 -->
|
||
|
||
# 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`, le décodeur contextualisé des neuf instructions stables et la matérialisation exhaustive 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.
|
||
- deux projections d’état autoritatives pour `Buffer` et `Metadata`, avec conservation bornée du contenu on-chain ;
|
||
- neuf faits de mutation d’instructions committées, non autoritatifs vis-à-vis de l’état final et réconciliables avec les snapshots post-exécution ;
|
||
- une classification où les neuf instructions stables sont courantes, sans opération officiellement remplacée ou obsolète à annoter `Deprecated`.
|
||
|
||
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_*`, fonctions `decoder_metadata_solana_program_metadata_decode_*_account` et helpers `materializer_metadata_materialize_solana_program_metadata_*_snapshot` ;
|
||
- 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, le décodeur contextualisé et la matérialisation des deux comptes et 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 instructions produisent des faits committés non autoritatifs ; les snapshots post-exécution restent la source de l’état final. 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)
|
||
- [Matrice de matérialisation Solana Program Metadata](../test-fixtures/contract-matrices/SOLANA_PROGRAM_METADATA_MATERIALIZATION_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)
|