0.7.40

ROADMAP.md

@@ -787,7 +787,7 @@ Contraintes :
 Réalisé :
 
 - ajouter `kb_lib/src/dex_support_matrix.rs` comme source commune de metadata DEX/surfaces ;
-- exposer pour chaque entrée : code interne, famille, version, type technique de surface, rôle stratégique de surface, program id connu ou à vérifier, support actuel, statut, confiance, raisons de skip et activation catalogue ;
+- exposer pour chaque entrée : code interne, famille, version, type de surface, program id connu ou à vérifier, support actuel, statut, confiance, raisons de skip et activation catalogue ;
 - raccorder `dex_catalog`, `transaction_classification` et `protocol_candidate_recording` à cette matrice ;
 - ajouter le profil `0.7.29_multi_dex_matrix_baseline` ;
 - exposer la matrice dans le rapport de validation local ;
@@ -949,30 +949,69 @@ Objectif : remplacer la priorité précédemment donnée aux launch surfaces par
 
 Réalisé :
 
-- modifier la matrice DEX pour distinguer explicitement les rôles `dex_effective`, `aggregator_router`, `launch_surface`, `to_verify` ;
-- vérifier les DEX de swap principaux déjà connus : `pump_swap`, `raydium_cpmm`, `raydium_clmm`, `raydium_amm_v4`, `raydium_stable_swap`, `meteora_dlmm`, `meteora_damm_v1`, `meteora_damm_v2`, `meteora_dbc`, `orca_whirlpools`, `fluxbeam`, `dexlab` ;
-- ajouter `metaDAO` et `Printr` comme entrées `to_verify` dans la matrice, sans `program_id` tant qu’ils ne sont pas prouvés ;
-- rechercher ou confirmer les `program_id` inconnus depuis les corpus locaux, les protocol candidates, DEX Screener, les explorateurs et les transactions résolues ;
-- ne promouvoir aucune entrée vers `partial` ou `supported` sans corpus transactionnel vérifiable ;
-- conserver les invariants `0.7.36` à `0.7.38` : aucun faux trade, aucune fausse candle, aucun événement non price-action transformé en trade/candle.
+- modification de la matrice DEX pour distinguer explicitement les rôles de surface : `dex_effective`, `aggregator_router`, `launch_surface`, `to_verify` ;
+- suppression de l’alias ambigu `raydium` comme code DEX autonome ; `raydium` reste uniquement une famille, avec `raydium_amm_v4` comme surface legacy explicite ;
+- ajout de `metaDAO` et `Printr` comme entrées `to_verify` sans `program_id` inventé ;
+- conservation des DEX de swap principaux déjà connus dans la matrice : `pump_swap`, `raydium_cpmm`, `raydium_clmm`, `raydium_amm_v4`, `raydium_stable_swap`, `meteora_dlmm`, `meteora_damm_v1`, `meteora_damm_v2`, `meteora_dbc`, `orca_whirlpools`, `fluxbeam`, `dexlab` ;
+- maintien des launch surfaces comme surfaces reportées et non prioritaires ;
+- ajout du profil `0.7.39_dex_first_effective_swap_surfaces` ;
+- validation locale confirmée avec `validationPassed = true`, `blockingIssueCount = 0`, `actionableMissingTradeEventCount = 0` et `missingTradeEventCount = 0` ;
+- confirmation par corpus local initial que Raydium CLMM est observé, tandis que Raydium AMM v4 et Stable Swap ne sont pas encore exploitables sans constitution de corpus dédiée.
 
-Résultat attendu : une matrice DEX réorientée vers les surfaces de swap effectives, avec les launch surfaces explicitement reportées.
+Décision : `0.7.39` est clos. La suite immédiate ne doit pas commencer par un décodeur Raydium AMM v4 sans corpus. Il faut d’abord ajouter les outils de découverte on-chain et de backfill ciblé afin d’obtenir des signatures, pools/state accounts, token mints et instructions exploitables.
 
