khadhroony-bobobot/NEXT_SESSION_PROMPT_0.7.49_RAYDIUM_CLMM.md

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'à :

0.7.48-raydium-cpmm-final

Docs à fournir aussi :

README.md
ROADMAP.md
CHANGELOG.md
DEX_DECODER_MATRIX.md
DEX_EVENT_COVERAGE_MATRIX.md
DB_EVENT_MODEL_REVIEW.md
RAYDIUM_CPMM_EVENT_COVERAGE_REPORT.md
SQL_VALIDATION_RAYDIUM_CPMM_0_7_48.sql

État validé avant reprise

0.7.48 a clôturé la tranche raydium_cpmm :

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 :

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 :

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 :

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 :

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 :

https://solscan.io/account/CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK#programIdl

et les filtres Solscan de type :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

cargo fmt
cargo test -p kb_lib
cargo clippy -p kb_lib --all-targets -- -D warnings