v0.4.8-pre.003

kb-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-lib/USAGE.md -->
-<!-- version: 8 -->
+<!-- version: 9 -->
 
 # Utilisation de kb-lib
 
@@ -82,6 +82,34 @@ 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.
 
+## Modèles Solana Program Metadata
+
+Les modèles `DcMetadataSpm*` représentent uniquement le contrat on-chain du programme `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S`. Ils ne téléchargent jamais les URL et ne lisent pas automatiquement les comptes référencés par `External`.
+
+```rust
+let seed_result = kb_lib::DcMetadataSpmSeed::from_utf8("idl");
+let seed = match seed_result {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+let external = kb_lib::DcMetadataSpmExternalData::from_zeroable_length(
+    solana_pubkey::Pubkey::new_from_array([7_u8; 32]),
+    128,
+    4096,
+);
+let data = kb_lib::DcMetadataSpmData::External(external);
+let wire_bytes = match data.to_wire_bytes() {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+assert_eq!(seed.as_bytes().len(), kb_lib::DC_METADATA_SPM_SEED_BYTES);
+assert_eq!(wire_bytes.len(), kb_lib::DC_METADATA_SPM_EXTERNAL_DATA_BYTES);
+```
+
+Le champ `length` externe suit le contrat zeroable : la valeur wire `0` devient `None` et signifie que la référence porte sur tout le compte à partir de `offset`. Les contenus `Direct` et `Url` doivent être non vides, et toute longueur doit rester représentable par le `u32` du header.
+
+Le décodeur de protocole `DcMetadataSolanaProgramMetadataDecoder` est encore réservé. Les modèles servent déjà de contrat public stable aux futurs décodeurs de comptes, décodeurs d’instructions, matérialisateurs et builders.
+
 ## 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.