Sasedev/khadhroony-bobobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.7.28

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-05-11 11:02:47 +02:00
parent d66afede28
commit 7f130dba6b
49 changed files with 10301 additions and 8481 deletions
Download Patch File Download Diff File Expand all files Collapse all files

463
README.md
View File

@@ -2,256 +2,259 @@
# khadhroony-bobobot
Projet personnel Rust de détection, d’analyse de patterns et de trading/swap semi-automatisé de tokens et meme-tokens sur la blockchain Solana.
`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 du projet est de construire une application capable de :
L’objectif opérationnel est de construire progressivement une application capable de :
- détecter la création de tokens et de paires sur Solana,
- suivre leur évolution technique et de marché,
- collecter des informations utiles au filtrage,
- analyser des patterns statistiques ou comportementaux,
- préparer ensuite la gestion de wallets et les opérations de swap/trading.
- 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.
Les cibles observées incluent notamment les DEX et protocoles tels que :
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.
- Pump.fun
- PumpSwap
- Raydium
- Meteora
- Bags
- FluxBeam
- LaunchLab / LaunchBeam
- Heaven
- DexLab
- Moonit
- Zora
## 2. Workspace
La liste exacte pourra évoluer au fil du projet.
Le workspace contient deux crates principales.
## 2. Architecture générale
| 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. |
Le workspace Rust est organisé autour de deux sous-crates principales :
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.
- `kb_lib`
- `kb_demo_app`
## 3. État actuel autour de `0.7.27`
### `kb_lib`
### 3.1. Socle stabilisé à ne pas refactorer maintenant
`kb_lib` porte la logique métier et technique :
Ces éléments fonctionnent et ne sont pas bloquants pour les DEX. Ils ne doivent pas être remaniés dans la phase immédiate :
- configuration JSON,
- tracing,
- constantes Solana,
- clients réseau HTTP / WebSocket,
- gestion future de gRPC Yellowstone,
- persistance,
- analyse de patterns,
- gestion des wallets,
- logique de détection et de filtrage.
- `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 :
### `kb_demo_app`
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
`kb_demo_app` est l’application Demo Tauri V2 avec frontend TypeScript.
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 :
Son rôle est de :
- `pump_fun` ;
- `pump_swap` ;
- `raydium_cpmm` ;
- `raydium_clmm`.
- afficher l’interface utilisateur,
- exposer les commandes Tauri,
- déléguer la logique à `kb_lib`,
- afficher les états, logs et événements remontés par la bibliothèque.
### 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 :
Le crate expose une bibliothèque interne `kb_demo_app_lib` afin de limiter le couplage avec `main.rs` et de préparer une évolution mobile ultérieure.
- `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`.
## 3. Contraintes techniques
## 4. Matrice DEX et launch surfaces
Le projet suit des contraintes strictes.
La distinction importante est la suivante :
### Contraintes de style et de structure
- 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.
- Rust 2024.
- Pas de `mod.rs`.
- Les fichiers Rust commencent par une entête `// file: ...`.
- Les fichiers `lib.rs` et `main.rs` activent `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]`.
- Les éléments publics sont documentés.
- Les expositions publiques passent par la racine des crates.
### Contraintes de code
- pas de `anyhow`,
- pas de `thiserror`,
- pas de `?` dans le code applicatif,
- pas de `unwrap` ni `expect` dans le code applicatif,
- utilisation préférée de `match`, `if let Err`, `let Err = ... else`.
Les tests unitaires peuvent utiliser `?`, `unwrap` et `expect` si nécessaire.
### Contraintes d’import
- pas de `use` sur les types/fonctions des crates externes,
- seuls les imports de traits sont tolérés,
- les appels doivent utiliser les chemins complets, par exemple `std::string::String` ou `tokio::sync::mpsc::Sender`.
## 4. Configuration
L’application utilisera un fichier `config.json`.
La configuration devra à terme permettre de définir :
- les endpoints HTTP,
- les endpoints WebSocket,
- leur nom logique,
- les rôles affectés à chaque endpoint,
- les limitations de débit,
- les délais et timeouts,
- les répertoires locaux,
- la base SQLite,
- le futur répertoire des wallets Solana,
- les paramètres de tracing,
- la politique de reconnexion.
Chaque endpoint devra pouvoir être identifié et affecté à une tâche spécifique, par exemple :
- réception des notifications de slots,
- réception des program subscriptions,
- réception des logs,
- exécution des requêtes HTTP,
- endpoint de secours.
Cela permet de répartir la charge ou d’adapter le provider selon son niveau de service, ses limitations ou l’usage d’une API key.
## 5. Tracing et logs
Le tracing sera centralisé dans `kb_lib`.
Le système devra supporter :
- sortie console,
- sortie fichier,
- niveau configurable,
- format de message configurable,
- format temporel configurable,
- ANSI console activable/désactivable,
- comportement spécifique pour les tests.
## 6. Clients réseau
## 6.1. `WsClient`
`kb_lib` devra contenir un `WsClient` asynchrone basé sur `tokio-tungstenite`.
Exigences initiales :
- client duplicable,
- connexion à plusieurs serveurs WS RPC,
- identifiants de requêtes incrémentaux par instance,
- flux de lecture et flux d’écriture séparés,
- séparation des réponses RPC et des notifications,
- registre `subscribe` / `unsubscribe`,
- tentative d’unsubscribe avant fermeture,
- timeout pour ne pas bloquer le disconnect.
Le client ne devra pas s’appuyer sur `solana-pubsub-client`, même si son comportement fonctionnel peut s’en inspirer.
## 6.2. `HttpClient`
`kb_lib` devra contenir un `HttpClient` asynchrone basé sur `reqwest`.
Exigences initiales :
- client duplicable,
- connexion à plusieurs endpoints HTTP RPC,
- limites de requêtes configurables,
- profils par endpoint,
- adaptation à des providers publics ou privés.
Le client ne devra pas s’appuyer sur le `RpcClient` officiel de `solana-client`.
## 6.3. `GrpcClient`
Le support `GrpcClient` basé sur `yellowstone-grpc-client` et `yellowstone-grpc-proto` est prévu dans une phase ultérieure.
## 7. Types et RPC
Le projet cherchera à réutiliser autant que possible les types officiels fournis par l’écosystème Solana, notamment pour les payloads et surtout pour le parsing des réponses.
Objectif :
- limiter l’invention de structures approximatives,
- réutiliser les types des crates officielles lorsque cela est pertinent,
- encapsuler si besoin ces types dans une couche propre au projet.
Le projet pourra embarquer son propre générateur de requêtes JSON-RPC 2.0 afin d’encapsuler proprement les appels HTTP et WS.
## 8. Base de données
Le stockage initial se fera dans SQLite.
Cette première étape doit permettre :
- de conserver l’historique observé,
- de stocker des événements et états techniques,
- de préparer l’analyse.
Une migration vers PostgreSQL pourra être envisagée plus tard lorsque l’application aura stabilisé ses besoins.
## 9. Frontend
L’application Tauri démarrera avec une interface volontairement simple.
### UI minimale prévue
- un bouton ou toggle de connexion,
- un bouton d’arrêt si nécessaire,
- une zone de texte scrollable et en lecture seule,
- affichage des messages reçus depuis `kb_lib`.
Cette première UI servira surtout à valider :
- l’initialisation,
- le tracing,
- la délégation vers `kb_lib`,
- la remontée d’événements depuis les clients réseau.
## 10. Constantes Solana
Le projet devra réutiliser autant que possible les Program IDs et identifiants officiels fournis par les crates officielles au lieu de les recopier à la main.
Exemples :
- SPL Token
- SPL Token-2022
- Associated Token Account
- Wrapped SOL mint
- System Program
- Compute Budget Program
## 11. Génération de bindings TypeScript
Les structures partagées entre Rust et le frontend devront être générées avec `ts-rs`.
Le flux prévu est :
```bash
cargo test export_bindings
### 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.
```
Exemple déjà présent :
- `kb_demo_app/src/splash.rs`
- `kb_demo_app/frontend/ts/bindings/SplashOrder.ts`
## 12. État du projet
voir `CHANGELOG.md`
## 13. Feuille de route
La feuille de route détaillée est disponible dans :
- `ROADMAP.md`
## 14. Licence
Licence MIT.