khadhroony-bobobot/docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.48-raydium-cpmm.md

<!-- file: docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.48-raydium-cpmm.md -->

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