khadhroony-bobobot/docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.51-raydium-amm-v4.md

Prompt de reprise — khadhroony-bobobot 0.7.51 / Raydium AMM v4 event coverage

Reprise du projet khadhroony-bobobot après clôture de 0.7.50 raydium_launchpad et re-vérification finale CPMM/CLMM.

Archive de départ

Utiliser la dernière archive complète du workspace intégrant les deltas validés jusqu'à :

0.7.50-raydium-launchpad-final

Joindre aussi les docs et SQL de validation à jour :

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_LAUNCHPAD_EVENT_COVERAGE_REPORT.md
docs/reports/RAYDIUM_CPMM_EVENT_COVERAGE_REPORT.md
validation_sql/SQL_VALIDATION_RAYDIUM_LAUNCHPAD_0_7_50.sql
validation_sql/SQL_VALIDATION_RAYDIUM_CPMM_AUDIT_CLEANUP_0_7_50_FINAL.sql
validation_sql/SQL_VALIDATION_RAYDIUM_CPMM_0_7_50_RECHECK.sql
validation_sql/SQL_VALIDATION_RAYDIUM_CLMM_0_7_50_RECHECK.sql

État validé avant reprise

0.7.50 a clôturé raydium_launchpad et consolidé les rechecks CPMM/CLMM.

Dernier replay local rapporté après cleanup final CPMM :

1124 replayed
0 decode skipped
1124 ledger upserts
539 unsafe ledger rows
561 trades
50 liquidity
13 lifecycle
0 tokenAccount
2224 candle upserts
instructionObservations = 7010
resetDeleted = 1182
catalog = 37 tokens / 40 pools / 40 pairs

Points de clôture à préserver :

raydium_launchpad : surface canonique, program id LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj
Launchpad trade_event matérialisé seulement quand corpus + successful tx le prouvent
Launchpad initialize* fournit le catalogue pool/pair, pas de faux trade/candle
CPMM 40f4bc78a7e9690a est raydium_cpmm.anchor_idl_instruction decoded-only
CPMM residual raydium_cpmm.instruction_audit 40f4bc78a7e9690a = vide après replay final
CPMM decoded event without coverage entry = vide après replay final
CPMM upstream_git.instruction_match fallback résiduel = vide
CPMM non-swap materialization gap hors failed tx = vide
CLMM residual instruction_audit / upstream fallback doivent rester vides
k_sol_instruction_observations reste une table technique, pas une table métier
Solscan instruction=<discriminator> est une aide de découverte, pas une preuve métier

Requêtes CPMM post-fix obligatoires avant d'ouvrir 0.7.51 :

SELECT
    json_extract(payload_json, '$.discriminatorHex') AS discriminator_hex,
    COUNT(*) AS audit_count,
    COUNT(DISTINCT transaction_id) AS tx_count
FROM k_sol_dex_decoded_events
WHERE protocol_name = 'raydium_cpmm'
  AND event_kind = 'raydium_cpmm.instruction_audit'
GROUP BY discriminator_hex
ORDER BY audit_count DESC, discriminator_hex;

SELECT
    de.event_kind,
    COUNT(*) AS decoded_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_dex_event_coverage_entries ce
    ON ce.decoder_code = 'raydium_cpmm'
   AND ce.local_event_kind = de.event_kind
WHERE de.protocol_name = 'raydium_cpmm'
  AND ce.id IS NULL
GROUP BY de.event_kind
ORDER BY decoded_count DESC, de.event_kind;

Ces deux requêtes doivent être vides après replay forceDexDecode=yes.

Décision de reprise

Ouvrir une nouvelle tranche :

0.7.51 raydium_amm_v4

Ne pas commencer par raydium_pool_v4 comme nouveau decoder autonome tant que son program id et son rôle métier ne sont pas prouvés localement.

raydium_pool_v4 doit être traité dans 0.7.51 comme une source à auditer / comparer avec raydium_amm_v4, pas comme version déjà décidée. La roadmap peut conserver une entrée de décision raydium_pool_v4 audit / program-id decision, mais cette entrée doit être reformulée comme décision conditionnelle :

si raydium_pool_v4 correspond au même program id AMM v4 ou à un layout alternatif -> intégrer à raydium_amm_v4
si raydium_pool_v4 correspond à un autre program id / strategy / farm / pool wrapper -> créer une tranche dédiée seulement après corpus local

Objectif 0.7.51 — raydium_amm_v4

Reprendre Raydium AMM v4 legacy au même niveau de couverture que CPMM/CLMM :

