khadhroony-bobobot/DEX_EVENT_COVERAGE_MATRIX.md

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

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

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

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.