khadhroony-bot3/olddocs/archivekbot2/prompts/023_v0_4_4_spl_token.md

Prompt de session — 0.4.4 SPL Token

1. Mission

Reprendre khadhroony-bot2 après la clôture validée de 0.4.3 et démarrer 0.4.4.

Le jalon couvre exclusivement le programme SPL Token classique :

TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  -> audit du wire historique et courant
  -> décodage maximal des instructions outer et inner
  -> projections métier explicites et idempotentes
  -> exécuteur typé pour toutes les opérations officiellement constructibles
  -> simulation, politiques d’autorité/multisig et validation post-exécution

Le décodeur doit comprendre les instructions anciennes, actuelles et officiellement publiées même lorsqu’une opération récente n’est pas encore déployée sur tous les clusters. L’exécuteur est une bibliothèque universelle : il ne doit pas interdire artificiellement un cluster. La disponibilité du programme et d’une instruction est prouvée par l’audit de déploiement et la simulation ; les applications et politiques communes décident ensuite si un envoi est autorisé.

Ne pas commencer SPL Associated Token Account, Token-2022, ses extensions, Transfer Hook, MemoTransfer, Stake Pool ou une surface DEX. Le worker décrit dans docs/HISTORICAL_DATA_ACQUISITION_PLAN.md reste différé et hors périmètre.

2. Base de travail

La base attendue est le commit Git qui clôture 0.4.3 et contient notamment :

• ROADMAP.md avec 0.4.3 coché et 0.4.4 — SPL Token actif ;
• CHANGELOG.md avec l’entrée validée 0.4.3 ;
• prompts/022_v0_4_3_spl_memo.md conservé comme historique ;
• prompts/023_v0_4_4_spl_token.md comme contrat actif ;
• docs/HISTORICAL_DATA_ACQUISITION_PLAN.md hors ROADMAP actif.

Avant toute modification :

1. lire RULES.md, README.md, ROADMAP.md et CHANGELOG.md ;
2. lire prompts/020_v0_4_1_native_solana_programs.md, prompts/021_v0_4_2_executor_solana_core.md et prompts/022_v0_4_3_spl_memo.md pour préserver les contrats de décodage, matérialisation, exécution et validation post-exécution ;
3. lire docs/EXECUTION_MODEL.md, docs/SOLANA_INTERFACE_DEPENDENCIES.md, docs/SPL_MEMO_MATRIX.json et les audits de clôture 0.4.1/0.4.2 ;
4. auditer kb_decoder_spl_token, kb_executor_spl_token, kb_program_ids, kb_decoder_api, kb_materializer_api, kb_materializer_token_accounts, kb_materializer_admin, kb_materializer_fees, kb_materializer_risk, kb_execution_api, kb_execution_safety, kb_execution_solana, kb_pipeline, kb_rpc, kb_store_core, kb_store_pg et kb_app_demo ;
5. inspecter les types réellement présents et les événements core déjà extraits, notamment les balances SPL, sans supposer qu’un helper, snapshot de compte ou schéma métier existe ;
6. vérifier avec Cargo la version exacte de spl-token-interface résolue depuis la contrainte workspace ^3.0, ses features effectives et ses sources locales avant d’écrire le wire ;
7. comparer cette version à la version réellement déployée du programme sur Localnet, Devnet et Mainnet, instruction par instruction.

État de départ connu : kb_decoder_spl_token et kb_executor_spl_token sont encore des scaffolds Maybe; kb_materializer_token_accounts, kb_materializer_fees et kb_materializer_risk sont des scaffolds inactifs ; kb_materializer_admin est déjà réel et ne doit pas régresser.

3. État validé à préserver

La clôture 0.4.3 a été validée avec :

