khadhroony-bot3/docs/legacy-khadhroony-bot2

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 :

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.