khadhroony-bot3/docs/DEVNET_EXECUTION_GUIDE.md

Guide d’exécution Devnet

1. Objet et ordre de validation

Ce guide décrit la campagne Devnet de kb-app-demo-desktop et kb-pipeline-demo-scenarios. Après une modification de nomenclature persistée ou une recréation de la base Devnet, reprendre les scénarios depuis le début dans l’ordre suivant :

1. préparation commune et base PostgreSQL propre ;
2. Solana Core — System Transfer ;
3. SPL Memo v4 ;
4. SPL Associated Token Account — mint Token classique ;
5. SPL Associated Token Account — mint Token-2022 ;
6. SPL Token classique ;
7. Token-2022 ;
8. registre ElGamal.

Les commandes réutilisables sont centralisées en section 4. Chaque scénario référence leur identifiant Cxx au lieu de les recopier.

2. Préconditions

• .env contient KB_POSTGRES_DEVNET_URL et les secrets de transport requis ;
• KB_POSTGRES_DEVNET_URL, KB_POSTGRES_MAINNET_URL et KB_POSTGRES_TEST_URL désignent des bases distinctes ;
• le profil sélectionné est Devnet et autorise explicitement l’envoi Devnet ;
• l’envoi Mainnet reste désactivé ;
• les plafonds de frais, de dépense et de rent sont contrôlés ;
• la politique reste simulation-first ;
• le wallet temporaire persistant n’est jamais copié dans les logs ou les preuves ;
• le financement est réalisé par un faucet Web Devnet, pas par solana airdrop.

Lorsque database.postgres.auto_initialize_schema vaut true, l’ouverture d’une fenêtre Devnet crée les tables manquantes. Lorsqu’il vaut false, le schéma doit être préparé avant l’ouverture.

3. Organisation des terminaux

La campagne utilise deux terminaux distincts. Les variables d’environnement exportées dans un terminal ne sont pas visibles dans l’autre.

Terminal A — application Tauri

Ce terminal reste occupé par cargo tauri dev pendant toute la campagne. Il affiche les logs Rust, Tauri, Vite, PostgreSQL et RPC.

Terminal B — contrôles CLI et preuves

Ce terminal reste disponible pour les commandes Solana, PostgreSQL, balances, confirmations et captures avec tee.

Les commandes C01 à C05 doivent être exécutées dans le terminal B. Le terminal A doit exécuter T01, puis rester ouvert. Avant chaque scénario, le terminal B doit définir KB_DEVNET_SCENARIO avant d’appeler C06.

4. Commandes communes

Les commandes suivantes sont exécutées depuis la racine du workspace dans un terminal interactif. Ne pas utiliser set -e ou set -u dans ce terminal : une commande de contrôle non satisfaite fermerait la session. set -o pipefail est suffisant pour fiabiliser les pipelines vers tee.

T01 — Démarrer l’application dans le terminal A

Premier lancement du workspace ou après modification des dépendances frontend :

cd ~/Projects/khadhroony-bot3; command -v cargo; command -v npm; command -v cargo-tauri || cargo install tauri-cli --locked; test -d kb-app-demo-desktop/node_modules || npm --prefix kb-app-demo-desktop i; cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

La commande npm --prefix kb-app-demo-desktop i -D ... installe ou réaligne explicitement les dépendances de développement déclarées par l’application. npm --prefix kb-app-demo-desktop i reste nécessaire pour les dépendances runtime.

Installation ou réalignement conditionnel des dépendances de développement, uniquement après modification de package.json, suppression de node_modules ou erreur de dépendance frontend :

npm --prefix kb-app-demo-desktop i -D @tauri-apps/cli @types/bootstrap @types/markdown-it @types/node sass-embedded typescript vite

npm run dev est lancé automatiquement par Tauri via beforeDevCommand; il exécute le script dev du package.json, actuellement Vite. Il ne faut pas le lancer dans un troisième terminal.

La validation frontend de cette campagne est effectuée par cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json, qui lance Vite. Ne pas ajouter npm --prefix kb-app-demo-desktop run build à la procédure.

Lancements suivants, lorsque cargo-tauri et node_modules sont déjà présents :

cd ~/Projects/khadhroony-bot3; cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

Attendre avant tout scénario :

• le démarrage de Vite ;
• le lancement du binaire kb-app-demo-desktop ;
• l’ouverture de la fenêtre ;
• le message PostgreSQL indiquant que les 13 tables sont prêtes ;
• la résolution correcte du profil local_devnet.

Ne pas exécuter les commandes C06 ou C07 dans ce terminal.

T02 — Arrêter et redémarrer Tauri conditionnellement

Redémarrer Tauri après :

• recréation du schéma PostgreSQL si l’application était déjà ouverte ;
• modification de .env, de la configuration ou du profil actif ;
• recompilation liée à une correction de code ;
• perte de connexion entre Vite et la fenêtre.

Arrêter avec Ctrl+C, puis relancer T01.

C01 — Initialiser l’environnement de validation

