232 lines
7.7 KiB
Markdown
232 lines
7.7 KiB
Markdown
<!-- file: kb-lib/USAGE.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# Utilisation de kb-lib
|
||
|
||
## Objectif
|
||
|
||
Ce guide présente les familles d’API publiques significatives de `kb-lib`. Les helpers privés, éléments `pub(crate)` et modules non réexportés ne font pas partie du contrat consommateur.
|
||
|
||
## Dépendance
|
||
|
||
```toml
|
||
[dependencies]
|
||
kb-lib = { path = "../kb-lib" }
|
||
```
|
||
|
||
Toutes les fonctions retournant `kb_core::Result<T>` utilisent le contrat d’erreur structuré du workspace.
|
||
|
||
## Décodage contextualisé
|
||
|
||
`DcApiInstructionDecoder` définit la reconnaissance et le décodage d’une instruction contextualisée. Les décodeurs concrets sont des valeurs sans état.
|
||
|
||
```rust
|
||
use kb_lib::{DcApiInstructionDecoder, DcSolanaCoreDecoder};
|
||
|
||
let decoder = DcSolanaCoreDecoder;
|
||
let recognition = DcApiInstructionDecoder::recognize(&decoder, &input);
|
||
let result = DcApiInstructionDecoder::decode(&decoder, &input);
|
||
```
|
||
|
||
Le consommateur doit vérifier le résultat typé et ses diagnostics. Une transaction échouée peut produire une intention structurée, mais pas une mutation committée.
|
||
|
||
```rust
|
||
let execution = DcApiInstructionDecoder::decode(&decoder, &input);
|
||
|
||
match execution {
|
||
Ok(result) => {
|
||
println!("status={:?}", result.status);
|
||
println!("observations={}", result.observations.len());
|
||
println!("diagnostics={}", result.diagnostics.len());
|
||
},
|
||
Err(error) => return Err(error),
|
||
}
|
||
```
|
||
|
||
Décodeurs fonctionnels principaux :
|
||
|
||
- `DcSolanaCoreDecoder` ;
|
||
- `DcSplMemoDecoder` ;
|
||
- `DcSplTokenDecoder` ;
|
||
- `DcSplAssociatedTokenAccountDecoder` ;
|
||
- `DcSplToken2022Decoder` ;
|
||
- `DcSplElgamalRegistryDecoder` ;
|
||
- `DcMetadataMetaplexTokenMetadataDecoder`.
|
||
|
||
Les types réservés `Dc*Decoder` ne doivent pas être interprétés comme des décodeurs complets : ils publient une compatibilité conservatrice et aucune observation fonctionnelle.
|
||
|
||
## Lecture d’états Token-2022 et ElGamal
|
||
|
||
```rust
|
||
let state = match kb_lib::decoder_spl_token_2022_parse_token_2022_state(
|
||
kb_lib::DcToken2022StateKind::Account,
|
||
&account_data,
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
println!("parsed token-2022 state: {state:#?}");
|
||
```
|
||
|
||
```rust
|
||
let registry = match kb_lib::decoder_spl_elgamal_registry_parse_elgamal_registry_state(
|
||
&account_data,
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
println!("parsed registry state: {registry:#?}");
|
||
```
|
||
|
||
Les parseurs vérifient les bornes et formats qu’ils annoncent. Ils ne reconstruisent pas un état historique depuis un RPC courant.
|
||
|
||
## Comptes Metaplex Token Metadata
|
||
|
||
Les fonctions `decoder_metadata_metaplex_token_metadata_decode_*_account` décodent les familles de comptes publiques prises en charge. Le consommateur doit fournir les données et le contexte attendus par la signature exacte de la fonction concernée. Les parseurs conservent les variantes historiques et refusent les longueurs, propriétaires ou suffixes incompatibles.
|
||
|
||
```rust
|
||
let metadata = match kb_lib::decoder_metadata_metaplex_token_metadata_decode_metadata_account(
|
||
metadata_account.as_str(),
|
||
metadata_owner.as_str(),
|
||
&account_data,
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
println!("metadata mint={}", metadata.mint);
|
||
println!("metadata name={}", metadata.name);
|
||
```
|
||
|
||
```rust
|
||
let edition = match kb_lib::decoder_metadata_metaplex_token_metadata_decode_edition_account(
|
||
edition_account.as_str(),
|
||
metadata_owner.as_str(),
|
||
mint.as_str(),
|
||
&account_data,
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
println!("edition kind={:?}", edition.kind);
|
||
println!("edition parent={:?}", edition.parent);
|
||
```
|
||
|
||
Les signatures exactes doivent être vérifiées lors de l’utilisation : certaines familles exigent un contexte ou une identité canonique supplémentaire.
|
||
|
||
|
||
## Exécution typée
|
||
|
||
`ExApiTypedInstructionExecutor` produit un `ExApiPreparedExecutionPlan` à partir d’une intention et d’une politique explicites. Les exécuteurs concrets incluent notamment :
|
||
|
||
- `ExSolanaCoreExecutor` ;
|
||
- `ExSplMemoExecutor` pour Memo v4 ;
|
||
- `ExSplTokenExecutor` ;
|
||
- `ExSplAssociatedTokenAccountExecutor` ;
|
||
- `ExSplToken2022Executor` ;
|
||
- `ExSplElgamalRegistryExecutor`.
|
||
|
||
```rust
|
||
use kb_lib::{ExApiTypedInstructionExecutor, ExSplMemoExecutor};
|
||
|
||
let executor = ExSplMemoExecutor;
|
||
let plan = ExApiTypedInstructionExecutor::build_prepared_plan(
|
||
&executor,
|
||
&intent,
|
||
&policy,
|
||
);
|
||
```
|
||
|
||
Le plan ne signe et n’envoie rien. La simulation, la confirmation opérateur, la soumission et la confirmation réseau appartiennent aux couches d’orchestration et de transport.
|
||
|
||
```rust
|
||
let plan = match ExApiTypedInstructionExecutor::build_prepared_plan(
|
||
&executor,
|
||
&intent,
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
println!("instructions={}", plan.instructions.len());
|
||
println!("required_signers={}", plan.required_signers.len());
|
||
```
|
||
|
||
Memo v1 et v3 restent non exécutables. Memo v4 est la seule génération exécutable.
|
||
|
||
## Sécurité
|
||
|
||
Les types `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` permettent d’évaluer un plan avant son utilisation. Une décision conservatrice doit être respectée par le consommateur ; elle ne doit pas être contournée par l’application.
|
||
|
||
```rust
|
||
let evaluation = match checker.evaluate_prepared_plan(&plan) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
|
||
match evaluation.decision {
|
||
kb_lib::ExSafetyDecision::Allow => {
|
||
println!("execution plan accepted");
|
||
},
|
||
kb_lib::ExSafetyDecision::Deny => {
|
||
for violation in evaluation.violations {
|
||
eprintln!("safety violation: {violation:#?}");
|
||
}
|
||
},
|
||
}
|
||
```
|
||
|
||
## Matérialisation
|
||
|
||
`MtApiEventMaterializer` définit le contrat public de matérialisation. Les résultats `MtApiMaterializerExecutionResult` contiennent les sorties et diagnostics sans dépendre d’un backend de stockage.
|
||
|
||
```rust
|
||
let result = kb_lib::MtApiEventMaterializer::materialize(
|
||
&materializer,
|
||
&decoded_observation,
|
||
);
|
||
|
||
println!("status={:?}", result.status);
|
||
println!("outputs={}", result.outputs.len());
|
||
println!("diagnostics={}", result.diagnostics.len());
|
||
```
|
||
|
||
Les fonctions stateful publiques comprennent notamment :
|
||
|
||
- `materializer_admin_materialize_token_2022_state_snapshots` ;
|
||
- `materializer_admin_materialize_elgamal_registry_state_snapshot` ;
|
||
- `materializer_token_materialize_token_2022_state_snapshot` ;
|
||
- `materializer_metadata_materialize_token_2022_snapshot` ;
|
||
- `materializer_metadata_materialize_metaplex_metadata_snapshot` ;
|
||
- `materializer_metadata_materialize_metaplex_account_snapshot`.
|
||
|
||
## Contrat de replay
|
||
|
||
`MdCoreInstructionReplayInput` représente une instruction extraite avec son contexte transactionnel. Il constitue la frontière entre l’extraction Core, le pipeline de replay et les décodeurs.
|
||
|
||
```rust
|
||
let recognition = DcApiInstructionDecoder::recognize(&decoder, &replay_input);
|
||
|
||
if recognition.compatible {
|
||
let decoded = DcApiInstructionDecoder::decode(&decoder, &replay_input);
|
||
if let Err(error) = decoded {
|
||
return Err(error);
|
||
}
|
||
}
|
||
```
|
||
|
||
## Tests et matrices utiles
|
||
|
||
Les tests unitaires du décodeur Metaplex et du décodeur Solana Core chargent directement certaines matrices de [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Ils vérifient notamment l’égalité entre les entrées compilées et les contrats JSON, les discriminants, les bornes et les comportements historiques.
|
||
|
||
Les tests des exécuteurs comparent les instructions produites aux builders officiels et vérifient signers, comptes ordonnés, coûts et politiques de sécurité.
|
||
|
||
## Limites
|
||
|
||
- aucune persistance ni acquisition réseau ;
|
||
- aucun chargement dynamique des IDL en production ;
|
||
- les squelettes réservés ne sont pas des implémentations ;
|