kb_program_ids                              5 tests
kb_decoder_spl_memo                        9 tests
kb_materializer_transaction_annotations    7 tests
kb_executor_spl_memo                      15 tests
kb_execution_api                          22 tests
kb_execution_safety                       15 tests
kb_execution_solana                       12 tests
kb_pipeline                               61 tests
kb_rpc                                   113 tests
kb_app_demo                               96 tests
kb_store_pg                               46 tests avec PostgreSQL réel
cargo clippy --all-targets                  propre

Le parcours Memo v4 Devnet réel a validé simulation, signature, envoi, confirmation, insertion canonique, extraction core, decode replay, annotation et second replay idempotent. Les trois générations Memo restent décodables et exécutables par la bibliothèque. Les 52 méthodes HTTP et neuf paires WS standard restent couvertes.

Aucune régression de ces invariants n’est acceptable.

4. Sources normatives

Utiliser en priorité :

• kb_program_ids::SPL_TOKEN_PROGRAM_ID pour l’ID exact ;
• le dépôt officiel SPL Token : https://github.com/solana-program/token ;
• le tag exact correspondant à la crate spl-token-interface résolue ;
• interface/src/instruction.rs, les builders officiels et le processor runtime officiel ;
• les layouts officiels state::Mint, state::Account et state::Multisig lorsque leur lecture est nécessaire ;
• la documentation officielle Solana Token ;
• des transactions Mainnet réelles et des fixtures synthétiques contrôlées ;
• des scénarios Localnet/Devnet pour les opérations stateful et les instructions nouvellement publiées.

Au 15 juillet 2026, le catalogue workspace déclare spl-token-interface = ^3.0 sans feature. La publication officielle 3.0.0 ajoute notamment UnwrapLamports au tag 45 et Batch au tag 255. Ne pas conclure qu’elles sont déployées partout, ni les ignorer parce qu’elles sont récentes. Auditer séparément :

• le layout publié par l’interface ;
• le processor et le binaire déployé par cluster ;
• la constructibilité du builder ;
• le résultat de simulation ;
• le corpus réel disponible.

Ne pas activer bincode. Utiliser l’unpack officiel lorsqu’il correspond exactement au runtime audité ou reproduire localement un wire borné avec tests différentiels.

5. Program ID et frontières

Le jalon couvre exactement :

SPL_TOKEN_PROGRAM_ID = TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA

Le Native Mint So11111111111111111111111111111111111111112 est un compte mint spécial du programme SPL Token, pas un autre programme. Il doit être pris en compte pour SyncNative, CloseAccount, retraits de lamports et transferts wrapped SOL, sans être enregistré comme décodeur distinct.

Sont hors surface de dispatch 0.4.4 :

• TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb et toutes les extensions Token-2022 ;
• ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL ;
• Metaplex Token Metadata ;
• Token Group, Token Metadata Interface et Transfer Hook tiers ;
• les programmes DEX qui invoquent SPL Token par CPI.

Une instruction SPL Token en CPI reste toutefois décodée par kb_decoder_spl_token grâce à son Program ID exact et à son chemin inner stable.

6. Contraintes normatives du workspace

Respecter strictement :

• Rust 2024 ;
• async-first pour l’I/O ;
• kb_core::Error et kb_core::Result ;
• aucun anyhow, thiserror, unwrap, expect, unsafe, panic de production ou opérateur ? dans les nouveaux chemins de production ;
• warn(missing_docs), deny(unreachable_pub), forbid(unsafe_code) ;
• imports de traits uniquement lorsque possible, chemins pleinement qualifiés et crate:: en intra-crate ;
• commentaires/docstrings Rust en anglais, Markdown projet en français ;
• header file: puis version: avec un seul incrément par fichier modifié ;
• aucun bincode direct ;
• aucune logique métier lourde dans kb_app_demo ;
• CHANGELOG.md inchangé avant validation complète de 0.4.4 ;
• TRACING_TARGET canonique dans src/constants.rs pour toute crate opérationnelle ;
• aucune valeur JSON Tauri exportée en bigint lorsqu’elle traverse invoke, emit ou JSON.stringify ;
• montants on-chain bruts sérialisés sans perte, sous forme de chaîne à la frontière Tauri si nécessaire.

