v0.4.8-pre.006

kb-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-lib/USAGE.md -->
-<!-- version: 11 -->
+<!-- version: 12 -->
 
 # Utilisation de kb-lib
 
@@ -153,6 +153,35 @@ println!("status={:?}", result.status);
 
 Le tag `5` est toujours publié comme `trim`. Son ancien nom pré-stable `withdraw_excess_lamports` est conservé uniquement comme provenance, car aucune release stable ne l’expose comme instruction distincte. Les URL et références externes restent des données on-chain ; le décodeur ne réalise aucun fetch.
 
+Le matérialiseur `MtMetadataMaterializer` accepte les neuf observations d’instructions de la surface exacte `metadata.solana_program_metadata`. Il refuse les transactions échouées et produit un fait de mutation par instruction. Ces faits ne remplacent pas un snapshot de compte : l’état final doit être matérialisé depuis la lecture post-exécution.
+
+```rust
+let materializer = kb_lib::MtMetadataMaterializer;
+if kb_lib::MtApiEventMaterializer::accepts_observation(&materializer, &observation) {
+    let result = kb_lib::MtApiEventMaterializer::materialize(&materializer, &observation);
+    println!("materialization status={:?}", result.status);
+}
+```
+
+Les trois helpers d’état acceptent les snapshots déjà validés par le décodeur :
+
+- `materializer_metadata_materialize_solana_program_metadata_account_snapshot` distribue `Buffer` ou `Metadata` ;
+- `materializer_metadata_materialize_solana_program_metadata_buffer_snapshot` conserve tous les octets du Buffer sous une forme bornée avec base64 et SHA-256 ;
+- `materializer_metadata_materialize_solana_program_metadata_metadata_snapshot` conserve le contenu direct, l’URL ou la référence externe, ainsi que l’autorité, la mutabilité, le format et la capacité allouée.
+
+```rust
+let output = match kb_lib::materializer_metadata_materialize_solana_program_metadata_account_snapshot(
+    slot,
+    &snapshot,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+println!("projection={}", output.payload_json);
+```
+
+Une URL reste une chaîne observée avec `fetched = false`. Une référence externe reste une adresse, un offset et une longueur avec `accountRead = false`. La matérialisation canonique ne réalise aucun enrichissement off-chain.
+
 ## 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.