cd ~/Projects/khadhroony-bot3 && set -o pipefail && export KB_DEVNET_PROFILE="local_devnet" && export KB_DEVNET_RPC_URL="https://api.devnet.solana.com" && export KB_DEVNET_VALIDATION_DIR="/tmp/devnet-validation/pre.062-clean" && export KB_DEVNET_WALLET="$PWD/wallets/temporary/local_devnet/local-devnet-operator.json" && mkdir -p "$KB_DEVNET_VALIDATION_DIR" && printf 'Profil     : %s\n' "$KB_DEVNET_PROFILE" && printf 'RPC Devnet : %s\n' "$KB_DEVNET_RPC_URL" && printf 'Preuves    : %s\n' "$KB_DEVNET_VALIDATION_DIR" && printf 'Wallet     : %s\n' "$KB_DEVNET_WALLET"; 

C02 — Capturer les versions CLI

command -v solana && command -v solana-keygen && command -v spl-token && { date --iso-8601=seconds; solana --version; solana-keygen --version; spl-token --version; } | tee "$KB_DEVNET_VALIDATION_DIR/00-cli-versions.txt";

La première campagne pre.062 utilisait solana-cli 4.0.2, solana-keygen 4.0.2 et spl-token-cli 5.5.0. Une nouvelle campagne doit capturer ses propres versions.

C03 — Vérifier l’identité du réseau

solana config set --url "$KB_DEVNET_RPC_URL" && { date --iso-8601=seconds; solana config get; solana cluster-version --url "$KB_DEVNET_RPC_URL"; solana genesis-hash --url "$KB_DEVNET_RPC_URL";     solana epoch-info --url "$KB_DEVNET_RPC_URL"; } | tee "$KB_DEVNET_VALIDATION_DIR/01-devnet-network.txt"; 

Le genesis hash Devnet attendu est :

EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG

C04 — Vérifier le wallet opérateur

test -f "$KB_DEVNET_WALLET" && chmod 600 "$KB_DEVNET_WALLET" && export KB_DEVNET_WALLET_PUBKEY="$(solana-keygen pubkey "$KB_DEVNET_WALLET")" && { date --iso-8601=seconds; printf 'wallet_path=%s\n' "$KB_DEVNET_WALLET"; printf 'wallet_pubkey=%s\n' "$KB_DEVNET_WALLET_PUBKEY"; solana balance  "$KB_DEVNET_WALLET_PUBKEY" --url "$KB_DEVNET_RPC_URL" --commitment confirmed; } | tee "$KB_DEVNET_VALIDATION_DIR/02-wallet.txt"

C05 — Recréer la base Devnet

Cette commande est destructive. Elle ne doit viser que KB_POSTGRES_DEVNET_URL. Elle supprime toutes les données et tous les objets du schéma public, puis laisse l’application recréer son schéma lors de l’ouverture d’une fenêtre Devnet.

test -n "$KB_POSTGRES_DEVNET_URL" && printf '%s\n' "$KB_POSTGRES_DEVNET_URL" && export KB_CONFIRM_DEVNET_DATABASE_RESET="YES_RESET_SOLANA_DEVNET" && test "$KB_CONFIRM_DEVNET_DATABASE_RESET" = "YES_RESET_SOLANA_DEVNET" && psql "$KB_POSTGRES_DEVNET_URL" -v ON_ERROR_STOP=1 -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'

Après ouverture d’une fenêtre Devnet, contrôler les tables :

psql "$KB_POSTGRES_DEVNET_URL" -v ON_ERROR_STOP=1 -c "SELECT schemaname, tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename;" | tee "$KB_DEVNET_VALIDATION_DIR/03-devnet-schema.txt"

C06 — Capturer le solde avant scénario

Définir KB_DEVNET_SCENARIO avant l’appel.

test -n "${KB_DEVNET_SCENARIO:-}" && test -n "${KB_DEVNET_WALLET_PUBKEY:-}" && test -n "${KB_DEVNET_RPC_URL:-}" && test -n "${KB_DEVNET_VALIDATION_DIR:-}" && { date --iso-8601=seconds; printf 'scenario=%s\nwallet=%s\n' "$KB_DEVNET_SCENARIO" "$KB_DEVNET_WALLET_PUBKEY"; solana balance "$KB_DEVNET_WALLET_PUBKEY" --url "$KB_DEVNET_RPC_URL" --commitment confirmed; } | tee "$KB_DEVNET_VALIDATION_DIR/${KB_DEVNET_SCENARIO}-wallet-before.txt"

C07 — Confirmer une signature et capturer le solde après scénario

Définir KB_DEVNET_SCENARIO et KB_DEVNET_SIGNATURE avant l’appel.

