v0.1.0-pre.070

kb-pipeline-demo-scenarios/USAGE.md

@@ -0,0 +1,181 @@
+<!-- file: kb-pipeline-demo-scenarios/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-pipeline-demo-scenarios
+
+## Objectif
+
+La bibliothèque expose des scénarios Devnet contrôlés. Le binaire permet leur exécution hors de l’application desktop lorsque la commande correspondante est disponible.
+
+## Initialiser l’environnement
+
+```rust
+fn initialize_environment() -> kb_core::Result<()> {
+    kb_pipeline_demo_scenarios::initialize_demo_scenario_environment()
+}
+```
+
+`resolve_demo_devnet_profile` sélectionne un profil Devnet configuré et `prepare_demo_devnet_profile_store` vérifie ou initialise son stockage PostgreSQL.
+
+## Observer une exécution
+
+`NoopSolanaExecutionObserver` convient aux appels sans progression personnalisée.
+
+```rust
+fn observer() -> kb_pipeline_demo_scenarios::NoopSolanaExecutionObserver {
+    kb_pipeline_demo_scenarios::NoopSolanaExecutionObserver
+}
+```
+
+Une application peut implémenter `SolanaExecutionObserver` pour recevoir les événements et demander une annulation coopérative.
+
+## Préparer une simulation System Program
+
+```rust
+fn system_transfer_request(
+    recipient: kb_lib::MdPubkey,
+) -> kb_pipeline_demo_scenarios::DevnetSystemTransferRequest {
+    kb_pipeline_demo_scenarios::DevnetSystemTransferRequest::new(
+        "system-transfer-001",
+        recipient,
+        1_000,
+    )
+}
+```
+
+Le constructeur crée une requête conservative : `submit` et `operator_confirmed` restent à `false`.
+
+## Préparer et exécuter un Memo v4
+
+```rust
+fn memo_request() -> kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest {
+    kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest::new(
+        "memo-001",
+        "khadhroony-bot3 Devnet validation",
+    )
+}
+```
+
+```rust
+async fn run_memo<S, O>(
+    store: &S,
+    observer: &O,
+    request: kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest,
+) -> kb_core::Result<kb_pipeline_demo_scenarios::DevnetMemoExecutionSummary>
+where
+    S: kb_store::Store + Sync,
+    O: kb_pipeline_demo_scenarios::SolanaExecutionObserver,
+{
+    let result = kb_pipeline_demo_scenarios::execute_devnet_memo(
+        store,
+        observer,
+        request,
+    )
+    .await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Simuler Token-2022
+
+```rust
+async fn simulate_token_2022<O>(
+    request: kb_pipeline_demo_scenarios::DevnetSplToken2022ExecutionRequest,
+    observer: &O,
+) -> kb_core::Result<kb_pipeline_demo_scenarios::DevnetSplToken2022ExecutionSummary>
+where
+    O: kb_pipeline_demo_scenarios::SolanaExecutionObserver,
+{
+    let result =
+        kb_pipeline_demo_scenarios::simulate_devnet_spl_token_2022(request, observer).await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Charger la matrice de validation Token-2022
+
+```rust
+fn load_validation_matrix(
+) -> kb_core::Result<kb_pipeline_demo_scenarios::Token2022ValidationMatrix> {
+    let result = kb_pipeline_demo_scenarios::load_token_2022_validation_matrix();
+
+    match result {
+        Ok(matrix) => Ok(matrix),
+        Err(error) => Err(error),
+    }
+}
+```
+
+La matrice provient de `test-fixtures/contract-matrices/SPL_TOKEN_2022_VALIDATION_MATRIX.json` et est validée avant d’être retournée.
+
+## Parcourir les scénarios publics
+
+```rust
+fn scenario_ids() -> Vec<String> {
+    kb_pipeline_demo_scenarios::devnet_spl_validation_scenarios()
+        .iter()
+        .map(|scenario| scenario.id.clone())
+        .collect()
+}
+```
+
+Cette liste permet au CLI ou au desktop de présenter l’inventaire sans dupliquer les identifiants.
+
+## Préparer une fixture Token-2022
+
+```rust
+async fn prepare_fixture(
+    wallet_path: std::path::PathBuf,
+    wallet_dir: std::path::PathBuf,
+) -> kb_core::Result<kb_pipeline_demo_scenarios::Token2022FixturePreparationSummary> {
+    let options = kb_pipeline_demo_scenarios::Token2022FixturePreparationOptions {
+        rpc_url: "https://api.devnet.solana.com".to_string(),
+        wallet_path,
+        wallet_dir,
+        decimals: 9,
+    };
+    let result = kb_pipeline_demo_scenarios::prepare_token_2022_fixture(&options).await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+La préparation peut créer des comptes et exécuter des commandes Solana CLI. Elle doit rester explicitement déclenchée par l’opérateur.
+
+## Tests de référence
+
+Les tests de cette crate sont particulièrement utiles pour comprendre l’orchestration réelle :
+
+- validation de la matrice Token-2022 ;
+- préparation et réutilisation des fixtures ;
+- simulation et exécution des scénarios ;
+- hydratation canonique, extraction Core, replay et matérialisation ;
+- idempotence et confirmation des états finaux ;
+- test du binaire `kb-pipeline-demo-scenarios-cli`.
+
+Les tests Devnet restent opt-in et peuvent produire des transactions réelles lorsque la soumission est explicitement activée.
+
+## Erreurs et invariants
+
+- aucun envoi ne doit résulter d’une simple demande de simulation ;
+- le profil doit cibler Devnet pour les scénarios Devnet ;
+- les secrets restent gérés par `kb-wallet` ;
+- les résumés ne doivent pas déclarer une validation non observée ;
+- ElGamal ne doit pas être présenté comme validé sur réseau.
+
+## Limites durables
+
+- cette crate est destinée aux démonstrations, validations et outils opérateur, pas au moteur de production autonome ;
+- les scénarios réseau exigent un endpoint, un wallet et des fonds compatibles ;
+- la bibliothèque ne fournit pas d’interface graphique.