# 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. ## 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. ## 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 migré 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 au niveau de certaines couches internes, sans validation Devnet/Mainnet déclarée ; - décodeur Metaplex Token Metadata partiellement repris pendant le développement de `0.4.7` ; - acquisition HTTP et WebSocket ; - stockage PostgreSQL ; - replay, extraction Core, décodage, matérialisation et scénarios Devnet. ## 5. Hors périmètre immédiat Ne sont pas considérés comme achevés : - l’intégralité de Metaplex Token Metadata ; - un wallet utilisateur complet ; - l’autonomie complète de tous les scénarios de démonstration ; - tous les protocoles Anchor, SPL, Metaplex, AMM, launchpads et routers planifiés ; - 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é.