7. Audit préalable obligatoire

Créer une matrice machine-readable dédiée, par exemple :

docs/SPL_TOKEN_MATRIX.json

Elle doit être vérifiée par un test Rust et contenir au minimum, pour chaque instruction officielle :

• nom canonique et tag wire ;
• statut historique, courant, récent ou réservé ;
• layout exact et tailles autorisées ;
• comptes requis, ordre, writable et signer ;
• forme autorité simple et forme multisig ;
• champs décodés et limites ;
• événement produit ;
• projection(s) autorisée(s) ;
• builder officiel disponible ;
• support exécuteur exact avec éventuel motif Unsupported ;
• statut observé Localnet/Devnet/Mainnet ;
• fixtures synthétiques et signatures réelles.

L’audit doit couvrir l’ensemble de TokenInstruction de la version résolue, y compris :

• initialisation mint/account/multisig et variantes sans Rent ;
• Transfer, Approve, Revoke, SetAuthority, MintTo, Burn ;
• CloseAccount, FreezeAccount, ThawAccount ;
• les variantes Checked ;
• SyncNative ;
• GetAccountDataSize, InitializeImmutableOwner, conversions amount/UI amount ;
• WithdrawExcessLamports ;
• UnwrapLamports si présent dans la version résolue ;
• Batch si présent, avec parsing récursif borné et interdiction des batchs imbriqués selon le runtime officiel ;
• tout autre tag publié dans la version effectivement résolue.

Ne pas recopier une ancienne liste supposée de 25 instructions. L’égalité entre la matrice, l’interface résolue, les déclarations de couverture et les opérations compilées doit être testée.

8. kb_decoder_spl_token

8.1 Remplacement du scaffold

• remplacer DecoderSupport::Maybe par Yes uniquement pour l’ID SPL Token classique exact et No pour les autres ;
• déplacer le target tracing legacy vers src/constants.rs avec la valeur exacte kb_decoder_spl_token ;
• ajouter tracing seulement si des événements runtime réels sont émis ;
• ne produire aucun événement pour une observation hors surface.

8.2 Contrat décodé commun

Chaque observation lisible doit conserver au minimum :

• Program ID exact ;
• instruction et tag wire ;
• chemin outer/inner et index stable ;
• succès/échec de la transaction et état committed ;
• comptes ordonnés avec position, pubkey, signer et writable ;
• rôles de comptes résolus sans inventer un rôle absent ;
• forme d’autorité simple ou multisig ;
• autorité déclarée, signataires fournis et validation structurelle ;
• montants bruts exacts, decimals lorsqu’ils sont dans le wire et aucune valeur UI inventée ;
• mint explicite lorsqu’il est fourni ;
• diagnostic borné et préfixe hex/hash pour un wire invalide ou inconnu ;
• source de toute inférence issue du contexte core.

Les transactions échouées doivent produire des intentions structurées lorsque le wire et les comptes restent lisibles, sans prétendre que l’état Token a muté.

8.3 Sémantique et inférences

• Un Transfer non checked ne porte pas le mint ni les decimals dans son wire. Ne pas les inventer. Une corrélation via les token balance changes core peut être exposée avec provenance et confiance explicites ; une lecture RPC n’appartient pas au décodeur.
• Les variantes checked portent le mint et les decimals attendus, mais une transaction échouée ne prouve pas qu’ils ont été validés par le runtime.
• Distinguer owner, delegate, mint authority, freeze authority, close authority et multisig authority.
• Conserver l’ordre et les doublons des comptes réellement fournis. Valider MIN_SIGNERS, MAX_SIGNERS, M et N selon le runtime, sans confondre comptes membres du multisig et signataires effectifs de l’instruction.
• InitializeImmutableOwner est un no-op de compatibilité sur SPL Token classique si le runtime audité le confirme ; le représenter explicitement sans inventer une extension Token-2022.
• Les instructions de return data doivent conserver l’intention et, si la donnée de retour est disponible dans la transaction canonique, la valider sans dépendre des logs texte.
• Batch doit conserver ses sous-instructions, slices de comptes, ordre et diagnostics. Imposer des bornes de profondeur, compteur, longueur et comptes ; ne jamais accepter silencieusement un suffixe mal formé.

