v0.4.7-pre.007

kb-pipeline/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-pipeline/USAGE.md -->
-<!-- version: 2 -->
+<!-- version: 4 -->
 
 # Utilisation de kb-pipeline
 
@@ -178,3 +178,97 @@ Les campagnes longues exposent des traits d’observation distincts pour le back
 - la crate orchestre les traitements mais ne fournit pas d’interface opérateur ;
 - elle ne conserve pas de secret de wallet ;
 - elle ne remplace pas les scénarios Devnet et validations explicites de `kb-pipeline-demo-scenarios`.
+
+## Lire un compte Metaplex Token Metadata
+
+La lecture stateful exige un endpoint HTTP, une catégorie de compte explicite et une borne stricte sur les données décodées.
+
+```rust
+async fn read_metaplex_metadata(
+    pool: &kb_onchain_transport::HttpEndpointPool,
+    metadata: kb_lib::MdPubkey,
+) -> kb_core::Result<kb_pipeline::MetaplexTokenMetadataStatefulReadResult> {
+    let request = kb_pipeline::MetaplexTokenMetadataStatefulReadRequest {
+        query_role: "rpc".to_string(),
+        account: metadata,
+        kind: kb_pipeline::MetaplexTokenMetadataAccountKind::Metadata,
+        min_context_slot: std::option::Option::None,
+        max_data_bytes: kb_pipeline::MAX_METAPLEX_TOKEN_METADATA_ACCOUNT_BYTES,
+    };
+    let result = kb_pipeline::read_metaplex_token_metadata_stateful_snapshot(
+        pool,
+        &request,
+    )
+    .await;
+
+    match result {
+        Ok(snapshot) => Ok(snapshot),
+        Err(error) => Err(error),
+    }
+}
+```
+
+Pour une edition, fournir le mint dans `MetaplexTokenMetadataAccountKind::Edition`. Pour un token record programmable, fournir le mint et le token account dans `TokenRecord`.
+
+## Inspecter le préflight Metaplex
+
+Le préflight lie un plan préparé par `kb-lib` à des snapshots confirmés et applique la politique des opérations dépréciées.
+
+```rust
+fn inspect_metaplex_preflight(
+    plan: kb_lib::ExApiPreparedExecutionPlan,
+    snapshots: Vec<kb_pipeline::MetaplexTokenMetadataStatefulReadResult>,
+    allow_deprecated_operation: bool,
+) -> kb_core::Result<kb_pipeline::MetaplexTokenMetadataPreflightReport> {
+    let request = kb_pipeline::MetaplexTokenMetadataPreflightRequest {
+        plan,
+        snapshots,
+        allow_deprecated_operation,
+    };
+
+    kb_pipeline::inspect_metaplex_token_metadata_preflight(&request)
+}
+```
+
+Une opération marquée dépréciée par `kb-lib` est refusée lorsque `allow_deprecated_operation` vaut `false`.
+
+## Valider l’enveloppe d’exécution Metaplex
+
+L’orchestration refuse la signature ou la soumission tant que la simulation exacte du message, les signers et la confirmation opérateur ne sont pas cohérents.
+
+```rust
+fn validate_metaplex_execution(
+    plan: kb_lib::ExApiPreparedExecutionPlan,
+    preflight: kb_pipeline::MetaplexTokenMetadataPreflightReport,
+    message_hash: String,
+    resolved_signers: Vec<kb_lib::MdPubkey>,
+) -> kb_core::Result<kb_pipeline::MetaplexTokenMetadataExecutionReadinessReport> {
+    let request = kb_pipeline::MetaplexTokenMetadataExecutionReadinessRequest {
+        plan,
+        preflight,
+        message_hash: message_hash.clone(),
+        simulated_message_hash: message_hash,
+        simulated: true,
+        simulation_succeeded: true,
+        resolved_signers,
+        submit: false,
+        operator_confirmed: false,
+    };
+
+    kb_pipeline::validate_metaplex_token_metadata_execution_readiness(&request)
+}
+```
+
+Pour une soumission réelle, `submit` et `operator_confirmed` doivent être vrais et le plan ne doit plus être en `dry_run`.
+
+## Agréger les postconditions Metaplex
+
+```rust
+fn summarize_metaplex_postconditions(
+    statuses: &[kb_pipeline::MetaplexTokenMetadataPostconditionStatus],
+) -> kb_pipeline::MetaplexTokenMetadataPostconditionStatus {
+    kb_pipeline::summarize_metaplex_token_metadata_postconditions(statuses)
+}
+```
+
+`Contradicted` est prioritaire sur `Confirmed`, et l’absence de postcondition applicable reste `NotApplicable`.