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 :

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.