8.4 Corpus minimal

Le corpus synthétique et réel doit couvrir :

• chaque tag officiel de la version résolue ;
• autorité simple et multisig 1..11, seuils valides et invalides ;
• montants 0, 1, u64::MAX et valeurs intermédiaires ;
• decimals 0, 9, maximum wire et mismatch runtime ;
• authorities présentes, révoquées et COption::None ;
• comptes manquants, supplémentaires, dupliqués et flags incorrects ;
• outer instruction et CPI inner ;
• transaction réussie et échouée ;
• wrapped SOL et comptes non natifs ;
• payload vide, tag inconnu, taille tronquée, suffixe et UTF-8 invalide pour UiAmountToAmount ;
• batch vide, plusieurs sous-instructions, longueurs invalides et batch imbriqué ;
• transactions Mainnet réelles représentatives, avec signatures documentées.

9. Matérialisation

Stabiliser le décodage maximal avant les projections. Auditer d’abord les contrats existants ; ne pas conserver les sorties simplistes des scaffolds.

9.1 kb_materializer_token_accounts

Projeter les faits métier commités utiles concernant comptes et mints, par exemple :

• initialisation de mint, compte et multisig ;
• transfert, mint et burn comme mutation instructionnelle ;
• freeze/thaw ;
• close et wrapped SOL sync/unwrap ;
• état de délégation lorsqu’il relève explicitement du compte token.

Ne pas dupliquer les balance changes core. Les projections instructionnelles doivent référencer signature, path, comptes, mint connu ou inconnu, montant brut, provenance et clé d’idempotence. Elles ne doivent pas prétendre reconstruire un snapshot final de compte sans lecture stateful prouvée.

9.2 kb_materializer_admin

Étendre le matérialiseur réel uniquement pour les changements d’autorité Token et la configuration multisig qui appartiennent clairement au domaine admin. Préserver ses surfaces natives existantes et ses tests.

9.3 kb_materializer_risk

Activer une projection seulement pour des faits de risque stables et explicitement justifiés, par exemple délégation/allowance, freeze/thaw, autorité révoquée ou configuration multisig faible. Séparer constat on-chain et interprétation de risque ; ne pas produire un score arbitraire.

9.4 kb_materializer_fees

SPL Token classique ne possède pas les transfer fees de Token-2022. Ne pas fabriquer de frais à partir d’un transfert, ni dupliquer les frais réseau core. Si aucune instruction du runtime audité ne justifie une projection fee, documenter explicitement no projection et laisser le scaffold inactif jusqu’à un futur consommateur légitime.

9.5 Règles communes

• aucune projection mutable réussie pour une transaction non commitée ;
• replay identique = skip/idempotence ;
• changement de version = remplacement déterministe selon le ledger ;
• une sous-instruction Batch produit des identités stables dérivées du path parent et de sa position ;
• ne pas dupliquer logs, account keys, balances ou données core ;
• documenter les faits conservés uniquement dans le decode ;
• réutiliser kb_sol_mat_events sauf preuve qu’un contrat de persistance spécialisé est indispensable.

10. kb_executor_spl_token

10.1 Contrat typé

Remplacer le plan réservé par des intents explicites couvrant les opérations officiellement constructibles. Le contrat doit exposer :

