# Objectifs du projet Khadhroony Bot3 ## 1. Objet `khadhroony-bot3` est un workspace Rust modulaire destiné à acquérir, normaliser, décoder, matérialiser, valider et, lorsque le contrat le permet, exécuter des opérations Solana. Il succède à `khadhroony-bot2` en conservant les contrats fonctionnels validés tout en réduisant fortement le nombre de crates et en clarifiant les frontières entre modèles, traitements, stockage, transports, démonstrations et applications. La fondation `0.5.x` distingue désormais deux domaines : `khadhroony-solana` pour les bibliothèques généralistes Solana et `khadhroony-bot` pour les applications spécifiques au futur robot de trading. Le portefeuille plus large `khadhroony-project` pourra contenir d'autres projets de trading ou de crypto, y compris des projets non Solana et non crypto. ## 2. Objectifs structurants Le projet vise à : - consolider les contrats et implémentations métier dans un noyau maintenable ; - conserver des frontières explicites entre acquisition, stockage, pipeline et exécution ; - produire des observations et matérialisations déterministes, traçables et rejouables ; - appliquer des politiques de validation et de sécurité avant toute exécution ; - permettre les campagnes historiques, le traitement temps réel et les validations Devnet ; - conserver les preuves de couverture sous forme de tests, fixtures, matrices contractuelles et rapports de validation ; - fournir des scénarios réutilisables indépendamment de l’application desktop ; - préparer l’ajout progressif de protocoles Solana sans réintroduire une fragmentation excessive du workspace ; - conserver une vocation généraliste de couverture des Program IDs Solana, même lorsque l’ordre de développement privilégie temporairement les protocoles utiles au trading. ## 3. Principes de conception ### 3.1 Consolidation contrôlée La consolidation ne signifie pas l’effacement des frontières métier. `kb-lib` regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. `kb-store`, `kb-pipeline` et `kb-onchain-transport` restent des crates séparées parce qu’ils représentent des responsabilités opérationnelles différentes. ### 3.2 Contrats explicites Les APIs publiques, erreurs, invariants, versions de contrats et statuts de validation doivent être explicites. Les comportements implicites, les chemins permissifs et les validations supposées sont évités. ### 3.3 Rejeu et idempotence Les données acquises doivent pouvoir être rejouées. Les extractions, décodages et matérialisations doivent préserver la traçabilité et éviter les doubles effets lors d’un rejeu. ### 3.4 Sécurité d’exécution La construction d’une instruction ne suffit pas à autoriser son envoi. Les exécuteurs, préflights, politiques de signataires, limites de frais, simulations et confirmations opérateur forment un contrat distinct. ### 3.5 Documentation fondée sur le code La documentation active est réécrite pour bot3 à partir du code, des tests, des matrices et des validations actuels. `olddocs/archivekbot2/` sert de source historique non normative ; aucun document n’en est promu automatiquement. ## 4. Périmètre actuel Le noyau livré jusqu’à `0.4.8` couvre notamment : - Solana Core ; - SPL Memo, avec exécution limitée à Memo v4 ; - SPL Token classique ; - SPL Associated Token Account ; - Token-2022 ; - registre SPL ElGamal aux couches decoder/executor/stateful/materialization, sans validation réseau réelle déclarée ; - Solana Program Metadata, avec neuf opérations stables validées sur Devnet ; - Token-2022 Token Metadata, avec cinq opérations d’interface validées sur Devnet ; - Metaplex Token Metadata, avec une matrice courante close à 15 `confirmed`, 5 `unavailable` et 0 `not_run` ; - acquisition HTTP et WebSocket ; - stockage PostgreSQL ; - replay, extraction Core, décodage, matérialisation et scénarios Devnet réutilisables. ## 5. Hors périmètre immédiat Ne sont pas considérés comme achevés : - la migration des bibliothèques généralistes vers `ks-*` et les restructurations de `ks-config`, `ks-wallet` et `ks-store`, planifiées en `0.5.x` ; - la réconciliation complète des scénarios réutilisables entre la future `ks-pipeline-demo-scenarios` et le desktop ; - le décodeur Anchor générique planifié en `0.6.x` ; - les protocoles trading prioritaires Meteora, Raydium, Pump, Orca et Jupiter ; - la couverture généraliste différée des autres Program IDs Solana, qui reste un objectif du projet après la séquence trading prioritaire ; - l’application de trading et les workers de production ; - la validation réelle du registre ElGamal sur un cluster où son déploiement et ses prérequis sont confirmés. ## 6. Critères généraux de qualité Une fonctionnalité n’est considérée comme livrée que si son niveau de preuve est indiqué : compilation, tests, matrice contractuelle, validation synthétique, simulation, Devnet ou Mainnet selon le cas. Une absence de validation externe doit rester visible et ne peut pas être transformée en affirmation de compatibilité.