Sasedev/khadhroony-bobobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.7.49

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-06-05 14:53:16 +02:00
parent 27e25d5bf4
commit f81e0f3bea
66 changed files with 7655 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/ARCHIVE_ORGANIZATION.md Normal file
View File

@@ -0,0 +1,22 @@
<!-- file: docs/ARCHIVE_ORGANIZATION.md -->
# Organisation de l’archive documentaire
La racine du workspace garde les documents de pilotage principaux :
```text
README.md
ROADMAP.md
CHANGELOG.md
```
Les documents spécialisés sont rangés par usage :
```text
docs/ matrices et revues transversales
docs/reports/ rapports de couverture par tranche DEX/version
docs/prompts/ prompts de reprise de session
validation_sql/ scripts SQL de validation
```
Cette réorganisation ne modifie pas le code Rust/Tauri. Elle sert uniquement à séparer les fichiers de pilotage, les rapports, les prompts et les validations SQL.

322
docs/DB_EVENT_MODEL_REVIEW.md Normal file
View 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.

238
docs/DEX_DECODER_MATRIX.md Normal file
View File

@@ -0,0 +1,238 @@
# DEX Decoder Matrix — `khadhroony-bobobot` `0.7.47-1FE5`
Cette matrice complète `kb_lib/src/dex_support_matrix.rs`. Elle documente **ce qui est fait**, **ce qui reste à faire**, et **le niveau de preuve attendu** par DEX/version.
## Règle de lecture
| Statut | Sens |
|---|---|
| `supported` | Decoder local actif et matérialisation métier possible sur corpus validé. |
| `partial` | Decoder partiel ou surface partielle : des events existent, mais la couverture n’est pas complète. |
| `audit-only` | Decoder local spécialisé, mais aucun trade/candle/matérialisation marché. |
| `planned` | Program id ou surface connue, mais decoder non prioritaire ou non activé. |
| `to_verify` | Source externe ou candidat : aucun statut vérifié sans corpus local. |
| `ignored/historical` | À conserver pour historique ou compatibilité, mais non prioritaire. |
## Sources upstream à comparer
- Carbon decoders : `https://github.com/sevenlabs-hq/carbon/tree/main/decoders`
- Solana Streamer : `https://github.com/0xfnzero/solana-streamer`
- Sol Parser SDK IDLs : `https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl`
- Pinax Substreams Solana IDLs : `https://github.com/pinax-network/substreams-solana-idls/tree/main/src`
- HODL Warden Solana Tx Parser : `https://github.com/hodlwarden/solana-tx-parser/tree/main/src`
- OpenBook v2 : `https://github.com/openbook-dex/openbook-v2`
- Phoenix on-chain MM : `https://github.com/all-in-one-blockchain/phoenix-onchain-mm`
- Vybe DEX/AMM support list : `https://docs.vybenetwork.com/docs/available-dexs-amms`
## Matrice prioritaire DEX/version
| Ordre | DEX/version | État actuel | Fait | Reste à faire |
|---:|---|---|---|---|
| 1 | `raydium_cpmm` | `supported / 0.7.48 closed` | Couverture CPMM clôturée : swaps, lifecycle, fees, admin/config, deposit/withdraw, `lp_change_event`, `swap_event` audit-only. | Réouvrir seulement en cas de nouveau corpus ou divergence upstream. |
| 2 | `raydium_clmm` | `supported / 0.7.49 closed` | Couverture CLMM clôturée : 45 entrées listées, 33 instructions observées/décodées, 25 matérialisées, orderbook events, fallback upstream nettoyé. | 11 Anchor Program-data events restent préparés mais `upstream_git_unverified` faute de corpus local. |
| 3 | `raydium_launchpad` | `planned / 0.7.50` | Prochaine tranche Raydium. | Identifier program ids/IDL, launch/pool creation, migration, fees/admin/config, corpus Solscan/Demo3 puis decoder spécialisé. |
| 4 | `raydium_amm_v4` | `supported / 0.7.51 planned` | Swaps AMM v4 legacy matérialisés. | Reprendre AMM v4 au niveau CPMM/CLMM : pool lifecycle, liquidity, fees/admin, side effects, fallback cleanup. |
| 5 | `raydium_stable_swap` | `planned / 0.7.52` | Entrée conservée. | Reprendre Stable séparément : swaps stables, pool lifecycle, liquidity, fees/admin, montants/prix exploitables. |
| 6 | `pump_swap` | `supported / 0.7.53 planned` | `buy`/`sell` décodés et matérialisés ; trade/candle OK. | Ajouter tous les events Carbon/Solana Streamer : cashback, fee, volume accumulator, admin/config ; conserver les non-trades hors candles. |
| 7 | `pump_fun` | `partial / launch_surface` | Création/token launch partiellement décodée ; intégrée au pipeline de listings. | Traiter tous les events Pump.fun disponibles : buy/sell/migrate/create/update ; séparer bonding/launch de DEX effectif ; valider migration vers PumpSwap. |
| 8 | `meteora_dbc` | `partial` | Swaps/instruction audits observés ; Demo3 donne du corpus. | Couverture complète DBC : launch/bonding curve, swap, migration, config/admin, fees ; matérialiser seulement ce qui est prouvé. |
| 9 | `meteora_dlmm` | `supported` | Couverture avancée validée en `0.7.45` : swaps, liquidity, positions, lifecycle, fees ; non-trade matérialisé. | Résoudre les audits résiduels non mappés ; comparer Carbon/IDL pour events rewards/admin restants ; revalidation base neuve. |
| 10 | `meteora_damm_v1` | `supported / partial events` | Couverture `0.7.46` : swap, create_pool, add/remove liquidity, claim_fee, create_lock_escrow, lock_liquidity. | Vérifier les surfaces upstream non observées ; améliorer rattachement pool/pair pour remove_liquidity non matérialisés ; revalidation stricte. |
| 11 | `meteora_damm_v2` | `partial` | `swap`, `instruction_audit`, registry/discriminants et corpus Demo3 existent. | Couvrir tous les events Carbon/source : create pool, liquidity, fees, dynamic config, admin ; déterminer actionability des swaps ; matérialiser si montants fiables. |
| 12 | `phoenix_v1` | `audit-only` | Decoder local audit-only ; `log_audit`, order place/cancel, withdraw ; parsing strict `0x0f`; events `Reduce`, `Place`, `TimeInForce` observés ; `trade_count=0`. | Terminer tous les events Git : `Fill`, `FillSummary`, `Fee`, `Evict`, `ExpiredOrder`, etc. ; ajouter counts/flags audit ; seulement ensuite étudier trade materialization. |
| 13 | `openbook_v2` | `audit-only` | Decoder local audit-only ; instructions order/cancel/consume/settle ; `Program data` mappé : `FillLog`, `OpenOrdersPositionLog`, `TotalOrderFillEvent`, `SettleFundsLog`; `trade_count=0`. | Vérifier layouts fill/out et sens maker/taker/base/quote ; ajouter table audit éventuelle ; ne matérialiser trades qu’après validation du sens économique. |
| 14 | `orca_whirlpools` | `partial` | Premier decoder historique présent ; swaps/create_pool partiels. | Comparer Carbon/IDL complet ; couvrir liquidity, positions, fees/rewards, tick arrays ; valider swaps exploitables et non-trades. |
| 15 | `legacy_launch_candidates` | `planned launch` | Anciennes entrées launch à réévaluer après `raydium_launchpad`. | Ne pas confondre Launchpad, LaunchLab, CPMM/CLMM/AMM v4 ; rattacher aux pools tradables seulement après corpus. |
| 16 | `meteora_vault` | `to_verify` | Présent comme indice upstream / compte associé. | Corpus direct obligatoire ; decoder séparé si events vault réels ; aucune promotion via DAMM indirect. |
| 17 | `fluxbeam` | `partial/to_verify` | Decoder initial existant ; Demo3 peut produire des candidats. | Vérifier source/IDL ; compléter swap, pool, liquidity, fees/admin ; matérialisation uniquement après corpus. |
| 18 | `dexlab` | `partial/to_verify` | Decoder initial historique ; ancienne entrée beta supprimée. | Reconfirmer program id/source ; décoder events disponibles ; distinguer DexLab natif et liens OpenBook/market. |
| 19 | `lifinity_v2` | `to_verify` | Program id listé par sources externes/Vybe ; pas de corpus concluant. | Trouver IDL/source ; Demo3 par program/market ; audit-only d’abord. |
| 20 | `stabble_stable_swap` / `stabble_weighted_swap` | `to_verify` | Program ids/indices via sources externes ; candidats Demo3 observables. | Source/IDL + corpus + decoder audit-only ; déterminer surface AMM et montants exploitables. |
| 21 | `bonkswap` | `to_verify` | Program id/Carbon/Vybe selon registre ; swaps candidats possibles. | Vérifier program id, source et corpus ; décoder tous events ; pas de trade sans montants. |
| 22 | `boop` / `boop_fun` | `to_verify / launch` | Entrée de découverte. | Séparer launch surface et swap effectif ; corpus + source obligatoire. |
| 23 | `moonshot` / `moonit` | `to_verify / launch` | Moonshot buy/sell observés via upstream candidates ; Moonit launch attribution historique. | Source/IDL + migration + rattachement pools ; éviter heuristiques seules. |
| 24 | `heaven` | `to_verify` | Program id/candidat ajouté en matrice. | Vérifier s’il est launch, AMM ou les deux ; corpus dédié. |
| 25 | `printr` | `to_verify` | Preset Demo3 ajouté ; candidats observables. | Source/IDL, discriminants, corpus, decoder audit-only. |
| 26 | `metadao_*` | `to_verify` | Presets spécifiques : launchpad, bid wall, futarchy, AMM. | Traiter par programme séparé ; ne pas utiliser mint ids comme program ids ; corpus obligatoire. |
| 27 | `jupiter_*`, `dflow_aggregator_v4`, `okx_dex` | `aggregator_router` | Registry/discovery pour contexte transactionnel. | Ne pas matérialiser en DEX direct ; utiliser pour routeSource/routing/context. |
## Checklist obligatoire par DEX/version
Pour chaque DEX ou version, la tranche doit fermer les points suivants :
- [ ] Source Git/IDL recensée.
- [ ] Tous les `program_id` vérifiés localement ou marqués `to_verify`.
- [ ] Tous les discriminants d’instructions listés.
- [ ] Tous les discriminants d’events/logs listés.
- [ ] Demo3 corpus constitué.
- [ ] Demo2 backfill de signatures réussies.
- [ ] Replay forcé sur base `0.7.47+`.
- [ ] SQL : decoded events par kind.
- [ ] SQL : `trade_count=0` pour audit-only.
- [ ] SQL : trade/candle uniquement si montants exploitables.
- [ ] Cleanup `upstream_git.instruction_match` si decoder spécialisé local.
- [ ] Décision finale : `audit-only`, `materialized`, `partial`, ou `to_verify`.
## Notes de matérialisation
Un event peut devenir `materialized` uniquement si :
1. la transaction est `OK` ;
2. les comptes nécessaires sont identifiés ;
3. les mints sont fiables ;
4. les montants sont fiables ;
5. le sens base/quote est validé ;
6. les requêtes SQL prouvent l’absence de faux trades/candles ;
7. les tests et clippy sont verts.
## Annexe — snapshot de `kb_lib/src/dex_support_matrix.rs` (`1FE5`)
| Code | Rôle | Surface | Program id status | Observed | Decoded | Materialized | Status | Skip reason |
|---|---|---|---|---:|---:|---:|---|---|
| `pump_fun` | `launch_surface` | `launch` | `known` | non | oui | oui | `partial` | launch_surface_requires_migration_linking_before_live_trading |
| `pump_swap` | `dex_effective` | `AMM` | `known` | oui | oui | oui | `supported` | |
| `raydium_cpmm` | `dex_effective` | `AMM` | `known` | oui | oui | oui | `supported` | |
| `raydium_clmm` | `dex_effective` | `CLMM` | `known` | oui | oui | oui | `supported` | |
| `raydium_amm_v4` | `dex_effective` | `AMM` | `known` | oui | oui | oui | `supported` | |
| `raydium_launchlab` | `launch_surface` | `launch` | `known` | non | non | non | `planned` | decoder_and_materialization_not_enabled |
| `raydium_liquidity_locking` | `to_verify` | `liquidity_locking` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `raydium_router` | `aggregator_router` | `router` | `known` | non | non | non | `partial` | router_not_materialized_as_direct_trade_surface |
| `raydium_stable_swap` | `dex_effective` | `AMM` | `known` | non | non | non | `planned` | deprecated_program_not_prioritized |
| `meteora_dlmm` | `dex_effective` | `DLMM` | `known` | oui | oui | oui | `supported` | |
| `meteora_dlc` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | surface_and_program_id_to_verify |
| `meteora_damm_v1` | `dex_effective` | `AMM` | `known` | oui | oui | non | `partial` | meteora_damm_v1_swap_without_amount_payload |
| `meteora_damm_v2` | `dex_effective` | `AMM` | `known` | non | oui | oui | `partial` | not_observed_in_0_7_28_replay |
| `meteora_dbc` | `dex_effective` | `bonding_curve` | `known` | non | oui | oui | `partial` | not_observed_in_0_7_28_replay |
| `orca_whirlpools` | `dex_effective` | `CLMM` | `known` | non | oui | oui | `partial` | not_observed_in_0_7_28_replay |
| `fluxbeam` | `dex_effective` | `AMM` | `known` | non | oui | oui | `partial` | not_observed_in_0_7_28_replay |
| `dexlab` | `dex_effective` | `AMM` | `known` | non | oui | oui | `partial` | not_observed_in_0_7_28_replay |
| `bags` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `letsbonk` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `bonk` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `bonk_fun` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `okx_dex` | `aggregator_router` | `aggregator` | `to_verify` | non | non | non | `planned` | program_id_to_verify |
| `boop_fun` | `launch_surface` | `launch` | `to_verify` | non | non | non | `planned` | program_id_to_verify |
| `moonshot` | `launch_surface` | `launch` | `to_verify` | non | non | non | `planned` | historical_entities_py_program_id_requires_corpus_verification |
| `believe` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `metadao` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | umbrella_surface_programs_split_into_specific_discovery_targets |
| `metadao_launchpad_v0_7_0` | `to_verify` | `launch` | `to_verify` | non | non | non | `to_verify` | official_metadao_program_id_requires_local_corpus_verification |
| `metadao_bid_wall_v0_7_0` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | official_metadao_program_id_requires_local_corpus_verification |
| `metadao_futarchy_v0_6_0` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | official_metadao_program_id_requires_local_corpus_verification |
| `metadao_amm_v0_5_0` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | official_metadao_program_id_requires_local_corpus_verification |
| `printr` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | solscan_program_label_requires_local_corpus_verification |
| `zora` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | solscan_program_label_requires_local_corpus_verification |
| `moonit` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `launchbeam` | `launch_surface` | `launch` | `unknown` | non | non | non | `planned` | program_id_to_verify |
| `heaven` | `launch_surface` | `launch` | `to_verify` | non | non | non | `planned` | program_id_to_verify |
| `gavel` | `to_verify` | `auction` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `pump_fees` | `to_verify` | `fee_program` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `meteora_pools` | `dex_effective` | `AMM` | `alias_of_meteora_damm_v1` | non | non | non | `to_verify` | program_id_alias_held_by_meteora_damm_v1 |
| `dflow_aggregator_v4` | `aggregator_router` | `aggregator` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `drift_v2` | `to_verify` | `perps` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_swap` | `aggregator_router` | `aggregator` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_dca` | `aggregator_router` | `dca` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_limit_order` | `aggregator_router` | `limit_order` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_limit_order_2` | `aggregator_router` | `limit_order` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_perpetuals` | `to_verify` | `perps` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `jupiter_lend` | `to_verify` | `lending` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `kamino_lending` | `to_verify` | `lending` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `kamino_vault` | `to_verify` | `vault` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `kamino_farms` | `to_verify` | `farms` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `kamino_limit_order` | `to_verify` | `limit_order` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `marginfi_v2` | `to_verify` | `lending` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `onchain_labs_dex_v1` | `dex_effective` | `AMM` | `alias_of_okx_dex` | non | non | non | `to_verify` | program_id_alias_held_by_okx_dex |
| `onchain_labs_dex_v2` | `dex_effective` | `AMM` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `pancake_swap` | `dex_effective` | `AMM` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `vertigo` | `dex_effective` | `AMM` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `virtuals` | `launch_surface` | `launch` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `wavebreak` | `dex_effective` | `AMM` | `to_verify` | non | non | non | `to_verify` | upstream_git_program_id_requires_local_corpus_verification |
| `aldrin` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `aldrin_v2` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `crema` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `cropper` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `lifinity_v1` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `lifinity_v2` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `mercurial` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `orca_v1` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `orca_v2` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `phoenix` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `saber` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `saber_decimals` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `openbook_v2` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `fox` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `sanctum_infinity` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `saros` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `stabble_stable_swap` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `stabble_weighted_swap` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `stepn` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `solayer` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `penguin` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `sanctum` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `one_dex` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `solfi` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `bonkswap` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `guacswap` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `invariant` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `oasis` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `token_swap` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `helium_network` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `marinade_liquid_staking` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `francium_yield_pools` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `marinade_governance` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `serum_dao` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `port_finance` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `solend_classic` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `hyperspace_nft_amm` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `magic_eden_nft_amm` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `raydium_staking_early` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `orca_aquafarm_v1` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `quarry_merge_mining` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | historical_entities_py_program_id_requires_corpus_verification |
| `goosefx_v1` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `obric_v2` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `ondo_global_market` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `scorch` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `zerofi` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `manifest_clob` | `to_verify` | `orderbook` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `alphaq` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `goonfi` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `goonfi_v2` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `byreal` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `bisonfi` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `fusionamm` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `woofi` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `aquifer` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `humidifi` | `to_verify` | `unknown` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
| `solfi_v2` | `to_verify` | `AMM` | `to_verify` | non | non | non | `to_verify` | vybe_supported_dex_amm_requires_local_corpus_and_decoder_source |
## Note `0.7.48` — Raydium CPMM
`raydium_cpmm` reste `supported`, mais sa couverture est maintenant explicitée au niveau entry/event coverage.
Entrées CPMM couvertes localement depuis Carbon/fnzero/IDL :
- swaps : `swap_base_input`, `swap_base_output` ;
- events Anchor self-CPI audit-only : `lp_change_event`, `swap_event` ;
- pool/lifecycle : `initialize`, `initialize_with_permission` ;
- liquidity : `deposit`, `withdraw` ;
- fees : `collect_creator_fee`, `collect_fund_fee`, `collect_protocol_fee` ;
- admin/config/permission : `create_amm_config`, `update_amm_config`, `update_pool_status`, `create_permission_pda`, `close_permission_pda`.
`create_amm_config` est traité comme admin/config, pas comme pool creation. `swap_event` est conservé comme audit-only pour ne pas doubler les trades matérialisés depuis les instructions `swap_base_input` / `swap_base_output`.
## Note `0.7.48 final` — Raydium CPMM
`raydium_cpmm` est considéré `supported` et clôturable pour la tranche `0.7.48`. Les entrées matérialisées couvrent swaps (`swap_base_input`, `swap_base_output`), liquidity (`deposit`, `withdraw`, `lp_change_event`), lifecycle (`initialize`, `initialize_with_permission`), fees (`collect_creator_fee`, `collect_fund_fee`, `collect_protocol_fee`) et admin/config (`create_amm_config`, `create_permission_pda`, `update_amm_config`).
`swap_event` reste audit-only pour éviter tout doublon de trade/candle. `close_permission_pda` et `update_pool_status` restent connus upstream mais non observés localement.
## Note `0.7.49` — Raydium CLMM initial coverage sync
`raydium_clmm` reste `supported`, mais la tranche `0.7.49` rouvre sa couverture événementielle complète au lieu de se limiter aux swaps.
État local repris : `swap`, `swap_v2`, `increase_liquidity_v2`, `decrease_liquidity_v2`, `open_position_with_token22_nft` et `close_position` disposent déjà d'un chemin local spécialisé ou mappé. Les autres entrées CLMM restent à confirmer par corpus avant toute promotion.
Le registre est complété avec les entrées issues de l'IDL officiel Raydium non présentes dans le snapshot Carbon courant : `close_limit_order`, `close_protocol_position`, `create_customizable_pool`, `create_dynamic_fee_config`, `create_support_mint_associated` et `settle_limit_order`.
Règle de clôture : les positions CLMM, fees/rewards et surfaces limit-order ne doivent produire aucune ligne trade/candle tant que le sens économique, les montants, les comptes et les mints ne sont pas prouvés par replay local.

102
docs/DEX_EVENT_COVERAGE_MATRIX.md Normal file
View File

@@ -0,0 +1,102 @@
# DEX Event Coverage Matrix — `khadhroony-bobobot` `0.7.49`
Cette matrice complète `docs/DEX_DECODER_MATRIX.md` avec une lecture par familles d'événements. Elle ne remplace pas la preuve locale : une entrée Git/IDL reste un indice tant qu'elle n'est pas observée dans le corpus local puis validée par replay et SQL.
## Règles de statut
| Statut | Sens |
|---|---|
| `decoded` | Un decoder local produit un event spécialisé ou un event audit-only classé. |
| `materialized` | L'event alimente une table métier existante validée par corpus. |
| `audit-only` | L'event reste dans `k_sol_dex_decoded_events` et ne produit jamais trade/candle. |
| `upstream_git_mapped_unverified` | L'entrée est connue depuis Carbon/fnzero/IDL, mais non observée localement. |
| `not_applicable` | La famille n'existe pas pour ce DEX/version ou appartient à un autre programme. |
## `0.7.48` — `raydium_cpmm`
Sources inventoriées : Carbon `carbon-raydium-cpmm-decoder`, fnzero `solana-streamer` / `sol-parser-sdk` IDL `raydium_cpmm.json`.
| Famille | Entrées Raydium CPMM | Statut `0.7.48` | Cible DB | Justification / règle |
|---|---|---|---|---|
| `swap` | `swap_base_input`, `swap_base_output`, `swap_event` | `materialized` pour `swap_base_*`; `swap_event` audit-only | `k_sol_trade_events` seulement pour `swap_base_*`; `k_sol_dex_decoded_events_only` pour `swap_event` | `swap_event` est décodé mais ne produit jamais trade/candle afin d'éviter les doublons. |
| `pool_create` | `initialize`, `initialize_with_permission` | `materialized` | `k_sol_pool_lifecycle_events` | `initialize_with_permission` est lifecycle-only et ne crée plus d'admin row. |
| `add_liquidity` | `deposit`, `lp_change_event(changeType=0)` | `materialized` | `k_sol_liquidity_events` | `deposit` et `lp_change_event(changeType=0)` matérialisent liquidity, sans trade/candle. |
| `remove_liquidity` | `withdraw`, `lp_change_event(changeType=1)` | `materialized` | `k_sol_liquidity_events` | `withdraw` et `lp_change_event(changeType=1)` matérialisent liquidity, sans trade/candle. |
| `position_open` | `-` | `not_applicable` | `-` | CPMM n'a pas de position CLMM. |
| `position_close` | `-` | `not_applicable` | `-` | CPMM n'a pas de position CLMM. |
| `fee` | `collect_creator_fee`, `collect_fund_fee`, `collect_protocol_fee` | `materialized` | `k_sol_fee_events` | Les trois familles de fee CPMM observées sont matérialisées avec `trade_count=0`. |
| `reward` | `-` | `not_applicable` | `-` | Aucune entrée reward CPMM dans Carbon/fnzero IDL inventoriée pour cette tranche. |
| `admin/config` | `create_amm_config`, `update_amm_config`, `create_permission_pda`, `update_pool_status`, `close_permission_pda` | `materialized` pour les entrées observées ; `upstream_git_mapped_unverified` pour `update_pool_status` / `close_permission_pda` | `k_sol_pool_admin_events` ou decoded-only selon corpus | `create_amm_config`, `create_permission_pda` et `update_amm_config` sont matérialisés ; les deux autres restent non observés localement. |
| `mint` | `-` direct | `not_applicable` | `-` | Mint LP implicite possible dans les instructions, mais pas d'instruction CPMM `mint` dédiée. |
| `burn` | `-` direct | `not_applicable` | `-` | Burn LP implicite possible dans `withdraw`, mais pas d'instruction CPMM `burn` dédiée. |
| `transfer` | SPL Token inner transfers | `audit-only` indirect | `k_sol_dex_decoded_events` pour cette tranche | Pas de table `k_sol_token_transfer_events` ajoutée en `0.7.48`. |
| `account_create` | comptes système/ATA indirects | `audit-only` indirect | decoded-only | Hors programme CPMM direct. |
| `account_close` | comptes système/ATA indirects | `audit-only` indirect | decoded-only | Hors programme CPMM direct. |
| `wrap_sol` | user/router side | `not_applicable` | `-` | Préparation WSOL hors CPMM. |
| `unwrap_sol` | user/router side | `not_applicable` | `-` | Cleanup WSOL hors CPMM. |
| `order_place` | `-` | `not_applicable` | `-` | CPMM est AMM, pas orderbook. |
| `order_cancel` | `-` | `not_applicable` | `-` | CPMM est AMM, pas orderbook. |
| `order_fill` | `-` | `not_applicable` | `-` | CPMM est AMM, pas orderbook. |
| `consume_events` | `-` | `not_applicable` | `-` | CPMM est AMM, pas orderbook. |
| `settle_funds` | `-` | `not_applicable` | `-` | CPMM est AMM, pas orderbook. |
| `vault_deposit` | `-` | `not_applicable` | `-` | Les vaults CPMM sont des comptes de pool, pas une surface vault séparée. |
| `vault_withdraw` | `-` | `not_applicable` | `-` | Les vaults CPMM sont des comptes de pool, pas une surface vault séparée. |
| `lock` | `-` | `not_applicable` | `-` | Raydium liquidity locking est une surface séparée. |
| `unlock` | `-` | `not_applicable` | `-` | Raydium liquidity locking est une surface séparée. |
| `launch` | `-` | `not_applicable` | `-` | Raydium LaunchLab/Launchpad est séparé de CPMM. |
| `migration` | `-` | `not_applicable` | `-` | Les migrations launch → pool relèvent des launch surfaces. |
| `stake` | `-` | `not_applicable` | `-` | Hors CPMM. |
| `unstake` | `-` | `not_applicable` | `-` | Hors CPMM. |
| `unknown/unmapped audit` | `raydium_cpmm.instruction_audit` | `audit-only` | `k_sol_dex_decoded_events_only` | Toute instruction observée mais non mappée reste audit-only et ne produit jamais trade/candle. |
## Validation attendue
- `k_sol_dex_event_coverage_entries.decoder_code = 'raydium_cpmm'` contient toutes les entrées Carbon/fnzero synchronisées.
- `upstream_git.instruction_match` ne doit plus apparaître pour une instruction CPMM remplacée par un decoder local spécialisé.
- Les familles non-trade CPMM doivent rester `trade_count = 0`.
- Les transactions failed CPMM doivent rester décodées/auditables mais non matérialisées en trade/candle.
## Note `0.7.48-part2-fix2` — CPMM official instruction parity
La couverture `raydium_cpmm` est alignée avec les instructions exposées par le programme officiel Raydium CP-Swap et par Carbon : `create_amm_config`, `update_amm_config`, `update_pool_status`, `collect_protocol_fee`, `collect_fund_fee`, `collect_creator_fee`, `create_permission_pda`, `close_permission_pda`, `initialize`, `initialize_with_permission`, `deposit`, `withdraw`, `swap_base_input`, `swap_base_output`, `lp_change_event` et `swap_event`.
`lp_change_event` est maintenant classé `event_family=liquidity` dans la table coverage, parce que l'event couvre à la fois dépôt et retrait. La matérialisation reste déterminée par `changeType` dans le payload décodé : `0` = add/deposit, `1` = remove/withdraw.
## Note `0.7.48 final` — Raydium CPMM clôturable
Validation finale locale : `deposit` = `11/11` liquidity, `withdraw` = `14/14` liquidity, `lp_change_event` = `25/25` liquidity, fees = `26/26` fee, admin/config observés = `23/23` admin, lifecycle = `9/9`, `swap_event` = audit-only avec `0` trade, et trades matérialisés uniquement depuis `swap_base_input` / `swap_base_output`.
`close_permission_pda` et `update_pool_status` restent `upstream_git_mapped_unverified` faute de corpus local. Les filtres Solscan `instruction=9c5420764587467b` et `instruction=82576c062ee0757b` n'ont pas fourni de signatures exploitables dans l'horizon testé.
## `0.7.49` — `raydium_clmm` final coverage
Sources inventoriées : Carbon `raydium-clmm-decoder`, fnzero `sol-parser-sdk`, Pinax `substreams-solana-idls/src/raydium/clmm`, Raydium/Solscan Program IDL.
État final validé : `45` entrées listées, `33` instructions locales observées/décodées, `25` entrées matérialisées, `1186` trades, `raydium_clmm.instruction_audit = 0`, fallback `upstream_git.instruction_match` localement couvert = `0`.
| Famille | Entrées Raydium CLMM | Statut `0.7.49` | Cible DB | Justification / règle |
|---|---|---|---|---|
| `swap` | `swap`, `swap_v2` | `materialized` | `k_sol_trade_events` | Seuls ces swaps produisent trades/candles lorsque les montants sont exploitables. |
| `swap audit` | `swap_event`, `swap_router_base_in` | `observed/audit` ou `upstream_git_unverified` selon corpus | `k_sol_dex_decoded_events_only` | Pas de double trade/candle. |
| `pool_create` | `create_pool`, `create_customizable_pool` | `decoded`; `create_pool` matérialisé quand prouvé | `k_sol_pool_lifecycle_events` | Création de pool = lifecycle, pas admin. |
| `add_liquidity` | `increase_liquidity`, `increase_liquidity_v2`, open position variants | `decoded`; variantes prouvées matérialisées | `k_sol_liquidity_events` | CLMM implique position/tick/NFT ; matérialisation seulement sur corpus OK. |
| `remove_liquidity` | `decrease_liquidity`, `decrease_liquidity_v2`, close position variants | `decoded`; variantes prouvées matérialisées | `k_sol_liquidity_events` | Aucune promotion trade/candle. |
| `fee` | `collect_fund_fee`, `collect_protocol_fee` | `decoded`; protocol fee matérialisé si tx OK | `k_sol_fee_events` | Mapping fee sans trade/candle. |
| `reward` | `initialize_reward`, `collect_remaining_rewards`, `set_reward_params`, `transfer_reward_owner`, `update_reward_infos` | `decoded`; variantes prouvées matérialisées | `k_sol_reward_events` / `k_sol_pool_admin_events` | Reward/config selon instruction. |
| `admin/config` | `create_amm_config`, `create_dynamic_fee_config`, `create_operation_account`, `update_amm_config`, `update_operation_account`, `update_pool_status` | `decoded`; variantes prouvées matérialisées | `k_sol_pool_admin_events` ou decoded-only | Config/admin sans trade/candle. |
| `account_create` | `create_support_mint_associated` | `observed/decoded` | `k_sol_token_account_events` prévu / decoded-only selon corpus | Side effect technique ; pas de trade/candle. |
| `order_place` | `open_limit_order`, `increase_limit_order` | `decoded/materialized` | `k_sol_orderbook_events` | Orderbook CLMM, jamais trade/candle. |
| `order_cancel` | `decrease_limit_order`, `close_limit_order` | `decoded/materialized` | `k_sol_orderbook_events` | Orderbook CLMM, jamais trade/candle. |
| `settle_funds` | `settle_limit_order` | `decoded/materialized` | `k_sol_orderbook_events` | Settlement orderbook, pas trade direct. |
| `mint/burn/transfer/account_close/wrap/unwrap` | Side effects SPL Token / Token-2022 | `indirect` | decoded-only | Pas de promotion en `raydium_clmm.*` sans instruction directe. |
| `launch/migration/lock/unlock/stake/unstake/vault` | `-` | `not_applicable` | `-` | Surfaces hors CLMM direct. |
| `unknown/unmapped audit` | `raydium_clmm.instruction_audit`, fallback upstream | `closed` | `k_sol_dex_decoded_events_only` | Résidu validé à zéro après replay. |
Les 11 Anchor / `Program data` events restent `upstream_git_unverified` et préparés audit-only faute d’observation locale : `collect_personal_fee_event`, `collect_protocol_fee_event`, `config_change_event`, `create_personal_position_event`, `decrease_liquidity_event`, `increase_liquidity_event`, `liquidity_calculate_event`, `liquidity_change_event`, `pool_created_event`, `swap_event`, `update_reward_infos_event`.
## `0.7.50` — `raydium_launchpad` planned
Prochaine tranche : identifier program ids/IDL, lister instructions/events/discriminants, constituer corpus Demo3/Solscan/Demo2, puis appliquer les mêmes règles de coverage et matérialisation que CPMM/CLMM.

191
docs/prompts/NEXT_SESSION_PROMPT_0.7.47_1FE5_CONTINUATION_V2.md Normal file
View File

@@ -0,0 +1,191 @@
# Prompt de reprise — khadhroony-bobobot `0.7.47-1FE5`
Reprise du projet `khadhroony-bobobot`.
## Archive de départ
Utiliser comme base de travail :
```text
kb_lib-v0.7.47-1FE5-full.zip
```
Joindre aussi les docs mises à jour :
```text
README.md
ROADMAP.md
CHANGELOG.md
docs/DEX_DECODER_MATRIX.md
```
## Décision de planification
Ne plus tenter “tous les events de tous les decoders” dans une seule session. L’objectif reste de couvrir tous les decoders disponibles dans Carbon et les sources Git/IDL, mais par tranches DEX/version.
Ordre cible :
```text
raydium_cpmm
raydium_clmm
pump_swap
pump_fun
meteora_dbc
meteora_dlmm
meteora_damm_v1
meteora_damm_v2
phoenix_v1
openbook_v2
orca_whirlpools
launch surfaces
DEX historiques / candidats
```
## Sources upstream obligatoires
Ces sources sont des indices de décodage, pas des preuves de validation locale :
```text
https://github.com/sevenlabs-hq/carbon/tree/main/decoders
https://github.com/0xfnzero/solana-streamer
https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
https://github.com/pinax-network/substreams-solana-idls/tree/main/src
https://github.com/hodlwarden/solana-tx-parser/tree/main/src
https://github.com/openbook-dex/openbook-v2
https://github.com/all-in-one-blockchain/phoenix-onchain-mm
https://docs.vybenetwork.com/docs/available-dexs-amms
```
## État validé
Dernier état validé côté `kb_lib` :
```text
cargo test -p kb_lib
371 passed
```
Clippy doit être relancé à chaque tranche :
```bash
cargo clippy -p kb_lib --all-targets -- -D warnings
```
## 0.7.47 acquis
- Upstream Git Registry ajouté.
- Demo3 étendu : multi-target, multi-source, pagination, orderbook targets, burn/mint/transfer/wrap/unwrap/stake.
- Demo2 backfill signature fonctionnel.
- Replay local avec ledger.
- OpenBook v2 decoder audit-only.
- Phoenix v1 decoder audit-only.
- Les decoders audit-only ne produisent aucun trade/candle.
## OpenBook v2
Program id :
```text
opnb2LAfJYbRMAHHvqjCwQxanZn7ReEHp1k81EohpZb
```
État :
```text
audit-only local decoder
upstream_git fallback cleaned
Program data mapped:
- FillLog
- OpenOrdersPositionLog
- TotalOrderFillEvent
- SettleFundsLog
trade_count = 0
```
Ne pas activer de trade/candle tant que maker/taker/base/quote et les lots ne sont pas validés.
## Phoenix v1
Program id :
```text
PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY
```
État :
```text
audit-only local decoder
log instruction strict 0x0f
events observed:
- Reduce
- Place
- TimeInForce
currentInstructionTag mappings:
- 0x09 CancelUpToWithFreeFunds
- 0x0c WithdrawFunds
- 0x10 PlaceMultiplePostOnlyOrders
trade_count = 0
```
Prochaine action préférée : finir Phoenix v1 avec tous les events disponibles dans les sources Git/IDL, mais rester audit-only jusqu’à validation économique.
## Contraintes
- Rust 2024.
- Pas de `mod.rs`.
- Fichiers Rust avec entête `// file: ...`.
- Exposition centralisée via `lib.rs`.
- `#![deny(unreachable_pub)]`, `#![warn(missing_docs)]`.
- Pas de `anyhow`.
- Pas de `thiserror`.
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
- Utiliser `match`, `if let Err`, `let Err = ... else`.
- Si une requête DB est ajoutée/modifiée, mettre à jour `kb_lib/src/db.rs`, puis `kb_lib/src/lib.rs` si nécessaire.
## Méthode par DEX/version
Pour chaque DEX/version :
1. inspecter Carbon + autres sources Git/IDL ;
2. lister tous les discriminants instructions/events ;
3. compléter `upstream_registry` / matrice si nécessaire ;
4. utiliser Demo3 pour corpus ;
5. backfill Demo2 ;
6. replay forcé ;
7. valider SQL ;
8. ajouter decoder audit-only ou materialized selon preuve ;
9. supprimer les doublons `upstream_git.instruction_match` si decoder spécialisé ;
10. ne jamais produire trade/candle sans montants exploitables et sens économique validé.
## Requêtes de sécurité audit-only
```sql
SELECT
de.protocol_name,
de.event_kind,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name IN ('openbook_v2', 'phoenix_v1')
GROUP BY de.protocol_name, de.event_kind
ORDER BY trade_count DESC;
```
Attendu :
```text
trade_count = 0
```
## Livrable attendu
Pour chaque tranche :
- fichiers ajoutés/modifiés seulement ;
- archive zip ;
- commandes de test ;
- requêtes SQL ;
- notes sur ce qui reste non vérifié ;
- ne pas prétendre qu’un event ou program id est vérifié sans corpus local.

