Files
khadhroony-bobobot/ROADMAP.md
2026-04-22 19:04:22 +02:00

15 KiB
Raw Blame History

khadhroony-bobobot — Roadmap

1. Objet du projet

khadhroony-bobobot est un workspace Rust destiné à la détection, lobservation, lanalyse de patterns et, à terme, à lexécution semi-automatisée dachats/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,
  • lanalyse statistique et comportementale des patterns,
  • la préparation dune couche wallet puis swap/trading.

2. Principes darchitecture

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 linterface 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 dusage de anyhow ni thiserror.
  • Pas dusage 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 lUI, 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 est stockée dans un fichier config.json.

4.1. Points à couvrir dans la configuration

Le fichier doit 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 dUI 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 doit pouvoir porter sa propre configuration, par exemple :

  • nom logique,
  • URL,
  • provider,
  • présence ou non dune clé API,
  • variable denvironnement pour 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 est 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.

Réalisé :

  • correction de kb_lib/src/lib.rs,
  • création de KbError,
  • création de KbConfig,
  • création de init_tracing,
  • création des constantes Solana officielles,
  • préparation des modules ws_client et http_client,
  • remise de kb_app/src/lib.rs en conformité,
  • documentation de kb_app/src/splash.rs,
  • UI Tauri minimale.

6.2. Version 0.1.x — Transport WebSocket générique

Objectif : construire un vrai WsClient asynchrone clonable.

Réalisé :

  • connect, disconnect, connection_state,
  • 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 larrêt propre,
  • fermeture avec timeout,
  • tests offline avec serveur mock.

6.3. Version 0.1.1 — Intégration Tauri minimale du WsClient

Objectif : valider le transport via lapplication desktop.

Réalisé :

  • intégration minimale de WsClient dans kb_app,
  • boutons start/stop,
  • zone de logs,
  • validation du flux frontend -> tauri -> kb_lib -> frontend.

6.4. Version 0.2.0 — Couche JSON-RPC WS Solana

Objectif : séparer clairement transport, réponses RPC et notifications.

Réalisé :

  • enveloppes JSON-RPC 2.0,
  • gestion des request_id,
  • parsing des réponses et erreurs,
  • parsing des notifications,
  • premiers helpers JSON-RPC sur WsClient.

6.5. Version 0.3.0 — Registre subscriptions / notifications

Objectif : fiabiliser la gestion des subscriptions.

Réalisé :

  • stockage des subscriptions actives,
  • mapping entre requête de subscribe et subscription_id serveur,
  • unsubscribe propre avant fermeture,
  • timeout dattente sur unsubscribe,
  • purge locale si nécessaire,
  • routage séparé des notifications.

6.6. Version 0.3.1 — Helpers subscribe/unsubscribe WebSocket

Objectif : ajouter les helpers haut niveau correspondant aux principales méthodes PubSub Solana.

Réalisé :

  • helpers pour account, block, logs, program, root, signature, slot, slotsUpdates, vote,
  • helpers dunsubscribe correspondants,
  • premiers tests de validation des noms de méthodes.

6.7. Version 0.3.2 — Helpers typed et notifications typed

Objectif : sappuyer principalement sur solana-rpc-client-api pour typer les subscribe et les notifications.

Réalisé :

  • helpers typed pour account, block, logs, program, signature,
  • parsing typed des notifications,
  • base de travail pour réduire lusage direct de serde_json::Value.

6.8. Version 0.3.3 — Distinction API typed / raw

Objectif : clarifier lAPI publique de WsClient.

Réalisé :

  • suffixe _raw sur les helpers raw,
  • conservation des helpers typed comme interface plus propre,
  • préparation dune hiérarchie API plus explicite.

6.9. Version 0.3.4 — Fenêtre Demo Ws dans kb_app

Objectif : tester manuellement les souscriptions live dans une fenêtre dédiée.

Réalisé :

  • fenêtre séparée demo_ws,
  • ouverture depuis la fenêtre principale,
  • connexion/déconnexion dun client de démo,
  • test de souscriptions live,
  • affichage des événements raw et typed,
  • premiers tests réels sur wss://api.mainnet.solana.com.

6.10. Version 0.3.5 — Stabilisation de Demo Ws

Objectif : rendre la fenêtre de démonstration robuste sous flux élevé et cohérente avec la configuration.

