0.7.49
This commit is contained in:
322
docs/DB_EVENT_MODEL_REVIEW.md
Normal file
322
docs/DB_EVENT_MODEL_REVIEW.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user