76 lines
8.9 KiB
Markdown
76 lines
8.9 KiB
Markdown
<!-- file: ks-pipeline-demo-scenarios/README.md -->
|
||
<!-- version: 32 -->
|
||
|
||
# ks-pipeline-demo-scenarios
|
||
|
||
`ks-pipeline-demo-scenarios` fournit des scénarios synthétiques et des campagnes Devnet/Testnet automatisables au-dessus de `ks-pipeline`.
|
||
|
||
La crate ouvre désormais le stockage de ses profils via la façade backend-agnostique `ks_store::Store`. Elle ne construit ni `PostgresStore`, ni pool SQLx ; les paramètres du moteur restent interprétés par `ks-store`.
|
||
|
||
La crate contient :
|
||
|
||
- la bibliothèque Rust `ks_pipeline_demo_scenarios` ;
|
||
- le binaire ciblé `ks-pipeline-demo-scenarios-cli` ;
|
||
- les adaptateurs de sélection wallet qui respectent `wallet_alias` sans stocker de password dans la configuration.
|
||
|
||
## Responsabilités
|
||
|
||
- préparer les profils, comptes et fixtures nécessaires aux campagnes de test ;
|
||
- exécuter des scénarios synthétiques déterministes ;
|
||
- exécuter des campagnes réseau explicites avec simulation ou soumission contrôlée ;
|
||
- produire des résultats structurés et des preuves vérifiables ;
|
||
- posséder les fixtures, séquences et qualifications réseau réutilisables appelées par les tests, CLI ou démonstrations UI ;
|
||
- conserver la séparation entre preuve synthétique, simulation RPC, soumission confirmée et postcondition stateful.
|
||
|
||
La crate couvre les scénarios Solana Core et SPL historiques, les inventaires synthétiques et Devnet-cibles Metaplex pour NFT, SFT, token fongible, collection et pNFT, ainsi que le runner générique des opérations Metaplex courantes et deux parcours Solana Program Metadata couvrant les neuf opérations stables. Une famille déclarée dans l’inventaire ne vaut pas fixture spécialisée ni preuve réseau ; les validations restent qualifiées séparément.
|
||
|
||
Le réaudit Metaplex de `0.4.8-pre.013` ferme les 20 opérations courantes avec **15 `confirmed`, 5 `unavailable` et 0 `not_run`**. `Create` et `Mint` sont confirmés sur les cinq chemins NFT, SFT, fungible, collection et pNFT ; `Verify`/`Unverify`, `Print`/`Burn`, le lifecycle pNFT `Delegate/Revoke/Lock/Unlock/Transfer`, Token Owned Escrow `CreateEscrowAccount/TransferOutOfEscrow/CloseEscrowAccount` et `Update` disposent également de preuves Devnet complètes. `Use`, `Resize`, `Migrate`, `Collect` et `CloseAccounts` restent explicitement `unavailable` pour des causes distinctes documentées par leurs probes runtime. Toute soumission Metaplex confirmée passe par l’hydratation canonique de sa signature, l’extraction Core, le replay avec les matérialiseurs du domaine et une seconde passe d’idempotence. La fixture `Create` prépare en outre le mint SPL classique et l’ATA canonique de l’opérateur dans une même transaction, vérifie les deux comptes après confirmation et laisse volontairement la supply à zéro. Elle fournit ensuite un intent `Mint` typé par famille ; pour pNFT, elle dérive le token-record PDA attendu sans le créer prématurément. La campagne collection parent-membre qualifiée réutilise ces fixtures et valide la relation `verified false -> true -> false` ainsi que la taille de collection `0 -> 1 -> 0` sans utiliser `SetCollectionSize`.
|
||
Depuis `pre.013-delta-fix-010`, cette fixture est **fresh-only** : elle crée un nouveau keypair persistant sans rechargement implicite, refuse toute adresse déjà présente on-chain, puis borne les relectures du mint et de son ATA au slot confirmé de la préparation native. Une campagne ne peut donc plus reprendre silencieusement un mint issu d’une exécution antérieure.
|
||
Depuis `pre.013-delta-fix-011`, la campagne distingue aussi le contrat d’autorité SPL avant et après `Create` : NFT, collection et pNFT attendent le PDA Master Edition comme mint/freeze authority après création, alors que SFT et fungible conservent l’autorité opérateur.
|
||
Depuis `pre.013-delta-fix-016`, la postcondition du compte token distingue aussi pNFT : l’ATA est `Initialized` avant `Mint`, puis doit être `Frozen` après `Mint`; les quatre autres familles restent `Initialized`. Le Token Record pNFT est validé séparément comme état programmable Metaplex.
|
||
Depuis `pre.013-delta-fix-020`, la campagne `Print -> Burn` conserve uniquement un keypair frais pour `edition_mint` et exige que le mint **et** son ATA canonique soient absents avant `Print`. Le programme Metaplex courant crée alors le mint, crée l’ATA et frappe l’unique token imprimé. Précréer un ATA vide est interdit : le chemin `Print` d’un compte token déjà existant exige exactement un token. Le runner vérifie aussi que l’ATA du master contient exactement un token avant la simulation afin de distinguer une précondition master invalide d’un défaut de l’édition fraîche.
|
||
Depuis `pre.013-delta-fix-030`, le probe `Use` est classé : Devnet rejette l’instruction courante de discriminant 51 avec `InvalidInstructionData`. Le scénario conserve ce refus comme preuve `unavailable`, ne soumet aucune transaction et peut retourner proprement une simulation négative en mode probe sans affaiblir la barrière de soumission.
|
||
Depuis `pre.013-delta-fix-021`, les références de signataires supplémentaires conservent explicitement `Sync` et la lecture stateful accepte l'`Edition` compacte réellement allouée. La validation suivante montre toutefois que la conversion locale en `Vec<&dyn Signer>` rend encore le futur desktop non-`Send`; `pre.013-delta-fix-022` confine donc cette conversion à la fonction synchrone qui signe immédiatement la transaction. Le rerun Devnet de `fix-022` termine désormais `Print -> Burn` avec les deux signatures, les slots, les postconditions stateful, l’hydratation canonique, l’extraction Core, le replay, les matérialisations et l’idempotence. `Print` et `Burn` sont donc qualifiés sur la famille NFT. `fix-023` prépare ensuite une campagne pNFT spécialisée `Delegate(Staking) -> Lock -> Unlock -> Revoke(Staking) -> Delegate(Transfer) -> Transfer`, avec deux wallets temporaires frais pour le delegate et le propriétaire destination et des contrôles exacts du Token Record et des ATA gelées.
|
||
|
||
Pour Token-2022 Token Metadata, `0.4.8-pre.012` ajoute une campagne Devnet dédiée aux cinq instructions de `spl-token-metadata-interface`. Elle prépare nativement un mint frais avec `MetadataPointer`, puis enchaîne `Initialize`, `UpdateField`, `Emit`, `RemoveKey` et `UpdateAuthority` avec simulation-first, soumission explicitement autorisée, confirmation, replay, matérialisation lorsque applicable et postcondition stateful. La campagne de validation de `pre.012` a confirmé les cinq scénarios sur Devnet ; la matrice et le rapport conservent les signatures, slots et preuves observées.
|
||
|
||
## Organisation interne
|
||
|
||
Les modules internes suivent désormais les domaines fonctionnels plutôt que l'ordre historique des ajouts :
|
||
|
||
```text
|
||
src/
|
||
├── solana.rs
|
||
├── metadata/
|
||
│ ├── solana_program/
|
||
│ └── metaplex_token_metadata/
|
||
└── spl/
|
||
├── associated_token_account.rs
|
||
├── memo.rs
|
||
├── token/
|
||
└── token_2022/
|
||
└── metadata/
|
||
```
|
||
|
||
Les exports publics restent fournis depuis `lib.rs`. Le rangement interne ne doit donc pas imposer aux consommateurs des chemins de modules privés ni modifier les noms des contrats publics existants.
|
||
|
||
## Binaire CLI
|
||
|
||
Le CLI a été introduit pour les préparations de fixtures qui nécessitent une commande autonome, notamment Token-2022. Il n’est pas l’interface générale obligatoire de tous les scénarios. Une commande Metaplex ne doit être ajoutée que si une préparation de fixture ne peut pas être réalisée proprement par les tests ou APIs existantes.
|
||
|
||
## Relations avec le workspace
|
||
|
||
La crate dépend du pipeline généraliste. `ks-pipeline` ne dépend jamais d’elle. Le desktop réutilise déjà ses campagnes ; `0.5.4` doit déplacer ici les dispatchs et critères de campagne encore réutilisables afin de ne laisser localement que l'adaptation UI/Tauri, les presets strictement visuels et la présentation opérateur.
|
||
|
||
## Documentation
|
||
|
||
- [Guide d’utilisation](USAGE.md)
|
||
- [Travaux restant à réaliser](TODO.md)
|
||
- [Historique des changements](CHANGELOG.md)
|
||
- [Architecture du pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
|
||
## Qualification Metaplex `0.4.8-pre.013`
|
||
|
||
La matrice Devnet courante est désormais fermée avec **15 opérations `confirmed`**, **5 opérations `unavailable` (`Use`, `Resize`, `Migrate`, `Collect`, `CloseAccounts`)** et **0 opération `not_run`**. Les parcours qualifiés incluent `Create/Mint`, collection `Verify/Unverify`, `Print/Burn`, le lifecycle pNFT, les trois opérations Token Owned Escrow et `Update`.
|
||
|
||
La campagne finale `maintenance_campaign` confirme `Update` sur un NFT frais avec `primary_sale_happened false -> true`. Elle conserve `Resize`, `Migrate`, `Collect` et `CloseAccounts` comme probes simulation-only : `Resize` expose `AccountAlreadyResized(201)` sur les comptes au layout courant, `Migrate` est retiré avec `Removed(75)`, et `Collect`/`CloseAccounts` exigent des autorités Metaplex fixes que le scénario contrôlé n’essaie jamais d’imiter.
|