155
docs/prompts/NEXT_SESSION_PROMPT_0.7.47_EVENT_COVERAGE_V3.md Normal file
View File

@@ -0,0 +1,155 @@
# Prompt de reprise — khadhroony-bobobot `0.7.47-1FE5` / Event coverage
Reprise du projet `khadhroony-bobobot`.
## Archive de départ
Utiliser :
```text
khadhroony-bobobot-v0.7.47-1FE5-full.zip
```
Et les docs :
```text
README.md
ROADMAP.md
CHANGELOG.md
docs/DEX_DECODER_MATRIX.md
docs/DEX_EVENT_COVERAGE_MATRIX.md
docs/DB_EVENT_MODEL_REVIEW.md
```
## Décision de reprise
Ne pas essayer de “faire tous les events de tous les DEX” dans une seule session.
La stratégie est maintenant :
```text
un DEX/version = une tranche
tous les events listés = audit coverage
matérialisation seulement après corpus + SQL + invariants
```
## Sources Git/IDL à utiliser systématiquement
- https://github.com/sevenlabs-hq/carbon/tree/main/decoders
- https://github.com/0xfnzero/solana-streamer
- https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
- https://github.com/pinax-network/substreams-solana-idls/tree/main/src
- https://github.com/hodlwarden/solana-tx-parser/tree/main/src
- https://github.com/openbook-dex/openbook-v2
- https://github.com/all-in-one-blockchain/phoenix-onchain-mm
- https://docs.vybenetwork.com/docs/available-dexs-amms
## Objectif événementiel
Décoder le maximum d’events, pas seulement les swaps.
Inclure explicitement :
```text
swap
pool_create
add_liquidity
remove_liquidity
position_open
position_close
fee
reward
admin/config
mint
burn
transfer
account_create
account_close
wrap_sol
unwrap_sol
order_place
order_cancel
order_fill
consume_events
settle_funds
vault_deposit
vault_withdraw
lock
unlock
launch
migration
stake
unstake
unknown/unmapped audit
```
Raison : burn, perte de liquidité, changements admin/config, vault withdraw, migration, mint anormal, close account, etc. peuvent influencer une décision de trading même si ce ne sont pas des trades.
## Base de données
La base actuelle suffit pour audit-only via `k_sol_dex_decoded_events`, mais elle n’est pas suffisante pour tout exploiter en requêtes métier.
À considérer avant ou pendant `0.7.48` :
```text
k_sol_dex_event_coverage_entries
k_sol_token_transfer_events
k_sol_token_account_events
k_sol_orderbook_events
k_sol_vault_events
k_sol_launch_events
k_sol_liquidity_lock_events
```
Priorité minimale :
```text
1. k_sol_dex_event_coverage_entries
2. k_sol_token_transfer_events
3. k_sol_orderbook_events
```
## Ordre des versions
```text
0.7.48-pre event coverage + DB model checkpoint
0.7.48 raydium_cpmm
0.7.49 raydium_clmm
0.7.50 pump_swap
0.7.51 pump_fun
0.7.52 meteora_dbc
0.7.53 meteora_dlmm
0.7.54 meteora_damm_v1
0.7.55 meteora_damm_v2
0.7.56 phoenix_v1
0.7.57 openbook_v2
0.7.58 orca_whirlpools
0.7.59 launch surfaces
0.7.60 DEX historiques/candidats
0.7.61 validation consolidée
```
## Règles fixes
- Un event non-trade ne produit jamais trade/candle.
- Une transaction failed reste audit, jamais trade/candle.
- Un discriminator upstream n’est pas une preuve métier.
- Un program id upstream n’est pas vérifié sans corpus local.
- Chaque decoder spécialisé doit remplacer le fallback `upstream_git.instruction_match` pour éviter les doublons.
- Tout event connu mais non observé reste `upstream_git_mapped_unverified`.
- Tout event observé mais non matérialisé reste audit-only ou decoded, pas materialized.
## Prochaine tâche recommandée
Commencer par :
```text
0.7.48-pre — event coverage + DB model checkpoint
```
Livrables attendus :
1. ajouter/documenter une table de couverture event/discriminator ;
2. générer un rapport de couverture par DEX/version ;
3. préparer `raydium_cpmm` avec la liste complète des events depuis Carbon/fnzero/IDL ;
4. ne pas changer encore la matérialisation trade/candle.