-### 6.072. Version `0.7.40` — Raydium effectif : AMM v4, Stable Swap, CPMM, CLMM
-Objectif : consolider la famille Raydium côté DEX effectifs avant les launch surfaces Raydium.
+### 6.072. Version `0.7.40` — Demo3 on-chain discovery et backfill par signature
+Objectif : ajouter les outils de constitution de corpus nécessaires avant de consolider les décodeurs DEX incomplets.
+
+Réalisé :
+
+- ajout de `Demo3` dans `kb_demo_app` pour rechercher on-chain à partir d’un `dex_code` et/ou d’un `program_id` ;
+- utilisation de la chaîne `getSignaturesForAddress(program_id)` puis `getTransaction(signature)` pour récupérer des transactions récentes liées à un programme DEX ;
+- extraction générique, indépendante des décodeurs DEX existants, de preuves on-chain : `observedTokenMints`, `tokenBalanceDeltas`, `candidatePoolAccounts`, `candidateTokenVaultAccounts` et `candidateProgramAccounts` ;
+- distinction explicite entre `verifiedPoolAddress` et comptes candidats : un compte candidat n’est pas promu en pool vérifié sans décodage/layout/corpus fiable ;
+- conservation de `metaDAO` et `Printr` comme surfaces à vérifier sans `program_id` ;
+- ajout du backfill par signature dans Demo Pipeline 2, en complément du backfill par token mint et pool address ;
+- réutilisation du pipeline existant pour le backfill signature : résolution transactionnelle, projection `k_sol_chain_transactions` / `k_sol_chain_instructions`, décodage DEX existant, détection, matérialisation non-trade, trades, candles et classification ;
+- validation pratique sur `raydium_amm_v4` : les signatures et inner instructions associées au programme `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8` sont maintenant persistées et inspectables ;
+- observation de patterns Raydium AMM v4 récurrents dans les instructions projetées : `accounts_json[1]` comme candidat pool/state, `accounts_json[2]` comme autorité Raydium AMM, `accounts_json[3]` et `accounts_json[4]` comme vaults candidats, avec les comptes utilisateur en fin d’instruction ;
+- maintien des invariants : aucune transaction failed ne produit `trade_events`, metrics ou candles ; aucun candidat sans montants exploitables ne devient trade/candle ; aucun `program_id` n’est inventé.
+
+Décision : `0.7.40` est clos. `Demo3` et Demo Pipeline 2 suffisent pour constituer le corpus nécessaire à la suite immédiate. `Demo4` est décalée à une version ultérieure, car la priorité est maintenant d’utiliser le corpus on-chain local pour consolider `raydium_amm_v4`.
+
+### 6.073. Version `0.7.41` — Raydium AMM v4 swap decoder v1
+Objectif : ajouter un premier décodeur fiable pour les swaps Raydium AMM v4 observés dans le corpus constitué avec Demo3 et Demo Pipeline 2.
 
 À faire :
 
