223 lines
6.8 KiB
Markdown
223 lines
6.8 KiB
Markdown
<!-- file: kb-pipeline-demo-scenarios/USAGE.md -->
|
||
<!-- version: 3 -->
|
||
|
||
# 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.
|
||
|
||
|
||
## Charger les scénarios synthétiques Metaplex
|
||
|
||
```rust
|
||
fn metaplex_scenario_ids() -> Vec<String> {
|
||
kb_pipeline_demo_scenarios::metaplex_token_metadata_synthetic_scenarios()
|
||
.iter()
|
||
.map(|scenario| scenario.id.clone())
|
||
.collect()
|
||
}
|
||
```
|
||
|
||
L’inventaire couvre NFT, SFT, token fongible, collection et pNFT. Ces scénarios sont déterministes et ne soumettent aucune transaction.
|
||
|
||
## Charger la matrice de validation Metaplex
|
||
|
||
```rust
|
||
fn load_metaplex_matrix(
|
||
) -> kb_core::Result<kb_pipeline_demo_scenarios::MetaplexTokenMetadataValidationMatrix> {
|
||
let result = kb_pipeline_demo_scenarios::load_metaplex_token_metadata_validation_matrix();
|
||
|
||
match result {
|
||
Ok(matrix) => Ok(matrix),
|
||
Err(error) => Err(error),
|
||
}
|
||
}
|
||
```
|
||
|
||
Une validation réseau ne peut passer à `confirmed` que lorsque toutes les preuves déclarées sont présentes. Les statuts `not_run` et `unavailable` n’acceptent aucune preuve observée.
|
||
|
||
## Inventaire Metaplex Devnet
|
||
|
||
```rust
|
||
let scenarios = kb_pipeline_demo_scenarios::metaplex_token_metadata_devnet_scenarios();
|
||
assert!(scenarios.iter().all(|scenario| {
|
||
scenario.mode == kb_pipeline_demo_scenarios::MetaplexTokenMetadataScenarioMode::NetworkSimulation
|
||
}));
|
||
```
|
||
|
||
Cet inventaire prépare les tests et campagnes Devnet simulation-first. Il ne constitue pas à lui seul une validation réseau réussie.
|