v0.4.8-pre.004

kb-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-lib/USAGE.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->
 
 # Utilisation de kb-lib
 
@@ -82,7 +82,7 @@ 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
+## Modèles et comptes 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`.
 
@@ -108,7 +108,37 @@ 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.
+Les trois fonctions publiques de comptes vérifient le propriétaire `ProgM6…`, la borne maximale de données et les layouts fixes :
+
+- `decoder_metadata_solana_program_metadata_decode_account` sélectionne `Buffer` ou `Metadata` depuis le discriminateur ;
+- `decoder_metadata_solana_program_metadata_decode_buffer_account` conserve tous les octets alloués après le header, sans prétendre qu’un Buffer garde un PDA vérifiable après une modification d’autorité ;
+- `decoder_metadata_solana_program_metadata_decode_metadata_account` valide le PDA canonical ou non-canonical, `data_length`, les enums fermées et les contraintes propres à `Direct`, `Url` et `External`.
+
+```rust
+let snapshot = match kb_lib::decoder_metadata_solana_program_metadata_decode_account(
+    metadata_account.as_str(),
+    account_owner.as_str(),
+    &account_data,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error.to_string()),
+};
+
+match snapshot {
+    kb_lib::DcMetadataSpmAccountSnapshot::Buffer(value) => {
+        println!("buffer bytes={}", value.allocated_data_bytes);
+    },
+    kb_lib::DcMetadataSpmAccountSnapshot::Metadata(value) => {
+        println!("metadata program={}", value.program);
+        println!("logical bytes={}", value.data_length);
+        println!("reserved capacity={}", value.trailing_capacity_bytes);
+    },
+}
+```
+
+Une URL est seulement décodée comme chaîne UTF-8 on-chain. Aucune requête HTTP, IPFS ou Arweave n’est effectuée. Une référence `External` est seulement décodée en adresse, offset et longueur zeroable ; le compte référencé n’est pas lu.
+
+Le décodeur de protocole `DcMetadataSolanaProgramMetadataDecoder` reste réservé aux instructions. Les comptes constituent désormais un contrat public stable pour les futurs matérialisateurs, builders et parcours stateful.
 
 ## Comptes Metaplex Token Metadata