test -n "${KB_DEVNET_SCENARIO:-}" && test -n "${KB_DEVNET_SIGNATURE:-}" && test -n "${KB_DEVNET_WALLET_PUBKEY:-}" && test -n "${KB_DEVNET_RPC_URL:-}" && test -n "${KB_DEVNET_VALIDATION_DIR:-}" && { date --iso-8601=seconds; printf 'scenario=%s\nsignature=%s\n' "$KB_DEVNET_SCENARIO" "$KB_DEVNET_SIGNATURE"; solana confirm "$KB_DEVNET_SIGNATURE" --url "$KB_DEVNET_RPC_URL" --commitment finalized --verbose; solana balance "$KB_DEVNET_WALLET_PUBKEY" --url "$KB_DEVNET_RPC_URL" --commitment confirmed; } | tee "$KB_DEVNET_VALIDATION_DIR/${KB_DEVNET_SCENARIO}-confirmation.txt"

C08 — Préparer un mint SPL Token classique pour ATA

Cette commande crée uniquement un mint de test persistant. Elle ne crée aucun compte token associé : l’ATA doit être dérivé, simulé et créé par kb-app-demo-desktop.

L’option --silent est obligatoire afin que la phrase de récupération ne soit pas affichée dans le terminal, les captures ou l’historique de validation.

La commande est idempotente au niveau du guide : si le compte du mint existe déjà sur Devnet, elle le réutilise.

export KB_SPL_TOKEN_PROGRAM_ID="TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" && export KB_DEVNET_CLASSIC_MINT_KEYPAIR="$PWD/wallets/temporary/local_devnet/mints/ata-classic-mint.json" && mkdir -p "$(dirname "$KB_DEVNET_CLASSIC_MINT_KEYPAIR")" && { test -f "$KB_DEVNET_CLASSIC_MINT_KEYPAIR" || solana-keygen new --no-bip39-passphrase --force --silent --outfile "$KB_DEVNET_CLASSIC_MINT_KEYPAIR"; }

export KB_DEVNET_CLASSIC_MINT="$(solana-keygen pubkey "$KB_DEVNET_CLASSIC_MINT_KEYPAIR")" && { solana account "$KB_DEVNET_CLASSIC_MINT" --url "$KB_DEVNET_RPC_URL" --output json >/dev/null 2>&1 || spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" create-token "$KB_DEVNET_CLASSIC_MINT_KEYPAIR" --decimals 9; } && printf 'classic_mint=%s\n' "$KB_DEVNET_CLASSIC_MINT" | tee "$KB_DEVNET_VALIDATION_DIR/30a-spl-ata-classic-mint.txt"

C09 — Préparer un mint Token-2022 pour ATA

Cette commande crée uniquement un mint Token-2022 de test persistant, sans extension supplémentaire. Elle ne crée aucun ATA.

export KB_SPL_TOKEN_2022_PROGRAM_ID="TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" && export KB_DEVNET_TOKEN_2022_MINT_KEYPAIR="$PWD/wallets/temporary/local_devnet/mints/ata-token-2022-mint.json" && mkdir -p "$(dirname "$KB_DEVNET_TOKEN_2022_MINT_KEYPAIR")" && { test -f "$KB_DEVNET_TOKEN_2022_MINT_KEYPAIR" || solana-keygen new --no-bip39-passphrase --force --silent --outfile "$KB_DEVNET_TOKEN_2022_MINT_KEYPAIR"; }

export KB_DEVNET_TOKEN_2022_MINT="$(solana-keygen pubkey "$KB_DEVNET_TOKEN_2022_MINT_KEYPAIR")" && { solana account "$KB_DEVNET_TOKEN_2022_MINT" --url "$KB_DEVNET_RPC_URL" --output json >/dev/null 2>&1 || spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_2022_PROGRAM_ID" create-token "$KB_DEVNET_TOKEN_2022_MINT_KEYPAIR" --decimals 9; } && printf 'token_2022_mint=%s\n' "$KB_DEVNET_TOKEN_2022_MINT" | tee "$KB_DEVNET_VALIDATION_DIR/30b-spl-ata-token-2022-mint.txt"

C10 — Préparer les comptes du scénario SPL Token classique

La fenêtre actuelle Décodeur spl_token — TransferChecked valide uniquement TransferChecked. Elle exige :

• un mint SPL Token classique ;
• un compte source appartenant au wallet opérateur et possédant un solde token suffisant ;
• un compte destination distinct pour le même mint ;
• l’autorité simple du compte source, qui doit être le wallet opérateur.

Cette préparation réutilise le mint créé par C08 et l’ATA classique créée pendant S03A.

1. Dériver l’ATA source avec la syntaxe exigée par spl-token-cli 5.5.0 :

export KB_DEVNET_CLASSIC_SOURCE_ATA="$(spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" address --verbose --token "$KB_DEVNET_CLASSIC_MINT" --owner "$KB_DEVNET_WALLET_PUBKEY" | awk -F': ' '/Associated token address/ {print $2}')" && test -n "$KB_DEVNET_CLASSIC_SOURCE_ATA" && printf 'source_ata=%s\n' "$KB_DEVNET_CLASSIC_SOURCE_ATA"

2. Préparer un owner destinataire persistant :

export KB_DEVNET_CLASSIC_RECIPIENT_KEYPAIR="$PWD/wallets/temporary/local_devnet/recipients/spl-token-transfer-recipient.json" && mkdir -p "$(dirname "$KB_DEVNET_CLASSIC_RECIPIENT_KEYPAIR")" && { test -f "$KB_DEVNET_CLASSIC_RECIPIENT_KEYPAIR" || solana-keygen new --no-bip39-passphrase --force --silent --outfile "$KB_DEVNET_CLASSIC_RECIPIENT_KEYPAIR"; } && export KB_DEVNET_CLASSIC_RECIPIENT="$(solana-keygen pubkey "$KB_DEVNET_CLASSIC_RECIPIENT_KEYPAIR")"

3. Dériver puis créer l’ATA destination si elle n’existe pas :

export KB_DEVNET_CLASSIC_DESTINATION_ATA="$(spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" address --verbose --token "$KB_DEVNET_CLASSIC_MINT" --owner "$KB_DEVNET_CLASSIC_RECIPIENT" | awk -F': ' '/Associated token address/ {print $2}')" && test -n "$KB_DEVNET_CLASSIC_DESTINATION_ATA" && { solana account "$KB_DEVNET_CLASSIC_DESTINATION_ATA" --url "$KB_DEVNET_RPC_URL" --output json >/dev/null 2>&1 || spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" create-account "$KB_DEVNET_CLASSIC_MINT" --owner "$KB_DEVNET_CLASSIC_RECIPIENT" --fee-payer "$KB_DEVNET_WALLET"; }

