khadhroony-bobobot/README.md

<!-- file: README.md -->

# khadhroony-bobobot

`khadhroony-bobobot` est un workspace Rust destiné à la détection, au décodage, à l’analyse et, à terme, au trading semi-automatisé de tokens Solana.

Le README précédent décrivait surtout l’état `0.3.1`. Ce fichier reflète l’état de reprise autour de `0.7.37-A` : le socle transport HTTP/WS, la résolution transactionnelle, le modèle SQLite, plusieurs connecteurs DEX, les candles, les signaux analytiques, la validation locale et une matrice DEX commune existent déjà.

## 1. Objectif

L’objectif opérationnel est de construire progressivement une application capable de :

- détecter l’apparition de nouveaux tokens, pools, paires et listings sur Solana ;
- identifier la première source de mint ou de lancement, même lorsque le token migre ensuite vers un autre DEX ;
- décoder les transactions pertinentes des DEX et launch surfaces ciblés ;
- séparer les swaps/candles des événements utiles seulement à l’analyse : liquidité, cycle de vie de pool, fees, rewards, administration, wallets observés ;
- produire des métriques exploitables : prix, volume, candles/OHLCV, activité, bursts, déséquilibres buy/sell, signaux analytiques ;
- préparer ensuite des règles déterministes de filtrage, d’achat, de vente, de stop-loss et de trailing stop ;
- conserver une traçabilité locale suffisante pour rejouer, diagnostiquer et améliorer les décodeurs.

Le but court terme n’est pas encore le live trading. Le but court terme est de fiabiliser le décodage multi-DEX et la matérialisation des objets métier nécessaires au trading.

## 2. Workspace

Le workspace contient deux crates principales.

| Crate | Rôle |
|---|---|
| `kb_lib` | Bibliothèque métier : configuration, tracing, clients réseau, pool HTTP, manager WS, résolution transactionnelle, décodage DEX, détection métier, persistance SQLite, backfill, metadata, candles, signaux analytiques. |
| `kb_demo_app` | Application Tauri V2 de démonstration et d’inspection : fenêtres `Demo Ws`, `Demo Ws Manager`, `Demo Http`, `Demo Pipeline`, `Demo Pipeline 2`, graphiques candles et commandes de backfill/replay. |

La logique métier doit rester dans `kb_lib`. `kb_demo_app` doit rester une façade UI/Tauri et ne doit pas récupérer de logique Solana ou DEX profonde.

## 3. État actuel autour de `0.7.37-A`

### 3.1. Socle stabilisé à ne pas refactorer maintenant

Ces éléments fonctionnent et ne sont pas bloquants pour les DEX. Ils ne doivent pas être remaniés dans la phase immédiate :

- `ws_client.rs` ;
- `ws_manager.rs` ;
- `http_client.rs` ;
- `http_pool.rs` ;
- couches JSON-RPC WS/HTTP déjà stabilisées ;
- orchestration réseau utilisée par les fenêtres de démonstration.

Ils pourront être améliorés plus tard, mais la priorité actuelle est le décodage DEX, les événements métier et les tables d’analyse.

### 3.2. Pipeline métier existant

Le pipeline `0.7.x` couvre déjà les étapes suivantes :

1. réception d’observations via RPC WS ou backfill HTTP ;
2. résolution des transactions via HTTP RPC ;
3. projection transactionnelle normalisée en base ;
4. décodage DEX dans `k_sol_dex_decoded_events` ;
5. détection métier vers tokens, pools, paires, listings, origins et wallets observés ;
6. matérialisation des trades exploitables ;
7. agrégation pair metrics ;
8. génération candles/OHLCV ;
9. signaux analytiques simples ;
10. inspection via l’application de démonstration.

### 3.3. Connecteurs validés ou observés via l’application de démo

Les connecteurs suivants sont les surfaces actuellement les plus importantes pour la validation locale :

- `pump_fun` comme surface de launch / mint initial ;
- `pump_swap` pour les swaps post-migration Pump ;
- `raydium_cpmm` ;
- `raydium_clmm` ;
- `meteora_dlmm` ;
- `meteora_damm_v1`, partiel : les swaps sans payload montant/prix exploitable restent conservés mais non actionnables ;
- `meteora_damm_v2`, observé dans le corpus `0.7.36`, mais les swaps sans payload montant/prix exploitable sont maintenant `non_actionable_trade` ;
- `meteora_dbc`, observé dans le corpus `0.7.36`, mais les swaps sans payload montant/prix exploitable sont maintenant `non_actionable_trade`.

