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

# Prompt de reprise — khadhroony-bobobot 0.7.54 — pump_fun

Tu reprends le workspace Rust/Tauri `khadhroony-bobobot` après clôture documentaire et fonctionnelle de `0.7.53 pump_swap`.

## 1. Fichiers à utiliser comme base

Je fournis l’archive la plus récente du workspace, intégrant normalement les deltas de clôture `0.7.53`.

À considérer comme sources locales de savoir :

- le code Rust du workspace ;
- les fichiers Markdown (`README.md`, `ROADMAP.md`, `CHANGELOG.md`, `docs/**`) ;
- les SQL de validation dans `validation_sql/**` ;
- le répertoire `idls/**`, ajouté au projet, contenant des IDL JSON téléchargés depuis Solscan ;
- les liens Git/upstream déjà documentés dans les docs ;
- les résultats SQL/logs que je colle dans la conversation.

Ne pas supposer que les docs sont parfaites : les vérifier contre le code et contre les IDL locales.

## 2. État validé avant cette version

La version `0.7.53` a fermé `pump_swap` côté transaction/log decoder :

- `cargo test -p kb_lib` : `421 passed`;
- `cargo clippy -p kb_lib --all-targets -- -D warnings` : OK ;
- `pump_swap.buy`, `pump_swap.sell`, `pump_swap.buy_exact_quote_in` matérialisent correctement les trades ;
- `buy_exact_quote_in` utilise `pump_swap_anchor_buy_event` quand l’Anchor `BuyEvent` exact est disponible ;
- les `*_event` Anchor PumpSwap sont décodés en audit-only sauf exception métier explicite ;
- `claim_token_incentives_event` est prêt à matérialiser `k_sol_reward_events` si un event réussi apparaît ;
- `pump_swap` ne présente plus de decoded event sans coverage, ni fallback upstream résiduel, ni trade candidate réussi non matérialisé ;
- les surfaces Raydium déjà travaillées (`raydium_amm_v4`, `raydium_clmm`, `raydium_cpmm`) ne doivent pas être rouvertes sauf bug prouvé ;
- les petits gaps Meteora sont volontairement différés.

Ne pas modifier PumpSwap ou Raydium sauf preuve SQL/code claire d’une régression.

## 3. Objectif de la version 0.7.54

Objectif principal : ouvrir et avancer une tranche `pump_fun`.

Cette tranche doit traiter la surface launch/mint Pump.fun, qui est logiquement prioritaire avant `pump_fees`.

Le backlog global montre des entrées `pump_fun` encore en fallback upstream, notamment :

- `pump_fun.collect_creator_fee` / discriminator `1416567bc61cdb84` ;
- `pump_fun.migrate_bonding_curve_creator` / `577c34bf3426d6e8` ;
- `pump_fun.distribute_creator_fees` / `a572670079cef751` ;
- `pump_fun.admin_set_creator` / `4519ab8e39ef0d04` ;
- `pump_fun.extend_account` / `ea66c2cb96483ee5` ;
- `pump_fun.set_creator` / `fe94ff70cf8eaaa5` ;
- `pump_fun.migrate` / `9beae792ec9ea21e` ;
- `pump_fun.claim_cashback` / `253a237ebe35e4c5` ;
- `pump_fun.sell` / `33e685a4017f83ad` ;
- autres discriminators `pump_fun` observés dans `k_sol_instruction_observations`.

L’objectif n’est pas seulement de faire disparaître un fallback : il faut couvrir proprement la surface `pump_fun` :

- registry/coverage ;
- decoder local ou statut local explicitement decoded-only/audit-only ;
- matérialisation métier si les données sont fiables ;
- tests unitaires ;
- SQL de validation ;
- documentation.

## 4. Périmètre

### Inclus