-- vérifier `raydium_cpmm` et `raydium_clmm` comme références déjà supportées ;
-- rechercher des pools réellement rattachés au programme AMM v4 `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8` ;
-- vérifier l’usage réel de `raydium_stable_swap` et du programme `5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h` ;
-- distinguer clairement `raydium_amm_v4`, `raydium_cpmm`, `raydium_clmm`, `raydium_router`, `raydium_stable_swap`, `raydium_launchlab` et `raydium_launchpad` ;
-- identifier les instructions swap, initialize/create pool, liquidité, fees/admin réellement observées ;
-- ajouter des requêtes diagnostics par `program_id`, `accounts_json`, `data_json`, signature et pool address ;
-- documenter les limites si le corpus Raydium legacy reste faible.
+- créer ou compléter le décodeur `raydium_amm_v4` pour les instructions de swap AMM v4 ;
+- traiter explicitement les inner instructions dont `program_id = 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`, notamment lorsqu’elles sont appelées via Jupiter ou un autre routeur top-level ;
+- conserver dans le payload décodé les informations de routage utiles : `routeSource`, `topLevelProgram`, `innerInstruction`, `instructionIndex`, `innerInstructionIndex` ;
+- extraire les comptes selon le layout observé lorsque le format est compatible : token program, pool/state candidat, authority, vault A, vault B, comptes intermédiaires, comptes utilisateur ;
+- utiliser les deltas SPL Token et/ou les transferts inner instruction-scoped pour dériver les montants `base_amount_raw` et `quote_amount_raw` ;
+- marquer `eventActionability = trade_candidate` seulement si les montants et les mints sont exploitables ;
+- classer en `non_actionable_trade` les swaps ou routes dont les montants sont absents, ambigus, multi-hop non isolables ou issus de transactions failed ;
+- matérialiser `trade_events`, metrics et candles uniquement pour les transactions OK avec payload de montants exploitable ;
+- matérialiser ou mettre à jour pools/paires/listings uniquement lorsque les comptes permettent un rattachement fiable ;
+- ajouter des tests de non-régression sur les signatures et patterns Raydium AMM v4 observés localement ;
+- maintenir `blockingIssueCount = 0`, `actionableMissingTradeEventCount = 0`, `missingTradeEventCount = 0` après replay/validation.
 
-### 6.073. Version `0.7.41` — Meteora effectif : DLMM, DAMM v1/v2, DBC
-Objectif : compléter la famille Meteora en couvrant les événements réellement utiles au DEX effectif.
+Corpus de travail initial : comptes candidats tels que `48yaEzz1JSHoghWYg3RGE31srN66ubfPgm4Wc5556YTG`, `SJmR8rJgzzCi4sPjGnrNsqY4akQb3jn5nsxZBhyEifC`, `EMFHrMra2GepQK9KtkQ9C65zxqdDCpQM2uKySPyNEFDA`, `58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2`, et les signatures associées issues de Demo3.
+
+### 6.074. Version `0.7.42` — Raydium effectif : famille Raydium consolidée
+Objectif : consolider la famille Raydium après le premier décodeur AMM v4.
+
+À faire :
+
+- vérifier `raydium_cpmm` et `raydium_clmm` comme références déjà supportées et éviter toute régression ;
+- étendre ou stabiliser `raydium_amm_v4` après le décodeur v1 : swaps directs, routes Jupiter, pools/state accounts récurrents, vaults et mints ;
+- vérifier l’usage réel de `raydium_stable_swap` et du programme `5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h` uniquement si un corpus local exploitable existe ;
+- distinguer clairement `raydium_amm_v4`, `raydium_cpmm`, `raydium_clmm`, `raydium_router`, `raydium_stable_swap`, `raydium_launchlab` et `raydium_launchpad` ;
+- identifier les instructions initialize/create pool, liquidité, fees/admin réellement observées ;
+- ajouter ou renforcer les diagnostics par `program_id`, `accounts_json`, `data_json`, signature et pool address ;
+- ne pas ajouter de trade/candle Stable Swap ou Router sans payload de montants exploitable.
+
+### 6.075. Version `0.7.43` — Meteora effectif : DLMM, DAMM v1/v2, DBC
+Objectif : compléter la famille Meteora en couvrant les événements réellement utiles au DEX effectif, avec corpus enrichi par Demo3 si nécessaire.
 
 À faire :
 
@@ -983,19 +1022,19 @@ Objectif : compléter la famille Meteora en couvrant les événements réellemen
 - clarifier la part `launch/bonding_curve` et la part `dex_effective` de `meteora_dbc` ;
 - éviter tout trade/candle artificiel lorsque les montants ou prix ne sont pas prouvés.
 