### 3.4. Connecteurs déjà présents mais à consolider par corpus

Les modules suivants existent ou sont partiellement représentés dans le code, mais doivent encore être consolidés par corpus local, invariants et documentation :

- `orca_whirlpools` ;
- `fluxbeam` ;
- `dexlab` ;
- `raydium_amm_v4` legacy ;
- launch origins déjà amorcées : `meteora_fun_launch`, `bags`, `moonit` ;
- launch surfaces à venir : `raydium_launchlab`, `raydium_launchpad`, `letsbonk` / `bonk`, `boop_fun`, `moonshot`, `believe`, `heaven`.

### 3.5. Validation acquise en `0.7.36`

La validation `0.7.36_meteora_family_consolidation` est considérée comme réalisée lorsque les invariants suivants restent vrais après replay local :

- `validationPassed = true` ;
- `diagnosticsClean = true` ;
- `blockingIssueCount = 0` ;
- `decodedTradeCandidateWithoutTradeEventCount = 0` ;
- `decodedTradeCandidateWithoutAmountPayloadCount = 0` ;
- `missingTradeEventCount = 0` ;
- `pairWithoutTradeCount = 0` pour les paires actionnables ;
- `pairWithoutCandleCount = 0` pour les paires actionnables.

Point important : `meteora_damm_v2` et `meteora_dbc` peuvent produire beaucoup d’événements `swap` décodés sans produire de `trade_events` lorsque les montants ou prix ne sont pas fiables. Ces événements doivent rester `non_actionable_trade` et ne doivent pas être comptés comme `tradeCandidate` ou `candleCandidate`.

## 4. Matrice DEX et launch surfaces

La distinction importante est la suivante :

- un **DEX effectif** permet de détecter et décoder des swaps, pools, liquidité et candles ;
- une **launch surface** peut être la première source de mint ou de lancement, même si le token migre ensuite vers Raydium, Meteora ou un autre AMM ;
- pour le trading, la première source de mint est une information de filtrage et de ciblage aussi importante que le DEX final.

### 4.1. Matrice de travail

Depuis `0.7.29`, la matrice de support DEX est portée par `kb_lib/src/dex_support_matrix.rs`. Elle centralise le code interne, la famille, la version, le type de surface, les program ids vérifiés localement, le statut de support, les capacités actuelles et les raisons de skip.

Depuis `0.7.30`, les événements décodés reçoivent aussi une classification plus fine : `eventLifecycleKind`, `eventActionability` et `nonTradeUseful`. Cette classification sert aux diagnostics et prépare la matérialisation future des événements non-trade sans alimenter directement les trades/candles.

Depuis `0.7.32`, les diagnostics distinguent explicitement les gaps littéraux de catalogue (`literalPairWithoutTradeCount`, `literalPairWithoutCandleCount`) des gaps bloquants/actionnables (`blockingPairWithoutTradeCount`, `blockingPairWithoutCandleCount`). Les anciens champs `pairWithoutTradeCount` et `pairWithoutCandleCount` restent exposés comme alias de compatibilité pour les gaps bloquants/actionnables.

Depuis `0.7.33`, les diagnostics ajoutent une classification `pairTradingReadiness` au niveau des paires et des résumés agrégés `pairTradingReadinessSummaries`. Cette classification sépare les paires directement lisibles/tradables contre WSOL ou stable, les paires inversées avec WSOL/stable en base, les paires cross-quote nécessitant un routeur/aggregator, les paires non matérialisées en trade et les cas de quote inconnue. Elle reste purement diagnostique : elle ne modifie ni le replay, ni les `trade_events`, ni les candles.

