khadhroony-bobobot/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 :

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 :

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 :

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 :

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