khadhroony-bobobot/docs/DB_EVENT_MODEL_REVIEW.md

Database Event Model Review — khadhroony-bobobot 0.7.47-1FE5

Conclusion courte

La base actuelle est suffisante pour continuer le décodage exhaustif en audit-only, parce que k_sol_dex_decoded_events garde les events décodés avec payload_json.

La base actuelle est partiellement insuffisante pour exploiter tous les events en requêtes métier, parce que certaines familles importantes n’ont pas encore de tables dédiées ou de modèle normalisé :

• transfers SPL / Token-2022 ;
• token account create/close ;
• wrap/unwrap SOL ;
• orderbook orders/fills/settlements ;
• vault deposit/withdraw ;
• launch/migration ;
• lock/unlock LP ;
• staking/unstaking ;
• coverage matrix persistée par discriminator/event.

Ce qui existe déjà

D’après le README, le modèle contient déjà notamment :

• k_sol_chain_transactions;
• k_sol_chain_instructions;
• k_sol_dex_decoded_events;
• k_sol_trade_events;
• k_sol_liquidity_events;
• k_sol_pool_lifecycle_events;
• k_sol_fee_events;
• k_sol_reward_events;
• k_sol_pool_admin_events;
• k_sol_token_mint_events;
• k_sol_token_burn_events;
• k_sol_transaction_classifications;
• k_sol_protocol_candidates;
• k_sol_dex_decode_replay_ledger.

Ces tables couvrent déjà les besoins principaux :

Besoin	Couverture actuelle
Stockage brut/audit de tout event décodé	Oui, via k_sol_dex_decoded_events.payload_json.
Trades/candles	Oui.
Liquidity/lifecycle/fee/reward/admin	Oui, au moins structurellement.
Mint/burn	Oui, structurellement.
Replay/skip sûr	Oui, via ledger.
Event coverage attendu vs observé	Non ou seulement implicite.
Transfers/token account lifecycle	Non spécialisé.
Orderbook events	Non spécialisé.
Vault events	Non spécialisé.
Launch/migration	Non spécialisé ou dispersé.

Ne pas modifier la DB trop vite

Il ne faut pas créer une table pour chaque DEX ou chaque event upstream.

La bonne stratégie :

1. Décoder tout ce qu’on peut en k_sol_dex_decoded_events.
2. Ajouter eventFamily, eventSemanticKind, eventActionability, proofStatus, sourceRepo, sourcePath.
3. Matérialiser seulement les familles prouvées et utiles.
4. Ajouter des tables transversales uniquement quand plusieurs DEX en ont besoin.

Ajouts DB recommandés

1. k_sol_dex_event_coverage_entries

But : stocker ce qui est attendu/listé depuis les sources upstream, même si non observé.

Colonnes conceptuelles :

id
decoder_code
program_id
program_family
surface_kind
source_repo
source_path
entry_kind               -- instruction/event/account/log/program_data
entry_name
discriminator_hex
discriminator_len
event_family             -- swap/burn/mint/admin/etc.
expected_db_target
proof_status
local_event_kind
observed_count
materialized_count
trade_count
first_signature
last_signature
notes
created_at
updated_at

Rôle : rendre la couverture objectivable. Exemple : “Carbon liste 42 instructions Raydium CPMM, notre code en décode 18, 4 sont matérialisées”.

2. k_sol_token_transfer_events

But : matérialiser les transfers significatifs hors trade.

Colonnes conceptuelles :

id
transaction_id
instruction_id
decoded_event_id
signature
slot
program_id
token_program_id
mint
source_token_account
destination_token_account
source_owner
destination_owner
amount_raw
amount_ui
transfer_kind            -- transfer, transfer_checked, routed_transfer, vault_transfer
reason                   -- audit_only, vault_movement, migration, settlement, unknown
payload_json

Important : ne pas créer de trade depuis cette table. Elle sert au risque/analyse.

3. k_sol_token_account_events