| Code cible | Type | Statut `0.7.29` | Prochaine action |
|---|---:|---|---|
| `pump_fun` | Launch + bonding curve | partiel | verrouiller le rattachement mint initial -> pools migrés |
| `pump_swap` | AMM / swap | supporté | conserver invariants trade/candle |
| `raydium_cpmm` | AMM | supporté | conserver invariants trade/candle |
| `raydium_clmm` | CLMM | supporté | conserver invariants trade/candle |
| `raydium_launchlab` | Launch surface | planifié, program id local connu | ajouter decoder/materialization dédiée |
| `raydium_launchpad` | Launch surface | à vérifier | ne pas inventer de program id |
| `raydium_amm_v4` | AMM legacy | partiel | traiter après les autres Raydium avec corpus dédié |
| `meteora_dlmm` | DLMM | supporté | verrouiller corpus et non-régression |
| `meteora_damm_v1` | AMM legacy | partiel validé | conserver le skip explicite des swaps sans montants exploitables |
| `meteora_damm_v2` | AMM | partiel validé `0.7.36` | conserver les swaps sans amounts en `non_actionable_trade`; ajouter extraction de montants seulement avec preuve |
| `meteora_dbc` | Launch / bonding curve | partiel validé `0.7.36` | conserver les swaps sans amounts en `non_actionable_trade`; étudier migration / launch origin |
| `meteora_dlc` | À vérifier | à vérifier | confirmer surface/program id avant intégration |
| `orca_whirlpools` | CLMM | partiel | corpus fiable et validation des instructions utiles |
| `fluxbeam` | AMM | partiel | corpus fiable avant validation |
| `dexlab` | AMM | partiel | corpus fiable avant validation |
| `bags` | Launch surface | planifié | conserver comme origine de lancement si corpus le prouve |
| `letsbonk` / `bonk` | Launch surface | planifié | ajouter comme origine de mint/lancement sans supposer un AMM autonome |
| `okx_dex` | Aggregator/router | planifié | classifier sans matérialiser en trade direct avant preuve |
| `boop_fun` | Launch surface | planifié | ajouter comme origine de mint/lancement et migration |
| `moonshot` / `moonit` | Launch surface | planifié | remplacer les heuristiques faibles par corpus et règles prouvées |
| `believe` | Launch surface | planifié | confirmer comptes, migration et rattachement |
| `heaven` | Launch + AMM candidat | planifié | ajouter corpus et déterminer séparation launch/swap |
| `zora` | À vérifier | à vérifier | ne pas intégrer avant preuve de programme Solana pertinent |

## 5. Base de données

SQLite reste le stockage local initial.

Organisation actuelle à conserver :

- `kb_lib/src/db/schema.rs` crée les tables et index ;
- chaque table/index est créée dans une fonction dédiée ;
- les requêtes sont sous `kb_lib/src/db/queries/` ;
- les entités persistées sont sous `kb_lib/src/db/entities/` ;
- les DTO applicatifs sont sous `kb_lib/src/db/dtos/`.

`schema.rs` n’est donc pas un fichier métier à splitter immédiatement. Il reste acceptable tant qu’il garde uniquement la responsabilité de création de schéma.

### 5.1. Tables existantes importantes

Le modèle actuel contient déjà notamment :

- transactions et instructions Solana normalisées ;
- DEX connus ;
- événements DEX décodés ;
- tokens, pools, pool tokens, paires, listings ;
- launch surfaces et attributions ;
- pool origins ;
- swaps et trade events ;
- liquidity events ;
- wallets, participations, holdings ;
- candles ;
- metrics et analytic signals ;
- diagnostics locaux.

### 5.2. Tables existantes à stabiliser pour les cas non-trade et inconnus

Avant d’étendre trop agressivement les DEX, ces tables doivent être stabilisées et raccordées progressivement aux diagnostics et matérialisations :

| Table cible | Rôle |
|---|---|
| `k_sol_transaction_classifications` | classifier les transactions connues, inconnues, partielles, échouées, non-DEX, DEX-candidates, launch-candidates. |
| `k_sol_protocol_candidates` | conserver les programmes ou patterns suspects/récurrents qui ne correspondent pas encore à un DEX connu. |
| `k_sol_pool_lifecycle_events` | matérialiser initialize/create/migrate/open/close/status events. |
| `k_sol_fee_events` | conserver fees, creator fees, protocol fees, fund fees. |
| `k_sol_reward_events` | conserver reward params, init rewards, collect rewards. |
| `k_sol_pool_admin_events` | conserver changements de config, authority, pause/resume, paramètres de pool. |

`k_sol_liquidity_events` existe déjà et doit être stabilisée/étendue plutôt que recréée sans nécessité.

## 6. Politique de refactor actuelle

Le code et la documentation sont vivants. Les refactors agressifs sont acceptables lorsque cela rend le pipeline plus propre et plus durable, à condition de respecter ces limites :

