82 lines
5.1 KiB
Markdown
82 lines
5.1 KiB
Markdown
<!-- file: docs/architecture/PROJECT_OBJECTIVES.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# 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é.
|