-### 6.074. Version `0.7.42` — Autres DEX effectifs : Orca, FluxBeam, DexLab, metaDAO, Printr
-Objectif : consolider les DEX non-Ray­dium/Meteora et intégrer les DEX récemment observés comme candidats vérifiables.
+### 6.076. Version `0.7.44` — Autres DEX effectifs : Orca, FluxBeam, DexLab, metaDAO, Printr
+Objectif : consolider les DEX non-Raydium/Meteora et intégrer les DEX récemment observés comme candidats vérifiables.
 
 À faire :
 
 - constituer des corpus locaux pour `orca_whirlpools`, `fluxbeam` et `dexlab` ;
 - vérifier les `program_id`, comptes, préfixes `data_json` et familles d’instructions utiles ;
 - stabiliser les événements `create_pool`, `swap`, liquidité, positions et admin lorsque prouvés ;
-- ajouter `metaDAO` et `Printr` en `to_verify` avec recherche explicite de program ids, signatures, comptes et pools ;
+- vérifier `metaDAO` et `Printr` par corpus on-chain local avant toute promotion ;
 - ne pas confondre source externe de découverte et preuve on-chain ;
 - marquer explicitement les variantes partiellement supportées ou heuristiques.
 
-### 6.075. Version `0.7.43` — Couverture événementielle DEX : swap, liquidité, fees, rewards, admin, burns
+### 6.077. Version `0.7.45` — Couverture événementielle DEX : swap, liquidité, fees, rewards, admin, burns
 Objectif : s’assurer que chaque DEX effectif expose les événements utiles au scoring et au risque sans polluer les trades/candles.
 
 À faire :
@@ -1009,31 +1048,19 @@ Objectif : s’assurer que chaque DEX effectif expose les événements utiles au
 - ajouter des compteurs et samples diagnostics par DEX et par type d’événement ;
 - conserver l’invariant : aucun fee/reward/admin/liquidity/lifecycle/burn non price-action ne produit de trade, metric ou candle.
 
-### 6.076. Version `0.7.44` — `kb_demo_app` Demo3 : recherche de paires/pools par DEX ou program id
-Objectif : ajouter une fenêtre ou vue de démonstration dédiée à la constitution de corpus par DEX.
-
-À faire :
-
-- ajouter une `Demo3` dans `kb_demo_app` ;
-- permettre la saisie d’un `program_id`, d’un `dex_code`, d’un `pool_address`, d’un `pair_id` ou d’un token mint ;
-- rechercher dans la base locale les transactions, instructions, decoded events, pools, paires, listings et candidates associés ;
-- fournir des presets pour les programmes à vérifier, par exemple `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`, `5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h`, `cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG` ;
-- afficher les signatures candidates à backfill/replay ;
-- garder `kb_demo_app` comme façade UI : toute requête métier doit rester dans `kb_lib`.
-
-### 6.077. Version `0.7.45` — `kb_demo_app` Demo4 : DEX Screener et sources externes de découverte
-Objectif : utiliser des sources externes comme aides à la découverte de corpus sans les traiter comme vérité métier.
+### 6.078. Version `0.7.46` — `kb_demo_app` Demo4 : DEX Screener et sources externes de découverte
+Objectif : utiliser des sources externes comme aides à la découverte de corpus sans les traiter comme vérité métier, après la première consolidation Raydium AMM v4.
 
 À faire :
 
 - ajouter une `Demo4` pour interroger DEX Screener ou une source équivalente ;
 - rechercher des paires par token mint, chain, DEX name, pool address ou program id lorsque disponible ;
-- comparer les résultats externes avec les objets locaux : tokens, pools, pairs, listings, decoded events ;
+- comparer les résultats externes avec les objets locaux : tokens, pools, pairs, listings, decoded events et protocol candidates ;
 - afficher les écarts : paire externe absente localement, pool local sans source externe, DEX label ambigu, program id manquant ;
 - permettre de copier les signatures/adresses candidates pour backfill ;
 - ne jamais promouvoir automatiquement un DEX, un `program_id` ou une paire sur la seule base d’une réponse externe.
 
-### 6.078. Version `0.7.46` — Démos spécialisées launch surfaces après DEX effectifs
+### 6.079. Version `0.7.47` — Démos spécialisées launch surfaces après DEX effectifs
 Objectif : préparer des vues spécialisées pour les launch surfaces, mais seulement après stabilisation des DEX effectifs.
 
 À faire plus tard :
