<!-- file: docs/reports/RAYDIUM_CLMM_EVENT_COVERAGE_REPORT.md -->

# Rapport `0.7.49` — Raydium CLMM event coverage

## Résumé

La tranche `0.7.49` clôture la couverture fonctionnelle `raydium_clmm` sur le corpus local validé. Elle reprend CLMM après `0.7.48 raydium_cpmm` et applique la même méthode : inventaire upstream, corpus local, replay forcé, materialization contrôlée, suppression des fallbacks remplacés, validation SQL.

Validation locale observée après le dernier replay :

```text
local replay: 2197 replayed, 0 decode skipped, 2197 ledger upserts, 1461 unsafe ledger rows, 1217 trades, 111 liquidity, 25 lifecycle, 4868 candle upserts, instructionObservations=19798
catalog: 41 tokens, 63 pools, 63 pairs
```

Synthèse coverage :

```text
listed_entry_count        = 45
decoded_entry_count       = 33
observed_entry_count      = 33
materialized_entry_count  = 25
total_observed_count      = 2560
total_materialized_count  = 1367
trade_count               = 1186
```

## Entrées couvertes

La tranche couvre `33` instructions locales CLMM observées et décodées, dont :

```text
swap
swap_v2
swap_router_base_in
open_position
open_position_v2
open_position_with_token22_nft
close_position
close_protocol_position
increase_liquidity
increase_liquidity_v2
decrease_liquidity
decrease_liquidity_v2
create_pool
create_customizable_pool
create_amm_config
create_dynamic_fee_config
update_amm_config
update_pool_status
create_operation_account
update_operation_account
create_support_mint_associated
collect_fund_fee
collect_protocol_fee
collect_remaining_rewards
initialize_reward
set_reward_params
transfer_reward_owner
update_reward_infos
open_limit_order
increase_limit_order
decrease_limit_order
close_limit_order
settle_limit_order
```

## Matérialisations validées

Les matérialisations sont limitées aux transactions réussies et aux familles déjà supportées par le modèle DB :

| Famille | Table | Règle |
|---|---|---|
| Swaps | `k_sol_trade_events` + candles | Uniquement `raydium_clmm.swap` / `raydium_clmm.swap_v2` quand les montants sont exploitables. |
| Liquidity / positions | `k_sol_liquidity_events` | Positions/liquidity prouvées par corpus, sans trade/candle. |
| Fees | `k_sol_fee_events` | Fees prouvées par corpus, sans trade/candle. |
| Rewards | `k_sol_reward_events` | Rewards prouvées par corpus, sans trade/candle. |
| Admin/config | `k_sol_pool_admin_events` | Config/admin prouvés par corpus, sans trade/candle. |
| Lifecycle | `k_sol_pool_lifecycle_events` | Pool creation prouvée par corpus, sans trade/candle. |
| Limit orders | `k_sol_orderbook_events` | Open/increase/decrease/close/settle matérialisés comme orderbook, jamais trade/candle. |

## Invariants validés

Les requêtes SQL finales valident :

```text
raydium_clmm.instruction_audit résiduel = 0
upstream_git.instruction_match localement couvert = 0
non-swap CLMM avec trade_count > 0 = 0
failed tx matérialisées = 0
```

Les fallbacks `upstream_git.instruction_match` localement couverts sont supprimés automatiquement, y compris quand `k_sol_instruction_observations.decoded_event_id` pointait encore vers une ligne fallback.

## Anchor / Program-data events non observés

Les `11` Anchor / `Program data` events CLMM ci-dessous restent listés en `upstream_git_unverified`, car aucun corpus local ne les observe encore comme event direct :

```text
collect_personal_fee_event      a6ae69c051a15369
collect_protocol_fee_event      ce57114f2d29d53d
config_change_event             f7bd07776a705f97
create_personal_position_event  641e57f9c4df9ace
decrease_liquidity_event        3ade563a44325538
increase_liquidity_event        314f69d420221e54
liquidity_calculate_event       ed7094e63954b4a2
liquidity_change_event          7ef0afce9e58996b
pool_created_event              195e4b2f7063353f
swap_event                      40c6cde8260871e2
update_reward_infos_event       6d7fba4e724125ec
```

Le code est préparé pour les accueillir comme audit-only lorsqu’ils seront observés dans un corpus local. Ils ne produisent pas de trade/candle par défaut.

## Sources utilisées

Les entrées ont été comparées aux sources Raydium CLMM suivantes :

```text
Solscan Program IDL CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK
sevenlabs-hq/carbon raydium-clmm-decoder
pinax-network/substreams-solana-idls raydium/clmm
0xfnzero/sol-parser-sdk idl
```

Les sources upstream restent des indices. La promotion locale dépend du corpus local, du replay et des validations SQL.

## SQL final

La validation finale est dans :

```text
validation_sql/SQL_VALIDATION_RAYDIUM_CLMM_0_7_49.sql
```

## Addendum `0.7.50-pre-r2` — source parity CLMM

La re-vérification CLMM ajoute `cpi_event` (`e445a52e51cb9a1d`) et `update_dynamic_fee_config` (`0707500802c784f0`) depuis Carbon. Les Program-data events CLMM reçoivent maintenant un `local_event_kind` et une famille explicite quand ils sont observables localement : `swap_event`, `pool_created_event`, `liquidity_change_event`, `create_personal_position_event`, `decrease_liquidity_event`, `increase_liquidity_event`, `collect_protocol_fee_event`, `config_change_event` et `update_reward_infos_event`.

`create_support_mint_associated` est matérialisable dans la nouvelle table `k_sol_token_account_events`. `liquidity_calculate_event` reste decoded-only car il représente un calcul/diagnostic et non une mutation de liquidité fiable. `swap_event` et `swap_router_base_in` restent également decoded-only : les trades matérialisés proviennent des instructions `swap` et `swap_v2`, ce qui évite les doublons de Program-data events et les routes sans pool direct.