Réalisé :

  • lire correctement les endpoints activés depuis la config et refléter les URLs résolues avec api_key_env_var,
  • améliorer la sélection réelle des endpoints affichés et utilisables,
  • ajouter du throttling / rate limiting de laffichage UI sous fort débit,
  • limiter ou résumer les événements affichés côté fenêtre,
  • conserver lintégralité des traces côté tracing,
  • éviter le gel de la fenêtre sur logsSubscribe et programSubscribe,
  • conserver des compteurs et états UI exploitables,
  • mieux gérer les fermetures/ralentissements dendpoints publics.

6.11. Version 0.4.x — Transport HTTP générique et helpers RPC

Objectif : construire un HttpClient clonable, limité et extensible, puis ajouter les premiers helpers HTTP Solana.

0.4.0 — Socle HttpClient

Réalisé :

  • client reqwest asynchrone clonable,
  • résolution dURL avec support de api_key_env_var,
  • limiteur local req/sec,
  • burst configurable,
  • délais configurables,
  • profils par endpoint,
  • abstraction JSON-RPC HTTP générique,
  • premiers appels de validation Solana.

Livrables :

  • HttpClient,
  • enveloppes JSON-RPC HTTP,
  • premiers appels :
    • getHealth
    • getVersion
    • getSlot

0.4.1 — Helpers HTTP Solana

Réalisé :

  • ajouter des helpers HTTP haut niveau comme pour le client WS,
  • distinguer helpers raw et helpers typed quand cela est pertinent,
  • couvrir les premières méthodes utiles du RPC HTTP Solana,
  • conserver HttpClient comme couche générique réutilisable.

0.4.2 — Politique HTTP avancée

Réalisé :

  • préparer un état de pause avant envoi pour un endpoint HTTP,
  • préparer plusieurs quotas par famille de méthodes,
  • distinguer quota RPC général et quota sendTransaction,
  • préparer un futur pool dendpoints HTTP et larbitrage entre eux.

0.4.3 — Pool dendpoints HTTP

Réalisé :

  • ajouter un pool dHttpClient,
  • sélectionner un endpoint selon le rôle demandé,
  • ignorer les endpoints Paused ou Disabled,
  • préparer une rotation simple entre endpoints actifs,
  • prendre en compte la classe de méthode HTTP,
  • préparer le routage multi-RPC et la limitation de concurrence par endpoint.

0.4.4 — Démo HTTP dans kb_app

Réalisé :

  • ajout dune fenêtre Demo Http,
  • ouverture depuis la fenêtre principale,
  • exécution manuelle de méthodes HTTP via le pool dendpoints,
  • affichage des réponses JSON-RPC HTTP et des erreurs associées,
  • affichage de létat du pool HTTP et des statuts des endpoints,
  • alignement visuel de la fenêtre sur le gabarit Demo Ws,
  • amélioration des presets UI, copie de réponse et bascule pretty/raw.

6.12. 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.13. Version 0.6.x — Détection technique on-chain / RPC

Objectif : commencer la détection utile pour lapplication.

À faire :

  • réception de notifications ciblées,
  • détection de créations de comptes/programmes dintérêt,
  • débuts de normalisation dévénements,
  • premiers connecteurs DEX.

6.14. 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.15. 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.16. Version 1.x.y — Wallets et swap préparatoire

Objectif : préparer la couche daction.

À faire :

  • gestion du répertoire wallets,
  • chargement sécurisé des keypairs,
  • abstraction wallet,
  • préparation dordres et de swaps,
  • simulation et garde-fous.

6.17. Version 2.x.y — Trading semi-automatisé

Objectif : brancher lanalyse à laction tout en gardant des garde-fous explicites.

À faire :

  • scénarios dachat/vente,
  • règles dentrée/sortie,
  • limites de risque,
  • confirmations explicites ou semi-automatiques,
  • journaux dexécution.

6.18. 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
  • rpc_ws_solana.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,
  • fenêtres de démonstration / diagnostic isolées.

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

Plus tard, ce comportement pourra devenir configurable dans config.json et pilotable depuis lapplication.

10. Politique initiale de fermeture

À la fermeture dun 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,
  • un CHANGELOG.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 désormais la suivante :

  1. démarrer la version 0.5.x avec le socle SQLite,
  2. ajouter la configuration database dans config.json,
  3. poser louverture et la validation de la base SQLite,
  4. définir les premières tables techniques utiles au stockage local,
  5. préparer la persistance des endpoints, événements et tokens observés,
  6. conserver kb_lib comme point central de la logique de stockage.