khadhroony-bot3/docs/architecture/PROJECT_OBJECTIVES.md

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. ks-lib regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. ks-store, ks-pipeline et ks-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 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é.