# 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 :

```text
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 :

```text
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.

```text
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.

```text
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.

```text
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.

```text
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.

```text
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 :

```text
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.