khadhroony-bobobot/docs/prompts/PROMPT_REPRISE_khadhroony-bobobot_0.7.50-raydium-launchpad.md

<!-- 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é.