# DEX Event Coverage Matrix — `khadhroony-bobobot` `0.7.47-1FE5`

Cette matrice complète `DEX_DECODER_MATRIX.md`.

La matrice précédente répondait à la question : **quel DEX/version est couvert ?**

Cette matrice répond à la question : **quels events/instructions doivent être décodés, audit-only ou matérialisés ?**

## Principe

L’objectif n’est plus seulement de décoder les swaps. L’objectif est de décoder le maximum d’événements disponibles dans les sources Git/IDL et dans le corpus local, parce que certains événements non-trade peuvent influencer une décision de trading :

- perte ou ajout de liquidité ;
- burn de tokens ou de LP ;
- mint anormal ;
- lock/unlock de liquidité ;
- close account / fermeture de position ;
- admin/config changes ;
- fees/rewards ;
- migration launch → DEX ;
- market/orderbook activity ;
- vault deposit/withdraw ;
- changement de market cap ou de supply dérivée.

Un event peut donc être important même s’il ne produit jamais de `trade_event` ou de candle.

## Règle de couverture

Pour chaque DEX/version, on doit viser trois niveaux :

| Niveau | Description |
|---|---|
| `listed` | L’event/instruction existe dans une source Git/IDL/Carbon/Vybe/autre. |
| `decoded_audit` | Le code local reconnaît l’event et le persiste dans `k_sol_dex_decoded_events` avec payload structuré ou audit-only. |
| `materialized` | L’event alimente une table métier spécialisée : trade, liquidity, lifecycle, fee, reward, admin, mint, burn, orderbook, vault, launch/migration, etc. |

Ne pas sauter directement de `listed` à `materialized`.

## Univers minimal d’events à suivre

Cette liste doit devenir la grille commune pour toutes les tranches `0.7.48+`.

| Famille | Exemples | Impact possible | Table actuelle / cible |
|---|---|---|---|
| `swap/trade` | swap, buy, sell, route swap, exact in/out | Prix, volume, candles | `k_sol_trade_events`, `k_sol_pair_metrics`, `k_sol_pair_candles` |
| `pool_create` | initialize, create_pool, initialize_market | Découverte pool/pair | `k_sol_pool_lifecycle_events`, `k_sol_pools`, `k_sol_pairs` |
| `liquidity_add` | add_liquidity, deposit liquidity, bootstrap | Profondeur, risque, market cap indirect | `k_sol_liquidity_events` |
| `liquidity_remove` | remove_liquidity, withdraw liquidity | Rug/liquidity drain | `k_sol_liquidity_events` |
| `position_open` | open_position, init_position | CLMM/DLMM state | `k_sol_pool_lifecycle_events` ou future `k_sol_position_events` |
| `position_close` | close_position, close_position_if_empty | Sortie de LP, risque | `k_sol_pool_lifecycle_events` ou future `k_sol_position_events` |
| `fee` | claim_fee, collect_protocol_fee, collect_creator_fee | Rentabilité, activité pool | `k_sol_fee_events` |
| `reward` | claim_reward, fund_reward, update_reward | Incitations, farming | `k_sol_reward_events` |
| `admin/config` | set_config, update_fee, pause, whitelist, authority change | Risque protocole/pool | `k_sol_pool_admin_events` |
| `mint` | token mint, LP mint, position NFT mint | Supply, launch, LP | `k_sol_token_mint_events` + future token activity |
| `burn` | token burn, LP burn, position NFT burn | Supply, LP burn, risque/réassurance | `k_sol_token_burn_events` + future token activity |
| `transfer` | SPL transfer, Token-2022 transfer, routed transfer | Flux wallet/vault, whale movement | future `k_sol_token_transfer_events` |
| `account_create` | ATA create, token account init | Préparation trade/wallet/vault | future `k_sol_token_account_events` |
| `account_close` | close token account, close open orders | Sortie position/wallet cleanup | future `k_sol_token_account_events` ou `k_sol_orderbook_events` |
| `wrap/unwrap` | wrap SOL, unwrap SOL, close WSOL ATA | Routing, PnL, trade prep | future token account/activity |
| `order_place` | place_order, post_only, IOC | Orderbook pressure | future `k_sol_orderbook_events` |
| `order_cancel` | cancel_order, cancel_all, reduce order | Changement intention | future `k_sol_orderbook_events` |
| `order_fill` | FillLog, fill event, trade event | Trade réel orderbook | future `k_sol_orderbook_events`; trade seulement après validation économique |
| `settle_funds` | settle_funds, withdraw funds | Finalisation CLOB | future `k_sol_orderbook_events` |
| `consume_events` | crank/event queue processing | Orderbook fill/out | future `k_sol_orderbook_events` |
| `vault_deposit` | deposit into vault | TVL/risque | future `k_sol_vault_events` |
| `vault_withdraw` | withdraw from vault | TVL drain | future `k_sol_vault_events` |
| `lock` | lock_liquidity, create_lock_escrow | LP lock/risk | `k_sol_pool_lifecycle_events` ou future lock table |
| `unlock` | unlock, release escrow | Risque de retrait LP | future lock/lifecycle |
| `launch` | create bonding curve, launch pool | Origine token | future `k_sol_launch_events` |
| `migration` | migrate to DEX, migrate liquidity | Passage launch → tradable | future `k_sol_launch_events`, pool origins |
| `stake/unstake` | stake LP/token, unstake | Incentives/withdraw risk | future staking/reward events |
| `oracle/price` | oracle update, price account update | Pricing/risk | future oracle/context events |
| `unknown` | unmapped discriminator | Dette de décodage | `k_sol_dex_decoded_events` audit-only |

