0.7.54

docs/reports/PUMP_FUN_EVENT_COVERAGE_REPORT.md

@@ -0,0 +1,127 @@
+<!-- file: docs/reports/PUMP_FUN_EVENT_COVERAGE_REPORT.md -->
+
+# Pump.fun event coverage report — clôture `0.7.54`
+
+## Statut du rapport
+
+Ce rapport clôture la tranche `0.7.54 pump_fun` côté coverage, décodage local, matérialisation métier prudente et validation SQL.
+
+Program id canonique :
+
+```text
+6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
+```
+
+Source IDL locale prioritaire :
+
+```text
+idls/pump_fun.6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P.json
+```
+
+## Sources utilisées
+
+- `kb_lib/src/dex/pump_fun.rs` ;
+- `kb_lib/src/dex_decode.rs` ;
+- `kb_lib/src/trade_aggregation.rs` ;
+- `kb_lib/src/trade_amount_resolution.rs` ;
+- `kb_lib/src/dex_detection_route.rs` ;
+- `kb_lib/src/dex_event_coverage.rs` ;
+- `kb_lib/src/upstream_registry_generated.rs` ;
+- `idls/pump_fun.6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P.json` ;
+- `validation_sql/SQL_VALIDATION_PUMP_FUN_0_7_54.sql` ;
+- `validation_sql/SQL_VALIDATION_PUMP_FUN_MATERIALIZATION_0_7_54.sql` ;
+- corpus SQLite bâti par backfills Demo3/signatures/pools et replay forcé.
+
+## Couverture finale
+
+L'IDL locale Pump.fun contient `40` instructions et `23` events Anchor. La tranche a ajouté la couverture locale des instructions/events connues, y compris les instructions IDL-only absentes du registre upstream initial :
+
+- `add_quote_mint` ;
+- `buy_exact_quote_in_v2` ;
+- `buy_v2` ;
+- `claim_cashback_v2` ;
+- `collect_creator_fee_v2` ;
+- `distribute_creator_fees_v2` ;
+- `migrate_v2` ;
+- `remove_quote_mint` ;
+- `sell_v2` ;
+- `set_virtual_quote_reserves` ;
+- `update_buyback_config`.
+
+Les events Anchor sont reconnus depuis `Program data:` et depuis le transport Anchor self-CPI/log `e445a52e51cb9a1d` quand présent.
+
+## Règles de matérialisation finales
+
+### Trades
+
+| Source locale | Matérialisation | Règle |
+|---|---|---|
+| `pump_fun.buy` | `k_sol_trade_events` | directe si montants fiables |
+| `pump_fun.sell` | `k_sol_trade_events` | directe si montants fiables |
+| `pump_fun.buy_exact_sol_in` | `k_sol_trade_events` | directe ; les logs `Program data` tronqués sont exploités quand les montants exacts sont extractibles |
+| `pump_fun.buy_v2` | non directe | instruction audit/coverage/routing uniquement |
+| `pump_fun.sell_v2` | non directe | instruction audit/coverage/routing uniquement |
+| `pump_fun.buy_exact_quote_in_v2` | non directe | instruction audit/coverage/routing uniquement |
+| `pump_fun.trade_event` | `k_sol_trade_events` | source canonique des montants exécutés v2/exact quand corrélée sans ambiguïté |
+
+Les `trade_event` déjà couverts par une instruction directe reçoivent un skip explicite afin d'éviter tout double-count.
+
+### Non-trades
+
+Les événements non-trade sont matérialisés uniquement vers leur table métier ciblée quand les comptes, acteurs et montants sont fiables :
+
+- `k_sol_launch_events` pour create/migrate/graduate ;
+- `k_sol_fee_events` pour creator fees, fee distribution et minimum fee ;
+- `k_sol_reward_events` pour cashback, incentives et volume accumulators exploitables ;
+- `k_sol_pool_admin_events` pour admin/config/creator/global authority ;
+- `k_sol_pool_lifecycle_events` pour initialization/lifecycle.
+
+Sinon, ils restent decoded-only/audit-only avec `skip*Reason` explicite. Les transactions failed ne produisent aucune matérialisation métier.
+
+## Replay final rapporté
+
+```text
+1679 replayed
+0 decode skipped
+1679 ledger upserts
+145 unsafe ledger rows
+89 trades
+0 liquidity
+10 lifecycle
+0 tokenAccount
+348 candle upserts
+instructionObservations = 13905
+resetDeleted = 1112
+catalog = 52 tokens / 50 pools / 50 pairs
+```
+
+## Matérialisation finale Pump.fun observée
+
+```text
+pump_fun.buy               17 trades
+pump_fun.sell              25 trades
+pump_fun.buy_exact_sol_in  15 trades
+pump_fun.trade_event       25 trades
+```
+
+Les variantes v2/exact restent à `0` dans `k_sol_trade_events` par `decoded_event_id` d'instruction, ce qui est attendu : leur matérialisation canonique se fait via `pump_fun.trade_event`.
+
+## Checks de fermeture SQL
+
+Résultats finaux rapportés :
+
+- `Q00` upstream fallback Pump.fun : vide ;
+- `Q04` decoded Pump.fun sans coverage : vide ;
+- `Q05` fallback upstream couvert localement : vide ;
+- `Q06` successful non-materialized sans skip reason : vide ;
+- `Q07` failed transaction materialization safety : vide ;
+- `Q08` multi-target materialization safety : vide ;
+- `Q11` trade candidates sans trade ni skip : vide ;
+- `Q12` watchlist globale : plus de `pump_fun` ; restent `pump_fees`, `jupiter_swap` et `dflow_aggregator_v4`.
+
+## Décisions de clôture
+
+- `pump_fun` est clos côté decoder maximal local et validation corpus.
+- Les prochaines interventions Pump.fun doivent être des corrections de bugs ou des adaptations à un changement externe prouvé.
+- La suite logique est `0.7.55 pump_fees` sur nouvelle base SQLite.
+- La politique reste : tout ce qui peut être décodé doit l'être ; tout ce qui peut être matérialisé de manière fiable doit l'être ; aucun trade/candle artificiel ne doit être créé.