swaps
pool lifecycle / pool_create
add_liquidity / remove_liquidity
fees / admin/config
open_orders / target_orders / serum/openbook side effects documentés
side effects SPL Token / Token-2022 documentés mais non promus comme raydium_amm_v4.* directs
fallback instruction_audit nettoyé quand une entrée locale spécialisée couvre l'instruction
coverage entries synchronisées et rafraîchies

Code local canonique :

raydium_amm_v4

Program id canonique connu :

675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8

Solscan Program IDL / recherche par instruction :

https://solscan.io/account/675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8#programIdl
https://solscan.io/account/675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8?instruction=<DISCRIMINATOR>&hide_spam=true&hide_failed=true&show_related=false&sort=desc

Nouvelle base de travail

Démarrer 0.7.51 sur une base SQLite vide dédiée.

Avant le replay de validation complet, prévoir un corpus initial construit volontairement :

1. Demo3 program_id = 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8
2. Solscan Program IDL + instruction=<DISCRIMINATOR>
3. backfill Demo2 de signatures contenant des instructions AMM v4 variées
4. backfill de pools AMM v4 quand Demo3/Solscan fournit un AMM/pool account fiable

Ne pas interpréter l'absence de résultat Solscan comme absence on-chain définitive.

Sources Git/IDL à utiliser systématiquement

Sources globales :

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/0xfnzero/sol-parser-sdk/tree/main/idls
https://github.com/pinax-network/substreams-solana-idls/tree/main/src
https://github.com/hodlwarden/solana-tx-parser/tree/main/src
https://docs.vybenetwork.com/docs/available-dexs-amms

Sources spécifiques raydium_amm_v4 à vérifier en priorité :

https://github.com/sevenlabs-hq/carbon/tree/main/decoders/raydium-amm-v4-decoder
https://github.com/pinax-network/substreams-solana-idls/tree/main/src/raydium/amm
https://github.com/0xfnzero/sol-parser-sdk/blob/main/idl/raydium_amm_v4.json
https://github.com/0xfnzero/sol-parser-sdk/blob/main/idls/raydium_amm_v4.json
https://github.com/0xfnzero/sol-parser-sdk/blob/main/idl/raydium_pool_v4.json
https://github.com/0xfnzero/sol-parser-sdk/blob/main/idls/raydium_pool_v4.json
https://solscan.io/account/675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8#programIdl

Vérification obligatoire raydium_pool_v4

Avant de coder une tranche séparée raydium_pool_v4, faire une vérification explicite :

1. comparer idl/raydium_pool_v4.json et idls/raydium_pool_v4.json
2. comparer idl/raydium_amm_v4.json et idls/raydium_amm_v4.json
3. chercher si raydium_pool_v4 contient un program id explicite
4. comparer les instructions communes : initialize, initialize2, deposit, withdraw, swapBaseIn, swapBaseOut, monitorStep, admin/config
5. vérifier si raydium_pool_v4 décrit :
   - le même Raydium AMM v4 program id 675kPX...
   - un layout alternatif d'instruction
   - un wrapper strategy / pool / farming / lending
   - une ancienne ABI non directement liée au program id 675kPX...
6. ne pas promouvoir `raydium_pool_v4` sans corpus local :
   - k_sol_instruction_observations
   - decoded events locaux
   - coverage local_event_kind
   - absence de fallback upstream

Décision attendue dans 0.7.51 :

Option A : raydium_pool_v4 = alias/source complémentaire de raydium_amm_v4 -> intégrer ses discriminants/layouts dans raydium_amm_v4 et supprimer la version roadmap autonome.
Option B : raydium_pool_v4 = autre program id / autre surface -> conserver une future version dédiée avec program id prouvé.
Option C : raydium_pool_v4 = IDL ambiguë / strategy wrapper sans corpus -> garder en audit roadmap, pas de decoder local.

Règles fixes

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

Invariants métier

non-trade event = jamais trade/candle
failed transaction = audit-only / jamais matérialisée métier
upstream Git/IDL/Solscan = indice, pas preuve métier
program id upstream non promu sans corpus local
side effects SPL Token / Token-2022 restent transversaux sauf preuve multi-DEX et décision DB
instruction_audit et upstream_git.instruction_match doivent être nettoyés quand une entrée locale spécialisée couvre le discriminant

Workflow conseillé