@@ -1044,7 +1071,7 @@ Objectif : préparer des vues spécialisées pour les launch surfaces, mais seul
 - exposer les origins dans les diagnostics et l’UI d’inspection ;
 - maintenir l’interdiction de faux program ids, faux trades et fausses candles.
 
-### 6.079. Version `0.7.47` — `kb_demo_app` Demo10 : watcher WebSocket live DEX
+### 6.080. Version `0.7.48` — `kb_demo_app` Demo10 : watcher WebSocket live DEX
 Objectif : valider le passage du replay/backfill vers l’observation temps réel contrôlée.
 
 À faire :
@@ -1058,7 +1085,7 @@ Objectif : valider le passage du replay/backfill vers l’observation temps rée
 - afficher les compteurs live, erreurs, subscriptions actives et derniers objets persistés ;
 - prévoir un arrêt propre avec unsubscribe avant close.
 
-### 6.080. Version `0.7.48` — Validation DEX v1 consolidée
+### 6.081. Version `0.7.49` — Validation DEX v1 consolidée
 Objectif : rejouer tous les DEX effectifs supportés et valider les invariants du pipeline complet avant de revenir aux launch surfaces ou à l’analyse `0.8.x`.
 
 À faire :
@@ -1071,7 +1098,7 @@ Objectif : rejouer tous les DEX effectifs supportés et valider les invariants d
 - conserver une matrice de support par DEX, variante, instruction et type d’événement ;
 - verrouiller les invariants avant d’ouvrir l’analyse `0.8.x`.
 
-### 6.081. Version `0.8.x` — Analyse et filtrage
+### 6.082. Version `0.8.x` — Analyse et filtrage
 Objectif : transformer les événements bruts en signaux exploitables.
 
 À faire :
@@ -1086,7 +1113,7 @@ Objectif : transformer les événements bruts en signaux exploitables.
 - outils de sélection manuelle de points ABC et projection d’un point D selon des règles temps/prix explicites ;
 - séparation stricte entre signaux analytiques observés, projections hypothétiques et décisions de trading.
 
-### 6.082. Version `1.x.y` — Wallets, comptes et transferts
+### 6.083. Version `1.x.y` — Wallets, comptes et transferts
 Objectif : préparer la couche d’action sans encore brancher l’achat/vente automatique.
 
 À faire :
@@ -1243,29 +1270,30 @@ Le projet doit maintenir au minimum :
 
 ## 12. Priorité immédiate
 
-La priorité immédiate après `0.7.38-B` est `0.7.39_dex_first_effective_swap_surfaces`. La phase launch surfaces est volontairement reportée : elle sera reprise après consolidation des DEX effectifs et des outils de constitution de corpus.
+La priorité immédiate après `0.7.40` est `0.7.41_raydium_amm_v4_swap_decoder_v1`. `Demo3` et le backfill par signature donnent maintenant assez de corpus on-chain pour travailler sur Raydium AMM v4 sans inventer de layout ni promouvoir de faux pool.
 
-Préconditions validées avant `0.7.39` :
+Préconditions validées avant `0.7.41` :
 
 1. validation `0.7.36` acquise : Meteora consolidé, transactions failed traçables mais non actionnables, swaps sans amounts classés `non_actionable_trade`, aucun diagnostic bloquant masqué ;
 2. validation `0.7.37` acquise : compteurs metadata/catalog exposés, backfill metadata idempotent, `pair_symbol` rafraîchissables, metadata manquantes non bloquantes ;
 3. validation `0.7.38` acquise : `tokenMetadataGapSamples` priorisés, Demo Pipeline 2 raccordé, `validationPassed = true`, `blockingIssueCount = 0`, registre local `WSOL`/`USDC`/`USDT`/`JUP`/`RAY`/`BONK` disponible ;