## Matrice de couverture par DEX/version

Légende :

- `M` = matérialisé déjà ou historiquement validé ;
- `A` = audit-only local ;
- `P` = partiel / doit être complété ;
- `L` = listé upstream, non validé localement ;
- `-` = non applicable connu ;
- `?` = à vérifier.

| DEX/version | swap | pool create | liq add/remove | position | fee/reward | admin/config | mint/burn | transfer/account | orderbook | vault | launch/migration | état immédiat |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---|
| `raydium_cpmm` | M | P | P | - | P | P | ? | ? | - | - | ? | Reprendre en `0.7.48`, comparer tous events Carbon/IDL/fnzero. |
| `raydium_clmm` | M | P | M/P | M/P | P | P | P | ? | - | - | ? | Reprendre en `0.7.49`, compléter positions/rewards/fees/admin. |
| `pump_swap` | M | P | P | - | P | P | ? | P | - | - | P | Reprendre en `0.7.50`, couvrir buy/sell/cashback/fee/volume/admin. |
| `pump_fun` | P | P | - | - | ? | P | P | P | - | - | M/P | Reprendre en `0.7.51`, launch/bonding/migration/buy/sell/create/update. |
| `meteora_dbc` | P | P | P | - | P | P | P | ? | - | P | M/P | Reprendre en `0.7.52`, séparer bonding, swap, migration, config, fees. |
| `meteora_dlmm` | M | M | M | M | M/P | P | ? | ? | - | ? | ? | Reprendre en `0.7.53` pour exhaustive upstream + audits résiduels. |
| `meteora_damm_v1` | M/P | M | M/P | - | M/P | P | ? | ? | - | P | ? | Reprendre en `0.7.54`, vérifier toutes surfaces upstream non observées. |
| `meteora_damm_v2` | P | P | L/P | - | L/P | L/P | ? | ? | - | P | ? | Reprendre en `0.7.55`, decoder tous events Carbon/source. |
| `phoenix_v1` | A | A/P | - | - | A/P | A/P | - | A/P | A | - | - | Continuer audit des events Git, pas de trade/candle. |
| `openbook_v2` | A | A/P | - | - | A/P | A/P | - | A/P | A | - | - | Audit-only avancé, matérialisation orderbook future. |
| `orca_whirlpools` | P | P | L/P | L/P | L/P | L/P | P | ? | - | - | ? | Reprendre en `0.7.58`, IDL complet + corpus dédié. |
| `raydium_launchlab` | - | P | ? | - | ? | P | P | P | - | - | P | Launch/migration après DEX effectifs. |
| `bonkswap` | L | L | L | - | L | L | ? | ? | - | - | L | Vérifier source/corpus. |
| `moonshot` | L/P | P | ? | - | ? | P | P | P | - | - | P | Séparer launch, buy/sell, migration. |
| `heaven` | L/P | L/P | L/P | - | L/P | L/P | P | P | - | ? | P | Vérifier AMM vs launch. |
| `goosefx_v1` | L/P | L/P | L/P | ? | ? | ? | ? | ? | ? | ? | ? | Vybe/Demo3 candidates ; source nécessaire. |
| `obric_v2` | L/P | L/P | ? | ? | ? | ? | ? | ? | ? | ? | ? | Bon candidat après sources. |
| `solfi_v2` | L/P | L/P | ? | ? | ? | ? | ? | ? | ? | ? | ? | Bon candidat après sources. |

