Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.0-pre.067

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-07-31 07:38:27 +02:00
parent 06fddf63b3
commit 5382cf8f43
11 changed files with 505 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/architecture/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,107 @@
<!-- file: docs/architecture/ARCHITECTURE.md -->
<!-- version: 1 -->
# Architecture générale
## 1. Vue d’ensemble
Le workspace est organisé en couches orientées responsabilités :
```text
configuration ─────┐
logging ───────────┼──────────────┐
program IDs ───────┘ │
v
transport -> store -> pipeline -> kb-lib
│ │
v v
demo scenarios wallet/signers
│ │
└────┬─────┘
v
desktop demo application
```
Cette représentation indique les relations dominantes. Elle ne remplace pas le graphe exact des dépendances Cargo.
## 2. Couches
### 2.1 Fondations
- `kb-core` fournit les erreurs et identités transversales minimales.
- `kb-config` charge, résout et valide la configuration.
- `kb-logging` initialise le logging et le tracing.
- `kb-program-ids` centralise les identifiants de programmes et comptes connus.
### 2.2 Noyau métier
`kb-lib` contient quatre familles principales :
- modèles et contrats partagés ;
- décodeurs ;
- exécuteurs ;
- matérialisateurs.
La façade publique est constituée par les réexports de `kb-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage.
### 2.3 Acquisition et stockage
- `kb-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC.
- `kb-store` regroupe les contrats store-neutral et l’implémentation PostgreSQL.
Les transports n’effectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée.
### 2.4 Orchestration
`kb-pipeline` orchestre :
- backfill ;
- extraction Core ;
- replay de décodage ;
- matérialisation ;
- corrélation stateful ;
- préflight et orchestration d’exécution pour les surfaces prises en charge.
Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacités de `kb-onchain-transport` sans absorber leurs responsabilités.
### 2.5 Démonstrations et applications
- `kb-pipeline-demo-scenarios` fournit une bibliothèque réutilisable et le binaire `kb-pipeline-demo-scenarios-cli`.
- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop.
- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son périmètre reste incomplet.
## 3. Flux principal de données
```text
Solana RPC / WebSocket
│
v
kb-onchain-transport
│
v
kb-store (données brutes/canoniques)
│
v
kb-pipeline
│
├── extraction Core
├── sélection des décodeurs
├── décodage via kb-lib
├── matérialisation via kb-lib
└── stockage des résultats
```
L’exécution suit un flux séparé : intention typée, construction, préflight, simulation, confirmation opérateur, envoi, confirmation et validation postérieure lorsque la surface le permet.
## 4. Frontières obligatoires
- Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de `kb-program-ids`.
- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`.
- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`.
- Les scénarios réutilisables doivent migrer vers `kb-pipeline-demo-scenarios` plutôt que rester enfouis dans l’UI.
- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont consommées par plusieurs tests.
- Les archives documentaires ne participent ni au build ni aux décisions normatives.
## 5. État de migration
L’architecture bot3 est largement alignée fonctionnellement sur le périmètre bot2 proche de `0.4.6`, avec des travaux `0.4.7` partiellement migrés. L’alignement officiel de version reste conditionné à l’audit ciblé prévu par `docs/V0_4_6_ALIGNMENT_AUDIT.md`.

51
docs/architecture/CRATE_MAP.md Normal file
View File

