add Readme / Roadmap / Changelog

2026-04-20 16:27:39 +02:00
parent 0858b72e31
commit 4261291ac1
3 changed files with 679 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1 @@
 0.0.1 - initial skel
--- a/README.md
+++ b/README.md
@@ -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.
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -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.