4. Créditer le compte source. Cette commande ajoute 10 tokens à chaque exécution ; ne la relancer que si le solde source est insuffisant :

spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" mint "$KB_DEVNET_CLASSIC_MINT" 10 "$KB_DEVNET_CLASSIC_SOURCE_ATA" --owner "$KB_DEVNET_WALLET" --fee-payer "$KB_DEVNET_WALLET"

5. Afficher les comptes par leur adresse. Avec cette version du CLI, utiliser display plutôt que account-info <adresse>, car l’argument positionnel de account-info est interprété comme un mint :

spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_SOURCE_ATA" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_DESTINATION_ATA"

6. Capturer la fixture :

{ printf 'mint=%s\n' "$KB_DEVNET_CLASSIC_MINT"; printf 'source=%s\n' "$KB_DEVNET_CLASSIC_SOURCE_ATA"; printf 'destination=%s\n' "$KB_DEVNET_CLASSIC_DESTINATION_ATA"; printf 'authority=%s\n' "$KB_DEVNET_WALLET_PUBKEY"; printf 'amount_raw=1000000000\n'; printf 'decimals=9\n'; } | tee "$KB_DEVNET_VALIDATION_DIR/40-spl-token-fixture.txt"

La création du compte destination par CLI est acceptable ici : S03A et S03B ont déjà validé l’executor ATA. S04 doit isoler et valider l’executor SPL Token TransferChecked.

C11 — Créer ou réutiliser la fixture Token-2022

Le workspace fournit une commande idempotente qui prépare les comptes publics requis par les huit scénarios Token-2022 :

cargo run -p kb-pipeline-demo-scenarios --bin kb-pipeline-demo-scenarios-cli -- prepare-token-2022-fixture --rpc-url "$KB_DEVNET_RPC_URL" --wallet "$KB_DEVNET_WALLET" --wallet-dir "$PWD/wallets/temporary/local_devnet" --decimals 9 | tee "$KB_DEVNET_VALIDATION_DIR/50-spl-token-2022-fixture-preparation.json"

Lorsque --rpc-url et --wallet sont omis, la commande utilise respectivement KB_DEVNET_RPC_URL et KB_DEVNET_WALLET. Lorsque --wallet-dir est omis, elle utilise le répertoire parent du wallet.

La commande :

• crée silencieusement les keypairs manquants avec des permissions 0600 ;
• crée ou réutilise un mint Token-2022 avec mint authority et freeze authority égales au wallet opérateur ;
• crée ou réutilise trois comptes Token-2022 distincts : source, destination et compte vide réservé à CloseAccount ;
• crée ou réutilise une pubkey delegate indépendante ;
• n'affiche jamais les phrases de récupération ni les octets privés ;
• écrit atomiquement la fixture publique attendue par l'application.

Les keypairs et la fixture sont conservés sous :

wallets/temporary/local_devnet/spl_token_2022_validation/

La fixture publique est :

wallets/temporary/local_devnet/spl_token_2022_validation/fixture.env

Elle définit :

TOKEN_2022_PROGRAM
TOKEN_2022_MINT
TOKEN_2022_SOURCE
TOKEN_2022_DESTINATION
TOKEN_2022_CLOSE_ACCOUNT
TOKEN_2022_DELEGATE
TOKEN_2022_AUTHORITY
TOKEN_2022_FREEZE_AUTHORITY
TOKEN_2022_DECIMALS
TOKEN_2022_MINT_AMOUNT_RAW
TOKEN_2022_TRANSFER_AMOUNT_RAW
TOKEN_2022_APPROVE_AMOUNT_RAW
TOKEN_2022_BURN_AMOUNT_RAW
KB_DEVNET_WALLET_ADDRESS

