88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
<!-- file: kb-lib/README.md -->
|
||
<!-- version: 4 -->
|
||
|
||
# kb-lib
|
||
|
||
`kb-lib` regroupe les modèles partagés et les composants de décodage, matérialisation et exécution de `khadhroony-bot3`. Les composants restent séparés par modules privés et sont exposés par la façade unique `kb-lib/src/lib.rs`.
|
||
|
||
## Décodeur Solana Core
|
||
|
||
`SolanaCoreDecoder` est le premier décodeur concret porté depuis bot2. Il implémente `InstructionDecoder` et `ProtocolDecoder` sans dépendre de PostgreSQL, du RPC, de Tauri ou du wallet.
|
||
|
||
Il couvre les 18 surfaces natives suivantes :
|
||
|
||
- System Program ;
|
||
- Compute Budget ;
|
||
- Address Lookup Table ;
|
||
- Config et Feature Gate ;
|
||
- Vote et Stake ;
|
||
- loaders natifs, BPF historiques, upgradeable et Loader v4 ;
|
||
- précompiles Ed25519, secp256k1 et secp256r1 ;
|
||
- Slashing ;
|
||
- ZK ElGamal Proof et l’ancien ZK Token Proof.
|
||
|
||
La matrice `docs/NATIVE_SOLANA_DECODER_MATRIX.json` reste la source machine-readable de la couverture. Les instructions inconnues, tronquées, historiques ou issues d’une transaction échouée conservent les statuts et diagnostics explicites définis par les contrats communs.
|
||
|
||
## Décodeur SPL Memo
|
||
|
||
`SplMemoDecoder` couvre exactement les générations v1, v3 et v4. Le payload est lu comme un message brut sans discriminator, borné à 4 096 octets, puis projeté avec son texte UTF-8 complet, sa longueur, son SHA-256, les comptes ordonnés et le statut de commit.
|
||
|
||
Memo v1 ignore les comptes lors de la validation runtime. Memo v3 et v4 exigent que chaque compte fourni soit signer. Les transactions échouées restent des intentions non commitées et les payloads UTF-8 invalides ou signatures manquantes deviennent des tentatives invalides explicites. La matrice normative est `docs/SPL_MEMO_MATRIX.json`.
|
||
|
||
## Décodeur SPL Token classique
|
||
|
||
`SplTokenDecoder` couvre exclusivement le Program ID classique
|
||
`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`. Il publie 28 déclarations de couverture pour
|
||
les tags `0..24`, `38`, `45` et `255`, y compris les variantes historiques, checked,
|
||
`WithdrawExcessLamports`, `UnwrapLamports` et `Batch`.
|
||
|
||
Le parseur conserve les montants bruts sans perte, les comptes dans leur ordre d’origine, les
|
||
formes d’autorité simple ou multisig, les suffixes runtime et les chemins outer/inner. Une
|
||
transaction échouée reste une intention non commitée. `Batch` est borné à 64 enfants, 512 comptes
|
||
cumulés et interdit les batches imbriqués. Le décodeur n’invente ni mint, ni decimals, ni état
|
||
final ; les validations `M/N`, soldes et autorités existantes restent stateful. La matrice
|
||
normative est `docs/SPL_TOKEN_MATRIX.json`.
|
||
|
||
## Décodeur SPL Associated Token Account
|
||
|
||
`SplAssociatedTokenAccountDecoder` couvre exclusivement
|
||
`ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. Il reconnaît les trois variantes publiées
|
||
`Create`, `CreateIdempotent` et `RecoverNested`, ainsi que l’encodage historique vide de `Create`.
|
||
|
||
Le décodeur conserve les comptes dans leur ordre original, leurs flags, doublons, chemins
|
||
outer/inner et le statut de transaction. Il dérive les PDA avec l’ordre canonique
|
||
`[wallet, token_program, mint]`, conserve simultanément l’adresse observée et l’adresse attendue,
|
||
puis expose tout écart comme diagnostic. SPL Token classique et Token‑2022 sont distingués par leur
|
||
Program ID sans reconstruire leur état ni interpréter leurs extensions. La matrice normative est
|
||
`docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json`.
|
||
|
||
## API publique utile
|
||
|
||
- `SolanaCoreDecoder` : décodeur concret natif ;
|
||
- `SplMemoDecoder` : décodeur exact des trois générations SPL Memo ;
|
||
- `SplTokenDecoder` : décodeur exact du programme SPL Token classique ;
|
||
- `SplAssociatedTokenAccountDecoder` : décodeur exact du programme Associated Token Account ;
|
||
- `InstructionDecoder` : contrat de reconnaissance, couverture et décodage contextualisé ;
|
||
- `ProtocolDecoder` : contrat de compatibilité avec les observations historiques ;
|
||
- `CoreInstructionReplayInput` : input source-neutral produit par l’extraction core ;
|
||
- `DecoderExecutionResult`, `DecoderRecognition` et `DecoderCoverageDeclaration` : résultats typés du pipeline ;
|
||
- modèles canoniques et nomenclature réexportés depuis la façade.
|
||
|
||
Les helpers, constantes wire et types intermédiaires de chaque composant restent internes. Leurs noms sont préfixés au niveau de la façade interne afin d’éviter les collisions lors de la fusion des anciens crates.
|
||
|
||
## Exemple
|
||
|
||
```rust
|
||
let decoder = kb_lib::SolanaCoreDecoder;
|
||
let recognition = kb_lib::InstructionDecoder::recognize(&decoder, &input);
|
||
```
|
||
|
||
L’appel de décodage complet utilise `InstructionDecoder::decode` après une reconnaissance compatible. Le pipeline demeure responsable de la sélection du décodeur et de la persistance du résultat.
|
||
|
||
## Frontières
|
||
|
||
- `kb-lib` ne dépend jamais de `kb-store`.
|
||
- Les décodeurs ne lisent pas un état RPC courant pour reconstruire une transaction historique.
|
||
- Une transaction échouée peut produire une intention structurée, jamais une mutation commitée.
|
||
- Les matérialisateurs et exécuteurs seront portés dans des tranches séparées.
|