69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
<!-- file: kb-lib/README.md -->
|
||
<!-- version: 14 -->
|
||
|
||
# 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)
|