diff --git a/CHANGELOG.md b/CHANGELOG.md index ec604f3..9db3a8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -87,3 +87,7 @@ 0.7.47-doc-matrix - Révision documentaire : ajout d’une matrice DEX dédiée, ajout explicite des sources Git/IDL à consulter, et redécoupage du plan `0.7.48+` en un DEX/version par tranche afin d’éviter les lots “tous events/tous decoders” trop larges. 0.7.47-doc-event-coverage - Ajout d'une matrice événementielle complémentaire `DEX_EVENT_COVERAGE_MATRIX.md` pour suivre, par DEX/version, les familles `swap`, `pool_create`, `liquidity`, `position`, `fee`, `reward`, `admin/config`, `mint`, `burn`, `transfer`, `account_create/close`, `wrap/unwrap`, `orderbook`, `vault`, `lock/unlock`, `launch` et `migration`; ajout de `DB_EVENT_MODEL_REVIEW.md` pour clarifier que `k_sol_dex_decoded_events` suffit à l'audit-only mais que des tables transversales sont nécessaires pour exploiter transfers, orderbook, vault, launch/migration et coverage upstream en requêtes métier. +0.7.48-pre-event-coverage-sync - Raccordement de `k_sol_dex_event_coverage_entries` au registre upstream Git : ajout de `DexEventCoverageService`, sync des entrées registry vers SQLite, inférence conservatoire `event_family` / `expected_db_target`, mapping local limité aux events Raydium déjà connus, refresh des compteurs observés/matérialisés depuis `k_sol_dex_decoded_events` et tables non-trade existantes, sans modification des decoders ni de la matérialisation trade/candle. +0.7.48-pre-event-coverage-fix-docs - Correction du refresh SQL `k_sol_dex_event_coverage_entries` pour éviter les requêtes dynamiques non compatibles avec `sqlx::query` 0.9 ; mise à jour documentaire README/ROADMAP pour acter `0.7.48-pre` comme checkpoint DB/reporting et réaligner la suite sur l’ordre Raydium avant Meteora (`0.7.48 raydium_cpmm`, `0.7.49 raydium_clmm`, puis Pump/Meteora). +0.7.48-pre-event-coverage-report - Clôture du checkpoint `0.7.48-pre` : raccordement des summaries `k_sol_dex_event_coverage_entries` aux diagnostics locaux, ajout des compteurs agrégés de couverture au `LocalPipelineDiagnosticSummaryDto` et au `LocalPipelineValidationReportDto`, ajout du profil `0.7.48-pre_event_coverage_db_checkpoint`, exposition du profil dans Demo Pipeline 2, et maintien des invariants : aucun decoder DEX modifié, aucun trade/candle créé, aucun `program_id` promu sans corpus. +0.7.48-pre-event-coverage-validation-scope - Correction du profil `0.7.48-pre_event_coverage_db_checkpoint` : le contrôle bloquant des trade candidates non matérialisés est maintenant borné aux DEX attendus de la tranche Raydium (`raydium_cpmm`, `raydium_clmm`, `raydium_amm_v4`) afin qu’un DEX partiel hors scope, comme `fluxbeam`, reste diagnostiqué sans bloquer le checkpoint DB/event coverage. diff --git a/README.md b/README.md index c718b52..1fd3d0f 100644 --- a/README.md +++ b/README.md @@ -438,3 +438,28 @@ Voir : - `DEX_EVENT_COVERAGE_MATRIX.md` pour les familles d'events à couvrir ; - `DB_EVENT_MODEL_REVIEW.md` pour les ajouts DB à envisager avant `0.7.48+`. + +## Note 0.7.48-pre — Event coverage DB checkpoint + +La micro-tranche `0.7.48-pre` introduit la persistance de couverture événementielle avant la reprise DEX par DEX. + +Ajouts côté `kb_lib` : + +- table `k_sol_dex_event_coverage_entries` ; +- entity, DTO et requêtes dédiées ; +- service `DexEventCoverageService` pour synchroniser les entrées du registre upstream Git vers SQLite ; +- refresh des compteurs locaux depuis `k_sol_dex_decoded_events` et les tables déjà existantes de matérialisation non-trade / trade ; +- exposition des summaries de coverage dans les diagnostics locaux ; +- ajout du profil de validation `0.7.48-pre_event_coverage_db_checkpoint`, qui synchronise le registre upstream avant validation ; +- le profil `0.7.48-pre` garde les invariants globaux de non-régression, mais borne le contrôle bloquant des trade candidates non matérialisés aux DEX Raydium attendus pour éviter qu’un DEX partiel hors scope bloque le checkpoint DB ; +- sélection du profil `0.7.48-pre` dans Demo Pipeline 2. + +Cette tranche ne modifie pas les decoders DEX, ne crée aucun trade/candle, et ne promeut aucun `program_id` comme vérifié. Elle sert uniquement à objectiver la couverture : `listed`, `decoded/audit`, `observed`, `materialized`, `trade_count` et statut de preuve. + +La suite fonctionnelle reprend par Raydium avant Meteora : + +1. `0.7.48` — `raydium_cpmm` ; +2. `0.7.49` — `raydium_clmm` ; +3. `0.7.50` — `pump_swap` ; +4. `0.7.51` — `pump_fun` ; +5. `0.7.52+` — Meteora puis les autres DEX/surfaces. diff --git a/ROADMAP.md b/ROADMAP.md index be9ba3f..3f5e451 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1242,101 +1242,112 @@ Aucun de ces programmes ne doit être marqué `verified_by_corpus` uniquement pa Objectif : éviter de limiter la matrice aux DEX/versions et imposer une couverture événementielle exhaustive avant la reprise DEX par DEX. -À faire : +Statut : implémenté en micro-tranche DB/reporting, sans modifier les decoders ni la matérialisation marché. -- maintenir `DEX_EVENT_COVERAGE_MATRIX.md` en plus de `DEX_DECODER_MATRIX.md` ; -- lister pour chaque DEX/version tous les events/instructions/logs connus depuis Carbon, fnzero, IDL, Pinax, HODL Warden, OpenBook, Phoenix et Vybe ; +Fait : + +- maintien de `DEX_EVENT_COVERAGE_MATRIX.md` en plus de `DEX_DECODER_MATRIX.md` ; +- ajout de `k_sol_dex_event_coverage_entries` dans `kb_lib/src/db/schema.rs` ; +- ajout des entity/DTO/queries/re-exports associés ; +- ajout de `DexEventCoverageService` pour synchroniser les entrées du registre upstream Git vers la table de coverage ; +- refresh des compteurs `observed_count`, `materialized_count`, `trade_count`, `first_signature` et `last_signature` depuis les events décodés et les tables métier existantes ; +- inférence conservatoire de `event_family`, `expected_db_target` et `local_event_kind`, sans promotion de `program_id` ni validation métier automatique ; +- correction du refresh SQL pour rester compatible avec `sqlx::query` en SQL statique ; +- exposition des summaries de coverage dans `LocalPipelineDiagnosticSummaryDto` et `LocalPipelineValidationReportDto` ; +- ajout du profil de validation `0.7.48-pre_event_coverage_db_checkpoint`, avec synchronisation upstream préalable ; +- contrôle bloquant des trade candidates non matérialisés borné aux DEX Raydium attendus dans ce profil, afin que les DEX partiels hors scope restent diagnostiqués sans bloquer le checkpoint DB/reporting ; +- sélection du profil `0.7.48-pre` dans Demo Pipeline 2. + +Reste à faire dans les tranches DEX : + +- compléter la liste exhaustive des events/instructions/logs par DEX depuis Carbon, fnzero, IDL, Pinax, HODL Warden, OpenBook, Phoenix et Vybe ; - inclure explicitement les familles non-trade : `burn`, `mint`, `transfer`, `account_create`, `account_close`, `wrap_sol`, `unwrap_sol`, `lock`, `unlock`, `vault_deposit`, `vault_withdraw`, `admin/config`, `fee`, `reward`, `launch`, `migration` ; -- vérifier si la DB actuelle suffit ou si une table transversale doit être ajoutée ; -- prioriser `k_sol_dex_event_coverage_entries`, puis `k_sol_token_transfer_events` et `k_sol_orderbook_events` ; +- ajouter plus tard `k_sol_token_transfer_events` et `k_sol_orderbook_events` quand le besoin métier est prouvé par plusieurs DEX ; - ne pas créer de trade/candle depuis ces nouveaux chemins sans validation économique et corpus. -### 6.080. Version `0.7.48` — `meteora_damm_v2` séparé -Objectif : reprendre `meteora_damm_v2` comme DEX effectif séparé après disponibilité du registre upstream Git. +### 6.080. Version `0.7.48` — `raydium_cpmm` event coverage +Objectif : reprendre `raydium_cpmm` en premier, avant Meteora, avec une couverture complète des events listés depuis Carbon/fnzero/IDL. À faire : -- utiliser le registre `0.7.47` comme source d’indices, pas comme preuve ; -- vérifier `cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG` dans le corpus local avant de le marquer `verified_by_corpus` ; -- consolider `create_pool`, swaps exploitables, configs dynamiques, fees/admin et events lifecycle ; -- conserver les swaps sans payload montant/prix fiables comme `non_actionable_trade` ; -- ne promouvoir aucun event depuis `instruction_audit` sans signature de validation. +- utiliser `k_sol_dex_event_coverage_entries` comme ledger de couverture attendu/observé/matérialisé ; +- lister tous les discriminants/instructions/events CPMM depuis les sources upstream ; +- comparer avec les events déjà connus localement : swap, initialize, withdraw, collect_creator_fee et audits restants ; +- conserver les swaps matérialisés uniquement si les montants et le sens économique restent validés ; +- compléter les events non-trade CPMM en audit ou matérialisation existante uniquement avec corpus local ; +- vérifier par SQL que les non-trades ne produisent aucun trade/candle. -### 6.081. Version `0.7.49` — `meteora_dbc` séparé -Objectif : séparer proprement bonding/launch, swap effectif, migration et attribution d’origine dans `meteora_dbc`. +### 6.081. Version `0.7.49` — `raydium_clmm` event coverage +Objectif : reprendre `raydium_clmm` après CPMM, avec couverture des swaps, positions, liquidité, rewards, fees, protocol fees et cas Token-2022. À faire : -- distinguer les events de bonding curve / launch des events de DEX effectif ; -- vérifier swaps exploitables, migration, lifecycle, mint/burn éventuels et launch attribution ; -- éviter toute candle artificielle sur events de bonding/launch non pricés ; -- documenter les signatures/corpus avant toute promotion. +- lister tous les events/instructions CLMM depuis Carbon/fnzero/IDL ; +- consolider `swap`, `swap_v2`, open/close position, increase/decrease liquidity, reward/fee/admin ; +- classer les events non observés en `upstream_git_mapped_unverified` ; +- matérialiser uniquement les events prouvés par corpus ; +- vérifier absence de faux trades/candles. -### 6.082. Version `0.7.50` — `orca_whirlpools` séparé -Objectif : revalider Orca Whirlpools par corpus dédié avant toute promotion au même niveau que Raydium/Meteora. +### 6.082. Version `0.7.50` — `pump_swap` event coverage +Objectif : compléter `pump_swap` au-delà de `buy/sell`. -À faire : +À faire : couvrir fees, cashback, volume accumulator, admin/config et autres events upstream disponibles, tout en maintenant l’invariant non-trade = zéro trade/candle. -- revalider create_pool, swap, liquidité, positions, mints et montants fiables ; -- traiter les swaps Orca partiels comme non-actionnables tant que les montants ne sont pas reconstruits ; -- matérialiser uniquement les events prouvés ; -- ajouter des diagnostics par event kind. +### 6.083. Version `0.7.51` — `pump_fun` launch/bonding/migration +Objectif : séparer launch/bonding de DEX effectif et valider migration vers PumpSwap ou autre surface tradable. -### 6.083. Version `0.7.51` — `fluxbeam` séparé -Objectif : vérifier FluxBeam comme DEX effectif distinct. +À faire : traiter create, buy/sell bonding, update/config, mint/burn éventuels, migration/graduate et rattachement au pool tradable. -À faire : constituer un corpus local, vérifier `program_id`, comptes, préfixes `data_json`, swaps, pools, liquidity et events non-trade prouvés. +### 6.084. Version `0.7.52` — `meteora_dbc` séparé +Objectif : reprendre Meteora après les tranches Raydium et Pump, en séparant bonding/launch, swap effectif, migration et attribution d’origine. -### 6.084. Version `0.7.52` — `dexlab` / OpenBook relation -Objectif : vérifier DexLab comme DEX effectif distinct sans le confondre avec OpenBook ou une couche de marché associée. +À faire : vérifier swaps exploitables, migration, lifecycle, mint/burn éventuels, launch attribution, fees/admin, sans candle artificielle sur events non pricés. -À faire : constituer un corpus local, vérifier `program_id`, comptes, préfixes `data_json`, swaps, pools et éventuels liens de market/pool. +### 6.085. Version `0.7.53` — `meteora_dlmm` parité upstream finale +Objectif : comparer la couverture locale DLMM déjà avancée avec toutes les sources Git/IDL et documenter ou fermer les audits résiduels. -### 6.085. Version `0.7.53` — Lifinity / Phoenix / OpenBook / Stabble -Objectif : traiter les DEX/orderbooks supplémentaires identifiés par le registre upstream Git. +À faire : revalider swaps, liquidity, positions, lifecycle, fees/rewards/admin, et garder les discriminants non mappés en audit documenté. -À faire : valider séparément `lifinity_amm_v2`, `phoenix_v1`, `openbook_v2`, `stabble_stable_swap` et `stabble_weighted_swap`, sans matérialiser de trade avant preuve de montants exploitables. +### 6.086. Version `0.7.54` — `meteora_damm_v1` parité upstream finale +Objectif : compléter la tranche DAMM v1 déjà engagée, résoudre les surfaces non observées et améliorer le rattachement pool/pair quand possible. -### 6.086. Version `0.7.54` — BonkSwap / Boop / Moonshot / Heaven / Wavebreak / Vertigo / Virtuals / Pancake / OKX DEX -Objectif : vérifier les surfaces de swap/launch hybrides ou candidates découvertes via registre et corpus. +À faire : vérifier toutes les instructions upstream restantes, matérialiser uniquement les events prouvés et documenter les cas sans pool/pair local. -À faire : séparer DEX effectif, launch surface, routeur/agrégateur et simple candidat ; ne promouvoir aucun `program_id` sans corpus local. +### 6.087. Version `0.7.55` — `meteora_damm_v2` séparé +Objectif : reprendre DAMM v2 comme DEX effectif séparé après disponibilité du ledger de coverage. -### 6.087. Version `0.7.55` — Raydium surfaces complémentaires -Objectif : traiter `raydium_launchpad`, `raydium_liquidity_locking`, `raydium_stable_swap` et éventuelles surfaces Raydium non couvertes par CPMM/CLMM/AMM v4. +À faire : consolider create_pool, swaps exploitables, configs dynamiques, liquidity, fees/admin, lifecycle ; conserver les swaps sans payload montant/prix fiable comme `non_actionable_trade`. -À faire : distinguer launch, lock, stable AMM et AMM legacy ; garder les events non prouvés en audit. +### 6.088. Version `0.7.56` — `phoenix_v1` audit-only complet +Objectif : finir tous les events Git disponibles en audit, sans activer de trade/candle. -### 6.088. Version `0.7.56` — Aggregators, limit orders, perps et lending -Objectif : intégrer les programmes utiles au routage, aux ordres, aux perps ou au lending sans les confondre avec les DEX effectifs. +À faire : couvrir `Fill`, `FillSummary`, `Fee`, `Evict`, `ExpiredOrder` et autres logs/events disponibles ; préparer le futur modèle orderbook sans matérialisation marché par défaut. -À faire : classifier `jupiter_*`, `kamino_*`, `drift_v2`, `marginfi_v2`, `dflow_aggregator_v4`, `zeta` comme contexte/routing/ordres tant qu’ils ne produisent pas directement une surface DEX matérialisable. +### 6.089. Version `0.7.57` — `openbook_v2` audit-only complet +Objectif : finir les layouts logs/events OpenBook v2 et définir les conditions futures de matérialisation orderbook/trade. -### 6.089. Version `0.7.57` — Couverture événementielle DEX consolidée -Objectif : s’assurer que chaque DEX effectif supporté expose les événements utiles au scoring et au risque sans polluer les trades/candles. +À faire : vérifier fills, settle, consume events, open orders create/close, maker/taker, lots/decimals et sens économique avant toute promotion. -À faire : vérifier par DEX `swap`, liquidité, lifecycle, fees, rewards, admin/config, burns/mints utiles, et matérialiser uniquement les événements prouvés. +### 6.090. Version `0.7.58` — `orca_whirlpools` event coverage +Objectif : reprendre Whirlpools depuis IDL/source avec corpus dédié. -### 6.090. Version `0.7.58` — `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. +À faire : swaps, pools, positions, liquidity, fees/rewards, tick arrays, mint/burn/Token-2022 si applicable. -À faire : rechercher des paires par token mint, chain, DEX name, pool address ou program id lorsque disponible, comparer avec la base locale, copier les signatures/adresses candidates pour backfill, sans promotion automatique. +### 6.091. Version `0.7.59` — Launch surfaces +Objectif : traiter les surfaces de lancement après les DEX effectifs prioritaires. -### 6.091. Version `0.7.59` — Démos spécialisées launch surfaces après DEX effectifs -Objectif : préparer des vues spécialisées pour les launch surfaces après stabilisation des DEX effectifs. +À faire : Raydium LaunchLab/Launchpad, PumpFun migration, Moonshot/Moonit, Boop, Heaven, Bags, LetsBonk, avec séparation stricte launch origin / pool origin / DEX effectif. -À faire : couvrir `pump_fun`, `raydium_launchpad`, `believe`, `bags`, `moonshot` / `moonit`, `boop_fun`, `letsbonk` / `bonk_fun`, `heaven`, avec séparation stricte entre launch origin, pool origin, DEX effectif et migration. +### 6.092. Version `0.7.60` — DEX historiques / candidats +Objectif : valider les DEX ou surfaces candidates par corpus, sans promotion automatique depuis les sources externes. -### 6.092. Version `0.7.60` — `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 : FluxBeam, DexLab, Lifinity, Stabble, BonkSwap, GooseFX, Obric, SolFi et autres entrées Vybe/registry. -À faire : sélectionner endpoints WS/HTTP et DEX/program ids à souscrire, utiliser le pipeline existant, afficher compteurs live, erreurs, subscriptions actives et derniers objets persistés. +### 6.093. Version `0.7.61` — Validation consolidée +Objectif : rejouer une base neuve multi-DEX et valider les invariants du pipeline complet. -### 6.093. Version `0.7.61` — 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 : bases neuves, compteurs globaux et par DEX, diagnostics bloquants, samples d’anomalie, corpus documentés et matrice de support par DEX/variante/instruction/event. +À faire : rapport coverage par DEX/event, zéro faux trade/candle, corpus documentés, matrices cohérentes, diagnostics bloquants à zéro. ### 6.091. Version `0.8.x` — Analyse et filtrage Objectif : transformer les événements bruts en signaux exploitables. @@ -1525,18 +1536,23 @@ Préconditions considérées acquises avant cette reprise : Ordre de travail recommandé pour la suite : -1. `0.7.44` : ledger de décodage/replay et skip sûr ; +1. `0.7.44` : ledger de décodage/replay et skip sûr — acquis ; 2. `0.7.45` : `meteora_dlmm` — clos ; -3. `0.7.46` : `meteora_damm_v1` ; -4. `0.7.47` : `meteora_damm_v2` ; -5. `0.7.48` : `meteora_dbc` ; -6. `0.7.49` : `orca_whirlpools` ; -7. `0.7.50` : `fluxbeam` ; -8. `0.7.51` : `dexlab` ; -9. `0.7.52` : `metaDAO` candidat DEX ; -10. `0.7.53` : `printr` candidat DEX ; -11. `0.7.54` : couverture événementielle DEX consolidée ; -12. `0.7.55+` : sources externes de découverte, launch surfaces, watcher live et validation consolidée. +3. `0.7.46` : `meteora_damm_v1` — clos côté corpus local ; +4. `0.7.47` : Upstream Git Registry / DEX discovery preparation — acquis ; +5. `0.7.48-pre` : event coverage + DB model checkpoint — clos après table, sync upstream, refresh counts, diagnostics et profil validation ; +6. `0.7.48` : `raydium_cpmm` ; +7. `0.7.49` : `raydium_clmm` ; +8. `0.7.50` : `pump_swap` ; +9. `0.7.51` : `pump_fun` ; +10. `0.7.52` : `meteora_dbc` ; +11. `0.7.53` : `meteora_dlmm` parité upstream finale ; +12. `0.7.54` : `meteora_damm_v1` parité upstream finale ; +13. `0.7.55` : `meteora_damm_v2` ; +14. `0.7.56` : `phoenix_v1` audit-only complet ; +15. `0.7.57` : `openbook_v2` audit-only complet ; +16. `0.7.58` : `orca_whirlpools` ; +17. `0.7.59+` : launch surfaces, DEX candidats/historiques et validation consolidée. Garde-fous constants : diff --git a/kb_demo_app/frontend/demo_pipeline2.html b/kb_demo_app/frontend/demo_pipeline2.html index 5331c05..77521df 100644 --- a/kb_demo_app/frontend/demo_pipeline2.html +++ b/kb_demo_app/frontend/demo_pipeline2.html @@ -197,7 +197,8 @@