• opération exacte ;
• Program ID exact ;
• comptes et rôles ordonnés ;
• mint, compte source/destination et authority selon l’opération ;
• montant brut et decimals séparés ;
• autorité simple ou multisig avec signataires ordonnés ;
• création ou initialisation stateful clairement séparée ;
• politique de simulation obligatoire, dry-run par défaut et plafond de frais ;
• coût token/SOL déclaré sans confondre montant transféré, rent et frais réseau ;
• Supported ou Unsupported(reason) exact par opération.

10.2 Builders et wire

• utiliser les builders spl-token-interface lorsqu’ils correspondent exactement à l’opération et au Program ID ;
• comparer chaque instruction produite au builder officiel et aux fixtures wire ;
• ne pas inventer de discriminator, Borsh ou sérialisation ;
• préserver strictement l’ordre, writable et signer des metas ;
• valider les formes multisig et dédupliquer seulement les signataires transactionnels requis, pas les metas si le contrat officiel les conserve ;
• construire les opérations publiées récentes, y compris UnwrapLamports ou Batch, seulement après preuve exacte du layout et du builder ;
• classer séparément constructibilité, déploiement et autorisation d’envoi.

La bibliothèque ne doit pas être limitée à Devnet. Mainnet reste gouverné par kb_execution_safety, les profils applicatifs et la confirmation explicite. Une instruction future/test peut être constructible et simulable sur un cluster qui la déploie même si Mainnet ne la supporte pas encore.

10.3 Préflight stateful

Définir dans kb_pipeline, lorsque nécessaire, des lectures préflight bornées pour :

• owner du compte et Program ID ;
• mint, decimals et état initialisé ;
• solde token et native reserve ;
• delegate et allowance ;
• authority/freeze authority ;
• multisig M/N et membres ;
• rent exemption et état de comptes à initialiser ;
• cohérence source/destination/mint ;
• préconditions close, freeze/thaw, mint, burn, sync et unwrap.

Le décodeur reste sans RPC. L’exécuteur reste sans wallet/RPC. L’orchestrateur possède les lectures stateful, la simulation, la signature, l’envoi et la validation.

11. Pipeline, store et démo

• enregistrer le décodeur et les matérialiseurs Token validés dans le replay commun ;
• ajouter les déclarations de couverture et tests de sélection exacts ;
• conserver les écritures atomiques avec le ledger decode/materialize ;
• toucher kb_store_pg seulement si un nouveau contrat de requête ou persistance est réellement nécessaire ;
• utiliser demo_backfill, demo_core_extraction, demo_sql_replay_candidates et demo_decode_replay pour le corpus Mainnet ;
• étendre le navigateur de matérialisations seulement avec des filtres bornés et des DTOs typés, sans SQL libre ;
• réutiliser la fenêtre d’exécution Devnet existante si une validation opérateur Token apporte une valeur claire ;
• ne pas créer une WebView par opération.

Pour la visualisation, afficher les mutations Token comme journal métier filtrable par signature, mint, compte, famille et opération. Les OHLC restent réservées aux futurs trades agrégés ; elles ne sont pas une représentation de SPL Token brut.

12. Validation cluster

Ajouter des tests opt-in et un parcours opérateur représentatif qui :

1. utilise Localnet ou Devnet selon le déploiement de l’instruction ;
2. prépare des comptes temporaires sans dépendre de l’ATA pour la logique du jalon ;
3. construit et simule l’opération exacte ;
4. signe et envoie seulement avec autorisation explicite ;
5. confirme ;
6. appelle getTransaction ;
7. insère la transaction canonique ;
8. exécute core extraction ;
9. exécute decode replay SPL Token ;
10. vérifie les projections attendues et l’idempotence.

Le scénario minimal Devnet devrait couvrir au moins initialisation contrôlée, mint, transfer checked, approve/revoke, burn et close, avec autorité simple. Ajouter un scénario multisig si le financement et la complexité restent raisonnables. Tester les instructions récentes sur Localnet lorsque le binaire Devnet ne les expose pas.