## Points critiques manquants dans l’ancienne matrice

### `burn`

`burn` doit être une famille de première classe, pas seulement une sous-note. Il peut signaler :

- burn de LP tokens ;
- burn de supply token ;
- fermeture ou destruction indirecte de position ;
- réduction du risque de dump si le burn est réel et vérifié ;
- au contraire, faux signal si le burn ne concerne pas la bonne mint ou si le compte propriétaire est ambigu.

Action : ajouter `burn` à toutes les checklists DEX et aux diagnostics de couverture.

### `transfer`

Les transfers ne sont pas des trades par défaut, mais ils sont nécessaires pour :

- repérer vault movements ;
- détecter migration / liquidity routing ;
- comprendre des orderbook settle/fill ;
- analyser whale movement ou sortie de pool.

Action : prévoir une table dédiée plutôt que tout stocker uniquement dans `payload_json`.

### `account close/create`

Les close/create ATA sont utiles pour détecter :

- fin de route WSOL ;
- sortie de position ;
- cleanup après swap ;
- close open-orders account ;
- activité de bots.

Action : famille dédiée `token_account` / `account_lifecycle`.

## Checklist exhaustive par DEX

Pour chaque DEX/version, la tranche doit remplir un tableau événementiel :

| Colonne | Description |
|---|---|
| `source_repo` | Git/IDL/source utilisée. |
| `source_path` | Chemin exact du fichier source. |
| `decoder_code` | Code interne/upstream. |
| `program_id` | Program id ou `to_verify`. |
| `entry_kind` | `instruction`, `event`, `account`, `log`, `program_data`. |
| `entry_name` | Nom source exact. |
| `discriminator_hex` | Discriminator ou tag. |
| `discriminator_len` | Longueur en octets. |
| `event_family` | Famille commune : swap, burn, admin, order_fill, etc. |
| `local_event_kind` | Event local produit. |
| `local_status` | `not_implemented`, `audit_only`, `decoded`, `materialized`. |
| `db_target` | Table cible ou `k_sol_dex_decoded_events_only`. |
| `proof_status` | Statut upstream/local. |
| `observed_count` | Count local après replay. |
| `materialized_count` | Count table métier. |
| `trade_count` | Count trades générés, doit être 0 sauf swap validé. |
| `notes` | Ambiguïtés, layout, corpus, reste à faire. |

## Requêtes SQL génériques de couverture

### Couverture decoded events par programme

```sql
SELECT
    protocol_name,
    event_kind,
    program_id,
    json_extract(payload_json, '$.upstreamEntryName') AS upstream_entry_name,
    json_extract(payload_json, '$.upstreamDiscriminatorHex') AS upstream_discriminator_hex,
    COUNT(*) AS n
FROM k_sol_dex_decoded_events
GROUP BY
    protocol_name,
    event_kind,
    program_id,
    upstream_entry_name,
    upstream_discriminator_hex
ORDER BY protocol_name, n DESC;
```

### Sécurité trades pour audit-only

```sql
SELECT
    de.protocol_name,
    de.event_kind,
    COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_trade_events te
    ON te.decoded_event_id = de.id
WHERE de.event_kind LIKE '%_audit'
   OR de.protocol_name IN ('upstream_git', 'phoenix_v1', 'openbook_v2')
GROUP BY de.protocol_name, de.event_kind
ORDER BY trade_count DESC;
```

### Vérifier burn/mint présents dans decoded payloads

```sql
SELECT
    protocol_name,
    event_kind,
    json_extract(payload_json, '$.eventLifecycleKind') AS lifecycle,
    json_extract(payload_json, '$.eventActionability') AS actionability,
    COUNT(*) AS n
FROM k_sol_dex_decoded_events
WHERE event_kind LIKE '%burn%'
   OR event_kind LIKE '%mint%'
   OR lifecycle IN ('burn', 'mint')
GROUP BY protocol_name, event_kind, lifecycle, actionability
ORDER BY n DESC;
```

## Décision

À partir de maintenant, une tranche DEX n’est pas complète si elle ne liste que les swaps. Elle doit explicitement indiquer :

- events source listés ;
- events décodés audit-only ;
- events matérialisés ;
- events volontairement non implémentés ;
- events non observés localement ;
- trous de DB éventuels.