Vérifier puis charger uniquement les valeurs publiques dans le terminal B :

export KB_DEVNET_TOKEN_2022_FIXTURE="$PWD/wallets/temporary/local_devnet/spl_token_2022_validation/fixture.env" && test -f "$KB_DEVNET_TOKEN_2022_FIXTURE" && sed -n '/^export [A-Z0-9_]*=/p' "$KB_DEVNET_TOKEN_2022_FIXTURE" | sed 's/=.*$/=<défini>/' | tee "$KB_DEVNET_VALIDATION_DIR/50-spl-token-2022-fixture-keys.txt" && source "$KB_DEVNET_TOKEN_2022_FIXTURE"

Afficher le mint et les trois comptes Token-2022 avec le Program ID explicite :

spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$TOKEN_2022_PROGRAM" display "$TOKEN_2022_MINT" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$TOKEN_2022_PROGRAM" display "$TOKEN_2022_SOURCE" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$TOKEN_2022_PROGRAM" display "$TOKEN_2022_DESTINATION" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$TOKEN_2022_PROGRAM" display "$TOKEN_2022_CLOSE_ACCOUNT"

Le compte TOKEN_2022_CLOSE_ACCOUNT doit rester vide jusqu'au scénario CloseAccount. Ne pas utiliser account-info <adresse> dans cette campagne : avec spl-token-cli 5.5.0, cette forme peut interpréter l'adresse comme un mint.

C12 — Preuves applicatives communes

Pour chaque scénario, conserver depuis l’application :

• profil et cluster résolus ;
• paramètres saisis ;
• operation_code, program_id et plan préparé ;
• signers requis et fee payer ;
• plafond de frais et plafond de dépense ;
• résultat et logs de simulation ;
• signature d’envoi ;
• résultat de confirmation ;
• insertion canonique ;
• extraction Core ;
• Decode replay ciblé ;
• projections matérialisées ;
• second replay démontrant l’idempotence ;
• diagnostics ou écarts observés.

Un scénario n’est validé que si le replay ne produit ni échec fonctionnel ni erreur de traitement et si les projections attendues sont présentes et idempotentes.

5. Préparation initiale de la campagne

1. Dans le terminal B, exécuter C01, C02, C03 et C04.
2. Dans le terminal B, exécuter C05 pour repartir d’une base propre.
3. Dans le terminal A, exécuter T01.
4. Attendre la création des 13 tables et la disponibilité de la fenêtre.
5. Dans la fenêtre Configuration, vérifier que local_devnet utilise la base Devnet.
6. Dans le terminal B, exécuter le contrôle de tables de C05.
7. Financer la pubkey par un faucet Web Devnet si le solde est insuffisant.
8. Réexécuter C04 dans le terminal B après financement.
9. Avant chaque scénario, définir KB_DEVNET_SCENARIO dans le terminal B, puis exécuter C06.

6. Scénario S01 — Solana Core System Transfer

Objectif

Valider la chaîne complète : préparation, simulation, envoi, confirmation, stockage canonique, extraction Core et replay.

Procédure

1. Définir puis exécuter C06 :

export KB_DEVNET_SCENARIO="10-system-transfer"

2. Dans la fenêtre Exécution Devnet — Solana Core :
   • générer un nouveau destinataire ;
   • conserver sa pubkey ;
   • saisir un montant borné ;
   • vérifier solana.core.system.transfer ;
   • simuler ;
   • contrôler frais, spend et signer ;
   • confirmer explicitement l’envoi.
3. Définir la signature et exécuter C07.
4. Capturer séparément le solde du destinataire :

export KB_DEVNET_RECIPIENT="COLLER_LE_DESTINATAIRE"

solana balance \
  "$KB_DEVNET_RECIPIENT" \
  --url "$KB_DEVNET_RPC_URL" \
  --commitment confirmed \
  | tee "$KB_DEVNET_VALIDATION_DIR/${KB_DEVNET_SCENARIO}-recipient-after.txt"

5. Exécuter les contrôles applicatifs C08 sur la signature.

Contrat d’erreur de l’interface

Pour un nouveau destinataire inexistant, le montant doit être au moins égal au minimum de rent exemption indiqué par l’application. Avec la valeur observée de 890880 lamports, une demande de 10000 lamports doit être refusée avant simulation.

Ce refus est attendu fonctionnellement, mais l’interface doit afficher l’erreur dans les panneaux de résultat :

• Résumé doit passer de idle à error ;
• Plan exact doit afficher l’échec de préparation ou rester explicitement indisponible avec sa cause ;
• Simulation exacte doit indiquer qu’aucune simulation n’a été lancée à cause du préflight ;
• Confirmation et replay doit rester non exécuté, avec une raison explicite.

Un message uniquement présent dans le journal est insuffisant. Tant que les panneaux restent à idle, ne pas considérer le scénario comme validé et ne pas utiliser « Signer et envoyer ».

Résultat historique de référence

