258 lines
7.0 KiB
Markdown
258 lines
7.0 KiB
Markdown
<!-- 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
|
||
|
||
voir `CHANGELOG.md`
|
||
|
||
## 13. Feuille de route
|
||
|
||
La feuille de route détaillée est disponible dans :
|
||
|
||
- `ROADMAP.md`
|
||
|
||
## 14. Licence
|
||
|
||
Licence MIT.
|