Ne pas utiliser le programme ATA pour masquer l’initialisation de comptes Token dans la couverture 0.4.4; ATA sera traité en 0.4.5.

13. Documentation attendue

Mettre à jour au minimum :

kb_decoder_spl_token/README.md
kb_executor_spl_token/README.md
kb_materializer_token_accounts/README.md
README.md
ROADMAP.md
docs/SOLANA_INTERFACE_DEPENDENCIES.md
docs/SPL_TOKEN_MATRIX.json

Mettre aussi à jour les README des matérialiseurs réellement modifiés. Documenter :

• version résolue de l’interface et différences avec le programme déployé ;
• inventaire exact des instructions et tags ;
• événements et diagnostics ;
• projections par famille et absences volontaires ;
• opérations exécutables et Unsupported(reason) ;
• règles simple authority/multisig ;
• corpus et signatures réelles ;
• résultats Localnet/Devnet/Mainnet ;
• limites et non-revendications.

CHANGELOG.md ne doit être modifié qu’après validation complète de 0.4.4.

14. Interdictions

Ne pas :

• commencer ATA ou Token-2022 ;
• absorber les extensions Token-2022 dans le décodeur SPL Token classique ;
• créer ou commencer l’acquisition historique différée ;
• fusionner Token dans kb_decoder_solana_core ;
• déduire silencieusement un mint absent d’un Transfer non checked ;
• utiliser les logs RPC comme source principale lorsque l’instruction est disponible ;
• inventer des fees, snapshots finaux, balances ou autorités validées ;
• produire une projection committed pour une transaction échouée ;
• considérer les membres d’un multisig comme tous signataires de chaque instruction ;
• désactiver une opération dans la bibliothèque uniquement parce qu’elle n’est pas encore déployée sur Mainnet ;
• exposer un envoi Mainnet par défaut dans la démo ;
• ajouter du SQL libre à l’UI ;
• générer des bindings TypeScript contenant des bigint dans les frontières Tauri JSON.

15. Validations minimales

Selon les fichiers touchés :

cargo test -p kb_program_ids
cargo test -p kb_decoder_spl_token
cargo test -p kb_materializer_token_accounts
cargo test -p kb_materializer_admin
cargo test -p kb_materializer_fees
cargo test -p kb_materializer_risk
cargo test -p kb_executor_spl_token
cargo test -p kb_execution_api
cargo test -p kb_execution_safety
cargo test -p kb_execution_solana
cargo test -p kb_pipeline
cargo test -p kb_rpc
cargo test -p kb_app_demo
cargo clippy --all-targets

Si le store ou une projection est touché :

KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
  cargo test -p kb_store_pg -- --nocapture

Si Tauri est touché :

cargo tauri dev -c kb_app_demo/tauri.conf.json

Le serveur Vite lancé par Tauri constitue la validation frontend normale ; ne pas imposer un npm run build séparé sans besoin particulier.

16. Livraison

Livrer des tranches fonctionnelles sous la forme :

khadhroony-bot2_v0.4.4-pre.NNN-delta.zip

Après la livraison d’un delta pre.NNN, tout correctif conserve le même numéro :

khadhroony-bot2_v0.4.4-pre.NNN-delta-fix-001.zip
khadhroony-bot2_v0.4.4-pre.NNN-delta-fix-002.zip

Ne pas incrémenter NNN pour réparer une archive déjà livrée. Le numéro suivant est réservé à une nouvelle tranche fonctionnelle.

Chaque archive doit contenir :

• uniquement les fichiers ajoutés ou modifiés ;
• delta.md non versionné ;
• manifest.json ;
• les suppressions manuelles explicitement listées ;
• les validations exécutées et non exécutées ;
• aucune archive complète sauf demande explicite ;
• aucune modification de CHANGELOG.md avant validation finale du jalon.