249
docs/prompts/NEXT_SESSION_PROMPT_0.7.47_UPSTREAM_REGISTRY.md Normal file
View File

@@ -0,0 +1,249 @@
# Prompt de reprise — khadhroony-bobobot `0.7.47`
Reprise du projet `khadhroony-bobobot`.
## Contexte
Le workspace contient principalement :
- `kb_lib` : logique métier Solana/DEX, clients HTTP/WS, décodage, détection, SQLite, replay, validation, diagnostics, metadata, candles, signaux ;
- `kb_demo_app` : application Tauri V2 de démo/inspection. Elle doit rester une façade UI et ne pas contenir de logique métier DEX profonde.
La version `0.7.46` est clôturée sur `meteora_damm_v1`.
## État validé à la fin de `0.7.46`
- `cargo test -p kb_lib` : vert.
- `cargo clippy -p kb_lib --all-targets -- -D warnings` : vert.
- Demo2 et Demo3 fonctionnent bien pour backfill et discovery.
- Demo3 supporte :
- multi-target ;
- multi-source ;
- pagination `before` / `until` ;
- `max_pages` ;
- `newest_first` / `oldest_first`.
- Le replay local supporte le ledger de décodage/replay et les options `skipDexDecode` / `forceDexDecode`.
- `meteora_damm_v1` couvre les surfaces observées localement :
- `swap` ;
- `claim_fee` ;
- `create_lock_escrow` ;
- `lock_liquidity` ;
- `remove_liquidity` ;
- `add_liquidity` ;
- `create_pool`.
- Les statuts/payloads ne doivent plus utiliser une terminologie spécifique à un dépôt externe particulier.
- Les statuts génériques attendus sont :
- `upstream_git_unverified` ;
- `upstream_git_mapped_unverified` ;
- `upstream_git_local_corpus_observed` ;
- `upstream_git_local_corpus_materialized` ;
- `upstream_git_layout_unverified` si le layout est connu depuis une source Git mais pas encore validé localement.
## Décision base de données pour `0.7.47`
La version `0.7.46` est considérée finalisée. Ne pas demander ni proposer de replay forcé de l’ancienne base `0.7.46` pour clôturer cette version, sauf demande explicite.
Pour `0.7.47`, le développement et la validation doivent se faire de préférence sur une **nouvelle base SQLite dédiée**. Cette base servira à constituer un corpus propre avec Demo3 et Demo2 sur plusieurs paires, pools ou programmes de DEX différents.
Règles pratiques :
- l’ancienne base `0.7.46` peut servir de référence historique ou de comparaison, mais elle ne doit pas être migrée ou redécodée automatiquement ;
- si une validation DB est nécessaire en `0.7.47`, elle doit cibler la nouvelle base de travail `0.7.47` ;
- les backfills `0.7.47` doivent être construits à partir de Demo3 discovery puis Demo2 signature/pool backfill ;
- le replay local reste utile, mais seulement après constitution du corpus `0.7.47`, pas comme étape de finalisation de `0.7.46` ;
- les entrées du registre upstream Git restent des indices tant qu’elles ne sont pas observées sur cette nouvelle base ou sur un corpus explicitement indiqué.
## Objectif de `0.7.47`
`0.7.47` est dédiée à :
```text
Upstream Git Registry / DEX discovery preparation
```
L’objectif n’est pas de valider directement un DEX unique. L’objectif est de créer un registre générique permettant d’indexer les `program_id`, discriminants d’instructions, discriminants d’events, noms d’instructions, familles de programmes et types de surfaces issus de dépôts Git externes de decoders Solana.
Ces entrées sont des **indices de découverte**, pas des preuves métier. Elles doivent rester non vérifiées tant qu’elles ne sont pas confirmées par :
1. Demo3 discovery ;
2. backfill signature/pool via Demo2 ;
3. replay local sur la base de travail `0.7.47` ;
4. requêtes SQL de validation sur cette même base ;
5. invariants métier : pas de faux trade, pas de fausse candle, pas de promotion de `program_id` sans corpus.
## Noms recommandés
Modules possibles :
```text
kb_lib/src/upstream_registry.rs
kb_lib/src/upstream_registry_types.rs
kb_lib/src/upstream_registry_match.rs
kb_lib/src/upstream_registry_generated.rs
```
Nom fonctionnel :
```text
Upstream Git Registry
```
Ne pas utiliser de nom de dépôt externe spécifique dans les noms publics, les statuts, les tables ou les payloads métier.
## Première tranche attendue
Créer une première version statique du registre dans `kb_lib`, sans modifier la DB si ce n’est pas nécessaire.
Chaque entrée de registre devrait contenir au minimum :
```text
source_repo
source_path
decoder_code
program_id
program_family
surface_kind
entry_kind = instruction | event | account | program
entry_name
discriminator_hex
discriminator_len
proof_status
notes
```
Les entrées de registre doivent être exposées à `kb_demo_app` via une commande Demo3 ou une commande dédiée, mais la logique reste dans `kb_lib`.
## Familles à indexer en priorité
DEX / AMM / CLMM / orderbook :
```text
meteora_damm_v2
meteora_dbc
meteora_dlmm
meteora_vault
raydium_amm_v4
raydium_clmm
raydium_cpmm
raydium_launchpad
raydium_liquidity_locking
raydium_stable_swap
orca_whirlpools
fluxbeam
lifinity_v2
phoenix_v1
openbook_v2
stabble_stable_swap
stabble_weighted_swap
bonkswap
boop
moonshot
heaven
okx_dex
pancake_swap
vertigo
virtuals
wavebreak
onchain_labs_dex_v1
onchain_labs_dex_v2
```
Agrégateurs / ordres / perps / lending :
```text
jupiter_swap
jupiter_dca
jupiter_limit_order
jupiter_limit_order_2
jupiter_perpetuals
jupiter_lend
kamino_lending
kamino_vault
kamino_farms
kamino_limit_order
drift_v2
marginfi_v2
dflow_aggregator_v4
zeta
```
Contexte transactionnel non DEX :
```text
system_program
token_program
token_2022
associated_token_account
address_lookup_table
memo_program
stake_program
mpl_token_metadata
mpl_core
bubblegum
name_service
marinade_finance
solayer_restaking_program
swig
sharky
circle_message_transmitter_v2
circle_token_messenger_v2
```
## Règles de validation
- Une entrée upstream Git reste `upstream_git_unverified` tant qu’elle n’a pas été vue localement.
- Une entrée branchée dans un decoder mais jamais vue localement reste `upstream_git_mapped_unverified`.
- Une entrée vue après Demo3/backfill/replay peut devenir `upstream_git_local_corpus_observed`.
- Une entrée qui alimente correctement une table métier dédiée peut devenir `upstream_git_local_corpus_materialized`.
- Aucun `program_id`, event ou discriminator ne doit être déclaré vérifié uniquement parce qu’il existe dans un dépôt Git externe.
- Aucun event non-trade ne doit produire trade, metric ou candle.
## Contraintes de code
- Rust 2024.
- Pas de `mod.rs`.
- Fichiers Rust avec entête `// file: ...`.
- Fichiers `.toml` avec entête `# file: ...`.
- Exposition centralisée via `lib.rs`.
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]`.
- Pas de `anyhow`.
- Pas de `thiserror`.
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
- Utiliser `match`, `if let Err`, `let Err = ... else`.
- Tests verts à chaque étape.
- Si une requête DB est ajoutée/modifiée, mettre à jour les re-exports dans `kb_lib/src/db.rs`, puis `kb_lib/src/lib.rs` si nécessaire.
## Format de livraison attendu
Pour chaque tranche :
1. expliquer brièvement les fichiers touchés ;
2. fournir une archive des fichiers ajoutés/modifiés seulement, avec l’arborescence du projet ;
3. indiquer les commandes de test à lancer ;
4. indiquer les requêtes SQL utiles si validation DB nécessaire ;
5. ne jamais prétendre qu’un `program_id` ou un event est vérifié sans preuve/corpus.
dexlab
bags / letsbonk / bonk_fun
believe
moonit
launchbeam
metadao / metaDAO
printr
zora
aldrin
aldrin_v2
crema
cropper
cropper_legacy
guacswap
invariant
lifinity_v1
openbook_v1 / serum-style legacy
orca_v1
orca_v2
saber
saros
serum_v3
token_swap

327
docs/prompts/NEXT_SESSION_PROMPT_0.7.49_RAYDIUM_CLMM.md Normal file
View File

@@ -0,0 +1,327 @@
# Prompt de reprise — khadhroony-bobobot `0.7.49` / Raydium CLMM event coverage
Reprise du projet `khadhroony-bobobot` après clôture fonctionnelle de `0.7.48 raydium_cpmm`.
## Archive de départ
Utiliser la dernière archive complète du workspace intégrant les deltas validés jusqu'à :
```text
0.7.48-raydium-cpmm-final
```
Docs à fournir aussi :
```text
README.md
ROADMAP.md
CHANGELOG.md
docs/DEX_DECODER_MATRIX.md
docs/DEX_EVENT_COVERAGE_MATRIX.md
docs/DB_EVENT_MODEL_REVIEW.md
docs/reports/RAYDIUM_CPMM_EVENT_COVERAGE_REPORT.md
validation_sql/SQL_VALIDATION_RAYDIUM_CPMM_0_7_48.sql
```
## État validé avant reprise
`0.7.48` a clôturé la tranche `raydium_cpmm` :
```text
k_sol_dex_event_coverage_entries synchronisée en snake_case local
k_sol_instruction_observations ajoutée comme table technique d'index instruction/discriminator
Demo3 enrichie avec recherche instruction/discriminator
Solscan instruction=<discriminator> utilisé comme accélérateur de recherche de signatures
raydium_cpmm Program data décodé pour lp_change_event / swap_event
raydium_cpmm deposit / withdraw / lp_change_event matérialisés liquidity
raydium_cpmm initialize / initialize_with_permission matérialisés lifecycle-only
raydium_cpmm collect_*_fee matérialisés fee
raydium_cpmm create_amm_config / create_permission_pda / update_amm_config matérialisés admin/config
raydium_cpmm swap_event conservé audit-only
close_permission_pda et update_pool_status conservés upstream_git_mapped_unverified faute de corpus local
instruction inconnue 40f4bc78a7e9690a conservée raydium_cpmm.instruction_audit
```
Validation locale finale observée :
```text
cargo test -p kb_lib: ok, 386 passed
cargo clippy -p kb_lib --all-targets -- -D warnings: ok
replay local: 1124 replayed, 561 trades, 50 liquidity, 9 lifecycle, 2224 candle upserts
```
Couverture finale `raydium_cpmm` :
```text
lp_change_event 25/25 liquidity, 0 trade
swap_event 529 decoded-only, 0 trade
deposit 11/11 liquidity, 0 trade
withdraw 14/14 liquidity, 0 trade
initialize 5/5 lifecycle, 0 admin, 0 trade
initialize_with_permission 4/4 lifecycle, 0 admin, 0 trade
collect_creator_fee 4/4 fee, 0 trade
collect_fund_fee 7/7 fee, 0 trade
collect_protocol_fee 15/15 fee, 0 trade
create_amm_config 6/6 admin, 0 trade
create_permission_pda 4/4 admin, 0 trade
update_amm_config 13/13 admin, 0 trade
swap_base_input 750 decoded, 482 trades
swap_base_output 25 decoded, 17 trades
close_permission_pda upstream_git_mapped_unverified
update_pool_status upstream_git_mapped_unverified
```
Invariants maintenus :
```text
non-trade event = jamais trade/candle
failed transaction = audit-only
upstream Git/IDL/Solscan = indice, pas preuve métier
program_id upstream non promu sans corpus local
chaque decoder spécialisé remplace le fallback upstream_git.instruction_match
side effects SPL Token / Token-2022 restent transversaux, pas raydium_cpmm.* directs
pas de nouvelle table métier transversale sans preuve multi-DEX
```
## Décision de reprise
Commencer `0.7.49` par `raydium_clmm`, avant Pump/Meteora.
Ordre courant :
```text
0.7.49 raydium_clmm
0.7.50 pump_swap
0.7.51 pump_fun
0.7.52 meteora_dbc
0.7.53 meteora_dlmm upstream parity
0.7.54 meteora_damm_v1 upstream parity
0.7.55 meteora_damm_v2
0.7.56 phoenix_v1 audit-only completion
0.7.57 openbook_v2 audit-only completion
0.7.58 orca_whirlpools
0.7.59+ launch surfaces, candidats/historiques, validation consolidée
```
## Sources Git/IDL à utiliser systématiquement
- https://github.com/sevenlabs-hq/carbon/tree/main/decoders
- https://github.com/0xfnzero/solana-streamer
- https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
- https://github.com/pinax-network/substreams-solana-idls/tree/main/src
- https://github.com/hodlwarden/solana-tx-parser/tree/main/src
- https://github.com/openbook-dex/openbook-v2
- https://github.com/all-in-one-blockchain/phoenix-onchain-mm
- https://docs.vybenetwork.com/docs/available-dexs-amms
Pour `0.7.49 raydium_clmm`, utiliser aussi explicitement :
```text
https://solscan.io/account/CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK#programIdl
```
et les filtres Solscan de type :
```text
https://solscan.io/account/CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK?instruction=<DISCRIMINATOR>&hide_spam=true&hide_failed=true&show_related=false&sort=desc
```
Solscan doit servir à trouver vite des signatures à backfiller, jamais comme preuve métier finale.
## Objectif `0.7.49` — `raydium_clmm`
Objectif : reprendre `raydium_clmm` comme deuxième tranche Raydium/version après CPMM.
À faire :
1. lire le code local `raydium_clmm` et les matérialisations existantes ;
2. lister toutes les instructions/events CLMM depuis Carbon/fnzero/IDL/Raydium/Solscan Program IDL ;
3. synchroniser/remplir `k_sol_dex_event_coverage_entries` pour `raydium_clmm` ;
4. utiliser `k_sol_instruction_observations` pour inspecter les discriminants réellement observés localement ;
5. ajouter à Demo3 les filtres instruction/discriminant CLMM si un binding/UI manque encore ;
6. chercher des signatures ciblées via Solscan `instruction=<discriminator>` ;
7. backfiller les signatures utiles dans Demo Pipeline 2 ;
8. rejouer localement `forceDexDecode=yes` ;
9. comparer listed/decoded/observed/materialized/trade_count via SQL coverage ;
10. compléter le decoder spécialisé `raydium_clmm` seulement pour les events confirmables ;
11. remplacer/nettoyer le fallback `upstream_git.instruction_match` quand un decoder local spécialisé couvre l'entrée ;
12. garder les events connus mais non observés en `upstream_git_mapped_unverified` ;
13. garder les events observés mais non matérialisés en audit-only/decoded ;
14. ne matérialiser que les non-trades prouvés par corpus et compatibles avec les tables existantes ;
15. ne pas modifier les règles trade/candle sauf bug de faux positif prouvé.
## Familles à couvrir explicitement
Ne pas se limiter aux swaps.
Inclure dans l'audit coverage CLMM :
```text
swap
pool_create
add_liquidity
remove_liquidity
position_open
position_close
fee
reward
admin/config
mint
burn
transfer
account_create
account_close
wrap_sol
unwrap_sol
order_place
order_cancel
order_fill
consume_events
settle_funds
vault_deposit
vault_withdraw
lock
unlock
launch
migration
stake
unstake
unknown/unmapped audit
```
Pour `raydium_clmm`, certaines familles sont probablement non applicables ou seulement observées comme side effects SPL Token/Token-2022. Elles doivent être explicitement justifiées dans la coverage matrix.
## Points d'attention hérités de CPMM
- `decoder_code` local doit rester en `snake_case` : `raydium_clmm`, pas `raydium-clmm`.
- Les slugs/chemins upstream peuvent garder les tirets : `raydium-clmm-decoder`.
- Les events side effects SPL Token (`burn`, `transfer`, `transferChecked`, `closeAccount`) ne doivent pas devenir `raydium_clmm.*` sans preuve qu'ils sont des instructions directes du programme CLMM.
- `k_sol_instruction_observations` est technique et peut être enrichie ; ne pas la confondre avec une table métier.
- `initialize_*` / création de pool doit rester lifecycle-only si c'est bien une création, pas admin.
- Les positions CLMM sont potentiellement des tables/catégories existantes ou à auditer : ne pas forcer liquidity simple si l'event représente une position NFT/tick.
- Les rewards/fees CLMM peuvent nécessiter un mapping plus fin que CPMM.
## Requêtes SQL utiles
Coverage CLMM :
```sql
SELECT
entry_name,
entry_kind,
event_family,
expected_db_target,
proof_status,
observed_count,
materialized_count,
trade_count
FROM k_sol_dex_event_coverage_entries
WHERE decoder_code = 'raydium_clmm'
ORDER BY entry_kind, entry_name, discriminator_hex;
```
Instruction observations CLMM :
```sql
SELECT
instruction_name,
discriminator_hex,
COUNT(*) AS observed_count,
COUNT(DISTINCT signature) AS tx_count
FROM k_sol_instruction_observations
WHERE decoder_code = 'raydium_clmm'
GROUP BY instruction_name, discriminator_hex
ORDER BY observed_count DESC;
```
Non-trade safety :
```sql
SELECT
de.event_kind,
COUNT(*) AS decoded_count,
COUNT(le.id) AS liquidity_count,
COUNT(fe.id) AS fee_count,
COUNT(pa.id) AS admin_count,
COUNT(ple.id) AS lifecycle_count,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_liquidity_events le
ON le.decoded_event_id = de.id
LEFT JOIN k_sol_fee_events fe
ON fe.decoded_event_id = de.id
LEFT JOIN k_sol_pool_admin_events pa
ON pa.decoded_event_id = de.id
LEFT JOIN k_sol_pool_lifecycle_events ple
ON ple.decoded_event_id = de.id
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_clmm'
GROUP BY de.event_kind
ORDER BY de.event_kind;
```
Fallback upstream CLMM :
```sql
SELECT
json_extract(payload_json, '$.upstreamDecoderCode') AS upstream_decoder_code,
json_extract(payload_json, '$.entryName') AS entry_name,
json_extract(payload_json, '$.discriminatorHex') AS discriminator_hex,
COUNT(*) AS fallback_count
FROM k_sol_dex_decoded_events
WHERE protocol_name = 'upstream_git'
AND event_kind = 'upstream_git.instruction_match'
AND json_extract(payload_json, '$.upstreamDecoderCode') = 'raydium_clmm'
GROUP BY upstream_decoder_code, entry_name, discriminator_hex
ORDER BY fallback_count DESC, entry_name;
```
Failed transaction safety :
```sql
SELECT
de.event_kind,
COUNT(*) AS decoded_count,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
JOIN k_sol_chain_transactions tx
ON tx.id = de.transaction_id
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_clmm'
AND tx.err_json IS NOT NULL
AND tx.err_json <> ''
GROUP BY de.event_kind
ORDER BY trade_count DESC, decoded_count DESC;
```
## Contraintes de code
Conserver les règles du workspace :
```text
Rust 2024
pas de mod.rs
fichiers Rust avec // file: ...
pas de anyhow
pas de thiserror
pas de ? / unwrap / expect dans kb_lib applicatif
match / if let Err / let Err = ... else
rustdoc sur API publique
re-exports db.rs puis lib.rs si DB modifiée
```
## Livrables attendus pour `0.7.49`
1. delta archive avec uniquement les fichiers ajoutés/modifiés ;
2. mise à jour `README.md`, `ROADMAP.md`, `CHANGELOG.md` si la tranche avance ;
3. rapport de couverture `raydium_clmm` ;
4. SQL de validation ;
5. tests verts :
```bash
cargo fmt
cargo test -p kb_lib
cargo clippy -p kb_lib --all-targets -- -D warnings
```

245
docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.48-raydium-cpmm.md Normal file
View File

@@ -0,0 +1,245 @@
# Prompt de reprise — khadhroony-bobobot `0.7.48` / Raydium CPMM event coverage
Reprise du projet `khadhroony-bobobot` après clôture de `0.7.48-pre`.
## Archive de départ
Utiliser la dernière archive complète du workspace intégrant les deltas validés jusqu'à :
```text
0.7.48-pre-event-coverage-report
```
Docs à fournir aussi :
```text
README.md
ROADMAP.md
CHANGELOG.md
docs/DEX_DECODER_MATRIX.md
docs/DEX_EVENT_COVERAGE_MATRIX.md
docs/DB_EVENT_MODEL_REVIEW.md
```
## État validé avant reprise
`0.7.48-pre` a ajouté et clôturé le checkpoint DB/reporting de couverture événementielle :
```text
k_sol_dex_event_coverage_entries
DexEventCoverageService
sync upstream registry -> coverage table
refresh local counts depuis k_sol_dex_decoded_events + tables métier existantes
summaries coverage dans LocalPipelineDiagnosticSummaryDto
summaries/counters coverage dans LocalPipelineValidationReportDto
profil validation 0.7.48-pre_event_coverage_db_checkpoint
profil exposé dans Demo Pipeline 2
```
Invariants maintenus :
```text
aucun decoder DEX modifié
aucun trade/candle créé par la couverture
aucun program_id promu sans corpus local
upstream Git/IDL = indice, pas preuve métier
failed transaction = audit-only
non-trade event = jamais trade/candle
```
## Décision de reprise
Commencer maintenant par Raydium avant Meteora.
Ordre courant :
```text
0.7.48 raydium_cpmm
0.7.49 raydium_clmm
0.7.50 pump_swap
0.7.51 pump_fun
0.7.52 meteora_dbc
0.7.53 meteora_dlmm upstream parity
0.7.54 meteora_damm_v1 upstream parity
0.7.55 meteora_damm_v2
0.7.56 phoenix_v1 audit-only completion
0.7.57 openbook_v2 audit-only completion
0.7.58 orca_whirlpools
0.7.59+ launch surfaces, candidats/historiques, validation consolidée
```
## Sources Git/IDL à utiliser systématiquement
- https://github.com/sevenlabs-hq/carbon/tree/main/decoders
- https://github.com/0xfnzero/solana-streamer
- https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
- https://github.com/pinax-network/substreams-solana-idls/tree/main/src
- https://github.com/hodlwarden/solana-tx-parser/tree/main/src
- https://github.com/openbook-dex/openbook-v2
- https://github.com/all-in-one-blockchain/phoenix-onchain-mm
- https://docs.vybenetwork.com/docs/available-dexs-amms
Pour `0.7.48`, commencer par Carbon + fnzero pour Raydium CPMM, puis comparer aux IDL complémentaires si disponibles.
## Objectif `0.7.48` — `raydium_cpmm`
Objectif : reprendre `raydium_cpmm` comme première tranche DEX/version après le checkpoint coverage.
À faire :
1. lister tous les discriminants/instructions/events `raydium_cpmm` depuis Carbon/fnzero/IDL ;
2. synchroniser/remplir `k_sol_dex_event_coverage_entries` pour `raydium-cpmm` ;
3. comparer listed/decoded/observed/materialized/trade_count via le rapport coverage ;
4. compléter le decoder spécialisé `raydium_cpmm` seulement pour les events CPMM confirmables ;
5. remplacer/nettoyer le fallback `upstream_git.instruction_match` quand un decoder local spécialisé couvre l'entrée ;
6. garder les events connus mais non observés en `upstream_git_mapped_unverified` ;
7. garder les events observés mais non matérialisés en audit-only/decoded ;
8. ne matérialiser que les non-trades déjà prouvés par corpus et compatibles avec les tables existantes ;
9. ne pas ajouter encore `k_sol_token_transfer_events` ou `k_sol_orderbook_events`, sauf besoin bloquant démontré ;
10. ne pas modifier les règles trade/candle sauf bug de faux positif prouvé.
## Events/familles à couvrir explicitement
Ne pas se limiter aux swaps.
Inclure dans l'audit coverage :
```text
swap
pool_create
add_liquidity
remove_liquidity
position_open
position_close
fee
reward
admin/config
mint
burn
transfer
account_create
account_close
wrap_sol
unwrap_sol
order_place
order_cancel
order_fill
consume_events
settle_funds
vault_deposit
vault_withdraw
lock
unlock
launch
migration
stake
unstake
unknown/unmapped audit
```
Pour `raydium_cpmm`, certaines familles seront probablement `-` ou `non applicable`, mais elles doivent être explicitement justifiées dans la coverage matrix ou la table.
## Règles fixes
- Un event non-trade ne produit jamais `trade_event`, metric ou candle.
- Une transaction failed reste audit, jamais trade/candle.
- Un discriminator upstream n'est pas une preuve métier.
- Un program id upstream n'est pas vérifié sans corpus local.
- Chaque decoder spécialisé doit remplacer le fallback `upstream_git.instruction_match` pour éviter les doublons.
- Tout event connu mais non observé reste `upstream_git_mapped_unverified`.
- Tout event observé mais non matérialisé reste audit-only ou decoded, pas materialized.
- Ne pas promouvoir de nouvelle table DB métier sans preuve que plusieurs DEX en auront besoin.
## Requêtes SQL utiles
Après sync/refresh coverage :
```sql
SELECT *
FROM k_sol_dex_event_coverage_entries
WHERE decoder_code = 'raydium-cpmm'
ORDER BY entry_kind, entry_name, discriminator_hex;
```
```sql
SELECT
decoder_code,
listed_entry_count,
decoded_entry_count,
observed_entry_count,
materialized_entry_count,
total_observed_count,
total_materialized_count,
trade_count,
audit_only_entry_count,
upstream_git_mapped_unverified_entry_count,
upstream_git_local_corpus_observed_entry_count,
upstream_git_local_corpus_materialized_entry_count
FROM (
SELECT
decoder_code,
COUNT(*) AS listed_entry_count,
SUM(CASE WHEN local_event_kind IS NOT NULL AND local_event_kind <> '' THEN 1 ELSE 0 END) AS decoded_entry_count,
SUM(CASE WHEN observed_count > 0 THEN 1 ELSE 0 END) AS observed_entry_count,
SUM(CASE WHEN materialized_count > 0 THEN 1 ELSE 0 END) AS materialized_entry_count,
COALESCE(SUM(observed_count), 0) AS total_observed_count,
COALESCE(SUM(materialized_count), 0) AS total_materialized_count,
COALESCE(SUM(trade_count), 0) AS trade_count,
SUM(CASE WHEN expected_db_target = 'k_sol_dex_decoded_events_only' THEN 1 ELSE 0 END) AS audit_only_entry_count,
SUM(CASE WHEN proof_status = 'upstream_git_mapped_unverified' THEN 1 ELSE 0 END) AS upstream_git_mapped_unverified_entry_count,
SUM(CASE WHEN proof_status = 'upstream_git_local_corpus_observed' THEN 1 ELSE 0 END) AS upstream_git_local_corpus_observed_entry_count,
SUM(CASE WHEN proof_status = 'upstream_git_local_corpus_materialized' THEN 1 ELSE 0 END) AS upstream_git_local_corpus_materialized_entry_count
FROM k_sol_dex_event_coverage_entries
GROUP BY decoder_code
)
WHERE decoder_code = 'raydium-cpmm';
```
Audit-only safety :
```sql
SELECT
de.protocol_name,
de.event_kind,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_cpmm'
AND (
de.event_kind LIKE '%audit%'
OR json_extract(de.payload_json, '$.eventActionability') IN ('non_trade_useful', 'informational', 'non_actionable_trade')
)
GROUP BY de.protocol_name, de.event_kind
ORDER BY trade_count DESC, de.event_kind;
```
## Contraintes de code
Conserver les règles du workspace :
```text
Rust 2024
pas de mod.rs
fichiers Rust avec // file: ...
pas de anyhow
pas de thiserror
pas de ? / unwrap / expect dans kb_lib applicatif
match / if let Err / let Err = ... else
rustdoc sur API publique
re-exports db.rs puis lib.rs si DB modifiée
```
## Livrables attendus pour `0.7.48`
1. delta archive avec uniquement les fichiers ajoutés/modifiés ;
2. mise à jour `README.md`, `ROADMAP.md`, `CHANGELOG.md` si la tranche avance ;
3. rapport de couverture `raydium_cpmm` ;
4. SQL de validation ;
5. tests verts :
```bash
cargo fmt
cargo test -p kb_lib
cargo clippy -p kb_lib --all-targets -- -D warnings
```

338
docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.50-raydium-launchpad.md Normal file
View File

@@ -0,0 +1,338 @@
<!-- file: docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.50-raydium-launchpad.md -->
# khadhroony-bobobot `0.7.50` / Raydium Launchpad event coverage
Reprise du projet `khadhroony-bobobot` après clôture fonctionnelle de `0.7.49 raydium_clmm`.
## Archive de départ
Utiliser la dernière archive complète du workspace intégrant les deltas validés jusqu'à :
```text
0.7.49-raydium-clmm-final
```
Inclure les docs et SQL de validation produits en fin de `0.7.49`, notamment :
```text
README.md
ROADMAP.md
CHANGELOG.md
docs/DEX_DECODER_MATRIX.md
docs/DEX_EVENT_COVERAGE_MATRIX.md
docs/DB_EVENT_MODEL_REVIEW.md
docs/RAYDIUM_CPMM_EVENT_COVERAGE_REPORT.md
docs/RAYDIUM_CLMM_EVENT_COVERAGE_REPORT.md
validation_sql/SQL_VALIDATION_RAYDIUM_CPMM_0_7_48.sql
validation_sql/SQL_VALIDATION_RAYDIUM_CLMM_0_7_49_PRE23.sql
```
## État validé avant reprise
`0.7.48` a clôturé `raydium_cpmm`.
`0.7.49` a clôturé `raydium_clmm` avec les invariants suivants :
```text
Raydium CLMM decoder_code local = raydium_clmm
coverage synchronisée avec Carbon / Raydium IDL / Pinax / fnzero
45 entrées coverage CLMM listées
33 entrées CLMM décodées localement
33 entrées observées localement
25 entrées matérialisées localement
residual raydium_clmm.instruction_audit = 0
fallback upstream_git.instruction_match localement couvert = 0 après cleanup FK-safe
non-trade CLMM = jamais trade/candle
failed transaction = jamais matérialisée dans les tables métier
Program data CLMM préparé mais non promu sans corpus local observé
side effects SPL Token / Token-2022 restent transversaux, pas raydium_clmm.* directs
```
Dernière validation locale observée :
```text
cargo test -p kb_lib: ok
local pipeline replay: 2197 replayed, 0 decode skipped, 2197 ledger upserts, 1461 unsafe ledger rows, 1217 trades, 111 liquidity, 25 lifecycle, 4868 candle upserts, instructionObservations='19798'
```
## Décision de reprise
Commencer `0.7.50` par `raydium_launchpad`, avant Pump/Meteora.
Ordre strict Raydium proposé avant Pump :
```text
0.7.50 raydium_launchpad / Raydium LaunchLab-Launchpad surface
0.7.51 raydium_amm_v4
0.7.52 raydium_stable
0.7.53 raydium_pool_v4 audit / program-id decision, seulement si program id distinct et corpus exploitable
0.7.54 pump_swap
0.7.55 pump_fun
0.7.56 meteora_dbc
0.7.57 meteora_dlmm upstream parity
0.7.58 meteora_damm_v1 upstream parity
0.7.59 meteora_damm_v2
0.7.60 phoenix_v1 audit-only completion
0.7.61 openbook_v2 audit-only completion
0.7.62 orca_whirlpools
0.7.63+ launch surfaces, candidats/historiques, validation consolidée
```
`raydium_pool_v4` ne doit pas être promu automatiquement comme DEX/surface métier tant que son program id et son rôle exact n'ont pas été confirmés. Le fichier `raydium_pool_v4.json` de `sol-parser-sdk` doit être audité comme source IDL annexe, pas comme preuve métier.
## Sources Git/IDL à utiliser systématiquement
- https://github.com/sevenlabs-hq/carbon/tree/main/decoders
- https://github.com/0xfnzero/solana-streamer
- https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
- copie locale fournie de `0xfnzero/sol-parser-sdk`, si présente dans l'archive de reprise
- https://github.com/pinax-network/substreams-solana-idls/tree/main/src
- https://github.com/hodlwarden/solana-tx-parser/tree/main/src
- https://github.com/openbook-dex/openbook-v2
- https://github.com/all-in-one-blockchain/phoenix-onchain-mm
- https://docs.vybenetwork.com/docs/available-dexs-amms
Pour `0.7.50 raydium_launchpad`, utiliser aussi explicitement :
```text
https://solscan.io/account/LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj#programIdl
```
et les filtres Solscan de type :
```text
https://solscan.io/account/LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj?instruction=<DISCRIMINATOR>&hide_spam=true&hide_failed=true&show_related=false&sort=desc
```
Solscan sert à trouver vite des signatures à backfiller. Solscan ne doit jamais être considéré comme preuve métier finale sans corpus local et validation SQL.
## Base de données de travail
Initialiser une nouvelle base SQLite dédiée à `0.7.50`.
Procédure attendue :
1. créer une nouvelle DB via `config.json` ou équivalent ;
2. démarrer `kb_demo_app` pour initialiser le schéma ;
3. backfiller des signatures ciblées par discriminant / instruction ;
4. backfiller des pools/comptes pertinents si la surface en expose ;
5. exécuter un replay local avec `forceDexDecode=yes` ;
6. relancer les SQL de coverage ;
7. ne promouvoir une entrée que si le corpus local confirme son sens métier.
## Objectif `0.7.50` — `raydium_launchpad`
Objectif : couvrir Raydium Launchpad/LaunchLab comme nouvelle surface Raydium après CPMM et CLMM.
À faire :
1. lire le code local existant lié à Raydium Launchpad, s'il existe ;
2. lister toutes les instructions/events depuis Carbon/fnzero/IDL/Pinax/Solscan Program IDL ;
3. synchroniser/remplir `k_sol_dex_event_coverage_entries` pour `raydium_launchpad` ;
4. vérifier `decoder_code` local en snake_case : `raydium_launchpad` ;
5. utiliser `k_sol_instruction_observations` pour inspecter les discriminants observés localement ;
6. utiliser Demo3 / Solscan `instruction=<discriminator>` pour trouver des signatures ciblées ;
7. backfiller les signatures via Demo2, idéalement par batch textarea ;
8. rejouer localement avec `forceDexDecode=yes` et `deferInstructionObservations=yes` ;
9. comparer listed/decoded/observed/materialized/trade_count via SQL coverage ;
10. compléter le decoder spécialisé seulement pour les entrées confirmées ;
11. supprimer/nettoyer `upstream_git.instruction_match` lorsque l'entrée est couverte localement ;
12. garder les entrées connues mais non observées en `upstream_git_unverified` ou `upstream_git_mapped_unverified` ;
13. garder les entrées observées mais non matérialisées en audit-only/decoded ;
14. ne matérialiser que les non-trades prouvés par corpus local et compatibles avec les tables existantes ;
15. ne modifier les règles trade/candle que si un faux positif est prouvé.
## Familles à auditer explicitement
Ne pas se limiter aux swaps.
Inclure dans la coverage :
```text
swap
pool_create
add_liquidity
remove_liquidity
position_open
position_close
fee
reward
admin/config
mint
burn
transfer
account_create
account_close
wrap_sol
unwrap_sol
order_place
order_cancel
order_fill
consume_events
settle_funds
vault_deposit
vault_withdraw
lock
unlock
launch
migration
stake
unstake
unknown/unmapped audit
```
Certaines familles peuvent être non applicables ou uniquement visibles comme side effects SPL Token / Token-2022. Elles doivent être explicitement justifiées dans `DEX_EVENT_COVERAGE_MATRIX.md`.
## Points d'attention hérités de CPMM/CLMM
- `decoder_code` local doit rester en `snake_case`.
- Les slugs upstream peuvent garder les tirets.
- `upstream Git/IDL/Solscan = indice, pas preuve métier`.
- `program_id` upstream non promu sans corpus local.
- Chaque decoder spécialisé doit remplacer le fallback `upstream_git.instruction_match` pour les entrées localement couvertes.
- Les side effects SPL Token (`mintTo`, `burn`, `transfer`, `transferChecked`, `closeAccount`) ne deviennent pas `raydium_launchpad.*` sans preuve qu'il s'agit d'instructions directes du programme Launchpad.
- Failed transaction = decoded/audit possible, jamais matérialisée métier.
- Non-trade event = jamais trade/candle.
- Pas de nouvelle table métier transversale sans preuve multi-DEX.
## Requêtes SQL minimales à produire
Créer un fichier :
```text
validation_sql/SQL_VALIDATION_RAYDIUM_LAUNCHPAD_0_7_50.sql
```
Inclure au minimum :
```sql
SELECT
entry_name,
entry_kind,
event_family,
expected_db_target,
proof_status,
local_event_kind,
discriminator_hex,
observed_count,
materialized_count,
trade_count
FROM k_sol_dex_event_coverage_entries
WHERE decoder_code = 'raydium_launchpad'
ORDER BY entry_kind, entry_name, discriminator_hex;
```
Coverage summary :
```sql
SELECT
decoder_code,
COUNT(*) AS listed_entry_count,
SUM(CASE WHEN local_event_kind IS NOT NULL AND local_event_kind <> '' THEN 1 ELSE 0 END) AS decoded_entry_count,
SUM(CASE WHEN observed_count > 0 THEN 1 ELSE 0 END) AS observed_entry_count,
SUM(CASE WHEN materialized_count > 0 THEN 1 ELSE 0 END) AS materialized_entry_count,
COALESCE(SUM(observed_count), 0) AS total_observed_count,
COALESCE(SUM(materialized_count), 0) AS total_materialized_count,
COALESCE(SUM(trade_count), 0) AS trade_count
FROM k_sol_dex_event_coverage_entries
WHERE decoder_code = 'raydium_launchpad'
GROUP BY decoder_code;
```
Instruction observations :
```sql
SELECT
instruction_name,
discriminator_hex,
COUNT(*) AS observed_count,
COUNT(DISTINCT signature) AS tx_count
FROM k_sol_instruction_observations
WHERE decoder_code = 'raydium_launchpad'
GROUP BY instruction_name, discriminator_hex
ORDER BY observed_count DESC, instruction_name;
```
```sql
SELECT
de.event_kind,
COUNT(*) AS decoded_count,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_launchpad'
GROUP BY de.event_kind
ORDER BY decoded_count DESC, de.event_kind;
```
```sql
SELECT
json_extract(payload_json, '$.upstreamDecoderCode') AS upstream_decoder_code,
json_extract(payload_json, '$.upstreamEntryName') AS entry_name,
json_extract(payload_json, '$.upstreamDiscriminatorHex') AS discriminator_hex,
COUNT(*) AS fallback_count
FROM k_sol_dex_decoded_events
WHERE protocol_name = 'upstream_git'
AND event_kind = 'upstream_git.instruction_match'
AND json_extract(payload_json, '$.upstreamDecoderCode') = 'raydium_launchpad'
GROUP BY upstream_decoder_code, entry_name, discriminator_hex
ORDER BY fallback_count DESC, entry_name;
```
```sql
SELECT
de.event_kind,
COUNT(*) AS decoded_count,
COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
JOIN k_sol_chain_transactions tx
ON tx.id = de.transaction_id
LEFT JOIN k_sol_trade_events te
ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_launchpad'
AND tx.err_json IS NOT NULL
AND tx.err_json <> ''
AND tx.err_json <> 'null'
GROUP BY de.event_kind
ORDER BY trade_count DESC, decoded_count DESC;
```
## Contraintes de code
Conserver les règles du workspace :
```text
Rust 2024
pas de mod.rs
fichiers Rust avec // file: ...
pas de anyhow
pas de thiserror
pas de ? / unwrap / expect dans kb_lib applicatif
match / if let Err / let Err = ... else
rustdoc sur API publique
re-exports db.rs puis lib.rs si DB modifiée
```
## Livrables attendus pour `0.7.50`
1. delta archive avec uniquement les fichiers ajoutés/modifiés ;
2. mise à jour `README.md`, `ROADMAP.md`, `CHANGELOG.md` ;
3. rapport `docs/RAYDIUM_LAUNCHPAD_EVENT_COVERAGE_REPORT.md` ;
4. SQL `validation_sql/SQL_VALIDATION_RAYDIUM_LAUNCHPAD_0_7_50.sql` ;
5. tests verts :
```bash
cargo fmt
cargo test -p kb_lib
cargo clippy -p kb_lib --all-targets -- -D warnings
```
## Question ouverte à traiter tôt dans `0.7.50`
Auditer `raydium_pool_v4.json` dans `sol-parser-sdk` :
- confirmer s'il correspond à un program id distinct ;
- confirmer s'il s'agit d'une surface Raydium Pool/Lending/Strategy différente de `raydium_amm_v4` ;
- décider si une version dédiée `0.7.53 raydium_pool_v4` est nécessaire ;
- ne pas modifier la roadmap comme surface finale tant que le program id n'est pas confirmé.

134
docs/reports/RAYDIUM_CLMM_EVENT_COVERAGE_REPORT.md Normal file
View File

@@ -0,0 +1,134 @@
<!-- file: docs/reports/RAYDIUM_CLMM_EVENT_COVERAGE_REPORT.md -->
# Rapport `0.7.49` — Raydium CLMM event coverage
## Résumé
La tranche `0.7.49` clôture la couverture fonctionnelle `raydium_clmm` sur le corpus local validé. Elle reprend CLMM après `0.7.48 raydium_cpmm` et applique la même méthode : inventaire upstream, corpus local, replay forcé, materialization contrôlée, suppression des fallbacks remplacés, validation SQL.
Validation locale observée après le dernier replay :
```text
local replay: 2197 replayed, 0 decode skipped, 2197 ledger upserts, 1461 unsafe ledger rows, 1217 trades, 111 liquidity, 25 lifecycle, 4868 candle upserts, instructionObservations=19798
catalog: 41 tokens, 63 pools, 63 pairs
```
Synthèse coverage :
```text
listed_entry_count = 45
decoded_entry_count = 33
observed_entry_count = 33
materialized_entry_count = 25
total_observed_count = 2560
total_materialized_count = 1367
trade_count = 1186
```
## Entrées couvertes
La tranche couvre `33` instructions locales CLMM observées et décodées, dont :
```text
swap
swap_v2
swap_router_base_in
open_position
open_position_v2
open_position_with_token22_nft
close_position
close_protocol_position
increase_liquidity
increase_liquidity_v2
decrease_liquidity
decrease_liquidity_v2
create_pool
create_customizable_pool
create_amm_config
create_dynamic_fee_config
update_amm_config
update_pool_status
create_operation_account
update_operation_account
create_support_mint_associated
collect_fund_fee
collect_protocol_fee
collect_remaining_rewards
initialize_reward
set_reward_params
transfer_reward_owner
update_reward_infos
open_limit_order
increase_limit_order
decrease_limit_order
close_limit_order
settle_limit_order
```
## Matérialisations validées
Les matérialisations sont limitées aux transactions réussies et aux familles déjà supportées par le modèle DB :
| Famille | Table | Règle |
|---|---|---|
| Swaps | `k_sol_trade_events` + candles | Uniquement `raydium_clmm.swap` / `raydium_clmm.swap_v2` quand les montants sont exploitables. |
| Liquidity / positions | `k_sol_liquidity_events` | Positions/liquidity prouvées par corpus, sans trade/candle. |
| Fees | `k_sol_fee_events` | Fees prouvées par corpus, sans trade/candle. |
| Rewards | `k_sol_reward_events` | Rewards prouvées par corpus, sans trade/candle. |
| Admin/config | `k_sol_pool_admin_events` | Config/admin prouvés par corpus, sans trade/candle. |
| Lifecycle | `k_sol_pool_lifecycle_events` | Pool creation prouvée par corpus, sans trade/candle. |
| Limit orders | `k_sol_orderbook_events` | Open/increase/decrease/close/settle matérialisés comme orderbook, jamais trade/candle. |
## Invariants validés
Les requêtes SQL finales valident :
```text
raydium_clmm.instruction_audit résiduel = 0
upstream_git.instruction_match localement couvert = 0
non-swap CLMM avec trade_count > 0 = 0
failed tx matérialisées = 0
```
Les fallbacks `upstream_git.instruction_match` localement couverts sont supprimés automatiquement, y compris quand `k_sol_instruction_observations.decoded_event_id` pointait encore vers une ligne fallback.
## Anchor / Program-data events non observés
Les `11` Anchor / `Program data` events CLMM ci-dessous restent listés en `upstream_git_unverified`, car aucun corpus local ne les observe encore comme event direct :
```text
collect_personal_fee_event a6ae69c051a15369
collect_protocol_fee_event ce57114f2d29d53d
config_change_event f7bd07776a705f97
create_personal_position_event 641e57f9c4df9ace
decrease_liquidity_event 3ade563a44325538
increase_liquidity_event 314f69d420221e54
liquidity_calculate_event ed7094e63954b4a2
liquidity_change_event 7ef0afce9e58996b
pool_created_event 195e4b2f7063353f
swap_event 40c6cde8260871e2
update_reward_infos_event 6d7fba4e724125ec
```
Le code est préparé pour les accueillir comme audit-only lorsqu’ils seront observés dans un corpus local. Ils ne produisent pas de trade/candle par défaut.
## Sources utilisées
Les entrées ont été comparées aux sources Raydium CLMM suivantes :
```text
Solscan Program IDL CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK
sevenlabs-hq/carbon raydium-clmm-decoder
pinax-network/substreams-solana-idls raydium/clmm
0xfnzero/sol-parser-sdk idl
```
Les sources upstream restent des indices. La promotion locale dépend du corpus local, du replay et des validations SQL.
## SQL final
La validation finale est dans :
```text
validation_sql/SQL_VALIDATION_RAYDIUM_CLMM_0_7_49.sql
```

130
docs/reports/RAYDIUM_CLMM_UPSTREAM_COVERAGE_REVIEW_PRE19.md Normal file
View File

@@ -0,0 +1,130 @@
# file: docs/reports/RAYDIUM_CLMM_UPSTREAM_COVERAGE_REVIEW_PRE19.md
# Raydium CLMM upstream coverage review — `0.7.49-pre.19`
## Scope
Decoder under review:
```text
raydium_clmm
program_id = CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK
```
External sources checked for the local coverage registry:
```text
https://solscan.io/account/CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK#programIdl
https://github.com/sevenlabs-hq/carbon/tree/main/decoders/raydium-clmm-decoder
https://github.com/pinax-network/substreams-solana-idls/tree/main/src/raydium/clmm
https://github.com/0xfnzero/sol-parser-sdk/tree/main/idl
```
Notes:
- Solscan is used as discovery / IDL cross-check, not as final business proof.
- `sol-parser-sdk/idl/raydium_clmm.json` maps to `raydium/amm_v3_with_swapv2.json` and exposes the CLMM program address.
- `pinax-network/substreams-solana-idls` exposes Raydium CLMM under `src/raydium/clmm/v3`.
- `sevenlabs-hq/carbon` exposes a dedicated `raydium-clmm-decoder` crate.
## Local registry status
The local registry now lists:
```text
45 entries total:
- 33 instructions
- 11 Anchor/program-data events
- 1 program row
```
All 33 instruction entries have a `local_event_kind` mapping in `dex_event_coverage.rs`, `instruction_observation_index.rs`, `dex_decode.rs`, and `upstream_registry_generated.rs`.
The 11 event entries are listed as upstream facts and stay `upstream_git_unverified` until local corpus provides program-data/Anchor event proof.
## Instruction coverage matrix
| Entry | Discriminator | Family | Local event kind | Expected target | Status |
|---|---|---|---|---|---|
| close_limit_order | `4c7c800fd55725fa` | order_cancel | `raydium_clmm.close_limit_order` | `k_sol_orderbook_events` | decoded/materializable |
| open_limit_order | `9d20dab7471d1293` | order_place | `raydium_clmm.open_limit_order` | `k_sol_orderbook_events` | decoded/materializable |
| increase_limit_order | `b19059ecfaba7d63` | order_place | `raydium_clmm.increase_limit_order` | `k_sol_orderbook_events` | decoded/materializable |
| decrease_limit_order | `759d3c674231a300` | order_cancel | `raydium_clmm.decrease_limit_order` | `k_sol_orderbook_events` | decoded/materializable |
| close_position | `7b86510031446262` | position_close | `raydium_clmm.close_position` | `k_sol_liquidity_events` | decoded/materializable |
| close_protocol_position | `c975989055556cb2` | position_close | `raydium_clmm.close_protocol_position` | `k_sol_liquidity_events` | decoded/materializable |
| collect_fund_fee | `a78a4e95dfc2067e` | fee | `raydium_clmm.collect_fund_fee` | `k_sol_fee_events` | decoded/materializable |
| collect_protocol_fee | `8888fcddc2427e59` | fee | `raydium_clmm.collect_protocol_fee` | `k_sol_fee_events` | decoded/materializable |
| collect_remaining_rewards | `12eda6c52210d590` | reward | `raydium_clmm.collect_remaining_rewards` | `k_sol_reward_events` | decoded/materializable |
| create_amm_config | `8934edd4d7756c68` | admin_config | `raydium_clmm.create_amm_config` | `k_sol_pool_admin_events` | decoded/materializable |
| create_customizable_pool | `2b44d4a7592fa401` | pool_create | `raydium_clmm.create_customizable_pool` | `k_sol_pool_lifecycle_events` | decoded/materializable |
| create_dynamic_fee_config | `bd0eb5785576e33e` | admin_config | `raydium_clmm.create_dynamic_fee_config` | `k_sol_pool_admin_events` | decoded/materializable |
| create_operation_account | `3f5794216d230868` | unknown | `raydium_clmm.create_operation_account` | `k_sol_dex_decoded_events_only` | decoded/audit-only unless admin evidence is required |
| create_pool | `e992d18ecf6840bc` | pool_create | `raydium_clmm.create_pool` | `k_sol_pool_lifecycle_events` | decoded/materializable |
| create_support_mint_associated | `11fb415c88f20ea9` | account_create | `raydium_clmm.create_support_mint_associated` | `k_sol_token_account_events` | decoded; token-account materialization remains a later cross-DEX topic |
| decrease_liquidity | `a026d06f685b2c01` | liquidity_remove | `raydium_clmm.decrease_liquidity` | `k_sol_liquidity_events` | decoded/materializable |
| decrease_liquidity_v2 | `3a7fbc3e4f52c460` | liquidity_remove | `raydium_clmm.decrease_liquidity_v2` | `k_sol_liquidity_events` | decoded/materializable |
| increase_liquidity | `2e9cf3760dcdfbb2` | liquidity_add | `raydium_clmm.increase_liquidity` | `k_sol_liquidity_events` | decoded/materializable |
| increase_liquidity_v2 | `851d59df45eeb00a` | liquidity_add | `raydium_clmm.increase_liquidity_v2` | `k_sol_liquidity_events` | decoded/materializable |
| initialize_reward | `5f87c0c4f281e644` | reward | `raydium_clmm.initialize_reward` | `k_sol_reward_events` | decoded/materializable |
| open_position | `87802f4d0f98f031` | position_open | `raydium_clmm.open_position` | `k_sol_liquidity_events` | decoded/materializable |
| open_position_v2 | `4db84ad67056f1c7` | position_open | `raydium_clmm.open_position_v2` | `k_sol_liquidity_events` | decoded/materializable |
| open_position_with_token22_nft | `4dffae527d1dc92e` | position_open | `raydium_clmm.open_position_with_token22_nft` | `k_sol_liquidity_events` | decoded/materializable |
| set_reward_params | `7034a74b20c9d389` | reward | `raydium_clmm.set_reward_params` | `k_sol_reward_events` | decoded/materializable |
| settle_limit_order | `cd4e74215c691a60` | settle_funds | `raydium_clmm.settle_limit_order` | `k_sol_orderbook_events` | decoded/materializable |
| swap | `f8c69e91e17587c8` | swap | `raydium_clmm.swap` | `k_sol_trade_events` | decoded/materializable as trade |
| swap_router_base_in | `457d73daf5baf2c4` | swap | `raydium_clmm.swap_router_base_in` | `k_sol_trade_events` | decoded; observed but not promoted to trade without corpus proof |
| swap_v2 | `2b04ed0b1ac91e62` | swap | `raydium_clmm.swap_v2` | `k_sol_trade_events` | decoded/materializable as trade |
| transfer_reward_owner | `07160c53f22b3079` | reward | `raydium_clmm.transfer_reward_owner` | `k_sol_reward_events` | decoded/materializable |
| update_amm_config | `313cae889a1c74c8` | admin_config | `raydium_clmm.update_amm_config` | `k_sol_pool_admin_events` | decoded/materializable |
| update_operation_account | `7f467728bce33d07` | unknown | `raydium_clmm.update_operation_account` | `k_sol_dex_decoded_events_only` | decoded/audit-only unless admin evidence is required |
| update_pool_status | `82576c062ee0757b` | admin_config | `raydium_clmm.update_pool_status` | `k_sol_pool_admin_events` | decoded/materializable |
| update_reward_infos | `a3ace0340b9a6adf` | reward | `raydium_clmm.update_reward_infos` | `k_sol_reward_events` | decoded/materializable |
## Anchor/program-data event entries
These entries remain listed, but no local corpus row has observed them as direct CLMM decoded events in the current replay corpus:
| Event entry | Discriminator | Family | Expected target | Status |
|---|---|---|---|---|
| collect_personal_fee_event | `a6ae69c051a15369` | fee | `k_sol_fee_events` | upstream listed, local corpus unobserved |
| collect_protocol_fee_event | `ce57114f2d29d53d` | fee | `k_sol_fee_events` | upstream listed, local corpus unobserved |
| config_change_event | `f7bd07776a705f97` | admin_config | `k_sol_pool_admin_events` | upstream listed, local corpus unobserved |
| create_personal_position_event | `641e57f9c4df9ace` | unknown | `k_sol_dex_decoded_events_only` | upstream listed, local corpus unobserved |
| decrease_liquidity_event | `3ade563a44325538` | liquidity_remove | `k_sol_liquidity_events` | upstream listed, local corpus unobserved |
| increase_liquidity_event | `314f69d420221e54` | liquidity_add | `k_sol_liquidity_events` | upstream listed, local corpus unobserved |
| liquidity_calculate_event | `ed7094e63954b4a2` | unknown | `k_sol_dex_decoded_events_only` | upstream listed, local corpus unobserved |
| liquidity_change_event | `7ef0afce9e58996b` | unknown | `k_sol_dex_decoded_events_only` | upstream listed, local corpus unobserved |
| pool_created_event | `195e4b2f7063353f` | unknown | `k_sol_dex_decoded_events_only` | upstream listed, local corpus unobserved |
| swap_event | `40c6cde8260871e2` | swap | `k_sol_trade_events` | upstream listed, local corpus unobserved |
| update_reward_infos_event | `6d7fba4e724125ec` | reward | `k_sol_reward_events` | upstream listed, local corpus unobserved |
## Patch `pre.19`
Patch goal:
```text
Stop replay/backfill from leaving `upstream_git.instruction_match` rows when a local specialized decoder already covers the same upstream decoder + entry + discriminator.
```
New DB query:
```text
query_dex_decoded_events_delete_locally_covered_upstream_instruction_matches(database, upstream_decoder_code)
```
Called from:
```text
local_pipeline_replay.rs::refresh_event_coverage_best_effort
token_backfill.rs::refresh_event_coverage_best_effort
```
Expected validation after replay:
```text
raydium_clmm.instruction_audit residual query -> empty
upstream_git.instruction_match where upstreamDecoderCode = raydium_clmm -> empty
non-swap CLMM trade_count -> empty
failed CLMM materialization query -> empty
coverage summary remains populated around 45 listed / 33 decoded / 33 observed
```

204
docs/reports/RAYDIUM_CPMM_EVENT_COVERAGE_REPORT.md Normal file
View File

@@ -0,0 +1,204 @@
# Rapport `0.7.48` — Raydium CPMM event coverage
## Scope
Tranche : `0.7.48`.
Decoder local : `raydium_cpmm`.
Programme : `CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C`.
Objectif : couvrir Raydium CPMM au-delà des swaps, avec preuve locale par backfill/replay SQL, sans modifier les règles trade/candle existantes et sans promouvoir de table métier transversale non nécessaire.
## Sources utilisées
Sources principales :
- Carbon `carbon-raydium-cpmm-decoder` ;
- fnzero `solana-streamer` / `sol-parser-sdk` IDL `raydium_cpmm.json` ;
- Raydium CP-Swap officiel ;
- Solscan page programme / Program IDL comme accélérateur de recherche de signatures, notamment via `instruction=<discriminator>`.
Règle retenue : Git/IDL/Solscan sont des indices de recherche. La preuve métier reste le corpus local backfillé puis rejoué.
## Entrées CPMM inventoriées
| Kind | Entrée | Discriminant | État final `0.7.48` |
|---|---|---|---|
| instruction | `close_permission_pda` | `9c5420764587467b` | connu upstream, non observé localement |
| instruction | `collect_creator_fee` | `1416567bc61cdb84` | décodé + matérialisé fee |
| instruction | `collect_fund_fee` | `a78a4e95dfc2067e` | décodé + matérialisé fee |
| instruction | `collect_protocol_fee` | `8888fcddc2427e59` | décodé + matérialisé fee |
| instruction | `create_amm_config` | `8934edd4d7756c68` | décodé + matérialisé admin/config |
| instruction | `create_permission_pda` | `878802d889a9b5ca` | décodé + matérialisé admin/config |
| instruction | `deposit` | `f223c68952e1f2b6` | décodé + matérialisé liquidity add |
| instruction | `initialize` | `afaf6d1f0d989bed` | décodé + matérialisé lifecycle |
| instruction | `initialize_with_permission` | `3f37fe4131b25979` | décodé + matérialisé lifecycle only |
| event | `lp_change_event` | `79a3cdc939da753c` | décodé + matérialisé liquidity bidirectionnelle |
| instruction | `swap_base_input` | `8fbe5adac41e33de` | décodé + trade matérialisé quand transaction OK |
| instruction | `swap_base_output` | `37d96256a34ab4ad` | décodé + trade matérialisé quand transaction OK |
| event | `swap_event` | `40c6cde8260871e2` | décodé audit-only, pas trade/candle |
| instruction | `update_amm_config` | `313cae889a1c74c8` | décodé + matérialisé admin/config |
| instruction | `update_pool_status` | `82576c062ee0757b` | connu upstream, non observé localement |
| instruction | `withdraw` | `b712469c946da122` | décodé + matérialisé liquidity remove |
## Décodage ajouté ou stabilisé
Le decoder spécialisé `raydium_cpmm` couvre maintenant :
- les swaps instruction-scoped `swap_base_input` / `swap_base_output` ;
- les events `Program data:` / Anchor CPI `swap_event` et `lp_change_event` ;
- les instructions lifecycle `initialize` / `initialize_with_permission` ;
- les instructions liquidity `deposit` / `withdraw` ;
- les fees `collect_creator_fee`, `collect_fund_fee`, `collect_protocol_fee` ;
- les instructions admin/config `create_amm_config`, `create_permission_pda`, `update_amm_config` ;
- les instructions connues mais non observées `close_permission_pda`, `update_pool_status` restent listées sans promotion métier.
Le fallback `upstream_git.instruction_match` ne doit plus apparaître pour les instructions CPMM couvertes localement.
## Matérialisation finale validée
Rejeu local validé après backfills ciblés Solscan + Demo Pipeline 2 :
| Event kind | Decoded | Table métier | Materialized | Trade count | Statut |
|---|---:|---|---:|---:|---|
| `raydium_cpmm.collect_creator_fee` | 4 | `k_sol_fee_events` | 4 | 0 | fee materialized |
| `raydium_cpmm.collect_fund_fee` | 7 | `k_sol_fee_events` | 7 | 0 | fee materialized |
| `raydium_cpmm.collect_protocol_fee` | 15 | `k_sol_fee_events` | 15 | 0 | fee materialized |
| `raydium_cpmm.create_amm_config` | 6 | `k_sol_pool_admin_events` | 6 | 0 | admin materialized |
| `raydium_cpmm.create_permission_pda` | 4 | `k_sol_pool_admin_events` | 4 | 0 | admin materialized |
| `raydium_cpmm.deposit` | 11 | `k_sol_liquidity_events` | 11 | 0 | liquidity add materialized |
| `raydium_cpmm.initialize` | 5 | `k_sol_pool_lifecycle_events` | 5 | 0 | lifecycle materialized |
| `raydium_cpmm.initialize_with_permission` | 4 | `k_sol_pool_lifecycle_events` | 4 | 0 | lifecycle only |
| `raydium_cpmm.lp_change_event` | 25 | `k_sol_liquidity_events` | 25 | 0 | liquidity materialized, `changeType` bidirectionnel |
| `raydium_cpmm.swap_base_input` | 750 | `k_sol_trade_events` | 482 | 482 | trade materialized for OK/actionable tx |
| `raydium_cpmm.swap_base_output` | 25 | `k_sol_trade_events` | 17 | 17 | trade materialized for OK/actionable tx |
| `raydium_cpmm.swap_event` | 529 | `k_sol_dex_decoded_events_only` | 0 | 0 | audit-only, no duplicate trade |
| `raydium_cpmm.update_amm_config` | 13 | `k_sol_pool_admin_events` | 13 | 0 | admin materialized |
| `raydium_cpmm.withdraw` | 14 | `k_sol_liquidity_events` | 14 | 0 | liquidity remove materialized |
| `raydium_cpmm.instruction_audit` | 3 | `k_sol_dex_decoded_events_only` | 0 | 0 | unknown audit-only |
Replay final observé :
```text
1124 replayed
561 trades
50 liquidity
9 lifecycle
2224 candle upserts
```
Le total liquidity correspond à :
```text
deposit 11
withdraw 14
lp_change_event 25
-------------------
total 50
```
## `lp_change_event`
`lp_change_event` est un event bidirectionnel :
- `changeType = 0` : add/deposit liquidity ;
- `changeType = 1` : remove/withdraw liquidity.
La coverage statique utilise donc `event_family = liquidity`, pas `liquidity_add`. La matérialisation résout le sens au niveau payload. Les events qui ne contiennent pas directement les mints sont enrichis via le contexte pool/pair local ou via le sibling `deposit` / `withdraw` déjà matérialisé dans la même transaction/replay.
Validation finale :
```text
changeType 0 -> 11 decoded / 11 liquidity / 0 trade
changeType 1 -> 14 decoded / 14 liquidity / 0 trade
```
## `initialize_with_permission`
`initialize_with_permission` est traité comme pool lifecycle only.
Validation finale :
```text
raydium_cpmm.initialize 5 decoded / 5 lifecycle / 0 admin / 0 trade
raydium_cpmm.initialize_with_permission 4 decoded / 4 lifecycle / 0 admin / 0 trade
```
Le cleanup de matérialisation supprime les anciennes lignes admin dérivées si elles existent déjà dans la base.
## Entrées non observées
Solscan avec filtre `instruction=` n'a pas retourné de transaction locale utile pour :
- `close_permission_pda` / `9c5420764587467b` ;
- `update_pool_status` / `82576c062ee0757b`.
Ces entrées restent donc :
```text
upstream_git_mapped_unverified
```
Absence Solscan ne signifie pas absence on-chain absolue, surtout si l'index UI ne couvre pas tout l'historique. Cela suffit cependant pour ne pas les promouvoir sans corpus local.
## Instruction audit inconnue
Le discriminator suivant a été observé localement :
```text
40f4bc78a7e9690a
```
Il produit actuellement `raydium_cpmm.instruction_audit` avec `tradeCandidate=false` / `candleCandidate=false`. Il n'est pas nommé dans la tranche `0.7.48`, faute de preuve upstream/corpus suffisante.
## Recherche Solscan retenue
La page programme Solscan et l'onglet Program IDL sont utiles pour accélérer la recherche :
```text
https://solscan.io/account/CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C#programIdl
```
Le filtre `instruction=<discriminator>` est documenté comme méthode pratique de découverte de signatures à backfiller localement, par exemple :
```text
https://solscan.io/account/CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C?instruction=f223c68952e1f2b6&instruction=b712469c946da122&hide_spam=true&hide_failed=true&show_related=false&sort=desc
```
Solscan reste une aide de recherche, pas une source de vérité métier.
## Table technique ajoutée
`k_sol_instruction_observations` est ajoutée comme table technique d'index local. Elle permet de retrouver les signatures observées par `decoder_code`, `instruction_name` et `discriminator_hex`, sans créer de nouvelle table métier.
Exemple :
```sql
SELECT
instruction_name,
discriminator_hex,
COUNT(*) AS observed_count,
COUNT(DISTINCT signature) AS tx_count
FROM k_sol_instruction_observations
WHERE decoder_code = 'raydium_cpmm'
GROUP BY instruction_name, discriminator_hex
ORDER BY observed_count DESC;
```
## Invariants validés
- `swap_event` ne produit aucun trade/candle.
- `deposit`, `withdraw`, `lp_change_event`, fees, admin/config et lifecycle gardent `trade_count=0`.
- Les transactions failed restent non matérialisées en trade/candle.
- Les side effects SPL Token / Token-2022 (`burn`, `transfer`, `transferChecked`, `closeAccount`) restent hors decoder métier CPMM direct et devront passer par une future table transversale si plusieurs DEX le justifient.
- Aucun program id n'est promu sans corpus local.
## État de clôture
`0.7.48 raydium_cpmm` est clôturable avec deux entrées connues mais non observées :
```text
close_permission_pda
update_pool_status
```
La prochaine tranche fonctionnelle est `0.7.49 raydium_clmm`.

72
docs/reports/RAYDIUM_CPMM_UPSTREAM_COVERAGE_REVIEW_PRE22.md Normal file
View File

@@ -0,0 +1,72 @@
# Raydium CPMM upstream coverage review — 0.7.49-pre.22
## Scope
Compared local `raydium_cpmm` coverage against the currently referenced upstream surfaces:
- Solscan program IDL for `CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C`.
- `sevenlabs-hq/carbon` `raydium-cpmm-decoder`.
- `0xfnzero/sol-parser-sdk` `idl/raydium_cpmm.json`.
- `pinax-network/substreams-solana-idls` `src/raydium/cpmm`.
- Raydium official `raydium-cp-swap` source.
## Local CPMM coverage entries
Local registry currently lists 16 `raydium_cpmm` entries:
### Instructions
- `close_permission_pda` — `9c5420764587467b`
- `collect_creator_fee` — `1416567bc61cdb84`
- `collect_fund_fee` — `a78a4e95dfc2067e`
- `collect_protocol_fee` — `8888fcddc2427e59`
- `create_amm_config` — `8934edd4d7756c68`
- `create_permission_pda` — `878802d889a9b5ca`
- `deposit` — `f223c68952e1f2b6`
- `initialize` — `afaf6d1f0d989bed`
- `initialize_with_permission` — `3f37fe4131b25979`
- `swap_base_input` — `8fbe5adac41e33de`
- `swap_base_output` — `37d96256a34ab4ad`
- `update_amm_config` — `313cae889a1c74c8`
- `update_pool_status` — `82576c062ee0757b`
- `withdraw` — `b712469c946da122`
### Anchor / Program-data events
- `lp_change_event` — `79a3cdc939da753c`
- `swap_event` — `40c6cde8260871e2`
## Upstream comparison
Carbon `raydium-cpmm-decoder` exposes the same 14 instruction modules and the two event-like discriminator entries, `lp_change_event` and `swap_event`.
`sol-parser-sdk` `idl/raydium_cpmm.json` exposes the core CPMM instruction set (`createAmmConfig`, `updateAmmConfig`, `updatePoolStatus`, `collectProtocolFee`, `collectFundFee`, `initialize`, `deposit`, `withdraw`, `swapBaseInput`, `swapBaseOutput`) and IDL events `LpChangeEvent` and `SwapEvent`. The local registry also includes the permission and creator-fee entries present in Carbon / Raydium source.
The official Raydium `raydium-cp-swap` source lists the CPMM program ID and the main program instructions including admin/config, fee collection, permission PDA, initialize, initialize with permission, deposit, withdraw, swap base input, and swap base output.
## Finding
No missing CPMM instruction/event discriminator was identified relative to the reviewed Carbon / Raydium / fnzero / Pinax surfaces available during this check.
## Current local caveat
CPMM remains covered by the earlier 0.7.48 tranche. The useful final validation remains DB-side:
```sql
SELECT
entry_name,
entry_kind,
event_family,
expected_db_target,
proof_status,
local_event_kind,
discriminator_hex,
observed_count,
materialized_count,
trade_count
FROM k_sol_dex_event_coverage_entries
WHERE decoder_code = 'raydium_cpmm'
ORDER BY entry_kind, entry_name, discriminator_hex;
```
Any future upstream addition should appear as a new entry in Carbon/Solscan/IDL and should be added to `upstream_registry_generated.rs`, `known_local_event_kind` only after local decoder support exists, and then validated with local corpus evidence.