294 lines
30 KiB
Markdown
294 lines
30 KiB
Markdown
<!-- file: README.md -->
|
||
<!-- version: 81 -->
|
||
|
||
# Khadhroony Bot2
|
||
|
||
Khadhroony Bot2 est un workspace Rust modulaire pour observer, décoder, matérialiser, exécuter et analyser des transactions Solana.
|
||
|
||
Le projet poursuit deux objectifs complémentaires. À court terme, il doit fournir un trading assisté contrôlable depuis des démos live Tauri. À long terme, il doit devenir une bibliothèque d'indexation et d'analyse Solana capable de classifier un grand nombre de programmes et de surfaces.
|
||
|
||
Le socle technique doit permettre de :
|
||
|
||
- ingérer des transactions Solana depuis RPC HTTP, WebSocket ou futures sources spécialisées ;
|
||
- normaliser chaque source vers une transaction canonique source-indépendante ;
|
||
- conserver la transaction canonique comme source d’audit et de replay ;
|
||
- conserver séparément les observations légères de provenance et de timing ;
|
||
- extraire les instructions, inner instructions, logs, comptes résolus et deltas de balances ;
|
||
- détecter les programmes impliqués dans chaque transaction ;
|
||
- décoder les programmes Solana de base, les programmes SPL, les surfaces DEX, les orderbooks, les routers et les protocoles annexes ;
|
||
- matérialiser les événements décodés en tables métier exploitables ;
|
||
- rejouer uniquement les modules nécessaires grâce à un ledger de traitement par module et version ;
|
||
- alimenter des agrégations, diagnostics, signaux de risque et futures règles de stratégie ;
|
||
- construire des plans d'exécution séparés des décodeurs ;
|
||
- tester les fonctionnalités live via `kb_app_demo` avant automatisation.
|
||
|
||
## Architecture générale
|
||
|
||
Le workspace suit une chaîne de traitement en couches :
|
||
|
||
```text
|
||
canonical transaction -> source observations -> Solana extraction -> decoding -> materialization -> aggregation -> strategy
|
||
```
|
||
|
||
Chaque couche doit être indépendante autant que possible. Les décodeurs ne dépendent pas du stockage, du RPC, de Tauri, du wallet ou des matérialisateurs. Les matérialisateurs travaillent sur les événements décodés et produisent des événements métier normalisés.
|
||
|
||
## Rôle des dossiers principaux
|
||
|
||
- `kb_core` contient les primitives partagées minimales.
|
||
- `kb_model` contient les types communs du modèle interne.
|
||
- `kb_config` définit le contrat JSON multi-profils, le schéma runtime, les validations typées et les exports TS-rs destinés aux applications Tauri.
|
||
- `kb_rpc` contient les protocoles et clients RPC Solana HTTP, WebSocket et futurs flux Helius/Yellowstone.
|
||
- `kb_execution_solana` assemble les plans communs en transactions Solana, lie la simulation au message exact et résout les signataires via l’interface Solana `Signer`; `kb_wallet` fournit actuellement le backend temporaire.
|
||
- Le projet différé d’acquisition historique gratuite est décrit dans `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md`. Il reste hors du ROADMAP actif tant que les décodeurs, matérialisateurs et exécuteurs prioritaires ne sont pas suffisamment avancés.
|
||
- `kb_store_core` définit les traits de stockage.
|
||
- `kb_store_pg` fournit le backend PostgreSQL cible.
|
||
- `kb_store_sqlite` reste limité aux tests et imports locaux.
|
||
- `kb_decoder_api` définit le contrat des décodeurs.
|
||
- `kb_materializer_api` définit le contrat des matérialisateurs.
|
||
- `kb_materializer_*` contient les projections métier par famille : trades, liquidité, NFT, oracle, lending, routing, compliance audit, etc.
|
||
- `kb_pipeline` orchestre backfill, extraction canonique vers core, décodage, matérialisation, agrégation et validation.
|
||
- `kb_app_demo` sert de démonstrateur Tauri, sans logique métier lourde. Il charge le profil actif, initialise `kb_logging`, rend le README en HTML et expose une fenêtre dédiée à la configuration.
|
||
- Chaque crate opérationnelle doit émettre ses propres événements `tracing` avec une cible canonique égale à son nom Cargo ; `kb_app_demo` reste limité aux frontières UI/Tauri et aux résumés.
|
||
- Chaque profil écrit des fichiers globaux `debug.log`, `info.log`, `error.jsonl` et `app.log`, ainsi que `debug.log`, `info.log` et `error.jsonl` dans un répertoire par crate utilisant `tracing`.
|
||
- Les interfaces officielles Solana/SPL étroites sont privilégiées ; `wincode` puis Borsh sont préférés, et un parser local borné reste autorisé lorsque l’interface officielle n’expose que `bincode`.
|
||
|
||
|
||
## État `0.4.1` validé
|
||
|
||
`0.4.1` clôt le décodage et les matérialisations instructionnelles stables des programmes Solana natifs, historiques, loaders, précompiles et surfaces ZK du périmètre core.
|
||
|
||
`kb_decoder_solana_core` couvre maintenant 18 surfaces exécutables natives : System, Vote, Stake, Config, Compute Budget, Address Lookup Table, Feature, ZK ElGamal Proof, l’ancien ZK Token Proof historique/no-op, Native Loader, BPF Loader v1/v2/Upgradeable/v4, Ed25519, secp256k1, secp256r1 et Slashing. `StakeConfig11111111111111111111111111111111` est classé comme compte historique non exécutable, sans dispatch ni plan d’exécution.
|
||
|
||
Les matérialisations natives actives sont réparties par famille :
|
||
|
||
- `kb_materializer_lifecycle` : Address Lookup Table, lifecycle loaders, Feature revoke, durable nonce, comptes System create/allocate, contextes ZK ElGamal et rapports Slashing ;
|
||
- `kb_materializer_admin` : assignations System, écritures Config opaques, changements d’autorité Loader ;
|
||
- `kb_materializer_compliance_audit` : écritures/copies de bytecode Loader et profil transactionnel Compute Budget ;
|
||
- `kb_materializer_staking` : projections instructionnelles Stake/Vote commitées, sans prétendre reconstruire les snapshots finaux.
|
||
|
||
Les précompiles de signature, les preuves ZK sans compte de contexte et l’ancien ZK Token Proof restent en decode/audit, sans duplication dans `kb_sol_mat_events` tant qu’aucun consommateur dédié ne l’exige. Les transactions échouées restent décodées comme intentions ou échecs, mais les matérialiseurs mutables appliquent `SuccessfulCommittedOnly`.
|
||
|
||
Les validations finales de `0.4.1` couvrent les tests unitaires, PostgreSQL réel, Clippy et des replays mainnet ciblés : System, Config, Stake, Vote, Compute Budget, ALT, ZK ElGamal et Slashing synthétique. Les replays terminent sans `unmatched`, `failedInputs` ou `unsupported`; les archives de logs fournies ont des `error.jsonl` vides.
|
||
|
||
## Couche d'exécution
|
||
|
||
Le workspace développe une couche d'exécution séparée du décodage. Les crates `kb_executor_*` sont des bibliothèques universelles : elles construisent des plans pour les applications de trading, les CLI, les workers, les outils d'administration et de futurs exécutables indépendants.
|
||
|
||
Les opérations dangereuses ne sont pas supprimées des bibliothèques. Elles doivent être encodées, testées et protégées par des politiques renforcées, tandis que `kb_app_demo` peut volontairement ne pas les exposer. Les exécuteurs ne dépendent ni du wallet, ni du RPC, ni des décodeurs ; l'orchestration assemble ensuite plan, sécurité, simulation, signature, envoi et validation post-exécution.
|
||
|
||
## Démos live
|
||
|
||
`kb_app_demo` reste le shell Tauri unique pour valider les capacités du workspace : configuration, logs, DB, RPC, wallet, listeners, décodage, matérialisation, exécution et validation post-transaction.
|
||
|
||
## Documentation
|
||
|
||
- `RUST_RULES.md` contient les règles Rust générales réutilisables ; `RULES.md` contient les règles spécifiques et normatives du workspace.
|
||
- `ROADMAP.md` contient les étapes futures et changements prévus.
|
||
- `CHANGELOG.md` ne reçoit une entrée qu'après validation d'une version.
|
||
- `docs/` contient les notes d'architecture et de conception, notamment `TRACING_CONTRACT.md`, `SOLANA_INTERFACE_DEPENDENCIES.md`, `NATIVE_SOLANA_CLOSURE_AUDIT.md`, `NATIVE_SOLANA_MATERIALIZATION_AUDIT.md` et `DEVNET_EXECUTION.md`.
|
||
- `validation_sql/` contient les contrôles SQL de validation.
|
||
|
||
## Jalon validé `0.4.2`
|
||
|
||
`0.4.2` valide l’infrastructure d’exécution et `kb_executor_solana_core`. L’exécuteur expose **109 opérations déterministes** : dix-sept System, quatre Compute Budget, cinq Address Lookup Table, six formes de précompile, deux Config, deux Feature, deux Slashing, trois ZK ElGamal, vingt-quatre Stake, vingt-quatre Vote, onze Loader v3 et neuf Loader v4. La surface Vote couvre les vingt variantes wire actuelles de `solana-vote-interface 6.0.3` ainsi que quatre plans composés de création legacy/V2, avec ou sans seed. Loader v3 consomme `solana-loader-v3-interface 8.x` et son schéma `wincode`; Loader v4 reproduit explicitement son wire officiel sans activer les helpers conditionnés par `bincode`. BPF Loader v1/v2 restent historiques `decode-only`, Native Loader ne possède pas de builder client et l’ancien ZK Token Proof reste historique. Les opérations nécessitant un état courant restent protégées par un préflight séparé et ne sont pas activées sur Mainnet par ce jalon.
|
||
|
||
`kb_pipeline` fournit le préflight stateful Localnet/Devnet pour ALT, Config, Feature, Slashing et les contextes ZK ElGamal. Le rapport `Ready`/`Blocked`/`NotRequired` expose les contrôles et faits mesurés avant simulation. `docs/NATIVE_SOLANA_EXECUTION_MATRIX.json` inventorie les dix-huit surfaces et les 109 opérations appelables, avec égalité imposée par un test Rust. La matrice décodeur couvre les mêmes dix-huit surfaces et 121 déclarations de couverture.
|
||
|
||
`kb_rpc` possède des contrats propres et configurables pour les 52 méthodes HTTP standard et les neuf paires WebSocket standard. Les options restent composables champ par champ et aucun DTO Agave n’est exposé par l’API publique. La session WebSocket persistante gère multiplexage, unsubscribe, timeout, reconnexion et réabonnement. `blockSubscribe`, `slotsUpdatesSubscribe` et `voteSubscribe` sont activables par endpoint ; lorsqu’un nœud les rejette comme indisponibles, la capacité concernée est désactivée automatiquement pour la session et les appels suivants sont refusés localement.
|
||
|
||
`kb_wallet` fournit un wallet temporaire en mémoire ou persistant sous `wallets/temporary/`, avec fichiers non écrasés, permissions privées et secrets confinés côté Rust. `kb_execution_solana` assemble les transactions, lie la simulation au hash exact du message et signe seulement après autorisation de `kb_execution_safety`. `kb_pipeline` orchestre le parcours backend Devnet complet : contrôle du destinataire et du minimum rent-exempt, financement plafonné, System transfer, simulation exacte, signature, envoi, confirmation, hydratation canonique, extraction core et decode replay ciblé. Ce parcours a été validé réellement sur Devnet avec un transfert de 1 000 000 lamports et PostgreSQL réel.
|
||
|
||
La frontière Tauri/TS-rs n’émet plus de `bigint` dans les payloads JSON actifs. Les identifiants WebSocket sont contrôlés contre `Number.isSafeInteger`, et les limites du navigateur SQL sont validées côté frontend avant l’appel backend. `cargo tauri dev` avec Vite constitue la validation frontend retenue ; aucun `npm run build` séparé n’est exigé pour cette clôture.
|
||
|
||
## Jalon validé `0.4.3`
|
||
|
||
Le prompt `prompts/022_v0_4_3_spl_memo.md` reste l’historique de travail du jalon. Le décodeur contextualisé distingue v1, v3 et v4 avec payload UTF‑8 ou tentative invalide, comptes ordonnés, signataires, outer/inner, hash et intentions non commitées. La projection dédiée `kb_materializer_transaction_annotations` transforme uniquement les Memo réussis et commités en annotations consultables et idempotentes ; les faits d’audit détaillés restent dans le decode. `demo_decode_replay` expose ces sorties comme un journal borné filtrable par signature, avec slot, instruction path, génération, texte, hash et signataires vérifiés.
|
||
|
||
`kb_executor_spl_memo` expose maintenant un intent typé `AddMemo` et appelle le builder officiel `spl-memo-interface 2.1.0` avec l’ID explicite v1/v3/v4. Le wire reste le texte UTF‑8 brut et chaque signer est readonly, ordonné et visible avant signature. La bibliothèque construit les trois générations sur tout cluster ; la disponibilité effective du programme est vérifiée par la simulation obligatoire, et Mainnet reste régi par les garde-fous communs plutôt que désactivé dans l’exécuteur. La démo opérateur reste volontairement limitée à Memo v4 Devnet et réutilise la fenêtre Solana existante. Elle montre la simulation, l’envoi explicitement confirmé, l’hydratation, l’extraction, le replay, l’annotation et l’idempotence avec des DTO Tauri JSON sans `bigint` actif.
|
||
|
||
Le parcours a été validé le 15 juillet 2026 avec une simulation seule puis trois transactions v4 Devnet confirmées. Chaque signature a produit une insertion canonique, une extraction core, un événement Memo, une annotation `transaction_annotation` et un second replay `skipped` sans nouvelle sortie. Le corpus Mainnet réel couvre séparément v1, v3 et v4 ; aucun envoi historique v1/v3 sur Devnet n’est revendiqué ni requis.
|
||
|
||
La matrice `docs/SPL_MEMO_MATRIX.json` conserve les différences historiques, le corpus Mainnet réel, les preuves Devnet v4 et les limitations explicitement non revendiquées pour v1/v3. Le worker d’acquisition historique reste un projet différé indépendant, sans numéro de version attribué.
|
||
|
||
La validation finale confirme 5 tests `kb_program_ids`, 9 tests décodeur Memo, 7 tests matérialiseur d’annotations, 15 tests exécuteur Memo, 22 tests API d’exécution, 15 tests safety, 12 tests Solana, 61 tests pipeline, 113 tests RPC, 96 tests démo et 46 tests PostgreSQL réels. Le test opt-in Devnet avec envoi et `cargo clippy --all-targets` sont propres. La version active devient `0.4.4 — SPL Token` selon `prompts/023_v0_4_4_spl_token.md`.
|
||
|
||
## Jalon validé `0.4.4`
|
||
|
||
Les premières tranches SPL Token établissent la matrice machine-readable des 28 tags publiés par
|
||
`spl-token-interface 3.0.0` et remplacent le scaffold du décodeur classique. Le wire local borné
|
||
conserve montants bruts, decimals explicites, autorités, comptes ordonnés, chemins outer/inner,
|
||
transactions échouées non commitées, suffixes et diagnostics. `Batch` produit un parent d'audit et
|
||
des enfants à identités dérivées stables sans accepter de batch imbriqué.
|
||
|
||
Les matérialiseurs actifs produisent un journal instructionnel `token_account`, des faits admin et
|
||
des constats de risque sans score ; aucune fee classique n'est inventée. Le replay Mainnet validé de
|
||
370 instructions a produit 371 sorties, huit refus expliqués par huit transactions échouées et un
|
||
second replay idempotent sans nouvelle sélection.
|
||
|
||
`kb_executor_spl_token` expose 24 opérations typées courantes ou récentes avec montants JSON en
|
||
chaînes, autorités simples/multisig et builders officiels. Quatre initialisations Rent obsolètes
|
||
restent decode-only. `UnwrapLamports` et `Batch` sont constructibles selon l'interface publiée ; leur
|
||
déploiement sur le programme classique Devnet a été observé le 16 juillet 2026 par deux simulations
|
||
réussies sans signature ni envoi. Localnet, Testnet et Mainnet restent non testés pour ces deux tags.
|
||
|
||
`0.4.4-pre.005` ajoute le préflight stateful Localnet/Devnet dans `kb_pipeline`. Les lectures RPC
|
||
restent hors du décodeur et de l’exécuteur ; elles valident les layouts Mint/Account/Multisig,
|
||
l’état, les relations de mint, les soldes, les réserves wrapped SOL, les délégations, les autorités,
|
||
les seuils multisig et le rent avant simulation. Les tests standards sont offline et un test Devnet
|
||
read-only reste opt-in. La démo Token réutilise la fenêtre d’exécution Solana existante : son panneau
|
||
`TransferChecked` expose préflight, simulation, confirmation et validation post-exécution, tandis
|
||
qu’un journal matérialisé borné accepte des filtres typés par signature, mint, compte, famille et
|
||
opération sans créer une WebView par opération.
|
||
|
||
Le correctif fonctionnel de `pre.005` ajoute l’orchestration Devnet générique : simulation autonome
|
||
après préflight, puis envoi explicitement confirmé lorsque le wallet du profil résout tous les
|
||
signataires. Une transaction envoyée est confirmée, hydratée, extraite, décodée et matérialisée,
|
||
avant un second replay idempotent. Cette couche ne restreint pas les builders universels aux seuls
|
||
clusters ou signataires disponibles dans la démo.
|
||
|
||
Le parcours `TransferChecked` a été validé réellement sur Devnet le 15 juillet 2026 avec deux
|
||
comptes Token auxiliaires du même mint et un wallet isolé correspondant exactement à l’autorité.
|
||
Le test opt-in impose désormais la présence de la soumission et de la confirmation, l’absence
|
||
d’échec ou de refus au premier replay, au moins une matérialisation Token et un second replay sans
|
||
nouvelle sortie ; il imprime aussi la signature afin qu’elle puisse rejoindre le corpus audité.
|
||
|
||
`0.4.4-pre.006` ajoute un lifecycle destructif explicitement autorisé pour trois comptes classiques
|
||
sans ATA. Son correctif crée d'abord les comptes bruts via trois instructions System officielles,
|
||
avec keypairs éphémères, rent et tailles 82/165/165 vérifiés, puis onze transactions initialisent le mint et deux comptes Token, mintent et
|
||
transfèrent un montant contrôlé, créent puis révoquent une délégation, brûlent exactement les deux
|
||
soldes et ferment les comptes Token. Chaque étape est simulée, confirmée, hydratée, décodée,
|
||
matérialisée et rejouée une seconde fois avant que l'étape suivante ne soit admise.
|
||
|
||
Le correctif de reprise du lifecycle traite explicitement les confirmations RPC interrompues : une
|
||
signature prédécesseur confirmée est hydratée, extraite, décodée, rapprochée de l'opération attendue
|
||
et rejouée idempotemment avant de reprendre à l'index demandé. Un délai borné sépare ensuite les
|
||
étapes afin de réduire la pression sur les endpoints Devnet publics, sans masquer leurs erreurs.
|
||
|
||
Le lifecycle Devnet réel a été validé le 15 juillet 2026 après une interruption du RPC public : la
|
||
reprise a récupéré l'initialisation déjà confirmée, puis achevé mint, transfer, approve/revoke, deux
|
||
burn et deux close. Chaque étape récupérée ou envoyée a produit exactement une matérialisation et un
|
||
second replay idempotent. La fenêtre opérateur `pre.007` permet désormais de rejouer le parcours
|
||
représentatif `TransferChecked` et de consulter ces faits `token_account`, `admin` et `risk` comme
|
||
événements chronologiques, sans inventer un état final de compte.
|
||
|
||
L'audit `pre.008` reporte dans `docs/SPL_TOKEN_MATRIX.json` les preuves par instruction. Le corpus
|
||
Mainnet réel couvre `Transfer`, `Approve`, `CloseAccount`, `TransferChecked`, `BurnChecked` et
|
||
`SyncNative`; ses trois initialisations restent volontairement référencées sous leur nom matérialisé
|
||
normalisé sans inventer une variante wire. Le lifecycle Devnet prouve `InitializeAccount3`,
|
||
`MintToChecked`, `TransferChecked`, `ApproveChecked`, `Revoke`, `BurnChecked` et `CloseAccount`.
|
||
Localnet n'a pas été exécuté, et la publication p-token des tags `45`/`255` n'est pas assimilée à
|
||
leur déploiement sur un cluster public.
|
||
|
||
La validation Tauri de `pre.007` a démarré Vite et l'application, réussi le préflight et la
|
||
simulation `TransferChecked`, puis refusé correctement l'envoi sans confirmation opérateur. Avec
|
||
confirmation, un second refus a identifié que le wallet du profil et l'autorité Token étaient deux
|
||
clés distinctes. La démo ne tente jamais de signer à la place d'une autorité externe ; pour envoyer,
|
||
les comptes Token doivent appartenir au wallet persistant sélectionné, comme dans le scénario
|
||
backend Devnet déjà confirmé et matérialisé.
|
||
|
||
La clôture du 16 juillet 2026 confirme les régressions ciblées, PostgreSQL réel, Clippy et Tauri.
|
||
Les validations finales couvrent notamment 5 tests Program IDs, 8 tests décodeur Token, 15 tests
|
||
exécuteur Token, 9 tests décodeur Memo, 7 tests annotations, 22 tests API d'exécution, 15 tests
|
||
safety, 12 tests transaction Solana, 81 tests pipeline, 113 tests RPC, 41 tests configuration,
|
||
102 tests démo et 46 tests PostgreSQL réels. Tauri charge 77 routes de logs, simule
|
||
`TransferChecked`, bloque l'envoi non confirmé, restitue sa matérialisation commitée exacte et
|
||
simule Memo v4 sans erreur runtime.
|
||
|
||
## Jalon validé `0.4.5`
|
||
|
||
`0.4.5` clôt la surface SPL Associated Token Account avec
|
||
`spl-associated-token-account-interface 2.0.0`. Le décodeur reconnaît exactement `Create`,
|
||
`CreateIdempotent`, `RecoverNested` et la forme historique vide de `Create`; il conserve comptes
|
||
ordonnés, flags, doublons, outer/inner paths, transactions échouées non commitées et diagnostics
|
||
bornés. Les PDA sont dérivés et validés explicitement avec les seeds
|
||
`[wallet, Token Program ID, mint]`, ce qui distingue les ATA classiques des ATA Token-2022 sans
|
||
prétendre décoder les extensions de ce dernier.
|
||
|
||
Le lifecycle ATA est possédé par `kb_materializer_token_accounts` : création normale, création ou
|
||
réutilisation idempotente non distinguable depuis le parent seul, et récupération nested.
|
||
`kb_materializer_risk` possède séparément le constat factuel d'anti-pattern nested récupéré. Les
|
||
matérialiseurs lifecycle général, admin et fees déclarent explicitement leur absence de projection,
|
||
et les CPI SPL Token conservent seules leurs initialisations, transferts et fermetures. Les
|
||
transactions échouées ou structurellement invalides ne produisent aucune mutation.
|
||
|
||
`kb_executor_spl_associated_token_account` construit les trois variantes actuelles avec les
|
||
builders officiels, pour SPL Token classique ou Token-2022. Simulation et dry-run sont obligatoires
|
||
par défaut. Le préflight Localnet/Devnet contrôle cluster, mints, Program IDs, dérivations, comptes
|
||
existants, signataires, rent et plafonds ; la post-validation vérifie création/réutilisation ou les
|
||
conditions de fermeture/transfert de `RecoverNested`.
|
||
|
||
Les preuves Devnet du 16 juillet 2026 couvrent deux parcours complets `CreateIdempotent` classiques,
|
||
la création puis la réutilisation d'un ATA Token-2022 avec `ImmutableOwner`, et un
|
||
`RecoverNested` classique transférant 1 000 000 000 unités brutes avant fermeture du nested ATA.
|
||
Chaque soumission a été simulée, confirmée, hydratée, extraite, décodée et matérialisée, puis rejouée
|
||
sans doublon. La fenêtre Tauri unique expose création ATA et journal lifecycle borné ;
|
||
`RecoverNested` reste couvert hors UI par un test opt-in contrôlé.
|
||
|
||
La validation finale confirme les régressions Token/Memo, 10 tests décodeur ATA, 10 tests exécuteur
|
||
ATA, 90 tests pipeline, 113 tests RPC, 41 tests configuration, 111 tests démo, 46 tests PostgreSQL
|
||
réels et `cargo clippy --all-targets` propre. Les versions Rust, npm et Tauri sont synchronisées en
|
||
`0.4.5`.
|
||
|
||
## Jalon validé `0.4.6`
|
||
|
||
`0.4.6` clôt Token-2022 et le registre ElGamal comme surfaces séparées. Token-2022 couvre les instructions de base, les extensions identifiables, les états Mint/Account/Multisig et TLV, les matérialisations propriétaires et les exécuteurs simulation-first. Le registre ElGamal conserve son propre Program ID, sa matrice, son état de 64 octets, son PDA et ses opérations administratives ; il n’est pas fusionné avec Token-2022 ni avec le programme natif ZK ElGamal Proof.
|
||
|
||
La validation publique Token-2022 comprend huit opérations Devnet confirmées et 55 instructions Mainnet décodées sans échec. La validation réseau ElGamal Registry reste indisponible sur les clusters publics au 20 juillet 2026, mais ses builders, parsers, préflights, preuves et scénarios stateful sont validés synthétiquement/offline. Le bilan détaillé est publié dans `docs/V0_4_6_VALIDATION.md`.
|
||
|
||
Le replay contextualisé dispose désormais du mode `incomplete_signatures`. Il sélectionne uniquement les signatures contenant au moins une instruction `pending`, `failed`, `replay_requested` ou `unsupported`, applique la limite aux signatures avant expansion et réévalue leurs instructions compatibles sans activer le force replay global. Deux campagnes PostgreSQL réelles ont sélectionné 81 entrées chacune : 1 décodée, 4 unsupported et 76 rejets fail-closed appartenant tous à des transactions Solana échouées.
|
||
|
||
La régression finale confirme `kb_store_core` 41/41, `kb_store_pg` 46/46 avec PostgreSQL réel, `kb_pipeline` 124/124, `kb_app_demo` 118/118 et `cargo clippy --all-targets` propre.
|
||
|
||
## Jalon actif `0.4.7`
|
||
|
||
La suite active est Metaplex Token Metadata selon `prompts/026_v0_4_7_metaplex_token_metadata.md`. La préversion `0.4.7-pre.001` ouvre l’audit avec les crates `kb_decoder_metadata_metaplex_token_metadata` et `kb_executor_metadata_metaplex_token_metadata`, ainsi que `docs/METAPLEX_TOKEN_METADATA_MATRIX.json`, sans activation runtime tant que le wire complet n’est pas prouvé. L’exécuteur existe comme frontière audit-only parce que le SDK officiel fournit des builders, mais il n’expose encore aucune construction de transaction. Ce programme indépendant complète les metadata externes des mints SPL Token classique et Token-2022 sans être absorbé par leurs décodeurs. La priorité porte sur la frontière exacte du Program ID, les PDA et layouts versionnés, les NFT/collections/programmable assets, la provenance des metadata et le replay PostgreSQL idempotent.
|
||
|
||
Anchor n’est pas requis par les programmes SPL planifiés dans `0.4.x`. Son infrastructure commune est reportée à `0.4.18`, immédiatement avant Meteora, afin d’être conçue à partir des besoins réels des protocoles Anchor sans retarder Metaplex et les autres surfaces Core/SPL.
|
||
|
||
## Backend de données
|
||
|
||
PostgreSQL est le backend principal prévu. SQLite reste présent uniquement pour les tests, les imports ponctuels ou les petits corpus locaux.
|
||
|
||
Les tables Solana PostgreSQL utilisent le schéma courant du profil, généralement `public`. Le projet ne crée pas de schémas applicatifs explicites comme `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`. La séparation logique se fait dans le nom physique de table au format `kb_sol_<domain>_<name>`, par exemple `kb_sol_raw_transactions`.
|
||
|
||
## Replay des signatures incomplètes
|
||
|
||
La fenêtre de replay contextualisé de `kb_app_demo` expose un mode `signatures_incomplete`. Il sélectionne uniquement les signatures contenant au moins une instruction `pending`, `failed`, `replay_requested` ou un résultat `unsupported`, puis réévalue les instructions compatibles de ces signatures sans activer le force replay global. La limite porte sur le nombre de signatures incomplètes avant expansion. La matérialisation reste optionnelle et idempotente.
|
||
|
||
Ce mode est destiné aux backfills croissants : une correction de décodeur peut reprendre seulement les signatures incomplètes au lieu de rejouer toutes les signatures déjà réussies.
|
||
|
||
## Livraison par delta
|
||
|
||
Après le squelette initial, les modifications doivent être livrées sous forme de zip delta contenant uniquement les fichiers ajoutés ou modifiés. Un delta multi-module ou racine utilise `khadhroony-bot2_vX.Y.Z-pre.abc-delta.zip`. Un delta limité à un module Rust utilise `kb_modulename_vX.Y.Z-pre.abc-delta.zip`. Un correctif conserve le même numéro `pre.abc` et ajoute `-delta-fix-001.zip`, puis `-fix-002.zip`, au lieu d’incrémenter la préversion. Chaque archive contient un `delta.md` non versionné listant les fichiers ajoutés, modifiés, à supprimer manuellement, ainsi que les validations exécutées ou non exécutées.
|
||
|
||
## Surfaces réservées
|
||
|
||
Le workspace réserve dès le squelette les crates de décodage pour les DEX, launchpads, orderbooks, routers, perps et surfaces candidates recensés dans `idls/` et dans la documentation de conception. Ces crates restent des points d'ancrage tant que les discriminants, corpus et règles de matérialisation ne sont pas validés.
|
||
|
||
|
||
## Registres de programmes
|
||
|
||
Le workspace distingue deux registres :
|
||
|
||
- `registry/program_registry_seed.toml` pour les surfaces applicatives et protocolaires ;
|
||
- `registry/core_program_id_seed.toml` pour les programmes primitifs, loaders, sysvars et comptes natifs Solana/SPL.
|
||
|
||
Les comptes non exécutables observés pendant la recherche restent documentés dans `docs/ACCOUNT_ONLY_CANDIDATES.md`. Bags dispose maintenant aussi d'une note dédiée dans `docs/BAGS_FM.md` pour les programmes Fee Share V1/V2 confirmés.
|
||
|
||
## Classification des surfaces
|
||
|
||
La classification des IDL locales est suivie dans `docs/IDL_SURFACE_CLASSIFICATION.md`. Le registre machine principal reste `registry/program_registry_seed.toml`.
|
||
|
||
## Configuration, endpoints et listeners
|
||
|
||
Le workspace utilise `kb_config` pour charger plusieurs profils de configuration, avec un seul profil actif. Le fichier JSON est d'abord validé par `config/schema.config.json`, puis désérialisé et validé par les règles métier Rust.
|
||
|
||
Le pipeline normalise toutes les sources vers une transaction canonique commune. HTTP JSON-RPC est utilisé d’abord pour les backfills gratuits. Helius `transactionSubscribe` et Yellowstone gRPC seront ajoutés plus tard dans `kb_rpc`, après les décodeurs prioritaires, sans créer de crate provider séparée. La fenêtre `demo_backfill` permet de lancer des campagnes bornées par liste de signatures, programme, token ou pool. En direction « avant, plus anciennes », une ancre vide commence sur la page la plus récente ; la direction « après, plus récentes » exige toujours une signature d’ancrage.
|
||
|
||
Les listeners WebSocket doivent permettre la détection temps réel des créations de token, créations de pool, migrations, swaps, changements de liquidité et changements sur les tokens ou pools surveillés. Les exports TS-rs de `kb_config` servent uniquement à partager les types Rust/TypeScript avec les applications Tauri comme `kb_app_demo`, puis les futures applications wallet ou finales. Les payloads Tauri partagés, comme la page de configuration, doivent aussi être exportés par TS-rs depuis leur crate applicative.
|
||
|
||
### Metaplex Token Metadata `0.4.7-pre.016`
|
||
|
||
L’inventaire officiel complet des modules d’instruction a été réaudité avant le passage aux comptes on-chain. `FreezeDelegatedAccount` et `ThawDelegatedAccount` historiques sont désormais décodés avec leurs contrats exacts ; les autres surfaces encore absentes restent planifiées avant toute déclaration de couverture exhaustive.
|
||
|