La première campagne a validé la signature 3k8BaQJKwSn8r2pYdvfp1Q3VYrPEcDEuUunMFn7NDq1ZqsvryjoGsxeBBNJjc1123RgDCoykp7w9VrtZgsDw4ph3, au slot 479589279, avec 890880 lamports transférés, 5000 lamports de frais et 150 compute units. Cette preuve réseau reste historique ; les lignes PostgreSQL doivent être recréées dans la nouvelle base.

7. Scénario S02 — SPL Memo v4

Objectif

Valider l’opération exécutable spl.memo.add_memo, l’événement observé spl.memo.v4.add_memo et la projection d’annotation.

Procédure

1. Définir puis exécuter C06 :

export KB_DEVNET_SCENARIO="20-spl-memo-v4"

2. Dans la fenêtre Exécution Devnet — SPL :
   • sélectionner Memo v4 ;
   • saisir un texte UTF-8 borné ;
   • vérifier le Program ID Memo4c2pN8afCj432Lb7RMVKi9PbQnnW7ewFFaV3oAH ;
   • vérifier le wallet signer ;
   • simuler puis confirmer l’envoi.
3. Définir KB_DEVNET_SIGNATURE et exécuter C07.
4. Exécuter C08 et vérifier précisément :
   • processor_name = materializer.transaction.annotations ;
   • surface_code = spl.memo.v4 ;
   • event_code = spl.memo.v4.add_memo ;
   • une seule annotation matérialisée ;
   • second replay ignoré/idempotent.

Résultat historique de référence

La première campagne a validé la signature 3uYNASrHibwpnsFWwV2JHAxtnci96RhFYf6zbUSfGMbQQV37gfHizstk7atiHYYQCBm4jhmC6cT3G3CCPCV38Lpx, au slot 479596483, avec 5000 lamports de frais et 513 compute units. Après recréation de la base, cette signature peut être réingérée pour tester le replay, mais la campagne propre doit également produire une nouvelle preuve complète.

8. Scénario S03 — SPL Associated Token Account

Le scénario ATA est divisé en deux validations indépendantes. Une ATA dépend du triplet exact :

owner + token_program + mint

Un même owner et deux mints appartenant à des Token Programs différents doivent donc produire deux dérivations et deux comptes distincts.

S03A — ATA avec SPL Token classique

Objectif

Valider la dérivation et la création idempotente d’une ATA dont le mint appartient au programme SPL Token classique.

Préparation dans le terminal B

1. Exécuter C08.
2. Définir le scénario et capturer le solde :

export KB_DEVNET_SCENARIO="30a-spl-ata-classic"

3. Exécuter C06.
4. Copier la valeur affichée par :

printf '%s\n' "$KB_DEVNET_CLASSIC_MINT"

Procédure dans l’application

1. Ouvrir la fenêtre SPL Associated Token Account.
2. Utiliser :
   • owner : wallet opérateur KB_DEVNET_WALLET_PUBKEY ;
   • mint : KB_DEVNET_CLASSIC_MINT ;
   • token program : SPL Token classique ;
   • payer : wallet opérateur.
3. Dériver l’ATA et conserver son adresse.
4. Vérifier que le Program ID sélectionné est TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA.
5. Simuler spl.associated_token_account.create_idempotent.
6. Contrôler le rent ceiling, le payer, l’owner, le mint, le token program et l’adresse ATA dérivée.
7. Confirmer explicitement l’envoi.
8. Définir KB_DEVNET_SIGNATURE, puis exécuter C07.
9. Exécuter C12.
10. Réexécuter la création idempotente et vérifier qu’elle ne produit ni fausse création ni duplication des projections.

S03B — ATA avec Token-2022

Objectif

Valider la dérivation et la création idempotente d’une ATA dont le mint appartient au programme Token-2022, puis démontrer qu’elle est distincte de l’ATA classique.

Préparation dans le terminal B

1. Exécuter C09.
2. Définir le scénario et capturer le solde :

export KB_DEVNET_SCENARIO="30b-spl-ata-token-2022"

3. Exécuter C06.
4. Copier la valeur affichée par :

printf '%s\n' "$KB_DEVNET_TOKEN_2022_MINT"

Procédure dans l’application

1. Utiliser :
   • owner : le même wallet opérateur ;
   • mint : KB_DEVNET_TOKEN_2022_MINT ;
   • token program : Token-2022 ;
   • payer : wallet opérateur.
2. Dériver l’ATA et conserver son adresse.
3. Vérifier que le Program ID sélectionné est TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb.
4. Vérifier que l’adresse dérivée diffère de l’ATA classique de S03A.
5. Simuler puis envoyer spl.associated_token_account.create_idempotent.
6. Définir KB_DEVNET_SIGNATURE, puis exécuter C07.
7. Exécuter C12.
8. Rejouer la création idempotente.
9. Vérifier séparément les faits parent ATA et les éventuels enfants CPI Token-2022, sans duplication.

Critères communs S03A/S03B

