khadhroony-bobobot/docs/DB_EVENT_MODEL_REVIEW.md

<!-- file: docs/DB_EVENT_MODEL_REVIEW.md -->

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


## Note `0.7.56` — modèle fee parent + amount legs

`0.7.56` ajoute `k_sol_fee_event_amounts` comme table enfant de `k_sol_fee_events`. Cette table est obligatoire dès qu'un event fee porte plusieurs montants, plusieurs mints ou plusieurs destinations. Le parent `k_sol_fee_events` reste l'ancre logique liée au `decoded_event_id`; les legs portent `leg_index`, `token_mint`, `amount_raw`, comptes source/destination et `amount_source`.

Invariants :

- tout parent fee avec `fee_token_mint + fee_amount_raw` doit avoir un leg scalaire automatique ;
- un fee multi-leg/multi-mint ne doit pas agréger artificiellement le parent ;
- les replays doivent supprimer/remplacer les legs avec le parent ;
- les transactions failed restent audit-only ;
- la recovery `allowlisted_inner_spl_transfer` est strictement allowlistée et ne s'applique pas par défaut aux futurs decoders.

Le contrôle standard `parent scalar without leg` doit être vide sur toute base de validation. Voir `docs/reports/FEE_EVENT_AMOUNTS_MODEL_NOTE_0_7_56.md`.

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

## 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.51` — impact AMM v4 sur le modèle DB

Aucune nouvelle table n'est ajoutée pour `raydium_amm_v4`.

Décisions DB maintenues :

- `k_sol_instruction_observations` reste une table technique d'indexation instruction/discriminant ;
- AMM v4 utilise des discriminants d'un octet, donc l'index technique doit conserver `09`, `0b`, `10`, `11`, etc. sans les convertir en discriminants Anchor huit octets ;
- le refresh de `k_sol_instruction_observations` reconstruit les observations par transaction avant upsert, afin de supprimer les restes historiques en huit octets après changement de stratégie d'indexation ;
- les side effects SPL Token / Token-2022 restent transversaux et ne doivent pas être promus comme events directs `raydium_amm_v4.*` ;
- les side effects Serum/OpenBook de AMM v4 doivent être documentés comme contexte orderbook, pas comme trades OpenBook autonomes ;
- `raydium_pool_v4` ne justifie aucune table ni aucun decoder séparé sans corpus local.

Le modèle actuel suffit pour ouvrir la tranche : decoded events + coverage entries + instruction observations + matérialisations existantes trade/liquidity/lifecycle/fee/admin/orderbook. Une extension future orderbook/vault/token-account ne doit être ajoutée qu'après preuves multi-DEX.



### Clôture `0.7.51` — AMM v4 et modèle DB

La validation finale AMM v4 confirme qu'aucune nouvelle table n'est requise pour `raydium_amm_v4`.

Règles validées :

- chaque decoded event AMM v4 matérialisé cible au plus une table métier principale ;
- `migrate_to_open_book`, `monitor_step` et `admin_cancel_orders` alimentent `k_sol_orderbook_events` uniquement ;
- `pre_initialize` alimente `k_sol_pool_lifecycle_events` comme audit deprecated/partial, sans création de paire exploitable ;
- `simulate_info` reste dans `k_sol_dex_decoded_events` uniquement ;
- les `deposit` / `withdraw` sans pool/pair catalogue ou sans deltas exploitables restent decoded-only expliqués ;
- les side effects SPL Token / Token-2022 restent transversaux.

Contrôle final AMM v4 : le SQL `materialized_target_count > 1` doit rester vide.

## 0.7.52 — Raydium Stable Swap DB model decision

No schema migration is introduced for `raydium_stable_swap` at tranche opening.

Stable Swap maps to existing DB targets:

- `initialize` / `pre_initialize` → `k_sol_pool_lifecycle_events` when pool context is sufficient;
- `deposit` / `withdraw` → `k_sol_liquidity_events` when pool/pair context is sufficient;
- `swap_base_in` / `swap_base_out` → `k_sol_trade_events` and candles only when mints and amounts are reliable;
- `swap_event` → `k_sol_dex_decoded_events` only until a corpus-backed materialization decision exists.

Side effects from SPL Token, Token-2022, Serum/OpenBook-style accounts or router transport remain transverse evidence and are not promoted as direct `raydium_stable_swap.*` business events without an explicit later DB decision.