<!-- file: docs/prompts/PROMPT_0_7_53_PUMP_SWAP.md -->

# Prompt de reprise — `0.7.53 pump_swap`

Nous reprenons le workspace Rust/Tauri `khadhroony-bobobot` après le commit final `0.7.52 raydium_stable_swap`.

## Objectif de tranche

Version cible : `0.7.53`

Surface cible unique : `pump_swap`

Program id cible unique :

```text
pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA
```

Règle de phasage validée : **une version = un `program_id`**.

`raydium_pool_v4.json` est explicitement repoussé vers la fin du phasage. Il ne doit pas bloquer `0.7.53`.

## Contexte validé avant reprise

Raydium est clos sur les surfaces suivantes :

- `raydium_cpmm` — `CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C` ;
- `raydium_clmm` — `CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK` ;
- `raydium_launchpad` — `LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj` ;
- `raydium_amm_v4` — `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8` ;
- `raydium_stable_swap` — `5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h`.

`0.7.52 raydium_stable_swap` est clos avec :

- `cargo test -p kb_lib` : `407 passed`, `0 failed` ;
- `cargo clippy -p kb_lib --all-targets -- -D warnings` : OK ;
- swaps matérialisés uniquement depuis `amountSource=stable_swap_vault_balance_delta` ;
- failed transactions conservées decoded-only ;
- aucun successful swap non expliqué.

## Sources à utiliser pour `pump_swap`

Sources obligatoires à vérifier avant de patcher :

- `kb_lib/src/constants.rs` et `SOLSCAN_ACCOUNT_SOURCES` ;
- sources upstream Git déjà intégrées dans le registre : Carbon, fnzero, Pinax, HODL Warden si disponibles ;
- IDL Solscan du programme `pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA` si disponible ;
- corpus local Demo3 + backfill signature/pool ;
- `k_sol_dex_event_coverage_entries` après replay.

Les sources Git/IDL/Solscan sont des indices. La preuve métier exige corpus local, replay et SQL.

## Tâches attendues

1. Inspecter le support local existant de `pump_swap`.
2. Lister toutes les instructions/events/discriminators disponibles depuis les sources upstream/IDL.
3. Comparer avec les events localement couverts.
4. Compléter le decoder `pump_swap` pour couvrir au minimum :
   - `buy` ;
   - `sell` ;
   - fees / creator fees / protocol fees si présents ;
   - admin/config si présents ;
   - events auxiliaires tels que cashback, volume accumulator ou équivalents si présents dans les sources.
5. Matérialiser en `k_sol_trade_events` et `k_sol_pair_candles` uniquement si les montants exacts et le sens économique sont prouvés.
6. Conserver les failed transactions comme decoded-only avec `failed_transaction`.
7. Matérialiser les non-trade uniquement vers les tables adaptées : liquidity, fee, admin, lifecycle, reward, orderbook ou decoded-only selon le cas.
8. Nettoyer les fallbacks `upstream_git.instruction_match` uniquement quand un decoder local spécialisé couvre vraiment l’entrée.
9. Mettre à jour la coverage DB et la matrice documentaire.
10. Ajouter ou mettre à jour le SQL de validation dédié : `validation_sql/SQL_VALIDATION_PUMP_SWAP_0_7_53.sql`.

## Invariants obligatoires

- Aucun non-swap ne doit créer de trade/candle.
- Aucune transaction failed ne doit créer de trade/candle.
- Aucun trade/candle ne doit être créé depuis des bornes d’instruction ou des montants incomplets.
- Aucun router/aggregator ne doit créer un doublon si le DEX effectif matérialise déjà le trade.
- Aucun `program_id` ne doit être inventé.
- Aucun compte non-programme de `SOLSCAN_ACCOUNT_SOURCES` ne doit être promu en decoder autonome.
- `kb_demo_app` ne doit pas contenir de logique métier DEX profonde.

## Contraintes de code

Respecter les contraintes du projet :

- Rust 2024 ;
- aucun fichier `mod.rs` ;
- pas de `pub mod` ; utiliser `mod` + `pub use` ;
- pas de `anyhow`, pas de `thiserror` ;
- pas de `?`, `unwrap`, `expect` dans le code applicatif `kb_lib` ;
- gestion d’erreurs explicite via `match`, `if let Err`, `let Err = ... else` ;
- rustdoc publique ;
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` ;
- tracing obligatoire ;
- tests offline ;
- si une requête DB est ajoutée ou modifiée, mettre à jour les re-exports dans `kb_lib/src/db.rs`, puis dans `kb_lib/src/lib.rs`.

## Validation attendue

Commandes locales à exécuter après patch :

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

Replay attendu sur une base dédiée `0.7.53 pump_swap` :

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

SQL de clôture attendu :

- coverage par entrée `pump_swap` ;
- instruction observations ;
- absence d’audit résiduel local non expliqué ;
- absence de fallback upstream pour les entrées couvertes localement ;
- failed tx -> zéro trade ;
- non-swap -> zéro trade ;
- decoded without coverage -> vide ;
- successful non-materialized inexpliqués -> vide ;
- multi-target materialization -> vide ;
- résumé matérialisation par event_kind.

## Livrables documentaires

Mettre à jour au minimum :

- `ROADMAP.md` ;
- `CHANGELOG.md` ;
- `docs/DEX_DECODER_MATRIX.md` ;
- `docs/DEX_EVENT_COVERAGE_MATRIX.md` ;
- `docs/reports/PUMP_SWAP_EVENT_COVERAGE_REPORT.md` ;
- `validation_sql/SQL_VALIDATION_PUMP_SWAP_0_7_53.sql`.

## Décision attendue en fin de tranche

`0.7.53 pump_swap` est clôturable uniquement si :

```text
- tous les events/instructions disponibles ont un statut explicite ;
- les swaps réussis exploitables produisent trades/candles ;
- les failed transactions restent decoded-only ;
- les non-trade sont matérialisés dans les bonnes tables ou restent decoded-only expliqués ;
- la coverage DB ne contient pas de gap local inexpliqué ;
- cargo test et clippy sont OK.
```