1. Créer une nouvelle base SQLite dédiée 0.7.51.
2. Inventorier Carbon/fnzero/Pinax/Solscan Program IDL pour raydium_amm_v4.
3. Auditer raydium_pool_v4 avant de décider si la roadmap garde une tranche dédiée.
4. Synchroniser k_sol_dex_event_coverage_entries avec decoder_code = raydium_amm_v4.
5. Utiliser Solscan instruction=<discriminator> pour obtenir rapidement des signatures non failed.
6. Backfill Demo2 signature/pool sur corpus varié.
7. Replay local avec :

skipDexDecode = no
forceDexDecode = yes
deferInstructionObservations = yes

8. Vérifier :

coverage listed/observed/materialized
residual instruction_audit
residual upstream_git.instruction_match
failed tx materialization = 0
non-trade trade_count = 0
trade/candle only for swap events validés
raydium_pool_v4 decision documented

SQL de contrôle minimal 0.7.51

Coverage AMM v4 :

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_amm_v4'
ORDER BY entry_kind, entry_name, discriminator_hex;

Instruction observations :

SELECT
    instruction_name,
    discriminator_hex,
    COUNT(*) AS observed_count,
    COUNT(DISTINCT signature) AS tx_count
FROM k_sol_instruction_observations
WHERE decoder_code = 'raydium_amm_v4'
GROUP BY instruction_name, discriminator_hex
ORDER BY observed_count DESC, instruction_name, discriminator_hex;

Residual audit :

SELECT
    json_extract(payload_json, '$.discriminatorHex') AS discriminator_hex,
    COUNT(*) AS audit_count,
    COUNT(DISTINCT transaction_id) AS tx_count
FROM k_sol_dex_decoded_events
WHERE protocol_name = 'raydium_amm_v4'
  AND event_kind = 'raydium_amm_v4.instruction_audit'
GROUP BY discriminator_hex
ORDER BY audit_count DESC, discriminator_hex;

Fallback upstream :

SELECT
    json_extract(ug.payload_json, '$.upstreamDecoderCode') AS upstream_decoder_code,
    json_extract(ug.payload_json, '$.upstreamEntryName') AS entry_name,
    json_extract(ug.payload_json, '$.upstreamDiscriminatorHex') AS discriminator_hex,
    json_extract(ug.payload_json, '$.upstreamSourceRepo') AS source_repo,
    COUNT(*) AS fallback_count,
    COUNT(DISTINCT ug.transaction_id) AS tx_count
FROM k_sol_dex_decoded_events ug
JOIN k_sol_dex_event_coverage_entries ce
    ON ce.decoder_code = json_extract(ug.payload_json, '$.upstreamDecoderCode')
   AND ce.entry_name = json_extract(ug.payload_json, '$.upstreamEntryName')
   AND ce.discriminator_hex = json_extract(ug.payload_json, '$.upstreamDiscriminatorHex')
   AND ce.local_event_kind IS NOT NULL
   AND ce.local_event_kind <> ''
WHERE ug.protocol_name = 'upstream_git'
  AND ug.event_kind = 'upstream_git.instruction_match'
  AND json_extract(ug.payload_json, '$.upstreamDecoderCode') = 'raydium_amm_v4'
GROUP BY upstream_decoder_code, entry_name, discriminator_hex, source_repo
ORDER BY fallback_count DESC, entry_name;

Non-swap safety :

SELECT
    de.event_kind,
    ce.event_family,
    COUNT(*) AS decoded_count,
    COUNT(te.id) AS trade_count
FROM k_sol_dex_decoded_events de
LEFT JOIN k_sol_dex_event_coverage_entries ce
    ON ce.decoder_code = 'raydium_amm_v4'
   AND ce.local_event_kind = de.event_kind
LEFT JOIN k_sol_trade_events te
    ON te.decoded_event_id = de.id
WHERE de.protocol_name = 'raydium_amm_v4'
GROUP BY de.event_kind, ce.event_family
HAVING ce.event_family <> 'swap'
   AND COUNT(te.id) > 0
ORDER BY trade_count DESC, de.event_kind;

Livrables attendus

archive delta fichiers modifiés/ajoutés
README.md / ROADMAP.md / CHANGELOG.md mis à jour
docs/DEX_DECODER_MATRIX.md
docs/DEX_EVENT_COVERAGE_MATRIX.md
docs/DB_EVENT_MODEL_REVIEW.md
docs/reports/RAYDIUM_AMM_V4_EVENT_COVERAGE_REPORT.md
docs/reports/RAYDIUM_POOL_V4_DECISION_NOTE.md
validation_sql/SQL_VALIDATION_RAYDIUM_AMM_V4_0_7_51.sql

Validation finale locale :

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