But : suivre create/close/init ATA/token accounts.

id
transaction_id
instruction_id
decoded_event_id
signature
slot
event_kind               -- create_ata, init_account, close_account, wrap_sol, unwrap_sol
account_address
mint
owner
token_program_id
lamports_delta
payload_json

Cela aide à comprendre WSOL wrap/unwrap, close accounts, cleanup bots, préparation de trades.

4. k_sol_orderbook_events

But : stocker OpenBook/Phoenix et autres CLOB sans les confondre avec swaps AMM.

id
transaction_id
instruction_id
decoded_event_id
signature
slot
protocol_name
market_account
event_kind               -- order_place, order_cancel, order_fill, settle_funds, consume_events, open_orders_create, open_orders_close
side
price_lots
base_lots
quote_lots
maker
taker
client_order_id
raw_event_name
interpretation_status
payload_json

Les fills ne deviennent trade_events que quand maker/taker, base/quote, lots/decimals et sens économique sont validés.

5. k_sol_vault_events

But : suivre vault deposit/withdraw, Meteora Vault, Kamino/Vault-like programs.

id
transaction_id
instruction_id
decoded_event_id
signature
slot
protocol_name
vault_account
event_kind               -- deposit, withdraw, claim, rebalance, update_config
mint_a
mint_b
amount_a_raw
amount_b_raw
owner
payload_json

6. k_sol_launch_events

But : séparer launch/bonding/migration du DEX effectif.

id
transaction_id
instruction_id
decoded_event_id
signature
slot
launch_protocol
event_kind               -- create, buy, sell, migrate, graduate, initialize_curve, close_curve
token_mint
curve_account
migration_target_program
migration_pool
quote_mint
amount_token_raw
amount_quote_raw
payload_json

7. k_sol_liquidity_lock_events

But : traiter LP lock/unlock explicitement.

id
transaction_id
instruction_id
decoded_event_id
signature
slot
protocol_name
pool_id
pair_id
lock_account
owner
event_kind               -- create_lock, lock, unlock, extend_lock, close_lock
lp_mint
lp_amount_raw
unlock_time
payload_json

Alternative minimaliste

Si on veut éviter trop de migrations immédiates, le minimum à ajouter d’abord est :

1. k_sol_dex_event_coverage_entries;
2. k_sol_token_transfer_events;
3. k_sol_orderbook_events.

Les autres tables peuvent attendre.

Impact sur le plan des versions

Chaque version DEX doit répondre à deux questions :

Couverture decoder

• A-t-on listé tous les events upstream ?
• A-t-on un decoder audit pour chaque discriminator connu ?
• Les events non observés sont-ils marqués upstream_git_mapped_unverified ?

Couverture DB

• L’event peut-il rester dans k_sol_dex_decoded_events ?
• Doit-il être matérialisé dans une table existante ?
• Faut-il une table transversale nouvelle ?
• Une table nouvelle peut-elle servir à plusieurs DEX ?

Décision pratique pour 0.7.48

Avant de reprendre raydium_cpmm, faire une micro-tranche DB/doc :

0.7.48-pre — event coverage + DB model checkpoint

Objectif :

• ajouter ou documenter k_sol_dex_event_coverage_entries;
• ne pas encore ajouter toutes les tables métier ;
• produire un rapport par DEX :
  • listed events,
  • decoded events,
  • materialized events,
  • missing DB target,
  • trade_count invariant.

Note 0.7.48 — Raydium CPMM sans nouvelle table DB

La tranche 0.7.48 confirme que k_sol_dex_decoded_events suffit pour continuer la couverture exhaustive CPMM en audit-only.

Aucune nouvelle table n'est ajoutée pour CPMM :

• les swaps exploitables restent dans k_sol_trade_events via les chemins existants ;
• deposit / withdraw utilisent les tables non-trade existantes seulement si le corpus et le rattachement pool/pair sont fiables ;
• les fees/admin/config/permission restent non-trade et ne peuvent pas produire candles ;
• les transfers SPL, account lifecycle, wrap/unwrap SOL, vault et launch/migration restent des familles transversales futures, à promouvoir seulement si plusieurs DEX en justifient le besoin.