• le mint existe et son owner on-chain correspond au Token Program choisi ;
• l’adresse ATA est dérivée avec les graines dans l’ordre canonique owner, token_program, mint ;
• le compte créé a pour owner le Token Program attendu ;
• le premier envoi peut créer le compte ;
• le second envoi idempotent ne crée pas un second compte ;
• le replay et les projections restent idempotents ;
• aucune ATA classique n’est confondue avec une ATA Token-2022.

9. Scénario S04 — SPL Token classique

Portée réellement exposée

La fenêtre actuelle expose uniquement :

spl.token.transfer_checked

Elle ne permet pas encore d’enchaîner depuis l’interface InitializeMint, MintToChecked, Approve, Revoke, BurnChecked et CloseAccount. Ces opérations restent hors de ce scénario Devnet tant qu’elles ne sont pas exposées par la fenêtre.

Préparation dans le terminal B

1. Réutiliser le mint classique de C08 :

export KB_SPL_TOKEN_PROGRAM_ID="TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" && export KB_DEVNET_CLASSIC_MINT_KEYPAIR="$PWD/wallets/temporary/local_devnet/mints/ata-classic-mint.json" && export KB_DEVNET_CLASSIC_MINT="$(solana-keygen pubkey "$KB_DEVNET_CLASSIC_MINT_KEYPAIR")"

2. Définir le scénario :

export KB_DEVNET_SCENARIO="40-spl-token"

3. Exécuter C06.
4. Exécuter C10.
5. Vérifier les comptes token avant l’opération :

spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_SOURCE_ATA" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_DESTINATION_ATA"

Valeurs à saisir dans l’application

Dans Décodeur spl_token — TransferChecked :

Champ	Valeur
Compte source	$KB_DEVNET_CLASSIC_SOURCE_ATA
Mint	$KB_DEVNET_CLASSIC_MINT
Compte destination	$KB_DEVNET_CLASSIC_DESTINATION_ATA
Autorité simple	$KB_DEVNET_WALLET_PUBKEY
Montant brut exact	1000000000 pour 1 token avec 9 décimales
Decimals	9

Afficher les valeurs à copier :

printf 'source=%s\nmint=%s\ndestination=%s\nauthority=%s\namount_raw=1000000000\ndecimals=9\n' "$KB_DEVNET_CLASSIC_SOURCE_ATA" "$KB_DEVNET_CLASSIC_MINT" "$KB_DEVNET_CLASSIC_DESTINATION_ATA" "$KB_DEVNET_WALLET_PUBKEY"

Exécution

1. Cliquer Préflight et simuler.
2. Vérifier :
   • owner des deux comptes = SPL Token classique ;
   • mint identique sur les deux comptes ;
   • decimals = 9 ;
   • source suffisamment financée ;
   • autorité simple = wallet opérateur ;
   • montant brut conservé exactement.
3. Cocher la confirmation opérateur.
4. Cliquer Signer et envoyer Token.
5. Copier la signature dans :

export KB_DEVNET_SIGNATURE="SIGNATURE_SPL_TOKEN"

6. Exécuter C07, puis C12.
7. Vérifier les comptes après transfert :

spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_SOURCE_ATA" && spl-token --url "$KB_DEVNET_RPC_URL" --program-id "$KB_SPL_TOKEN_PROGRAM_ID" display "$KB_DEVNET_CLASSIC_DESTINATION_ATA"

Critères de validation

• simulation réussie ;
• transaction confirmée puis finalisée ;
• operation_code = spl.token.transfer_checked ;
• montant brut exact ;
• insertion canonique, extraction Core et replay réussis ;
• projection métier présente ;
• second replay idempotent ;
• aucun compte Token-2022 impliqué.

Le journal métier SPL Token peut rester à empty après une simulation seule. Il doit être actualisé après l’envoi confirmé, le replay et la matérialisation.

10. Scénario S05 — Token-2022

Préparation

1. Définir le scénario et exécuter C06 :

export KB_DEVNET_SCENARIO="50-spl-token-2022"

2. Exécuter C11 pour créer ou réutiliser la fixture.
3. Contrôler le mint, la source, la destination et le compte réservé à la fermeture avec les commandes display de C11.
4. Dans l’application, ouvrir Exécution spl_token_2022 — scénarios publics.
5. Cliquer Charger la fixture Token-2022.
6. Vérifier que le message indique le chemin de fixture.env et le Program ID Token-2022.

Le bouton lit le fixture.env produit par kb-pipeline-demo-scenarios et remplit automatiquement :

• compte source ou cible ;
• mint ;
• compte destination ou destination lamports ;
• delegate ;
• autorité ;
• freeze authority ;
• montant brut ;
• décimales.

Ne remplacer manuellement une valeur que pour un test négatif délibéré.

Ordre des sous-scénarios

Exécuter les scénarios dans cet ordre, car certains modifient l’état nécessaire aux suivants :

S05.1 — MintToChecked

Champs utilisés :

• source/cible : compte token à créditer ;
• mint : mint Token-2022 ;
• autorité : mint authority ;
• montant brut : TOKEN_2022_MINT_AMOUNT_RAW chargé depuis la fixture ;
• décimales : valeur de la fixture.

