<!-- 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éé.