add Readme / Roadmap / Changelog

CHANGELOG.md

@@ -0,0 +1 @@
+0.0.1 - initial skel

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.

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.
+