- ne pas casser les fonctionnalités déjà validées ;
- ne pas toucher pour le moment aux clients et managers réseau stabilisés ;
- faire des étapes courtes, testables et rejouables ;
- conserver les invariants de replay local ;
- ne pas transformer un événement non price-action en trade/candle ;
- documenter les nouveaux types publics avec une rustdoc utile mais pas surchargée ;
- laisser `local_pipeline_diagnostics` servir d’outil temporaire de validation tant que les DEX ne sont pas stabilisés.

Les fichiers à surveiller en priorité sont :

| Fichier | Action recommandée |
|---|---|
| `kb_lib/src/dex_decode.rs` | extraire classification, catégories d’événements et enrichissement commun. |
| `kb_lib/src/dex_detect.rs` | extraire helpers communs pool/pair/listing/origin/wallets et isoler les handlers par famille. |
| `kb_lib/src/trade_aggregation.rs` | isoler extraction de montants, normalisation trade et pricing. |
| `kb_lib/src/dex/*.rs` | homogénéiser les contrats de décodeurs sans forcer un gros trait prématuré. |

## 7. Contraintes de code

Contraintes maintenues :

- Rust 2024 ;
- pas de `mod.rs` ;
- fichiers Rust avec entête `// file: ...` ;
- fichiers `.toml` avec entête `# file: ...` ;
- exposition centralisée via `lib.rs` ;
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` dans les racines concernées ;
- pas de `anyhow` ;
- pas de `thiserror` ;
- pas de `?`, `unwrap`, `expect` dans le code applicatif ;
- usage privilégié de `match`, `if let Err`, `let Err = ... else` ;
- imports externes limités, sauf traits lorsque nécessaire ;
- tests unitaires et tests de replay maintenus.

Les tests peuvent rester plus souples lorsque cela clarifie le test.

## 8. Priorité immédiate

La phase actuelle est `0.7.37_token_metadata_catalog_enrichment`.

Objectif : rendre le catalogue local exploitable visuellement et analytiquement sans toucher aux invariants de décodage/trade validés en `0.7.36`.

À faire en priorité :

1. ajouter ou compléter un registre local des mints connus : `SOL`, `WSOL`, `USDC`, `USDT`, puis autres mints fréquents si vérifiés ;
2. améliorer le service de backfill metadata pour traiter les tokens déjà présents en base ;
3. exposer un résumé de metadata manquantes par asset class, protocole d’origine, DEX et quote asset ;
4. rafraîchir automatiquement ou explicitement les `pair_symbol` après mise à jour des tokens ;
5. ajouter une commande UI ou clarifier la commande existante pour relancer le metadata backfill ;
6. vérifier l’idempotence : relancer le backfill metadata ne doit pas recréer tokens/pools/pairs/trades ;
7. conserver les compteurs DEX propres : `blockingIssueCount = 0`, `actionableMissingTradeEventCount = 0`, `missingTradeEventCount = 0` ;
8. préparer ensuite les launch surfaces, qui deviennent l’étape suivante de la roadmap.

## 9. Fichiers utiles pour reprendre dans une nouvelle session

Pour reprendre rapidement le codage dans une nouvelle session, fournir au minimum :

- `README.md` ;
- `ROADMAP.md` ;
- `CHANGELOG.md` ;
- `Cargo.toml` racine ;
- `kb_lib/Cargo.toml` ;
- `kb_lib/src/lib.rs` ;
- `kb_lib/src/constants.rs` ;
- `kb_lib/src/dex.rs` ;
- `kb_lib/src/dex/*.rs` ;
- `kb_lib/src/dex_decode.rs` ;
- `kb_lib/src/dex_detect.rs` ;
- `kb_lib/src/trade_aggregation.rs` ;
- `kb_lib/src/pair_candle_aggregation.rs` ;
- `kb_lib/src/local_pipeline_replay.rs` ;
- `kb_lib/src/local_pipeline_validation.rs` ;
- `kb_lib/src/local_pipeline_diagnostics.rs` ;
- `kb_lib/src/db/schema.rs` ;
- `kb_lib/src/db.rs` ;
- `kb_lib/src/db/entities.rs` et `kb_lib/src/db/entities/*` ;
- `kb_lib/src/db/dtos.rs` et `kb_lib/src/db/dtos/*` ;
- `kb_lib/src/db/queries.rs` et `kb_lib/src/db/queries/*`.

Ajouter `kb_demo_app/src/demo_pipeline*.rs` seulement si la tâche concerne l’UI ou les diagnostics affichés.