- `pump_fun` launch/mint/bonding-curve surface ;
- instructions/events liés à création/migration/configuration/creator fees/cashback si présents dans IDL ou corpus ;
- intégration coverage ;
- matérialisation vers tables métier seulement si fiable.

### Hors périmètre sauf nécessité démontrée

- `pump_swap`, déjà fermé en `0.7.53` ;
- `raydium_*`, sauf régression prouvée ;
- `meteora_*`, volontairement différé ;
- `jupiter_swap`, `dflow_aggregator_v4`, `onchain_labs_dex_v2`, `orca_whirlpools`, backlog futur ;
- `pump_fees`, qui doit venir après `pump_fun`, probablement en `0.7.55`.

## 5. Méthode obligatoire

### 5.1 Nouvelle base SQLite

Créer une nouvelle DB dédiée à `0.7.54`, ne pas travailler sur l’ancienne DB de validation PumpSwap.

Démarrage attendu :

- catalog initial propre ou connu ;
- backfills ciblés ;
- replay forcé ;
- validation SQL.

### 5.2 Backfill de corpus

Construire un corpus local à partir de :

1. filtres Solscan.io quand disponibles ;
2. Demo3 discovery quand nécessaire ;
3. batch backfill de groupes de signatures ;
4. program/signature backfill si pertinent ;
5. signatures issues des requêtes SQL `sample_signature`.

Utiliser d’abord les signatures fortes observées dans le backlog :

- `pump_fun.collect_creator_fee`;
- `pump_fun.migrate_bonding_curve_creator`;
- `pump_fun.distribute_creator_fees`;
- `pump_fun.admin_set_creator`;
- `pump_fun.extend_account`;
- `pump_fun.set_creator`;
- `pump_fun.migrate`;
- `pump_fun.claim_cashback`;
- puis autres discriminators observés.

Après chaque groupe de backfill :

- replay local avec `skipDexDecode=no`;
- utiliser `forceDexDecode=yes` quand le decoder/coverage change ;
- `deferInstructionObservations=yes` ;
- rafraîchir catalog ;
- relancer les SQL de surveillance.

### 5.3 Sources

Utiliser en priorité :

- `idls/**` local ;
- code existant ;
- docs existantes ;
- `upstream_registry_generated.rs` ;
- sources Git déjà référencées dans les docs ;
- Solscan signatures/logs ;
- payloads locaux DB.

Si une IDL locale contredit une source Git, signaler la divergence et ne pas inventer.

## 6. Contraintes de code Rust

Respecter strictement les conventions du projet :

- Rust 2024 ;
- pas de `?` ;
- pas de `unwrap()` / `expect()` en code applicatif ;
- pas de `anyhow` / `thiserror` ;
- `match` / `if let Err` explicites ;
- async-first ;
- `tracing` obligatoire ;
- pas de `mod.rs` ;
- pas de `pub mod` ; utiliser `mod` + `pub use` ;
- imports limités, types appelés de façon qualifiée quand c’est la convention locale ;
- tests offline ;
- ne pas casser `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]`.

Si des requêtes DB sont ajoutées ou déplacées, penser aux re-exports :

- `kb_lib/src/db.rs` ;
- `kb_lib/src/lib.rs`.

## 7. Matérialisation attendue

Pour `pump_fun`, ne pas forcer une matérialisation si les montants/acteurs/comptes ne sont pas prouvés.

Classer explicitement chaque entrée :

- `k_sol_launch_events` pour les événements de launch/mint/migration ;
- `k_sol_fee_events` si l’instruction représente réellement des frais exploitables ;
- `k_sol_pool_admin_events` si c’est de la configuration/admin/creator ;
- `k_sol_reward_events` uniquement si c’est réellement une récompense/incitation/cashback fiable ;
- `k_sol_dex_decoded_events_only` si audit-only ou données insuffisantes ;
- `k_sol_trade_events` seulement si c’est un swap/trade fiable ;
- `skip*Reason` explicite quand non matérialisable.

