261 lines
13 KiB
Markdown
261 lines
13 KiB
Markdown
<!-- 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.27` : le socle transport HTTP/WS, la résolution transactionnelle, le modèle SQLite, plusieurs connecteurs DEX, les candles, les signaux analytiques et l’application de démonstration 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.27`
|
||
|
||
### 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 manuellement via l’application de démo
|
||
|
||
Les connecteurs suivants ont déjà été testés via l’application de démonstration et doivent être verrouillés par corpus/replay avant d’ajouter de nouveaux DEX :
|
||
|
||
- `pump_fun` ;
|
||
- `pump_swap` ;
|
||
- `raydium_cpmm` ;
|
||
- `raydium_clmm`.
|
||
|
||
### 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 être consolidés par corpus local, invariants et documentation :
|
||
|
||
- `meteora_dbc` ;
|
||
- `meteora_damm_v1` ;
|
||
- `meteora_damm_v2` ;
|
||
- `orca_whirlpools` ;
|
||
- `fluxbeam` ;
|
||
- `dexlab` ;
|
||
- `raydium_amm_v4` legacy ;
|
||
- launch origins déjà amorcées : `meteora_fun_launch`, `bags`, `moonit`.
|
||
|
||
## 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
|
||
|
||
| Code cible | Type | Statut actuel | Prochaine action |
|
||
|---|---:|---|---|
|
||
| `pump_fun` | Launch + bonding curve | testé via démo | verrouiller corpus, invariants et documentation |
|
||
| `pump_swap` | AMM / swap | testé via démo | verrouiller corpus, invariants et candles |
|
||
| `raydium_cpmm` | AMM | testé via démo | verrouiller corpus, swaps et candles |
|
||
| `raydium_clmm` | CLMM | testé via démo | verrouiller corpus, swaps et candles |
|
||
| `raydium_launchlab` / `raydium_launchpad` | Launch surface + migration | manquant | ajouter comme origine de mint/lancement et migration vers Raydium |
|
||
| `raydium_amm_v4` | AMM legacy | présent, à isoler | traiter après les autres Raydium avec corpus dédié |
|
||
| `meteora_dbc` | Launch / bonding curve | présent, à consolider | corpus, lifecycle, migration et swaps exploitables |
|
||
| `meteora_damm_v1` | AMM legacy | présent, à consolider | corpus et séparation swaps/liquidité/events |
|
||
| `meteora_damm_v2` | AMM | présent, à consolider | corpus et séparation swaps/liquidité/events |
|
||
| `meteora_dlmm` | DLMM | manquant | ajouter à la matrice, puis corpus avant décodage |
|
||
| `orca_whirlpools` | CLMM | présent, à consolider | corpus fiable et validation des instructions utiles |
|
||
| `fluxbeam` | DEX | présent, à consolider | corpus fiable avant validation |
|
||
| `dexlab` | DEX | présent, à consolider | corpus fiable avant validation |
|
||
| `bags` | Launch surface / attribution | amorcé | conserver comme origine de lancement, relier à Meteora si prouvé |
|
||
| `letsbonk` / `bonk_fun` | Launch surface | manquant | ajouter comme origine LaunchLab/Raydium, pas comme AMM autonome tant que non prouvé |
|
||
| `boop_fun` | Launch surface | manquant | ajouter comme origine de mint/lancement et migration |
|
||
| `moonshot` / `moonit` | Launch surface | amorcé partiellement | remplacer les heuristiques faibles par corpus et règles prouvées |
|
||
| `believe` | Launch surface | manquant | ajouter comme origine associée à Meteora DBC si les comptes l’attestent |
|
||
| `heaven` | Launch + AMM candidat | manquant | ajouter corpus et déterminer séparation launch/swap |
|
||
| `zora_solana` | À vérifier | écarté maintenant | 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 futures prioritaires
|
||
|
||
Avant d’étendre trop agressivement les DEX, le modèle doit prévoir les cas non directement tradables :
|
||
|
||
| 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 reprise doit suivre cet ordre :
|
||
|
||
1. finir/verrouiller `0.7.27` sur `pump_fun`, `pump_swap`, `raydium_cpmm`, `raydium_clmm` ;
|
||
2. démarrer `0.7.28` par un refactor commun DEX sans toucher au transport ;
|
||
3. ajouter la matrice DEX documentée et les corpus de validation ;
|
||
4. ajouter les tables de classification des transactions inconnues et protocol candidates ;
|
||
5. matérialiser les événements non-trade : lifecycle, liquidité, fees, rewards, admin ;
|
||
6. consolider Meteora, y compris `meteora_dlmm` dans la matrice ;
|
||
7. ajouter les launch surfaces manquantes comme origines de mint : LaunchLab/Launchpad, LetsBonk/Bonk.fun, Boop.fun, Moonshot/Moonit, Believe ;
|
||
8. traiter Heaven ;
|
||
9. consolider Orca/FluxBeam/DexLab ;
|
||
10. isoler Raydium AMM v4 legacy ;
|
||
11. effectuer une validation DEX v1 consolidée ;
|
||
12. reprendre ensuite l’UI analytique et les vues token/pair/pool.
|
||
|
||
## 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.
|
||
|
||
## 10. Prompt court de reprise
|
||
|
||
```text
|
||
Je reprends le workspace Rust khadhroony-bobobot autour de la version 0.7.27.
|
||
Objectif actuel : finaliser le pipeline DEX Solana avant trading.
|
||
Ne pas toucher pour le moment à ws_client/ws_manager/http_client/http_pool : ils fonctionnent et sont non bloquants.
|
||
Priorité : refactor DEX commun à partir de 0.7.28, matrice DEX, transactions inconnues/protocol candidates, événements non-trade, puis ajout/consolidation des DEX et launch surfaces.
|
||
Respecter les contraintes : Rust 2024, pas de mod.rs, pas de anyhow/thiserror, pas de ?/unwrap/expect dans le code applicatif, rustdoc utile sur l’API publique.
|
||
Les connecteurs à verrouiller avant extension sont pump_fun, pump_swap, raydium_cpmm et raydium_clmm.
|
||
Les launch surfaces sont importantes comme première source de mint, même si le token migre ensuite vers Raydium/Meteora/autre.
|
||
```
|