233 lines
12 KiB
Markdown
233 lines
12 KiB
Markdown
# 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.
|