add Readme / Roadmap / Changelog
This commit is contained in:
413
ROADMAP.md
Normal file
413
ROADMAP.md
Normal file
@@ -0,0 +1,413 @@
|
||||
# file: Roadmap.md
|
||||
|
||||
# khadhroony-bobobot — Roadmap
|
||||
|
||||
## 1. Objet du projet
|
||||
|
||||
`khadhroony-bobobot` est un workspace Rust destiné à la détection, l’observation, l’analyse de patterns et, à terme, à l’exécution semi-automatisée d’achats/ventes de tokens sur la blockchain Solana.
|
||||
|
||||
Le projet vise en priorité :
|
||||
|
||||
- la détection de création de tokens et de paires sur différents DEX,
|
||||
- la réception et le tri des événements on-chain et RPC,
|
||||
- la collecte de métriques utiles au filtrage,
|
||||
- l’analyse statistique et comportementale des patterns,
|
||||
- la préparation d’une couche wallet puis swap/trading.
|
||||
|
||||
## 2. Principes d’architecture
|
||||
|
||||
### 2.1. Structure générale
|
||||
|
||||
Le workspace est organisé autour de deux sous-crates principales :
|
||||
|
||||
- `kb_lib` : bibliothèque métier, réseau, config, tracing, stockage, analyse et logique applicative.
|
||||
- `kb_app` : application Tauri V2 avec frontend TypeScript, chargée de l’interface et de la délégation vers `kb_lib`.
|
||||
|
||||
### 2.2. Contraintes de code
|
||||
|
||||
Le socle du projet doit respecter les contraintes suivantes :
|
||||
|
||||
- Rust 2024.
|
||||
- Aucun fichier `mod.rs`.
|
||||
- Exposition centralisée à la racine des crates via `lib.rs` ou `main.rs`.
|
||||
- Pas d’usage de `anyhow` ni `thiserror`.
|
||||
- Pas d’usage de `?`, `unwrap`, `expect` dans le code applicatif.
|
||||
- Utilisation de `match`, `if let Err`, `let Err = ... else`.
|
||||
- Documentation Rust obligatoire sur les éléments publics.
|
||||
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` activés et respectés.
|
||||
- Pas de `use` pour les types/fonctions externes, sauf pour les traits.
|
||||
- Tests unitaires importants et maintenus à chaque étape.
|
||||
|
||||
### 2.3. Règles de responsabilité
|
||||
|
||||
- `kb_app` ne doit pas embarquer la logique métier réseau ou Solana.
|
||||
- `kb_app` doit seulement orchestrer l’UI, les commandes Tauri et les appels vers `kb_lib`.
|
||||
- `kb_lib` doit porter les clients réseau, la config, le tracing, les types partagés, les registres et la logique métier.
|
||||
|
||||
## 3. Vision fonctionnelle
|
||||
|
||||
Le projet doit pouvoir évoluer progressivement vers les capacités suivantes :
|
||||
|
||||
1. Connexion à plusieurs endpoints HTTP / WS RPC Solana.
|
||||
2. Répartition des rôles par endpoint.
|
||||
3. Réception des notifications de slots, comptes, programmes, logs, signatures, blocs.
|
||||
4. Détection de créations de tokens, pools et paires sur plusieurs DEX.
|
||||
5. Collecte de métriques : liquidité, market cap, volume, prix, activité.
|
||||
6. Persistance locale dans SQLite, puis évolution possible vers PostgreSQL.
|
||||
7. Analyse de patterns et filtrage des tokens non tradables.
|
||||
8. Gestion de wallets Solana.
|
||||
9. Préparation puis exécution semi-automatisée de swaps/trading.
|
||||
10. Intégration future de gRPC Yellowstone.
|
||||
|
||||
## 4. Configuration cible
|
||||
|
||||
La configuration applicative sera stockée dans un fichier `config.json`.
|
||||
|
||||
### 4.1. Points à couvrir dans la configuration
|
||||
|
||||
Le fichier devra à terme permettre de configurer :
|
||||
|
||||
- les endpoints HTTP,
|
||||
- les endpoints WebSocket,
|
||||
- un nom logique par endpoint,
|
||||
- le rôle ou les tâches affectées à chaque endpoint,
|
||||
- les limites de débit par endpoint,
|
||||
- les options spécifiques aux providers publics ou privés,
|
||||
- les chemins de stockage local,
|
||||
- le répertoire des wallets Solana,
|
||||
- le tracing et ses formats,
|
||||
- la stratégie de reconnexion,
|
||||
- les paramètres de base de données,
|
||||
- les options d’UI persistées plus tard.
|
||||
|
||||
### 4.2. Exemple de catégories attendues
|
||||
|
||||
- `app`
|
||||
- `logging`
|
||||
- `database`
|
||||
- `wallets`
|
||||
- `network`
|
||||
- `solana`
|
||||
- `http_endpoints`
|
||||
- `ws_endpoints`
|
||||
|
||||
### 4.3. Exigences particulières
|
||||
|
||||
Chaque endpoint devra pouvoir porter sa propre configuration, par exemple :
|
||||
|
||||
- nom logique,
|
||||
- URL,
|
||||
- provider,
|
||||
- présence ou non d’une clé API,
|
||||
- plafond de requêtes,
|
||||
- burst,
|
||||
- timeout,
|
||||
- usages autorisés,
|
||||
- rôle principal.
|
||||
|
||||
Exemples de rôles futurs :
|
||||
|
||||
- `slot_notifications`
|
||||
- `program_subscriptions`
|
||||
- `account_subscriptions`
|
||||
- `logs_subscriptions`
|
||||
- `http_queries`
|
||||
- `fallback`
|
||||
|
||||
## 5. Tracing cible
|
||||
|
||||
Le tracing devra être centralisé dans `kb_lib`.
|
||||
|
||||
### 5.1. Exigences initiales
|
||||
|
||||
- sortie console paramétrable,
|
||||
- sortie fichier paramétrable,
|
||||
- niveau de log configurable,
|
||||
- format du message configurable,
|
||||
- format du temps configurable,
|
||||
- ANSI console activable/désactivable,
|
||||
- fonctionnement compatible tests,
|
||||
- séparation claire entre initialisation et usage.
|
||||
|
||||
### 5.2. Objectifs complémentaires
|
||||
|
||||
- pouvoir distinguer les logs du transport WS,
|
||||
- distinguer les logs HTTP,
|
||||
- distinguer les logs Tauri/UI,
|
||||
- distinguer les logs DB,
|
||||
- préparer une traçabilité par endpoint et par client.
|
||||
|
||||
## 6. Phasage par versions
|
||||
|
||||
## 6.1. Version `0.0.2` — Socle conforme
|
||||
|
||||
Objectif : corriger le squelette et poser la base de travail.
|
||||
|
||||
À faire :
|
||||
|
||||
- corriger `kb_lib/src/lib.rs`,
|
||||
- créer `KbError`,
|
||||
- créer `KbConfig`,
|
||||
- créer `init_tracing`,
|
||||
- créer les constantes Solana officielles,
|
||||
- préparer les modules `ws_client` et `http_client`,
|
||||
- remettre `kb_app/src/lib.rs` en conformité,
|
||||
- documenter `kb_app/src/splash.rs`,
|
||||
- garder une UI minimale avec bouton connect / disconnect et zone de sortie.
|
||||
|
||||
Livrables :
|
||||
|
||||
- squelette propre,
|
||||
- config JSON minimale,
|
||||
- tracing centralisé,
|
||||
- UI Tauri minimale opérationnelle,
|
||||
- premiers types partagés.
|
||||
|
||||
## 6.2. Version `0.1.x` — Transport WebSocket générique
|
||||
|
||||
Objectif : construire un vrai `WsClient` asynchrone clonable.
|
||||
|
||||
À faire :
|
||||
|
||||
- `connect`, `disconnect`, `is_connected`,
|
||||
- flux de lecture séparé du flux d’écriture,
|
||||
- identifiant incrémental interne par client,
|
||||
- canal sortant borné,
|
||||
- émission d’événements internes,
|
||||
- support de l’arrêt propre,
|
||||
- fermeture avec timeout.
|
||||
|
||||
Contraintes :
|
||||
|
||||
- aucune reconnexion implicite au départ,
|
||||
- pas d’usage de `solana-pubsub-client`,
|
||||
- tests offline avec serveur mock.
|
||||
|
||||
## 6.3. Version `0.2.x` — Couche JSON-RPC WS Solana
|
||||
|
||||
Objectif : séparer clairement transport, réponses RPC et notifications.
|
||||
|
||||
À faire :
|
||||
|
||||
- enveloppes JSON-RPC 2.0,
|
||||
- gestion des `request_id`,
|
||||
- registre des requêtes en attente,
|
||||
- distinction entre requêtes standard et subscribe/unsubscribe,
|
||||
- parsing des réponses,
|
||||
- séparation stricte des notifications.
|
||||
|
||||
Livrables :
|
||||
|
||||
- registre `request_id -> pending kind`,
|
||||
- registre `subscription_id -> metadata`,
|
||||
- tests de corrélation et de séparation des flux.
|
||||
|
||||
## 6.4. Version `0.3.x` — Registre subscriptions / notifications
|
||||
|
||||
Objectif : fiabiliser la gestion des subscriptions.
|
||||
|
||||
À faire :
|
||||
|
||||
- stockage des subscriptions actives,
|
||||
- mapping entre requête de subscribe et `subscription_id` serveur,
|
||||
- unsubscribe propre avant fermeture,
|
||||
- timeout d’attente sur unsubscribe,
|
||||
- purge locale même si le serveur ne répond pas,
|
||||
- routage séparé des notifications.
|
||||
|
||||
## 6.5. Version `0.4.x` — Transport HTTP générique
|
||||
|
||||
Objectif : construire un `HttpClient` clonable et limité.
|
||||
|
||||
À faire :
|
||||
|
||||
- client `reqwest` asynchrone,
|
||||
- limites req/sec,
|
||||
- burst configurable,
|
||||
- délais configurables,
|
||||
- profils par endpoint,
|
||||
- endpoints publics ou API-key.
|
||||
|
||||
Livrables :
|
||||
|
||||
- `HttpClient`,
|
||||
- abstraction de requêtes JSON-RPC HTTP,
|
||||
- premiers appels sur endpoints Solana.
|
||||
|
||||
## 6.6. Version `0.5.x` — Base de données SQLite
|
||||
|
||||
Objectif : poser la persistance locale.
|
||||
|
||||
À faire :
|
||||
|
||||
- configuration DB dans `config.json`,
|
||||
- ouverture/validation SQLite,
|
||||
- premières tables techniques,
|
||||
- stockage des endpoints, événements, tokens observés, subscriptions actives si utile.
|
||||
|
||||
## 6.7. Version `0.6.x` — Détection technique on-chain / RPC
|
||||
|
||||
Objectif : commencer la détection utile pour l’application.
|
||||
|
||||
À faire :
|
||||
|
||||
- réception de notifications ciblées,
|
||||
- détection de créations de comptes/programmes d’intérêt,
|
||||
- débuts de normalisation d’événements,
|
||||
- premiers connecteurs DEX.
|
||||
|
||||
## 6.8. Version `0.7.x` — DEX connectors v1
|
||||
|
||||
Objectif : structurer les connecteurs par protocole.
|
||||
|
||||
Cibles initiales possibles :
|
||||
|
||||
- Pump.fun
|
||||
- PumpSwap
|
||||
- Raydium
|
||||
- Meteora
|
||||
- FluxBeam
|
||||
- DexLab
|
||||
|
||||
À faire :
|
||||
|
||||
- identification des programmes,
|
||||
- décodage des événements utiles,
|
||||
- création de types métiers propres,
|
||||
- enrichissement des métadonnées token/pool/pair.
|
||||
|
||||
## 6.9. Version `0.8.x` — Analyse et filtrage
|
||||
|
||||
Objectif : transformer les événements bruts en signaux exploitables.
|
||||
|
||||
À faire :
|
||||
|
||||
- agrégation des métriques,
|
||||
- règles de filtrage,
|
||||
- exclusions des tokens non tradables,
|
||||
- statistiques de comportement,
|
||||
- premiers patterns.
|
||||
|
||||
## 6.10. Version `1.x.y` — Wallets et swap préparatoire
|
||||
|
||||
Objectif : préparer la couche d’action.
|
||||
|
||||
À faire :
|
||||
|
||||
- gestion du répertoire wallets,
|
||||
- chargement sécurisé des keypairs,
|
||||
- abstraction wallet,
|
||||
- préparation d’ordres et de swaps,
|
||||
- simulation et garde-fous.
|
||||
|
||||
## 6.11. Version `2.x.y` — Trading semi-automatisé
|
||||
|
||||
Objectif : brancher l’analyse à l’action tout en gardant des garde-fous explicites.
|
||||
|
||||
À faire :
|
||||
|
||||
- scénarios d’achat/vente,
|
||||
- règles d’entrée/sortie,
|
||||
- limites de risque,
|
||||
- confirmations explicites ou semi-automatiques,
|
||||
- journaux d’exécution.
|
||||
|
||||
## 6.12. Version `3.x.y` — Yellowstone gRPC
|
||||
|
||||
Objectif : ajouter le connecteur gRPC dédié.
|
||||
|
||||
À faire :
|
||||
|
||||
- `GrpcClient` basé sur `yellowstone-grpc-client`,
|
||||
- adaptation du pipeline d’événements,
|
||||
- coexistence HTTP / WS / gRPC,
|
||||
- politique de répartition par source.
|
||||
|
||||
## 7. Organisation des modules ciblés
|
||||
|
||||
## 7.1. `kb_lib`
|
||||
|
||||
Modules cibles à court terme :
|
||||
|
||||
- `error.rs`
|
||||
- `config.rs`
|
||||
- `tracing.rs`
|
||||
- `constants.rs`
|
||||
- `types.rs`
|
||||
- `ws_client.rs`
|
||||
- `http_client.rs`
|
||||
- `rpc_json.rs`
|
||||
- `rpc_ws.rs`
|
||||
|
||||
## 7.2. `kb_app`
|
||||
|
||||
Responsabilités cibles :
|
||||
|
||||
- lancement Tauri,
|
||||
- commandes UI,
|
||||
- affichage des états et messages,
|
||||
- réception des événements venant de `kb_lib`,
|
||||
- persistance future des préférences UI.
|
||||
|
||||
## 8. Ligne de conduite sur le `WsClient`
|
||||
|
||||
Le `WsClient` doit être conçu en plusieurs couches :
|
||||
|
||||
1. transport brut WebSocket,
|
||||
2. encodage/décodage JSON texte,
|
||||
3. couche JSON-RPC 2.0,
|
||||
4. couche Solana subscribe/unsubscribe/notification,
|
||||
5. couche métier pour la répartition des messages.
|
||||
|
||||
Cette séparation évite de mélanger :
|
||||
|
||||
- les réponses à requêtes simples,
|
||||
- les réponses de subscribe,
|
||||
- les réponses de unsubscribe,
|
||||
- les notifications push.
|
||||
|
||||
## 9. Politique initiale de reconnexion
|
||||
|
||||
Au départ :
|
||||
|
||||
- pas de reconnexion automatique,
|
||||
- pas de resubscribe automatique,
|
||||
- comportement explicite contrôlé par l’appelant.
|
||||
|
||||
Plus tard, ce comportement pourra devenir configurable dans `config.json` et pilotable depuis l’application.
|
||||
|
||||
## 10. Politique initiale de fermeture
|
||||
|
||||
À la fermeture d’un `WsClient` :
|
||||
|
||||
1. marquer le client en arrêt,
|
||||
2. tenter les `unsubscribe` actifs,
|
||||
3. attendre les réponses dans une fenêtre bornée,
|
||||
4. forcer la purge locale si nécessaire,
|
||||
5. fermer proprement le flux d’écriture,
|
||||
6. laisser se terminer le flux de lecture,
|
||||
7. journaliser clairement les cas dégradés.
|
||||
|
||||
## 11. Documentation et livrables de référence
|
||||
|
||||
Le projet doit maintenir au minimum :
|
||||
|
||||
- un `README.md` global,
|
||||
- un `Roadmap.md` global,
|
||||
- des `README.md` et `TODO.md` par crate à mesure de l’évolution,
|
||||
- des tests unitaires robustes,
|
||||
- les bindings TS générés via `cargo test export_bindings` lorsque les types partagés évoluent.
|
||||
|
||||
## 12. Priorité immédiate
|
||||
|
||||
La priorité immédiate est la suivante :
|
||||
|
||||
1. corriger le squelette,
|
||||
2. poser `KbError`,
|
||||
3. poser `KbConfig`,
|
||||
4. poser `init_tracing`,
|
||||
5. poser les constantes Solana,
|
||||
6. préparer `ws_client` et `http_client`,
|
||||
7. remettre `kb_app` en conformité,
|
||||
8. conserver une UI minimale, puis brancher progressivement les clients réseau.
|
||||
|
||||
Reference in New Issue
Block a user