v0.1.0-pre.073
This commit is contained in:
401
olddocs/archivekbobobot/docs/DB_EVENT_MODEL_REVIEW.md
Normal file
401
olddocs/archivekbobobot/docs/DB_EVENT_MODEL_REVIEW.md
Normal file
@@ -0,0 +1,401 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user