Avec la fixture par défaut, le mint initial est 10000000000 unités brutes, soit 10 tokens avec 9 décimales. Cette quantité couvre ensuite le transfert, l'approbation et le burn prévus.

Simuler, envoyer, exécuter C07, puis C12.

S05.2 — TransferChecked

Champs utilisés :

• source : compte financé par S05.1 ;
• mint ;
• destination : second compte Token-2022 ;
• autorité : owner du compte source ;
• montant brut et décimales.

Simuler, envoyer, confirmer et vérifier les balances source/destination.

S05.3 — ApproveChecked

Champs utilisés :

• source ;
• mint ;
• delegate ;
• autorité : owner du compte source ;
• montant brut ;
• décimales.

Après confirmation, vérifier la projection de délégation.

S05.4 — Revoke

Champs utilisés :

• source ;
• autorité : owner du compte source.

Le mint et le delegate ne sont pas requis par le formulaire pour cette opération. Vérifier que la délégation précédente est supprimée.

S05.5 — BurnChecked

Champs utilisés :

• source ;
• mint ;
• autorité : owner du compte source ;
• montant brut ;
• décimales.

Le compte source doit conserver un solde suffisant après le transfert.

S05.6 — FreezeAccount

Champs utilisés :

• source/cible ;
• mint ;
• freeze authority.

Vérifier que la fixture désigne une freeze authority réellement configurée sur le mint.

S05.7 — ThawAccount

Réutiliser le même compte cible et la même freeze authority. Ce scénario doit suivre FreezeAccount.

S05.8 — CloseAccount

À exécuter uniquement avec le compte de fermeture prévu par la fixture :

• source/cible : closeAccount chargé par l’application ;
• destination : autorité/destination lamports chargée ;
• autorité : owner ou close authority.

Le compte doit être vide et satisfaire toutes les préconditions de fermeture.

Pour chaque sous-scénario

1. sélectionner le scénario ;
2. laisser applyToken2022Fixture remplir les champs adaptés ;
3. cliquer Préflight et simuler ;
4. contrôler le plan, les owners, les autorités, le montant et les extensions ;
5. cocher la confirmation opérateur ;
6. envoyer ;
7. définir immédiatement KB_DEVNET_SIGNATURE avec la signature affichée pour cette sous-opération ;
8. vérifier qu'elle diffère de la signature du scénario précédent, puis exécuter C07 ;
9. appliquer C12 ;
10. conserver un fichier de preuve distinct en modifiant temporairement le préfixe, par exemple :

export KB_DEVNET_SCENARIO="50a-token-2022-mint-to-checked"

puis 50b, 50c, etc., avant chaque appel à C07.

Critères de validation

• chaque opération disponible est simulée sur son message exact ;
• les comptes sont owned par Token-2022 ;
• les autorités correspondent à la fixture ;
• les montants bruts et décimales sont exacts ;
• les projections token account, admin, fee, metadata ou risk attendues sont présentes selon l’opération ;
• aucun événement n’est attribué au programme Token classique ;
• chaque replay est sans échec ;
• le second replay est idempotent.

11. Scénario S06 — Registre ElGamal — reporté

Statut de 0.1.0-pre.062

Le registre ElGamal reste implémenté mais non validé sur Devnet dans cette campagne. Ce report ne remet pas en cause les validations S01 à S05.

Deux prérequis manquent :

• une fixture créant un compte de contexte de preuve PubkeyValidity valide et owned par le programme natif ZK ElGamal Proof ;
• le raccordement complet du panneau desktop : lecture des champs, handler du bouton Construire le plan Registry, commande Tauri, rendu du plan et affichage borné des erreurs.

Les champs envisagés sont :

• fee payer : wallet opérateur ;
• owner du registre : wallet opérateur ;
• opération initiale : CreateRegistry ;
• proof context state account : compte de contexte PubkeyValidity réel, jamais une adresse arbitraire.

Ne pas fabriquer une preuve de validation à partir d’un compte quelconque. La future campagne S06 devra produire sa propre fixture, exécuter simulation et envoi, confirmer la signature, puis vérifier insertion canonique, extraction Core, replay, projection admin et idempotence.

12. Future fenêtre Metadata

La future fenêtre metadata devra suivre la même structure : commandes communes C01 à C12, puis scénarios séparés pour les metadata incorporées Token-2022, Metaplex Token Metadata et l’enrichissement off-chain indépendant.

13. Critères de clôture de la campagne

La campagne est clôturable uniquement lorsque :

• tous les scénarios déclarés validables dans la campagne ont été rejoués depuis une base Devnet propre ;
• toutes les signatures S01 à S05 sont confirmées sur Devnet ;
• toute surface reportée est identifiée explicitement avec ses prérequis manquants ;
• les identités persistées respectent la nomenclature canonique ;
• aucun ancien processor_name, surface_code, operation_code ou event_code ne subsiste ;
• le replay ciblé est sans échec ni erreur de traitement ;
• les projections sont présentes et idempotentes ;
• le présent guide reflète les commandes réellement exécutées.