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

```text
0.7.50-raydium-launchpad-final
```

Joindre aussi les docs et SQL de validation à jour :

```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_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 :

```text
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 :

```text
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` :

```sql
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;
```

```sql
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 :

```text
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 :

```text
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 :

```text
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 :

```text
raydium_amm_v4
```

Program id canonique connu :

```text
675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8
```

Solscan Program IDL / recherche par instruction :

```text
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 :

```text
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 :

```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/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é :

```text
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 :

```text
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` :

```text
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

```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
```

## Invariants métier

```text
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 :

```text
skipDexDecode = no
forceDexDecode = yes
deferInstructionObservations = yes
```

8. Vérifier :

```text
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 :

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

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_amm_v4'
GROUP BY instruction_name, discriminator_hex
ORDER BY observed_count DESC, instruction_name, discriminator_hex;
```

Residual audit :

```sql
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 :

```sql
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 :

```sql
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

```text
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 :

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