-4. registre local minimal disponible : `SOL`, `WSOL`, `USDC`, `USDT` ;
-5. les diagnostics locaux restent l’outil de vérité pour décider si un DEX peut passer de `planned` ou `to_verify` à `partial` ou `supported`.
+4. validation `0.7.39` acquise : matrice DEX-first, suppression de l’alias `raydium`, `metaDAO` et `Printr` en `to_verify`, aucun `program_id` fictif ;
+5. validation `0.7.40` acquise : `Demo3` découvre on-chain des signatures, mints, deltas et comptes candidats ; Demo Pipeline 2 peut backfiller une signature précise ; les instructions Raydium AMM v4 sont persistées en base ;
+6. aucune transaction failed ne doit alimenter `trade_events`, metrics ou candles ;
+7. aucun decoded event AMM v4 ne doit être promu `trade_candidate` sans montants exploitables.
 
-Ordre de travail recommandé pour `0.7.39+` :
+Ordre de travail recommandé pour `0.7.41+` :
 
-1. scanner `dex_support_matrix.rs`, `dex.rs`, `dex/*.rs`, `dex_decode.rs`, `dex_detect.rs`, `trade_aggregation.rs`, `local_pipeline_validation.rs`, `local_pipeline_diagnostics.rs`, `transaction_classification.rs` et `protocol_candidate_recording.rs` ;
-2. produire un état des DEX effectifs déjà couverts, partiels, à vérifier ou absents ;
-3. ajouter `metaDAO` et `Printr` comme DEX `to_verify` sans `program_id` inventé ;
-4. vérifier les DEX principaux de swap : PumpSwap, Raydium CPMM/CLMM/AMM v4/Stable Swap, Meteora DLMM/DAMM/DBC, Orca Whirlpools, FluxBeam, DexLab ;
-5. rechercher des corpus par `program_id`, pair/pool address, signature et token mint ;
-6. ajouter `Demo3` pour rechercher localement les paires/pools/signatures par DEX ou `program_id` ;
-7. ajouter `Demo4` pour interroger DEX Screener ou sources externes et comparer avec la base locale sans promotion automatique ;
-8. compléter la couverture par DEX des swaps, liquidités, lifecycle, fees, rewards, admin/config, burns/mints utiles ;
-9. ajouter ensuite `Demo10` pour le watcher WebSocket live DEX avec start/stop, subscribe/unsubscribe et écriture en base via le pipeline existant ;
-10. reprendre seulement après cela les launch surfaces : Raydium LaunchLab/Launchpad, LetsBonk/Bonk.fun, Bags, Moonshot/Moonit, Boop.fun, Believe, Heaven ;
-11. passer ensuite à la couche wallet : création de wallet/keypair, inspection et transfert de fonds vers un autre account.
+1. implémenter `raydium_amm_v4.swap` v1 à partir du corpus local : instructions internes `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`, comptes, `data_json`, deltas SPL Token et routes Jupiter ;
+2. distinguer `routeSource` / routeur top-level et DEX effectif : une transaction Jupiter peut contenir un leg Raydium AMM v4, mais le decoded event métier doit rester attribué au DEX effectif ;
+3. matérialiser trades/candles uniquement pour transactions OK et montants fiables ;
+4. conserver les swaps ambigus ou multi-hop non isolables en `non_actionable_trade` ;
+5. consolider ensuite la famille Raydium (`cpmm`, `clmm`, `amm_v4`, `stable_swap`, router et launch surfaces reportées) ;
+6. reprendre Meteora, Orca, FluxBeam, DexLab, metaDAO et Printr avec la même approche corpus-first ;
+7. décaler `Demo4` après la première consolidation Raydium AMM v4, car la découverte on-chain locale suffit pour la suite immédiate ;
+8. ajouter ensuite `Demo10` pour le watcher WebSocket live DEX avec start/stop, subscribe/unsubscribe et écriture en base via le pipeline existant ;
+9. reprendre seulement après cela les launch surfaces spécialisées ;
+10. passer ensuite à la couche wallet : création de wallet/keypair, inspection et transfert de fonds vers un autre account.
 
 Garde-fous constants :