Ne jamais matérialiser une transaction failed comme business event.

## 8. SQL de validation à utiliser

Utiliser et adapter :

- `validation_sql/SQL_VALIDATION_DEX_COVERAGE_GLOBAL_0_7_53.sql`;
- les SQL de validation PumpSwap comme modèle ;
- une nouvelle validation dédiée à `pump_fun`, par exemple :
  - `validation_sql/SQL_VALIDATION_PUMP_FUN_0_7_54.sql`.

Requêtes minimales attendues :

1. coverage `pump_fun` ;
2. instruction observations `pump_fun` ;
3. decoded events `pump_fun` sans coverage ;
4. fallback upstream `pump_fun` résiduel ;
5. successful non-materialized events sans skip reason ;
6. failed tx materialization safety ;
7. multi-target materialization safety ;
8. materialization summary ;
9. comparaison entre `k_sol_instruction_observations` et `k_sol_dex_event_coverage_entries` ;
10. global watchlist après replay.

## 9. Invariants de validation

Après correction, viser :

- pas de `pump_fun` decoded event local sans coverage ;
- pas de fallback `upstream_git` résiduel pour les entrées `pump_fun` couvertes localement ;
- pas de materialized business event sur failed transaction ;
- pas de multi-target incohérent ;
- tous les events/instructions observés ont :
  - un decoder local,
  - ou un statut audit-only,
  - ou un skip reason explicite,
  - ou une justification documentée s’ils restent upstream-only.

## 10. Documentation à mettre à jour

À la fin de la tranche, mettre à jour :

- `CHANGELOG.md` : une ligne ;
- `README.md` : état courant, nouvelle version, validation ;
- `ROADMAP.md` : phasage et clôture/état de `pump_fun`, puis annonce de `pump_fees` en version suivante ;
- `docs/DEX_DECODER_MATRIX.md` ;
- `docs/DEX_EVENT_COVERAGE_MATRIX.md` ;
- éventuellement un rapport :
  - `docs/reports/PUMP_FUN_EVENT_COVERAGE_REPORT.md`.

Ne pas gonfler les docs inutilement : noter les faits validés, les limites, et les prochaines tranches.

## 11. Format de livraison attendu

Ne pas fournir une archive complète du workspace sauf demande explicite.

Fournir un delta zip contenant uniquement les fichiers modifiés/ajoutés.

Nom recommandé :

`khadhroony-bobobot-v0.7.54-pump_fun-delta-N-files.zip`

Chaque réponse de livraison doit inclure :

- résumé des changements ;
- liste exacte des fichiers modifiés ;
- commandes à lancer :
  - `cargo fmt`
  - `cargo test -p kb_lib`
  - `cargo clippy -p kb_lib --all-targets -- -D warnings`
- replay recommandé ;
- SQL à exécuter ;
- ce qui est attendu dans les résultats.

## 12. Priorités si plusieurs gaps apparaissent

Ordre de priorité :

1. `pump_fun` ;
2. `pump_fees` seulement si strictement nécessaire pour comprendre un flux `pump_fun` ;
3. ne pas traiter Meteora dans cette version ;
4. ne pas rouvrir Raydium sauf régression démontrée ;
5. ne pas ouvrir Jupiter/dFlow/onchain_labs dans cette tranche sauf pour les classer en backlog.

## 13. Première tâche demandée

Commencer par analyser l’archive fournie :

1. identifier les fichiers existants liés à `pump_fun`, `pump_fees`, upstream registry, coverage, materialization ;
2. chercher dans `idls/**` s’il existe une IDL Solscan liée à `pump_fun` ;
3. produire un état des lieux court :
   - entrées upstream disponibles ;
   - entrées observées dans SQL/logs fournis ;
   - fichiers à modifier ;
   - hypothèse de classification par entry ;
   - SQL initial de backfill/validation ;
4. proposer puis produire le premier delta archive minimal.