@@ -0,0 +1,51 @@
<!-- file: docs/architecture/CRATE_MAP.md -->
<!-- version: 1 -->
# Carte des crates
## 1. Inventaire
| Crate | Type | Responsabilité principale | État documentaire |
|------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------|
| `kb-core` | bibliothèque | erreurs, résultat et identité de module partagés | contrat par crate à créer |
| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | contrat par crate à créer |
| `kb-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | contrat par crate à créer |
| `kb-logging` | bibliothèque | initialisation du logging et du tracing | contrat par crate à créer |
| `kb-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | contrat par crate à créer |
| `kb-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | contrat par crate à créer |
| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | contrat par crate à créer |
| `kb-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools d’endpoints | contrat par crate à créer |
| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | contrat par crate à créer |
| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | ébauche à documenter explicitement |
| `kb-app-demo-desktop` | bibliothèque + binaire | application de démonstration Tauri | contrat par crate à créer |
## 2. Consolidations principales depuis bot2
La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges :
- les modèles et APIs de décodage, matérialisation et exécution ont rejoint `kb-lib` ;
- les implémentations de stockage core et PostgreSQL ont rejoint `kb-store` ;
- les responsabilités de pipeline ont été réunies dans `kb-pipeline` ;
- les transports Solana sont réunis dans `kb-onchain-transport` ;
- l’application et sa bibliothèque sont réunies dans `kb-app-demo-desktop` ;
- les scénarios réutilisables ont été extraits dans `kb-pipeline-demo-scenarios`.
Cette carte n’est pas une table de compatibilité exhaustive des anciennes crates. Les correspondances historiques détaillées seront synthétisées dans la documentation de migration et l’audit d’alignement.
## 3. Crates mixtes
### 3.1 `kb-pipeline-demo-scenarios`
- bibliothèque Rust : `kb_pipeline_demo_scenarios` ;
- binaire : `kb-pipeline-demo-scenarios-cli` ;
- `autobins = false` évite une cible implicite concurrente.
### 3.2 `kb-app-demo-desktop`
- bibliothèque Rust : `kb_app_demo_desktop_lib` ;
- binaire : `kb-app-demo-desktop` ;
- le package reste volontairement unique.
## 4. Relations documentaires
Chaque crate devra disposer de `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md`. Les documents transversaux présents dans `docs/architecture/` évitent de répéter l’architecture complète dans chaque README.

55
docs/architecture/PIPELINE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,55 @@
<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
<!-- version: 1 -->
# Architecture du pipeline
## 1. Responsabilité
`kb-pipeline` coordonne des opérations qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution.
## 2. Familles de traitements
### 2.1 Backfill
Le backfill sélectionne des signatures ou transactions selon une adresse, un programme, un rôle d’endpoint et des bornes explicites. Il gère progression, reprise, annulation et résultats partiels selon les contrats exposés par le pipeline.
### 2.2 Extraction Core
L’extraction Core transforme les transactions stockées en représentations d’instructions contextualisées nécessaires aux décodeurs. Elle constitue une phase distincte du replay de décodage.
### 2.3 Replay de décodage
Le replay sélectionne des candidats, applique les décodeurs compatibles de `kb-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver l’idempotence et les frontières de campagne.
### 2.4 Traitements stateful
Les modules stateful corrèlent instructions, comptes, états précédents et résultats de transaction lorsque le protocole l’exige. Les surfaces SPL Token, ATA, Token-2022 et registre ElGamal disposent de traitements spécialisés à des niveaux différents.
### 2.5 Préflight et exécution
Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `kb-lib` ; le pipeline orchestre leur utilisation.
## 3. Dépendances fonctionnelles
```text
kb-onchain-transport -> acquisition et appels RPC
kb-store -> lecture/écriture canonique et replay
kb-lib -> contrats et implémentations métier
kb-config -> profils et paramètres opérationnels
kb-logging -> observabilité
kb-wallet -> signataires lorsque requis
```
## 4. Scénarios de démonstration
`kb-pipeline-demo-scenarios` doit contenir les scénarios réutilisables hors UI. `kb-app-demo-desktop` adapte leurs requêtes, progrès et résultats en payloads Tauri. Une dépendance à l’application desktop dans le sens inverse serait incorrecte.
## 5. Contrats de preuve
Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contract-matrices/` participent à la preuve contractuelle. Une matrice peut être à la fois une référence lisible et une fixture chargée par le code de test ; elle ne doit pas être dupliquée sous `docs/`.
## 6. Limites connues
- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
- Certains scénarios restent à rendre pleinement autonomes hors desktop.
- La documentation détaillée des APIs publiques du pipeline sera produite dans `kb-pipeline/USAGE.md` après inventaire des exports.

75
docs/architecture/PROJECT_OBJECTIVES.md Normal file
View File

@@ -0,0 +1,75 @@
<!-- file: docs/architecture/PROJECT_OBJECTIVES.md -->
<!-- version: 1 -->
# 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é.

