71 lines
4.5 KiB
Markdown
71 lines
4.5 KiB
Markdown
<!-- file: kb-lib/README.md -->
|
||
<!-- version: 17 -->
|
||
|
||
# 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.
|
||
|
||
- Metaplex Token Metadata expose les wrappers canoniques courants et conserve les opérations obsolètes encore constructibles sous une API Rust `#[deprecated]` avec approbation opérateur explicite ; les versions remplacées ne reçoivent qu’un renvoi vers leur remplacement canonique final.
|
||
|
||
## 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 Metaplex Token Metadata couvre les 58 discriminants et les matérialisations possèdent désormais un contrat fermé de propriété des faits. L’exécuteur Metaplex ferme désormais les 35 opérations officiellement constructibles : 20 opérations courantes et 15 opérations obsolètes conservées sous `#[deprecated]` avec approbation opérateur explicite. Les 22 versions remplacées restent decode-only et Bubblegum demeure une frontière externe. La fermeture inclut les éditions, uses, escrow, mint, print, collect, migrate et resize. 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)
|