Note 0.7.48 final — Instruction observations et CPMM

La tranche raydium_cpmm ajoute k_sol_instruction_observations comme table technique d’index local, non comme table métier. Elle sert à chercher les instructions observées par decoder_code, instruction_name et discriminator_hex, puis à relier ces observations au corpus backfillé/rejoué.

La matérialisation métier reste limitée aux tables existantes : k_sol_trade_events, k_sol_liquidity_events, k_sol_pool_lifecycle_events, k_sol_fee_events et k_sol_pool_admin_events. Les opérations SPL Token / Token-2022 visibles dans Solscan (burn, transfer, transferChecked, closeAccount) ne sont pas promues en tables métier dans 0.7.48; elles justifient seulement une future table transversale si plusieurs DEX le nécessitent.

Note 0.7.49 — Raydium CLMM sans nouvelle table transversale immédiate

La reprise raydium_clmm confirme que la table k_sol_dex_event_coverage_entries suffit pour inventorier les instructions/events CLMM avant promotion métier. Les entrées IDL-only ajoutées en 0.7.49 restent des lignes de coverage et de recherche, pas des tables métier.

Aucune nouvelle table transversale n'est ajoutée dans ce delta :

• les swaps spécialisés restent dans k_sol_trade_events seulement lorsque les montants et le sens économique sont validés ;
• les liquidity/positions CLMM restent à distinguer : une position NFT/tick n'est pas forcément une liquidity row simple ;
• les fees et rewards peuvent utiliser k_sol_fee_events / k_sol_reward_events seulement après preuve de corpus et typage fin ;
• les side effects SPL Token / Token-2022 (mint, burn, transfer, closeAccount, wrap/unwrap SOL) restent indirects tant qu'une preuve multi-DEX ne justifie pas une table transversale.

La table k_sol_instruction_observations reste technique : elle sert à trouver des signatures et discriminants observés localement, sans être une preuve métier.

Note 0.7.50-pre-r2 — k_sol_token_account_events

La re-vérification Raydium CLMM introduit une table dédiée k_sol_token_account_events pour les événements de cycle de vie de comptes token qui ne sont ni des swaps, ni de la liquidité, ni du lifecycle pool. Le premier cas d'usage est raydium_clmm.create_support_mint_associated.

Règle de matérialisation

• create_support_mint_associated cible k_sol_token_account_events.
• cpi_event reste k_sol_dex_decoded_events_only : c'est un transport Anchor/CPI, pas un event métier autonome.
• liquidity_calculate_event reste k_sol_dex_decoded_events_only : c'est un event de calcul/diagnostic, pas une mutation de liquidité fiable.
• create_operation_account et update_operation_account relèvent de k_sol_pool_admin_events quand le corpus le permet.

Colonnes principales

k_sol_token_account_events conserve transaction_id, decoded_event_id, dex_id, pool_id, pair_id, signature, instruction_index, slot, protocol_name, program_id, event_kind, token_account, token_mint, owner_wallet, account_action, payload_json, executed_at et created_at.

Cette table permet de suivre les événements Token-2022/ATA significatifs sans les confondre avec les trades ou les liquidités.

Note 0.7.50-final — FK-safe cleanup for instruction observations

k_sol_instruction_observations is a technical index table. When a legacy *.instruction_audit decoded event is replaced by a local specialized event, existing observation rows can still point to the old decoded event id on already-created SQLite databases.

The final 0.7.50 cleanup therefore unlinks k_sol_instruction_observations.decoded_event_id before deleting replaced CPMM instruction-audit rows. New databases define the decoded_event_id foreign key with ON DELETE SET NULL for the same reason.

This is not a business-table promotion. It only keeps the technical observation index consistent with decoded event cleanup.