64
docs/architecture/STORAGE_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,64 @@
<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
<!-- version: 1 -->
# Architecture du stockage
## 1. Responsabilité de `kb-store`
`kb-store` réunit :
- les contrats store-neutral ;
- les DTO et entités persistées ;
- la pagination et les rapports de santé ;
- les traits de repositories ;
- l’implémentation PostgreSQL ;
- les migrations, requêtes et mécanismes de replay associés.
La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL.
## 2. Frontières
### 2.1 Contrats store-neutral
Les contrats ne doivent pas dépendre des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages et erreurs nécessaires aux consommateurs.
### 2.2 Adaptateur PostgreSQL
Le module PostgreSQL possède :
- la connexion et l’initialisation ;
- l’application idempotente des migrations ;
- les requêtes typées ;
- les diagnostics ;
- les opérations de replay et de sélection de candidats.
### 2.3 Modèles partagés
Les modèles métier communs restent dans `kb-lib` lorsqu’ils dépassent la seule persistance. `kb-store` ne doit pas créer une seconde définition concurrente d’un contrat partagé.
## 3. Catégories de données
Le stockage couvre plusieurs niveaux :
- données brutes acquises ;
- transactions et instructions canoniques ;
- événements de décodage et diagnostics ;
- matérialisations ;
- états de campagne et candidats de replay ;
- informations opérationnelles et de santé.
Les noms exacts de tables et APIs publiques seront documentés dans `kb-store/USAGE.md` à partir des exports et migrations actuels.
## 4. Propriétés attendues
- initialisation idempotente ;
- pagination bornée ;
- traçabilité des campagnes ;
- absence de double effet lors des replays ;
- validation stricte des entrées ;
- erreurs explicites ;
- séparation entre données brutes, résultats de décodage et matérialisations.
## 5. Données de test
Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont nécessaires aux tests.

35
docs/architecture/SURFACE_CRATE_MATRIX.md Normal file
View File

@@ -0,0 +1,35 @@
<!-- file: docs/architecture/SURFACE_CRATE_MATRIX.md -->
<!-- version: 1 -->
# Matrice des responsabilités par surface
## 1. Légende
- **Contrat/implémentation** : responsabilité métier principale.
- **Orchestration** : coordination entre couches.
- **Persistance** : stockage et replay.
- **Transport** : acquisition ou appel RPC.
- **Présentation** : UI ou adaptation de démonstration.
## 2. Matrice
| Surface | `kb-lib` | `kb-pipeline` | `kb-store` | `kb-onchain-transport` | scénarios | desktop |
|-------------------------|-----------------------------------------|---------------------------------------------|------------------------|------------------------|-----------------------------------|----------------------------------------------|
| Solana Core | décodeurs, exécuteurs, matérialisateurs | extraction, replay, exécution | persistance | RPC | validations Devnet | panneaux fonctionnels |
| SPL Memo | décodage v1/v3/v4, exécution v4 | replay et exécution v4 | persistance | RPC | scénario Memo v4 | panneau Memo v4 |
| SPL Token classique | contrats et implémentations | stateful, préflight, orchestration | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
| SPL ATA | contrats et implémentations | état et orchestration | persistance | RPC | scénarios classique/Token-2022 | panneaux fonctionnels |
| Token-2022 | contrats et implémentations | corrélation, preuves, préflight, validation | persistance | RPC | scénarios Devnet | panneaux fonctionnels |
| Registre ElGamal | implémentation partielle confirmée | traitement stateful à vérifier par API | persistance selon flux | acquisition de comptes | pas de validation réelle déclarée | présentation non raccordée fonctionnellement |
| Metaplex Token Metadata | décodeur partiellement migré | à compléter selon besoins | à compléter | acquisition standard | à créer/compléter | à créer/compléter |
## 3. Interprétation
Cette matrice décrit les responsabilités observées au niveau architectural. Elle ne déclare pas une couverture exhaustive de chaque instruction ou compte. La couverture détaillée reste démontrée par le code, les tests et les matrices sous `test-fixtures/contract-matrices/`.
## 4. Statuts sensibles
- Memo v1 et v3 restent non exécutables.
- Memo v4 est exécutable.
- Le registre ElGamal ne doit pas être présenté comme validé Devnet/Mainnet.
- Metaplex Token Metadata appartient au travail `0.4.7` commencé avant la migration et seulement partiellement repris dans bot3.