add Readme / Roadmap / Changelog
This commit is contained in:
265
README.md
Normal file
265
README.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# file: README.md
|
||||
|
||||
# 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.
|
||||
|
||||
## 1. Objectif
|
||||
|
||||
L’objectif du projet est de construire 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.
|
||||
|
||||
Les cibles observées incluent notamment les DEX et protocoles tels que :
|
||||
|
||||
- Pump.fun
|
||||
- PumpSwap
|
||||
- Raydium
|
||||
- Meteora
|
||||
- Bags
|
||||
- FluxBeam
|
||||
- LaunchLab / LaunchBeam
|
||||
- Heaven
|
||||
- DexLab
|
||||
- Moonit
|
||||
- Zora
|
||||
|
||||
La liste exacte pourra évoluer au fil du projet.
|
||||
|
||||
## 2. Architecture générale
|
||||
|
||||
Le workspace Rust est organisé autour de deux sous-crates principales :
|
||||
|
||||
- `kb_lib`
|
||||
- `kb_app`
|
||||
|
||||
### `kb_lib`
|
||||
|
||||
`kb_lib` porte la logique métier et technique :
|
||||
|
||||
- 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.
|
||||
|
||||
### `kb_app`
|
||||
|
||||
`kb_app` est l’application Tauri V2 avec frontend TypeScript.
|
||||
|
||||
Son rôle est de :
|
||||
|
||||
- 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.
|
||||
|
||||
Le crate expose une bibliothèque interne `kb_app_lib` afin de limiter le couplage avec `main.rs` et de préparer une évolution mobile ultérieure.
|
||||
|
||||
## 3. Contraintes techniques
|
||||
|
||||
Le projet suit des contraintes strictes.
|
||||
|
||||
### Contraintes de style et de structure
|
||||
|
||||
- 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
|
||||
```
|
||||
|
||||
Exemple déjà présent :
|
||||
|
||||
- `kb_app/src/splash.rs`
|
||||
- `kb_app/frontend/ts/bindings/SplashOrder.ts`
|
||||
|
||||
## 12. État du projet
|
||||
|
||||
Le dépôt est actuellement à un stade de fondation.
|
||||
|
||||
Les premières priorités sont :
|
||||
|
||||
- remettre le squelette en conformité,
|
||||
- poser la configuration JSON,
|
||||
- poser le tracing,
|
||||
- préparer `WsClient` et `HttpClient`,
|
||||
- brancher une UI Tauri minimale.
|
||||
|
||||
## 13. Feuille de route
|
||||
|
||||
La feuille de route détaillée est disponible dans :
|
||||
|
||||
- `Roadmap.md`
|
||||
|
||||
## 14. Licence
|
||||
|
||||
Licence MIT.
|
||||
Reference in New Issue
Block a user