0.5.0-pre.004
This commit is contained in:
@@ -1,17 +1,24 @@
|
||||
<!-- file: docs/IDEA_REMINDERS.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Rappels d’idées
|
||||
|
||||
Ce document conserve les idées utiles qui ne constituent pas encore des engagements de version. Les orientations déjà intégrées au ROADMAP ne sont pas répétées comme propositions ouvertes.
|
||||
Ce document conserve les idées utiles qui ne constituent pas encore des engagements de version ainsi que quelques repères de portefeuille explicitement demandés comme rappels. Lorsqu’une orientation est devenue normative, le document actif correspondant est indiqué et reste prioritaire.
|
||||
|
||||
## Positionnement futur des projets
|
||||
|
||||
- `khadhroony-project` est destiné à devenir une umbrella de projets trading et crypto ;
|
||||
- `khadhroony-solana` doit regrouper les bibliothèques généralistes dédiées à Solana, avec une convergence prévue vers les namespaces `ks-*`, `ks_*` et `KS_*` ;
|
||||
- `khadhroony-bot` / bot3 doit devenir, après stabilisation de la fondation et publication de `1.0`, le robot de trading consommant les composants Khadhroony Solana ;
|
||||
- la cible bot comprend à terme une partie d'analyse et de création de stratégies ainsi qu'un exécutable de trading automatique ;
|
||||
- `kb-app-demo-desktop` n'est actuellement pas cette application finale : il sert surtout à tester et valider les composants généralistes qui doivent migrer vers Khadhroony Solana.
|
||||
Repères durables de portefeuille, désormais également formalisés dans la politique de namespace active :
|
||||
|
||||
- `khadhroony-project` est une umbrella de projets de trading et/ou de crypto ; elle n'est pas limitée à Solana ni même à la crypto ;
|
||||
- des projets futurs pourront par exemple viser XTB (`khadhroony-xtb`) ou MetaTrader (`khadhroony-mt5`) sans dépendre de Solana ;
|
||||
- `khadhroony-solana` regroupe les bibliothèques généralistes dédiées à Solana et converge vers les namespaces `ks-*`, `ks_*` et `KS_*` ;
|
||||
- `ks-pipeline-demo-scenarios` appartient à ce domaine Solana généraliste : les scénarios de validation ne sont pas spécifiques au bot ;
|
||||
- `khadhroony-bot` / bot3 doit devenir le robot de trading consommant les composants Khadhroony Solana, avec à terme analyse/création de stratégies et exécution de trading automatique ;
|
||||
- `kb-app-demo-desktop` reste côté Bot : il valide aujourd'hui surtout les composants Solana généralistes mais pourra aussi accueillir des démonstrations spécifiques au bot ;
|
||||
- les identités techniques généralistes doivent migrer vers `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ;
|
||||
- les tables Solana doivent à terme utiliser `k_sol_*`, tandis que `kb_*` est réservé aux éventuelles tables réellement spécifiques au domaine Bot.
|
||||
|
||||
La décision normative et son calendrier sont dans [`decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md).
|
||||
|
||||
## Application desktop
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/README.md -->
|
||||
<!-- version: 29 -->
|
||||
<!-- version: 30 -->
|
||||
|
||||
# Documentation active de Khadhroony Bot3
|
||||
|
||||
@@ -39,9 +39,9 @@ Modèles documentaires non génératifs :
|
||||
|
||||
## 4. Audits et décisions actifs
|
||||
|
||||
- [`audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md`](audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md) ;
|
||||
- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
|
||||
- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md).
|
||||
- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md) ;
|
||||
- [`decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md) : séparation Khadhroony Solana/Bot, migration `ks-*` / `KS_*`, identités techniques et namespaces SQL.
|
||||
|
||||
Les audits et rapports de travail `0.4.8-pre.*` sont archivés sous `../olddocs/archivekbot3/`. Leur contenu reste disponible pour la traçabilité mais n’est plus un index actif.
|
||||
|
||||
@@ -102,12 +102,10 @@ Les preuves détaillées de `0.4.8-pre.*` restent accessibles sous `../olddocs/a
|
||||
|
||||
## 10. Plans de version actifs
|
||||
|
||||
- [`Plan 0.5.0 — cadrage de la fondation 0.5.x`](plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md) : plan temporaire actif créé pendant `0.5.0-pre.001`, à maintenir jusqu’à la clôture de `0.5.0`.
|
||||
- [`Audit 0.5.0-pre.002 — configuration, logging, wallet et namespaces`](plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md) : décisions de sécurité, split logging, namespace `KS_*`, migration wallet et audit du possible préfixe de crates `ks-*`.
|
||||
- [`Audit 0.5.0-pre.003 — store, scénarios, desktop et complétude`](plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md) : contrat temporel du store, préparation trading générique, frontière des scénarios, couverture des exécuteurs actifs et cible `ks-*`.
|
||||
Le cadrage `0.5.0` est clôturé. Son plan et les audits `pre.002`/`pre.003` sont archivés sous `../olddocs/archivekbot3/docs/plans/`.
|
||||
|
||||
Le plan `0.4.8` reste archivé sous `../olddocs/archivekbot3/docs/plans/`.
|
||||
Le prochain plan temporaire sera créé pendant la première prerelease de `0.5.1`, conformément au cycle de développement.
|
||||
|
||||
## 11. Prompt de reprise
|
||||
|
||||
- [`Prompt actif 0.5.0`](../prompts/029_v0_5_0_foundation_restructuring_plan.md).
|
||||
- [`Prompt actif 0.5.1`](../prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md).
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/ARCHITECTURE.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Architecture générale
|
||||
|
||||
@@ -69,7 +69,7 @@ Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacité
|
||||
- `kb-pipeline-demo-scenarios` fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop.
|
||||
- Le binaire `kb-pipeline-demo-scenarios-cli` reste un outil ciblé ; son existence n’impose pas d’exposer chaque scénario par un CLI.
|
||||
- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à `kb-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`.
|
||||
- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Sa restructuration est planifiée en `0.5.2`.
|
||||
- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Elle devient `ks-wallet` en `0.5.1`, puis sa restructuration fonctionnelle est planifiée en `0.5.2`.
|
||||
|
||||
## 3. Flux principal de données
|
||||
|
||||
@@ -99,7 +99,7 @@ L’exécution suit un flux séparé : intention typée, construction, préfligh
|
||||
- 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éseau réutilisables spécifiques à Devnet/Testnet appartiennent à `kb-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`.
|
||||
- Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `kb-pipeline-demo-scenarios`, future `ks-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`.
|
||||
- Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à `kb-pipeline` ou à la crate métier propriétaire.
|
||||
- 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.
|
||||
@@ -108,4 +108,4 @@ L’exécution suit un flux séparé : intention typée, construction, préfligh
|
||||
|
||||
La migration bot2 vers bot3 est close pour le périmètre fonctionnel repris jusqu’à `0.4.7`. La version `0.4.8` complète ensuite la fondation Metadata on-chain en distinguant Solana Program Metadata, Token-2022 Token Metadata et Metaplex Token Metadata, avec leurs décodeurs, matérialisateurs, exécuteurs lorsque applicables, orchestration stateful, scénarios réutilisables et intégration desktop.
|
||||
|
||||
La série `0.5.x` ne vise pas à étendre immédiatement la couverture protocolaire : elle stabilise d’abord `kb-config`, `kb-wallet`, `kb-store` et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. `0.6.x` introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter.
|
||||
La série `0.5.x` ne vise pas à étendre immédiatement la couverture protocolaire : elle migre d’abord les bibliothèques vers `ks-*`, puis stabilise `ks-config`, `ks-wallet`, `ks-store` et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. `0.6.x` introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/CRATE_MAP.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Carte des crates
|
||||
|
||||
@@ -8,17 +8,19 @@
|
||||
| Crate | Type | Responsabilité principale | État documentaire |
|
||||
|------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------------|
|
||||
| `kb-core` | bibliothèque | erreurs, résultat et identité de module partagés | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | documentée ; restructuration en `0.5.1` |
|
||||
| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | migration/restructuration en `0.5.1` |
|
||||
| `kb-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-logging` | bibliothèque | initialisation du logging et du tracing | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | documentée ; réconciliation en `0.5.4` |
|
||||
| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | renommage `0.5.1`, audit `0.5.4` |
|
||||
| `kb-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools d’endpoints | README/TODO/USAGE/CHANGELOG présents |
|
||||
| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | documentée ; audit structurel en `0.5.3` |
|
||||
| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | documentée ; restructuration en `0.5.2` |
|
||||
| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | renommage `0.5.1`, normalisation `0.5.3` |
|
||||
| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | renommage `0.5.1`, refonte `0.5.2` |
|
||||
| `kb-app-demo-desktop` | bibliothèque + binaire | application de démonstration Tauri | documentée ; réconciliation en `0.5.4` |
|
||||
|
||||
La table décrit les noms physiques du workspace `0.5.0`. La migration `0.5.1` renomme les dix crates généralistes en `ks-core`, `ks-config`, `ks-lib`, `ks-logging`, `ks-program-ids`, `ks-pipeline`, `ks-pipeline-demo-scenarios`, `ks-onchain-transport`, `ks-store` et `ks-wallet`. `kb-app-demo-desktop` conserve son nom parce qu’il appartient au domaine applicatif Bot. Voir [`../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md).
|
||||
|
||||
## 2. Consolidations principales depuis bot2
|
||||
|
||||
La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges :
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Architecture du pipeline
|
||||
|
||||
@@ -48,7 +48,7 @@ Cette crate peut préparer des wallets temporaires, demander des airdrops, crée
|
||||
|
||||
Le binaire `kb-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios.
|
||||
|
||||
`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et d’exécution de campagne appartient à `kb-pipeline-demo-scenarios`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite.
|
||||
`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et d’exécution de campagne appartient à `kb-pipeline-demo-scenarios`, renommée `ks-pipeline-demo-scenarios` en `0.5.1`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`.
|
||||
|
||||
## 5. Contrats de preuve
|
||||
|
||||
@@ -57,5 +57,5 @@ Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contra
|
||||
## 6. Limites connues
|
||||
|
||||
- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
|
||||
- La réconciliation finale des scénarios encore dupliqués entre desktop et `kb-pipeline-demo-scenarios` est planifiée en `0.5.4`.
|
||||
- Les futurs protocoles doivent conserver cette frontière : orchestration généraliste dans `kb-pipeline`, scénarios réseau réutilisables dans `kb-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop.
|
||||
- La réconciliation finale des scénarios encore dupliqués entre desktop et la future `ks-pipeline-demo-scenarios` est planifiée en `0.5.4`.
|
||||
- Après `0.5.1`, les futurs protocoles doivent conserver cette frontière : orchestration généraliste dans `ks-pipeline`, scénarios réseau réutilisables dans `ks-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/PROJECT_OBJECTIVES.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Objectifs du projet Khadhroony Bot3
|
||||
|
||||
@@ -9,6 +9,8 @@
|
||||
|
||||
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 à :
|
||||
@@ -66,8 +68,8 @@ Le noyau livré jusqu’à `0.4.8` couvre notamment :
|
||||
|
||||
Ne sont pas considérés comme achevés :
|
||||
|
||||
- la restructuration des fondations `kb-config`, `kb-wallet` et `kb-store`, planifiée en `0.5.x` ;
|
||||
- la réconciliation complète des scénarios réutilisables entre `kb-pipeline-demo-scenarios` et le desktop ;
|
||||
- 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 ;
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Architecture du stockage
|
||||
|
||||
@@ -59,7 +59,9 @@ Les noms de tables, contrats de replay et APIs publiques sont documentés dans `
|
||||
- erreurs explicites ;
|
||||
- séparation entre données brutes, résultats de décodage et matérialisations.
|
||||
|
||||
La série `0.5.3` réauditera cette fondation avant l’arrivée des protocoles trading. Cet audit doit notamment distinguer les timestamps observés sur la blockchain des timestamps d’insertion et de mise à jour locaux, normaliser la structure interne de `kb-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans casser les contrats de replay existants.
|
||||
La série `0.5.3` normalisera cette fondation avant l’arrivée des protocoles trading. Elle doit notamment distinguer `slot`, `block_time` et les timestamps d’acquisition/persistance, normaliser la structure interne de la future `ks-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans perdre les contrats de provenance et d’idempotence.
|
||||
|
||||
La même migration remplace le préfixe historique des tables Solana `kb_sol_*` par `k_sol_*`. La base peut encore être reconstruite ou migrée proprement avant `0.6.x`, il n’est donc pas nécessaire de conserver indéfiniment l’ancien préfixe. Le préfixe `kb_*` est réservé aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot, pas aux faits Solana simplement consommés par le bot.
|
||||
|
||||
## 5. Données de test
|
||||
|
||||
|
||||
117
docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md
Normal file
117
docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md
Normal file
@@ -0,0 +1,117 @@
|
||||
<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Politique de namespace Khadhroony Solana
|
||||
|
||||
## 1. Statut
|
||||
|
||||
Cette décision est adoptée pendant la clôture de `0.5.0` et devient la cible normative des migrations de fondation `0.5.1` à `0.5.3`.
|
||||
|
||||
Le workspace `0.5.0` conserve encore physiquement les noms `kb-*`, `kb_*`, `KB_*`, `kb-lib.*` et `kb_sol_*` là où ils existent. Leur présence avant migration ne remet pas en cause la cible ci-dessous.
|
||||
|
||||
## 2. Positionnement des projets
|
||||
|
||||
`khadhroony-project` est une umbrella de projets liés au trading et/ou aux technologies crypto. Elle n'est pas limitée à Solana ni même à la crypto. Des projets futurs pourront par exemple viser XTB ou MetaTrader indépendamment des composants Solana.
|
||||
|
||||
`khadhroony-solana` est le domaine des bibliothèques généralistes dédiées à Solana. Ces bibliothèques doivent pouvoir être réutilisées par plusieurs applications sans dépendre du futur robot de trading Khadhroony Bot.
|
||||
|
||||
`khadhroony-bot` / `khadhroony-bot3` est le domaine applicatif du futur robot de trading. Après stabilisation de la fondation et avant/après `1.0` selon le ROADMAP, il doit pouvoir consommer les composants `khadhroony-solana`, fournir des capacités d'analyse et de création de stratégies puis un exécutable de trading automatique.
|
||||
|
||||
`kb-app-demo-desktop` reste une application du workspace Bot. Elle sert actuellement surtout à tester et valider les composants Solana généralistes, mais elle pourra aussi recevoir des démonstrations spécifiques au bot. Son nom n'est donc pas inclus dans la migration `ks-*`.
|
||||
|
||||
## 3. Crates Solana généralistes
|
||||
|
||||
La migration `0.5.1` doit renommer les dix crates généralistes suivantes :
|
||||
|
||||
| Nom `0.5.0` | Nom cible |
|
||||
|------------------------------|------------------------------|
|
||||
| `kb-core` | `ks-core` |
|
||||
| `kb-config` | `ks-config` |
|
||||
| `kb-lib` | `ks-lib` |
|
||||
| `kb-logging` | `ks-logging` |
|
||||
| `kb-program-ids` | `ks-program-ids` |
|
||||
| `kb-pipeline` | `ks-pipeline` |
|
||||
| `kb-pipeline-demo-scenarios` | `ks-pipeline-demo-scenarios` |
|
||||
| `kb-onchain-transport` | `ks-onchain-transport` |
|
||||
| `kb-store` | `ks-store` |
|
||||
| `kb-wallet` | `ks-wallet` |
|
||||
|
||||
Les identifiants Rust correspondants migrent vers `ks_*` : par exemple `kb_config` devient `ks_config` et `kb_pipeline_demo_scenarios` devient `ks_pipeline_demo_scenarios`.
|
||||
|
||||
La migration doit couvrir les manifests, chemins de workspace, imports, exports, tests d'API externe, scripts, documentation, targets de build et bindings générés à la source. Les artefacts générés restent régénérés localement selon les règles du workspace et ne sont pas livrés sans nécessité explicite.
|
||||
|
||||
## 4. Variables d'environnement
|
||||
|
||||
Toutes les variables d'environnement appartenant aux contrats Khadhroony Solana/Bot doivent utiliser le namespace `KS_` après la migration `0.5.1`.
|
||||
|
||||
Trois classes sont retenues :
|
||||
|
||||
- `KS_SECRET_*` : secret absolu ; la valeur peut être utilisée côté backend mais ne doit jamais être loggée, sérialisée vers une surface publique, renvoyée par Tauri ni affichée en diagnostic, même en mode debug ;
|
||||
- `KS_PUBLIC_*` : valeur explicitement classée comme publiable ; le préfixe ne suffit pas à lui seul à autoriser une exposition, qui doit rester définie par un DTO ou une surface publique explicite ;
|
||||
- `KS_*` hors sous-préfixes précédents : valeur interne ; elle n'est pas exposée en fonctionnement normal mais peut être incluse dans un diagnostic explicitement demandé si sa sémantique n'est pas sensible.
|
||||
|
||||
Une variable appartenant au workspace qui ne commence pas par `KS_` est non conforme après migration. Les variables standard du système ou de dépendances externes ne sont pas reclassées artificiellement comme variables de configuration Khadhroony.
|
||||
|
||||
La classification d'une valeur sensible doit survivre à la substitution. Une chaîne composée contenant une valeur issue de `KS_SECRET_*` reste sensible dans son ensemble et ne doit pas redevenir une simple valeur publiable après résolution.
|
||||
|
||||
## 5. Configuration source, runtime et publique
|
||||
|
||||
La restructuration `0.5.1` doit séparer au minimum :
|
||||
|
||||
- la configuration généraliste dans son propre document et son propre schéma ;
|
||||
- la configuration logging dans un document et un schéma indépendants, avec des profils logging sélectionnables indépendamment des profils réseau/applicatifs.
|
||||
|
||||
D'autres documents spécialisés ne sont créés que si l'audit démontre une responsabilité, un cycle de vie ou une validation réellement indépendants.
|
||||
|
||||
La conception doit distinguer :
|
||||
|
||||
1. la représentation source, qui peut contenir des références `${KS_*}` ;
|
||||
2. la représentation runtime résolue, qui peut porter des secrets ;
|
||||
3. la représentation publique/diagnostique, construite explicitement et incapable d'exposer une valeur secrète résolue.
|
||||
|
||||
Une configuration runtime complète ne doit jamais être sérialisée puis « nettoyée » après coup pour produire un payload public.
|
||||
|
||||
## 6. Identités runtime et persistées
|
||||
|
||||
La migration de namespace ne se limite pas au nom des crates. Les identités techniques actuellement préfixées par `kb-lib` doivent être migrées vers le domaine Khadhroony Solana lorsqu'elles identifient des composants généralistes.
|
||||
|
||||
La convention cible retenue comprend notamment :
|
||||
|
||||
- `kb-lib.decoder.*` → `ks-lib-decoder.*` ;
|
||||
- `kb-lib.materializer.*` → `ks-lib-materializer.*` ;
|
||||
- `kb-lib.executor.*` → `ks-lib-executor.*`.
|
||||
|
||||
`0.5.1-pre.001` doit produire l'inventaire exhaustif des targets de tracing, `processor_name`, identités de replay/idempotence, codes persistés et autres chaînes techniques concernées avant modification. Les anciennes identités ne doivent pas être conservées par inertie puisque la fondation et la base peuvent encore être migrées avant `0.6.x`.
|
||||
|
||||
Les segments métier internes (`solana`, `spl`, protocoles, surfaces et opérations) conservent leurs règles propres ; la migration de préfixe ne doit pas altérer arbitrairement leur sémantique.
|
||||
|
||||
## 7. Namespace SQL
|
||||
|
||||
La normalisation SQL appartient à `0.5.3` avec `ks-store`.
|
||||
|
||||
Les tables génériques représentant des faits Solana doivent migrer du préfixe actuel `kb_sol_*` vers :
|
||||
|
||||
```text
|
||||
k_sol_*
|
||||
```
|
||||
|
||||
La base Mainnet/Devnet peut être reconstruite ou migrée proprement avant l'ouverture de `0.6.x`. Il n'est donc pas nécessaire de préserver indéfiniment un préfixe historique incohérent uniquement pour compatibilité.
|
||||
|
||||
Si des tables réellement spécifiques au robot de trading sont introduites ultérieurement, elles utilisent le préfixe :
|
||||
|
||||
```text
|
||||
kb_*
|
||||
```
|
||||
|
||||
Une table ne reçoit pas `kb_*` simplement parce qu'elle est consommée par le bot. Elle doit contenir des données dont la responsabilité appartient réellement au domaine applicatif Bot et non à la blockchain ou aux bibliothèques Solana généralistes.
|
||||
|
||||
La migration `kb_sol_*` → `k_sol_*` doit être traitée avec les contrats temporels, de provenance, d'idempotence, d'index et de replay de `0.5.3`, et non comme un remplacement textuel isolé.
|
||||
|
||||
## 8. Ordre des migrations
|
||||
|
||||
- `0.5.1` : crates `ks-*`, identifiants Rust `ks_*`, variables `KS_*`, identités runtime/persistées Khadhroony Solana et restructuration sûre de la configuration/logging ;
|
||||
- `0.5.2` : restructuration de `ks-wallet` sur la nouvelle fondation de configuration ;
|
||||
- `0.5.3` : normalisation de `ks-store`, y compris migration du préfixe SQL vers `k_sol_*` et contrats temporels/provenance ;
|
||||
- `0.5.4` : centralisation finale des scénarios dans `ks-pipeline-demo-scenarios` et audit de complétude des exécuteurs/validations.
|
||||
|
||||
Aucune de ces migrations ne doit réintroduire une dépendance du domaine Solana généraliste vers une application spécifique au bot.
|
||||
@@ -1,501 +0,0 @@
|
||||
<!-- file: docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Plan `0.5.0` — cadrage de la fondation `0.5.x`
|
||||
|
||||
## 1. Statut et rôle du document
|
||||
|
||||
Ce document est le livrable principal de `0.5.0-pre.001`.
|
||||
|
||||
`0.5.0` est une version de **cadrage, d'audit et de préparation des migrations**. Elle ne doit pas restructurer prématurément `kb-config`, `kb-wallet` ou `kb-store`, ni déplacer en masse les scénarios du desktop avant que leurs contrats actuels, leurs consommateurs et leurs preuves de validation aient été caractérisés.
|
||||
|
||||
Le plan reste temporaire pendant le développement de `0.5.0`. Il doit être maintenu à chaque prerelease, puis archivé sous `olddocs/archivekbot3/` lors de la dernière prerelease, après transfert des décisions durables vers le ROADMAP, les règles, les guides et les documents de crates appropriés.
|
||||
|
||||
**État de `pre.001` : plan validé.**
|
||||
|
||||
**État de `pre.002` : audit config/logging/wallet effectué ; les décisions détaillées sont consignées dans [`V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md`](V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md). Aucune restructuration fonctionnelle n'est encore appliquée.**
|
||||
|
||||
**État de `pre.003` : audit store/scénarios/desktop effectué ; le contrat temporel, la méthode de complétude et la cible de renommage `ks-*` sont consignés dans [`V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md`](V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md). Aucun changement runtime, SQL ou exécuteur n'est appliqué.**
|
||||
|
||||
## 2. Base `0.4.8` à préserver
|
||||
|
||||
La release `0.4.8` constitue la base fonctionnelle fermée de la série `0.5.x` :
|
||||
|
||||
- Solana Program Metadata est une surface indépendante avec neuf opérations confirmées sur Devnet ;
|
||||
- Token-2022 Token Metadata possède cinq opérations confirmées sur Devnet ;
|
||||
- la matrice Metaplex Token Metadata est fermée à 15 `confirmed`, 5 `unavailable` et 0 `not_run` ;
|
||||
- les scénarios Metadata réutilisables sont présents dans `kb-pipeline-demo-scenarios` et raccordés au desktop ;
|
||||
- les matrices, exports, registres runtime, IDL, stockage générique et documents Metadata ont été réconciliés ;
|
||||
- le workspace et le build desktop release ont été validés avant la release `0.4.8`.
|
||||
|
||||
Le registre ElGamal reste une exception connue : implémenté et validé synthétiquement, sans preuve réseau réelle disponible. `0.5.0` ne doit pas rouvrir implicitement ce sujet en l'absence d'une nouvelle possibilité de validation.
|
||||
|
||||
## 3. Sources de vérité et méthode
|
||||
|
||||
L'ordre de priorité utilisé pour le cadrage est :
|
||||
|
||||
1. code et contrats publics actuels ;
|
||||
2. règles actives sous `docs/rules/` ;
|
||||
3. schémas, migrations, matrices et tests actifs ;
|
||||
4. README, USAGE, TODO, changelogs et architecture actifs ;
|
||||
5. prompt actif `029` ;
|
||||
6. prompts archivés `027` et `028` uniquement comme références historiques et méthodologiques.
|
||||
|
||||
Les documents archivés ne sont jamais utilisés pour contredire un contrat actuel. Aucun changement de contrat public ne doit être entrepris sans recherche de ses consommateurs dans les onze crates et sans audit des tests d'API externe concernés.
|
||||
|
||||
## 4. Carte actuelle des responsabilités et couplages
|
||||
|
||||
Le workspace contient onze crates. Les six surfaces directement auditées pour `0.5.0` se placent aujourd'hui comme suit.
|
||||
|
||||
| Surface | Responsabilité actuelle | Dépendances workspace directes | Consommateurs directs principaux | Risque de migration |
|
||||
|---|---|---|---|---|
|
||||
| `kb-config` | schéma JSON, parsing, validation, profils, résolution d'environnement, sérialisation | `kb-core` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-onchain-transport`, `kb-app-demo-desktop` | très élevé : types publics et TS-RS largement consommés |
|
||||
| `kb-logging` | runtime `tracing`, routes, formats, rotations, filtres | `kb-core` | `kb-app-demo-desktop` | moyen : contrat runtime dupliqué dans `kb-config` |
|
||||
| `kb-wallet` | alias, keypair local temporaire, persistance JSON, signature | `kb-core` | `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | élevé : secret persistant et API signer traversant les scénarios |
|
||||
| `kb-store` | DTO, entités, repositories, migrations PostgreSQL, diagnostics, replay/persistance | `kb-core`, `kb-lib` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | très élevé : schéma SQL publié et grande façade publique |
|
||||
| `kb-pipeline-demo-scenarios` | fixtures et campagnes synthétiques/réseau réutilisables | `kb-core`, `kb-config`, `kb-lib`, `kb-onchain-transport`, `kb-pipeline`, `kb-program-ids`, `kb-store`, `kb-wallet` | `kb-app-demo-desktop` | élevé : convergence de presque toutes les fondations |
|
||||
| `kb-app-demo-desktop` | composition applicative, état Tauri, IPC, TS-RS et UI opérateur | les dix autres crates | frontend Tauri | élevé côté IPC ; ne doit pas devenir propriétaire de logique réutilisable |
|
||||
|
||||
Cette topologie confirme l'ordre du ROADMAP : stabiliser d'abord la configuration, puis le wallet, puis le store, avant l'audit final des scénarios et exécuteurs. Une inversion de cet ordre multiplierait les adaptations transitoires.
|
||||
|
||||
## 5. Contrats publics et formats sensibles aux migrations
|
||||
|
||||
### 5.1 `kb-config` et configuration frontend
|
||||
|
||||
Les contrats sensibles sont au minimum :
|
||||
|
||||
- `AppConfig`, `ProfileConfig` et les sous-structures publiques ;
|
||||
- les dérivations `serde` et TS-RS de ces structures ;
|
||||
- `config/schema.config.json` et son équivalent embarqué ;
|
||||
- `config/example.config.json` ;
|
||||
- la syntaxe `${NAME}` et `${NAME:-fallback}` ;
|
||||
- les fonctions de parsing, validation, sélection de profil et sérialisation ;
|
||||
- les erreurs et validations dont le code est consommé par les tests ou les adaptateurs ;
|
||||
- `DemoConfigPayload` et la commande Tauri `load_demo_config`.
|
||||
|
||||
Le split futur ne doit pas être traité comme un simple déplacement de fichiers : il peut affecter schéma, chargement, migration, TS-RS, exemples, diagnostics et consommateurs.
|
||||
|
||||
### 5.2 `kb-logging`
|
||||
|
||||
`kb-config` et `kb-logging` possèdent actuellement des structures presque identiques `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig`. Le desktop les convertit manuellement dans `app_state.rs`.
|
||||
|
||||
`pre.002` confirme que le logging doit devenir un document et un schéma distincts de la configuration généraliste. Les profils logging doivent pouvoir évoluer indépendamment des profils réseau/applicatifs et la conversion manuelle du desktop doit disparaître lors de `0.5.1`.
|
||||
|
||||
La propriété exacte du DTO source logging doit encore respecter la direction des dépendances : `kb-config` ne doit pas dépendre du runtime `kb-logging` par commodité. `0.5.1` devra choisir un propriétaire unique du contrat source et éviter une nouvelle crate si elle ne représente pas une responsabilité autonome.
|
||||
|
||||
### 5.3 `kb-wallet`
|
||||
|
||||
Le format persistant actuel est un contrat de compatibilité réel :
|
||||
|
||||
- chemin déterministe `<alias>.json` ;
|
||||
- contenu : tableau JSON standard du keypair Solana ;
|
||||
- création sans écrasement ;
|
||||
- permissions privées Unix et refus des liens symboliques/fichiers non réguliers ;
|
||||
- buffers temporaires secrets effacés ;
|
||||
- `TemporaryWallet` garde le keypair privé mais expose `as_signer()` et `as_sync_signer()` ;
|
||||
- `WalletSummary` est le contrat non secret destiné aux adaptateurs.
|
||||
|
||||
Un futur chiffrement ou format versionné doit donc définir l'import de ce format `0.4.8`, la détection de format, la sauvegarde, l'échec atomique et la stratégie de rollback. La présence de primitives cryptographiques dans les dépendances workspace ne constitue pas, à elle seule, une décision d'architecture.
|
||||
|
||||
### 5.4 `kb-store`
|
||||
|
||||
Les migrations publiées `0001` à `0004` sont immuables. Toute évolution devra passer par une nouvelle migration.
|
||||
|
||||
Les contrats sensibles incluent :
|
||||
|
||||
- les tables `kb_sol_*`, contraintes et index ;
|
||||
- les DTO/entités `*Insert`, `*Row`, bundles atomiques et filtres ;
|
||||
- les traits de repositories publics ;
|
||||
- les identités persistées de processeur, version, input/output et source ;
|
||||
- les états de ledger et de lifecycle ;
|
||||
- les noms de tables exportés pour diagnostics/audits ;
|
||||
- le JSON canonique des transactions, dont la version de format est gérée hors du SQL.
|
||||
|
||||
Le modèle canonique et les transports portent déjà `block_time`, mais les tables raw/Core/decode/materialization ne le promeuvent pas uniformément comme colonne de premier rang. Les timestamps de persistance (`created_at`, `updated_at`, `persisted_at`) ne doivent pas être confondus avec le temps on-chain.
|
||||
|
||||
### 5.5 `kb-pipeline-demo-scenarios`
|
||||
|
||||
Les contrats publics de scénarios, identifiants de campagnes, requêtes, résultats, matrices de qualification et preuves consommées par le desktop doivent être audités avant déplacement de logique. Une campagne `confirmed`, `unavailable` ou synthétique garde son niveau de preuve tant que la frontière couverte n'a pas changé.
|
||||
|
||||
### 5.6 `kb-app-demo-desktop`
|
||||
|
||||
Les commandes Tauri et payloads TS-RS sont une API applicative externe au backend Rust, même lorsque leurs structures Rust sont `pub(crate)`. Les noms de commandes, champs sérialisés, invariants d'annulation/progression et restauration d'état doivent être caractérisés avant changement.
|
||||
|
||||
Le desktop peut conserver :
|
||||
|
||||
- sélection et saisie opérateur ;
|
||||
- mapping UI vers une requête réutilisable ;
|
||||
- adaptation d'un résultat réutilisable vers TS-RS ;
|
||||
- progression, annulation et présentation ;
|
||||
- composition d'état strictement applicative.
|
||||
|
||||
La préparation de fixture, la construction d'une campagne, l'orchestration RPC, les postconditions et la qualification réutilisable n'ont pas vocation à rester dans le desktop.
|
||||
|
||||
## 6. Problèmes réels identifiés pendant `pre.001`
|
||||
|
||||
### P0 — exposition possible de secrets résolus vers le frontend
|
||||
|
||||
C'est le risque prioritaire de `0.5.1`.
|
||||
|
||||
La configuration charge et résout des placeholders susceptibles de contenir notamment :
|
||||
|
||||
- un DSN PostgreSQL avec identifiants ;
|
||||
- une clé d'API intégrée à une URL HTTP ou WebSocket.
|
||||
|
||||
`AppConfig` et `ProfileConfig` sont sérialisables. Le desktop construit actuellement `DemoConfigPayload` en clonant la configuration complète et le profil actif, puis le frontend les affiche dans des JSON viewers.
|
||||
|
||||
Il existe donc un chemin concret permettant à un secret résolu d'atteindre un payload Tauri et l'UI. `0.5.1` devra fermer ce chemin avant de considérer la nouvelle architecture de configuration comme sûre.
|
||||
|
||||
**Contraintes de correction futures :**
|
||||
|
||||
- aucune valeur secrète résolue en clair dans un payload UI ou diagnostic ;
|
||||
- aucune valeur secrète dans `Debug`, logs ou erreurs ;
|
||||
- sérialisation publique explicitement redacted ou séparée de la représentation runtime ;
|
||||
- tests avec sentinelles secrètes couvrant DSN, URL, query string et erreurs ;
|
||||
- absence de régression sur les consommateurs backend qui ont réellement besoin des valeurs résolues.
|
||||
|
||||
### P1 — duplication du contrat logging
|
||||
|
||||
Le même shape de configuration logging existe dans `kb-config` et `kb-logging`, avec conversion manuelle dans le desktop. C'est un couplage réel, pas seulement documentaire. `0.5.1` doit choisir un propriétaire de chaque responsabilité : format de configuration, validation et runtime.
|
||||
|
||||
### P1 — migration du wallet non définie
|
||||
|
||||
Le wallet actuel est fonctionnel mais son secret est persisté en clair dans le format Solana standard. Ajouter chiffrement, verrouillage, multi-wallet ou backup sans définir un format versionné et une migration ferait courir un risque de perte ou d'incompatibilité de clés.
|
||||
|
||||
### P1 — modèle temporel du store incomplet pour les futurs faits trading
|
||||
|
||||
Le store distingue déjà plusieurs timestamps d'acquisition dans les observations, mais cette distinction n'est pas propagée uniformément vers les tables Core, decode et materialization. `block_time` existe dans la transaction canonique mais n'est pas une dimension SQL commune de premier rang.
|
||||
|
||||
Avant toute table trading, `0.5.3` devra définir les dimensions stables : identité de transaction/instruction, slot, temps on-chain lorsqu'il existe, provenance, identité de processeur, idempotence et temps de persistance.
|
||||
|
||||
### P2 — orchestration résiduelle dans le desktop
|
||||
|
||||
Plusieurs modules d'exécution desktop combinent encore des appels directs à `kb-pipeline`, `kb-lib` executor, transport, wallet ou store en plus de `kb-pipeline-demo-scenarios`. C'est un signal d'audit pour `0.5.4`, pas une preuve que tout le module doit être déplacé.
|
||||
|
||||
L'audit devra distinguer précisément :
|
||||
|
||||
- orchestration réutilisable à déplacer ;
|
||||
- adaptation Tauri légitime à conserver ;
|
||||
- logique de rendu/frontend ;
|
||||
- diagnostics généralistes qui ne sont pas des scénarios.
|
||||
|
||||
### P2 — documentation active partiellement obsolète
|
||||
|
||||
Deux divergences sont déjà confirmées :
|
||||
|
||||
- `docs/guides/CONFIGURATION.md` cite `load_config_from_str` et `load_config_from_path`, absents de l'API actuelle ;
|
||||
- `kb-config/USAGE.md` présente l'affichage du JSON résolu comme cas de diagnostic, alors que ce JSON peut contenir des secrets ;
|
||||
- les README de `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` décrivent encore le maintien de « scénarios UI » dans le desktop, formulation incompatible avec la cible `0.5.4` lorsqu'elle concerne une orchestration réutilisable.
|
||||
|
||||
Ces écarts doivent être corrigés dans une prerelease documentaire de `0.5.0` ou dans la version propriétaire de la frontière, sans réécrire l'histoire des changelogs.
|
||||
|
||||
## 7. Ce qui appartient à `0.5.0`
|
||||
|
||||
`0.5.0` doit livrer uniquement la préparation fiable de la série :
|
||||
|
||||
- cartographie des responsabilités et dépendances ;
|
||||
- inventaire des contrats publics et formats persistés ;
|
||||
- identification des risques de migration et des consommateurs ;
|
||||
- tests de caractérisation non controversés et tests d'API externe manquants lorsque nécessaires ;
|
||||
- audits ciblés des quatre axes `0.5.1` à `0.5.4` ;
|
||||
- décisions de vocabulaire et critères d'acceptation ;
|
||||
- stratégie de migration et rollback à un niveau suffisant pour coder ensuite sans improvisation ;
|
||||
- correction de la documentation rendue factuellement fausse par l'audit ;
|
||||
- préparation des prompts suivants.
|
||||
|
||||
`0.5.0` ne doit pas :
|
||||
|
||||
- scinder effectivement les fichiers ou types de `kb-config` ;
|
||||
- modifier le format wallet persistant ;
|
||||
- ajouter une migration SQL trading ;
|
||||
- créer des tables spécifiques Meteora/Raydium/Pump/Orca/Jupiter ;
|
||||
- déplacer en masse les scénarios du desktop ;
|
||||
- ajouter des exécuteurs non justifiés ;
|
||||
- rejouer automatiquement les campagnes réseau déjà qualifiées ;
|
||||
- rouvrir ElGamal sans possibilité de preuve nouvelle ;
|
||||
- introduire de nouvelle surface protocolaire majeure.
|
||||
|
||||
## 8. Préparation de `0.5.1` — configuration et namespace `ks-*`
|
||||
|
||||
### Décisions fermées par `pre.002`
|
||||
|
||||
- toutes les variables d'environnement propres au projet devront utiliser le namespace `KS_*` ;
|
||||
- `KS_SECRET_*` est strictement non exposable, y compris en debug/diagnostic ;
|
||||
- `KS_PUBLIC_*` est seulement candidate à une exposition explicitement autorisée par un DTO public ;
|
||||
- autre `KS_*` reste interne et n'est visible que par un diagnostic explicite et borné ;
|
||||
- toute valeur composée contenant un secret hérite de la classification `Secret` ;
|
||||
- la configuration source, la configuration runtime résolue et les DTO publics/diagnostics doivent être des frontières distinctes ;
|
||||
- le logging doit être extrait dans un document et un schéma JSON indépendants ;
|
||||
- le profil logging doit pouvoir évoluer indépendamment du profil généraliste ;
|
||||
- la conversion manuelle `kb-config` -> `kb-logging` actuellement située dans le desktop doit disparaître ;
|
||||
- les bibliothèques Solana généralistes doivent migrer vers le namespace Cargo `ks-*` / Rust `ks_*` pendant `0.5.1` ; la liste exacte et le traitement des identités persistées doivent être fermés avant le premier renommage.
|
||||
|
||||
L'audit a recensé 84 noms d'environnement actifs ou de fixture dans le code/configuration de référence : 67 `KB_*` et 17 sans namespace cible. La migration exacte est détaillée dans [`V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md`](V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md).
|
||||
|
||||
### Critères d'acceptation préparés
|
||||
|
||||
- migration explicite du format `0.4.8` vers les documents séparés ;
|
||||
- schémas JSON général et logging distincts et synchronisés avec leurs modèles ;
|
||||
- table exhaustive ancien nom d'environnement -> nouveau nom `KS_*` ;
|
||||
- refus des variables Khadhroony hors namespace `KS_*` après migration ;
|
||||
- tests des profils, defaults, validations croisées et erreurs ;
|
||||
- tests `.env`, fichier dotenv sélectionné, placeholders et fallbacks ;
|
||||
- canaris `KS_SECRET_*` absents de tous les payloads publics, logs, diagnostics et erreurs ;
|
||||
- suppression du payload frontend de configuration résolue complète ;
|
||||
- aucun élargissement automatique de la surface publique uniquement parce que la build est debug ;
|
||||
- adaptation explicite de `kb-logging`, transport, pipeline, scénarios et desktop ;
|
||||
- aucune dépendance de `kb-store` vers `kb-config` ;
|
||||
- tests d'API externe de la façade `kb-config` avant changement structurel ;
|
||||
- documentation et exemples alignés.
|
||||
|
||||
## 9. Préparation de `0.5.2` — `kb-wallet`
|
||||
|
||||
### Frontières à concevoir
|
||||
|
||||
- identité publique d'un wallet ;
|
||||
- matériau secret persistant ;
|
||||
- état verrouillé/déverrouillé et durée de session ;
|
||||
- capacité de signature ;
|
||||
- sélection de wallet/profil ;
|
||||
- import/export, backup/restore et migration de format.
|
||||
|
||||
### Compatibilité à préserver
|
||||
|
||||
- lecture contrôlée des wallets `0.4.8` au format JSON Solana ;
|
||||
- correspondance alias -> clé publique ;
|
||||
- possibilité de fournir un signer aux exécuteurs sans exposer les octets ;
|
||||
- comportement atomique en cas de corruption ou d'échec d'écriture ;
|
||||
- permissions et protections filesystem existantes.
|
||||
|
||||
### Tests à préparer
|
||||
|
||||
- fixtures de wallet `0.4.8` ;
|
||||
- migration aller/échec/rollback ;
|
||||
- mauvais mot de passe et données corrompues ;
|
||||
- concurrence de création/import ;
|
||||
- lock/unlock et invalidation de session ;
|
||||
- absence de secret dans `Debug`, erreurs, résumés, config et Tauri ;
|
||||
- backup/restore si cette capacité est retenue.
|
||||
|
||||
## 10. Préparation de `0.5.3` — `kb-store`
|
||||
|
||||
### Vocabulaire temporel à normaliser
|
||||
|
||||
Le store doit distinguer explicitement :
|
||||
|
||||
- `slot` : ordre/position blockchain, pas un timestamp ;
|
||||
- `block_time` ou temps de transaction : temps on-chain optionnel fourni par la chaîne ;
|
||||
- temps d'observation/acquisition : `detected_at`, `received_at`, `normalized_at` lorsque pertinent ;
|
||||
- temps de persistance : `persisted_at`, `created_at`, `updated_at`.
|
||||
|
||||
Aucune requête temporelle métier ne doit utiliser `created_at` comme substitut implicite de `block_time`.
|
||||
|
||||
### Faits stables à définir avant les DEX
|
||||
|
||||
Sans inventer de table protocolaire, l'audit doit déterminer quelles dimensions génériques sont nécessaires pour que de futurs matérialisateurs puissent exprimer efficacement :
|
||||
|
||||
- création/identité d'un pool ou marché ;
|
||||
- actifs et comptes de réserve ;
|
||||
- variations de liquidité et réserves observées ;
|
||||
- swaps ;
|
||||
- prix observés et unités utilisées ;
|
||||
- séries temporelles ;
|
||||
- provenance du fait et idempotence ;
|
||||
- relation entre plusieurs pools et futures routes.
|
||||
|
||||
Le résultat attendu est un contrat de faits et d'indexation, pas un schéma Meteora ou Raydium anticipé.
|
||||
|
||||
### Migration à préparer
|
||||
|
||||
- ne jamais modifier `0001` à `0004` ;
|
||||
- définir une nouvelle migration uniquement après validation du modèle ;
|
||||
- préciser la nullabilité et le backfill de `block_time` ;
|
||||
- tester migration sur schéma `0.4.8`, réexécution idempotente et données existantes ;
|
||||
- mesurer/inspecter les index destinés aux requêtes temporelles et multi-entités ;
|
||||
- conserver les identités persistées de processeurs et clés d'idempotence ou fournir une migration explicite.
|
||||
|
||||
## 11. Préparation de `0.5.4` — scénarios et complétude d'exécution
|
||||
|
||||
L'audit doit produire une matrice par capacité avec au minimum :
|
||||
|
||||
- décodeur ;
|
||||
- matérialiseur ;
|
||||
- exécuteur ;
|
||||
- scénario synthétique ;
|
||||
- scénario réutilisable réseau ;
|
||||
- adaptation desktop ;
|
||||
- preuve simulation ;
|
||||
- preuve soumission ;
|
||||
- postcondition ;
|
||||
- qualification finale.
|
||||
|
||||
Chaque absence doit être classée dans une des catégories imposées :
|
||||
|
||||
- `implement` ;
|
||||
- `decode-only` ;
|
||||
- `deprecated` ;
|
||||
- `unavailable` ;
|
||||
- `not-applicable` ;
|
||||
- `deferred`.
|
||||
|
||||
Un exécuteur n'est pas requis uniquement parce qu'un décodeur existe. La justification doit intégrer sécurité, programme courant, possibilité de fixture et valeur pour les versions suivantes.
|
||||
|
||||
Le déplacement d'un scénario vers `kb-pipeline-demo-scenarios` doit conserver le desktop comme adaptateur et préserver les noms/payloads Tauri lorsque leur changement n'apporte aucune valeur.
|
||||
|
||||
## 12. Découpage borné de `0.5.0`
|
||||
|
||||
### `0.5.0-pre.001` — audit initial, brainstorming et plan
|
||||
|
||||
Livrables :
|
||||
|
||||
- lecture des règles, architecture, documents de crates, schémas et migrations ;
|
||||
- cartographie des six surfaces concernées ;
|
||||
- identification des contrats sensibles et premiers écarts réels ;
|
||||
- plan vivant de `0.5.0` et de la série `0.5.x` ;
|
||||
- ouverture de `workspace.package.version` sur `0.5.0-pre.1` ;
|
||||
- alignement frontend/Tauri sur la version fonctionnelle `0.5.0` ;
|
||||
- aucun changement fonctionnel ou structurel.
|
||||
|
||||
Critère de sortie : plan complet et **validation explicite du plan avant toute restructuration**.
|
||||
|
||||
### `0.5.0-pre.002` — audit config/logging/wallet et contrats de sécurité
|
||||
|
||||
Livrables réalisés :
|
||||
|
||||
- inventaire des consommateurs de `AppConfig`, `ProfileConfig`, structures logging et APIs wallet ;
|
||||
- audit des chemins de sérialisation, `Debug`, logs, erreurs, diagnostics et Tauri susceptibles de transporter un secret ;
|
||||
- confirmation du split logging en document + schéma indépendants ;
|
||||
- définition de la convention `KS_SECRET_*` / `KS_PUBLIC_*` / `KS_*` et de la propagation de sensibilité ;
|
||||
- inventaire de 84 contrats d'environnement actifs ou de fixture à migrer ;
|
||||
- audit des tests TS-RS et tests d'API externe manquants ;
|
||||
- caractérisation du format de configuration `0.4.8` et du format wallet `0.4.8` ;
|
||||
- dossier de migration `0.5.1` et `0.5.2` avec compatibilité, rollback et critères de non-divulgation ;
|
||||
- ouverture de l'audit transversal sur le namespace de crates `ks-*`, sans renommage prématuré ;
|
||||
- correction des documents de configuration rendus faux ou dangereux par l'audit, sans appliquer encore le nouveau format.
|
||||
|
||||
Critère de sortie : frontières source/runtime/public fermées, namespace d'environnement cible défini, split logging confirmé et contrat de migration wallet borné. `pre.003` ferme ensuite la direction : les bibliothèques Solana généralistes migreront vers `ks-*` en `0.5.1`, avec audit séparé des identités persistées.
|
||||
|
||||
### `0.5.0-pre.003` — audit store/scénarios/desktop et contrats de préparation
|
||||
|
||||
Livrables réalisés :
|
||||
|
||||
- matrice des migrations `0001` à `0004`, colonnes temporelles, provenance, idempotence, index et requêtes ;
|
||||
- définition du vocabulaire on-chain/persistance et des faits génériques requis avant trading ;
|
||||
- dossier de migration `0.5.3`, sans créer de table DEX ;
|
||||
- inventaire des scénarios/orchestrations du desktop et de leurs équivalents réutilisables ;
|
||||
- matrice decoder/materializer/executor/scenario/network-proof préparant `0.5.4` ;
|
||||
- classification des absences sans implémenter les exécuteurs ;
|
||||
- identification précise des validations réseau à rejouer uniquement si une frontière couverte change ;
|
||||
- inventaire statique des exécuteurs : 8 actifs et 103 réservés ;
|
||||
- confirmation qu'ElGamal est le seul exécuteur actif sans scénario réseau réutilisable et reste conditionnel faute de preuve disponible ;
|
||||
- correction de la frontière normative : campagnes réutilisables dans `kb-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop ;
|
||||
- décision de faire du renommage des bibliothèques généralistes vers `ks-*` une partie de `0.5.1`, sans renommer mécaniquement les tables ou identités persistées.
|
||||
|
||||
Critère de sortie : contrats de `0.5.3` et méthode de complétude `0.5.4` suffisamment fermés pour éviter une refonte spéculative. L'audit détaillé est consigné dans [`V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md`](V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md).
|
||||
|
||||
### `0.5.0-pre.004` — clôture obligatoire de `0.5.0`
|
||||
|
||||
Livrables prévus :
|
||||
|
||||
- réconciliation transversale des audits et corrections résiduelles ;
|
||||
- validations finales du workspace ;
|
||||
- mise à jour des README/USAGE/TODO/guides rendus faux ou incomplets ;
|
||||
- transfert des décisions durables dans ROADMAP/règles/architecture lorsque nécessaire ;
|
||||
- archivage du présent plan et du prompt `029` sous `olddocs/archivekbot3/` ;
|
||||
- préparation du prompt `0.5.1` ;
|
||||
- préparation de la release finale `0.5.0` sans nouvelle fonctionnalité structurelle majeure.
|
||||
|
||||
Le CHANGELOG racine conserve sa règle : les entrées fonctionnelles publiées sont ajoutées au moment de la release finale, pas sous une section « non publiée » artificielle.
|
||||
|
||||
## 13. Tests et audits à préparer avant code structurel
|
||||
|
||||
### Contrats publics
|
||||
|
||||
- rechercher chaque type/fonction modifié dans les onze crates ;
|
||||
- ajouter ou compléter les tests d'API externe lorsque la façade publique n'est pas caractérisée ;
|
||||
- tester les noms et champs Tauri/TS-RS lorsqu'ils constituent une interface frontend stable ;
|
||||
- ne pas figer par test une fuite de secret ou une mauvaise frontière connue.
|
||||
|
||||
### Configuration
|
||||
|
||||
- fixture `0.4.8` complète ;
|
||||
- round-trip du format actuel ;
|
||||
- tests d'environnement/placeholder ;
|
||||
- sentinelles secrètes et assertions de redaction pour chaque sortie publique future ;
|
||||
- migration old -> new et erreurs de migration explicites.
|
||||
|
||||
### Wallet
|
||||
|
||||
- fixture persistée `0.4.8` ;
|
||||
- identité de clé publique après import/migration ;
|
||||
- tests de corruption, permissions, concurrence et atomicité ;
|
||||
- tests de verrouillage/chiffrement uniquement après décision du format.
|
||||
|
||||
### Store
|
||||
|
||||
- application des migrations historiques sur base vide ;
|
||||
- migration d'une base `0.4.8` avec données ;
|
||||
- idempotence des migrations ;
|
||||
- conservation des clés de provenance et d'idempotence ;
|
||||
- backfill/nullabilité des temps on-chain ;
|
||||
- requêtes bornées et index adaptées aux dimensions retenues.
|
||||
|
||||
### Scénarios/exécution
|
||||
|
||||
- matrice automatisable de complétude des registres ;
|
||||
- tests synthétiques et contractuels en premier ;
|
||||
- simulation RPC exacte avant soumission ;
|
||||
- réseau uniquement lorsqu'une nouvelle capacité ou frontière modifiée le justifie ;
|
||||
- postconditions et matérialisation observables avant promotion du statut.
|
||||
|
||||
## 14. Politique de validation réseau pendant `0.5.x`
|
||||
|
||||
Pour une nouvelle capacité exécutable :
|
||||
|
||||
1. contrat et tests synthétiques ;
|
||||
2. scénario réutilisable ;
|
||||
3. simulation RPC exacte ;
|
||||
4. soumission Devnet/Testnet sûre et disponible ;
|
||||
5. postconditions et matérialisation observables ;
|
||||
6. adaptateur desktop ;
|
||||
7. qualification explicite.
|
||||
|
||||
Une preuve synthétique seule ne promeut jamais un statut réseau. Inversement, une campagne `0.4.8` déjà qualifiée n'est pas rejouée après un refactor si aucune frontière qu'elle couvre n'a changé et si les tests de compatibilité restent propres.
|
||||
|
||||
## 15. Contrôles de référence
|
||||
|
||||
Après chaque delta Rust ou de contrat :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --all-targets
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Le desktop est validé par Tauri uniquement :
|
||||
|
||||
```bash
|
||||
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
|
||||
cargo tauri build -c kb-app-demo-desktop/tauri.conf.json
|
||||
```
|
||||
|
||||
Ne jamais lancer directement les scripts npm de développement ou build. Les commandes npm manuelles restent limitées à l'installation explicite de dépendances.
|
||||
|
||||
## 16. Critères de clôture de `0.5.0`
|
||||
|
||||
`0.5.0` peut être clôturée lorsque :
|
||||
|
||||
- les six surfaces ont un audit suffisamment précis pour leurs versions propriétaires ;
|
||||
- les contrats publics et formats persistés à migrer sont inventoriés ;
|
||||
- le chemin de fuite de configuration résolue est explicitement attribué à `0.5.1` avec critères de non-divulgation ;
|
||||
- le namespace d'environnement `KS_*` et les classes `Secret/Public/Internal` sont documentés avec propagation de sensibilité ;
|
||||
- le split logging en document et schéma indépendants est retenu comme cible de `0.5.1` ;
|
||||
- le format wallet `0.4.8` et ses exigences de migration sont documentés ;
|
||||
- le vocabulaire temporel/provenance/idempotence du store est défini avant tout schéma trading ;
|
||||
- la méthode d'audit decoder/executor/scenario/validation de `0.5.4` est fermée ;
|
||||
- aucun chantier `0.5.1` à `0.5.4` n'a été implémenté prématurément ;
|
||||
- les documents actifs ne présentent plus les hypothèses obsolètes identifiées ;
|
||||
- les contrôles de référence sont propres sur le workspace réel ;
|
||||
- le plan et le prompt terminés sont archivés et le prompt `0.5.1` est prêt.
|
||||
@@ -1,380 +0,0 @@
|
||||
<!-- file: docs/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Audit `0.5.0-pre.002` — configuration, logging, wallet et namespaces
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Ce document complète le plan temporaire [`V0_5_0_FOUNDATION_0_5_X_PLAN.md`](V0_5_0_FOUNDATION_0_5_X_PLAN.md) avec l'audit approfondi prévu pour `0.5.0-pre.002`.
|
||||
|
||||
Cette prerelease reste **non structurelle** : elle ferme les contrats à préparer pour `0.5.1` et `0.5.2`, mais ne scinde pas encore les fichiers de configuration, ne change pas les noms de variables d'environnement utilisés par le runtime, ne modifie pas le format wallet persistant et ne renomme aucune crate.
|
||||
|
||||
## 2. Décisions de cadrage fermées
|
||||
|
||||
### 2.1 Namespace des variables d'environnement
|
||||
|
||||
Toutes les variables d'environnement appartenant à Khadhroony/Solana devront obligatoirement commencer par `KS_`.
|
||||
|
||||
La convention cible comporte trois niveaux :
|
||||
|
||||
- `KS_SECRET_*` : secret absolu, utilisable uniquement côté backend et jamais exposé, sérialisé, loggé ou inclus en clair dans une erreur, y compris en mode debug ou diagnostic ;
|
||||
- `KS_PUBLIC_*` : valeur explicitement candidate à l'exposition publique, mais seulement lorsqu'un DTO public l'autorise ;
|
||||
- autre `KS_*` : valeur interne, non exposée en fonctionnement normal et consultable uniquement par un diagnostic explicite et borné.
|
||||
|
||||
Aucune variable hors namespace `KS_*` ne doit être lue comme contrat propre au projet après migration. Le runtime ne doit jamais énumérer l'environnement du processus pour décider automatiquement ce qui est exposable.
|
||||
|
||||
Le préfixe ne remplace pas la politique de type : une valeur `KS_PUBLIC_*` n'est pas envoyée au frontend si aucun DTO public ne l'autorise, et une valeur issue d'un champ sémantiquement secret reste secrète même si son nom est mal classé.
|
||||
|
||||
### 2.2 Propagation de la sensibilité
|
||||
|
||||
La résolution d'un placeholder ne doit plus perdre son origine de sécurité.
|
||||
|
||||
Si une chaîne composée contient au moins une valeur `KS_SECRET_*`, la chaîne résolue complète devient secrète. Exemple :
|
||||
|
||||
```text
|
||||
https://mainnet.helius-rpc.com/?api-key=${KS_SECRET_HELIUS_API_KEY}
|
||||
```
|
||||
|
||||
Le résultat complet doit être traité comme secret. La même règle s'applique aux DSN PostgreSQL et à toute autre composition.
|
||||
|
||||
Ordre de dominance prévu pour une valeur composée :
|
||||
|
||||
```text
|
||||
Secret > Internal/DebugOnly > Public
|
||||
```
|
||||
|
||||
Une représentation publique doit être construite explicitement à partir du runtime ; elle ne doit jamais provenir d'une sérialisation complète suivie d'une suppression opportuniste de champs.
|
||||
|
||||
### 2.3 Split de la configuration logging
|
||||
|
||||
Le split du logging n'est plus une question ouverte : `0.5.1` devra extraire le logging du document général dans **un document et un schéma JSON distincts**.
|
||||
|
||||
La cible minimale est donc :
|
||||
|
||||
- un document de configuration général ;
|
||||
- un document de configuration logging ;
|
||||
- un schéma JSON général ;
|
||||
- un schéma JSON logging.
|
||||
|
||||
Les profils généralistes et les profils logging doivent pouvoir évoluer indépendamment. Un profil réseau ne doit plus contenir une copie complète de toutes les routes logging.
|
||||
|
||||
D'autres documents spécialisés ne seront ajoutés que si l'audit de `0.5.1` démontre une responsabilité, une validation ou un cycle de vie suffisamment indépendant ; le split ne doit pas devenir une fragmentation systématique.
|
||||
|
||||
## 3. État réel de la configuration `0.4.8`
|
||||
|
||||
### 3.1 Taille et duplication
|
||||
|
||||
`config/example.config.json` représente environ 154 Ko.
|
||||
|
||||
Les trois profils actifs (`local_devnet`, `mainnet_research`, `mainnet`) embarquent chacun un bloc logging d'environ 23 à 24 Ko. Ensemble, ces blocs représentent environ **70 Ko** de configuration, soit une part disproportionnée du document général.
|
||||
|
||||
Les trois blocs ont la même structure et diffèrent principalement par :
|
||||
|
||||
- les noms de routes associés au profil ;
|
||||
- les chemins sous `logs/<profil>/...` ;
|
||||
- quelques valeurs de niveau ou de sélection liées au profil.
|
||||
|
||||
La séparation du logging est donc justifiée à la fois par la lisibilité, la maintenance et la réduction du couplage entre profil réseau et politique de tracing.
|
||||
|
||||
### 3.2 Contrat public actuel
|
||||
|
||||
`kb-config::ProfileConfig` contient directement :
|
||||
|
||||
```text
|
||||
app
|
||||
logging
|
||||
database
|
||||
data
|
||||
solana
|
||||
wallet
|
||||
execution
|
||||
demo
|
||||
```
|
||||
|
||||
`AppConfig`, `ProfileConfig` et toutes les sous-structures sont actuellement `Clone + Debug + Serialize + Deserialize + TS`.
|
||||
|
||||
Les fonctions publiques `serialize_config_json` et `serialize_config_json_pretty` peuvent sérialiser la configuration runtime complète. Après résolution d'environnement, cette configuration peut contenir des secrets en clair.
|
||||
|
||||
`DemoConfigPayload` clone aujourd'hui `AppConfig` et `ProfileConfig` complets et le frontend les affiche intégralement dans des JSON viewers avec copie activée. Cette surface doit disparaître dans `0.5.1` au profit d'un DTO public explicitement borné.
|
||||
|
||||
### 3.3 Consommateurs actuels
|
||||
|
||||
L'audit des onze crates confirme les principaux couplages suivants :
|
||||
|
||||
- `AppConfig` est consommé directement par le desktop et `kb-pipeline-demo-scenarios` ;
|
||||
- `ProfileConfig` traverse le desktop, `kb-onchain-transport`, `kb-pipeline-demo-scenarios` et certaines fixtures/tests de `kb-pipeline` ;
|
||||
- les types logging de `kb-config` ne sont convertis vers `kb-logging` que par le desktop aujourd'hui ; cette conversion constitue donc un adaptateur applicatif accidentel à supprimer ;
|
||||
- `kb-wallet` est consommé principalement par `kb-pipeline-demo-scenarios` et quelques adaptations desktop ; les scénarios utilisent directement `TemporaryWallet`, `TemporaryWalletStore`, `WalletAlias`, `WalletSummary`, `as_signer()` et `as_sync_signer()`.
|
||||
|
||||
Cette concentration permet de préparer des migrations bornées, mais `ProfileConfig` reste suffisamment diffus pour interdire un changement de shape sans phase de compatibilité/test.
|
||||
|
||||
### 3.4 Résolution d'environnement actuelle
|
||||
|
||||
`resolve_environment_placeholders` :
|
||||
|
||||
- accepte n'importe quel nom dans `${NAME}` ;
|
||||
- lit directement `std::env::var(name)` ;
|
||||
- retourne une `String` ordinaire ;
|
||||
- ne conserve ni origine, ni visibilité, ni indicateur de secret ;
|
||||
- peut donc transformer une URL ou un DSN contenant un secret en simple chaîne indistinguable d'une valeur publique.
|
||||
|
||||
Le futur resolver devra refuser les variables de projet hors namespace `KS_*` et conserver suffisamment de métadonnées pour empêcher la perte de sensibilité.
|
||||
|
||||
## 4. Inventaire des contrats d'environnement
|
||||
|
||||
L'audit du code, de `config/example.config.json`, de `.env.example` et des fichiers de fixture `.env` Token-2022 trouve **84 noms de variables/entrées de type environnement actuellement utilisés comme contrats actifs ou de fixture** :
|
||||
|
||||
- 67 commencent par `KB_` ;
|
||||
- 17 ne commencent ni par `KB_` ni par `KS_` ;
|
||||
- aucune n'utilise encore le namespace cible `KS_`.
|
||||
|
||||
Les variables non conformes comprennent notamment :
|
||||
|
||||
- `HELIUS_API_KEY` ;
|
||||
- les familles `TOKEN_2022_*` ;
|
||||
- des entrées de fixture ElGamal/validity proof.
|
||||
|
||||
Les guides opérateur contiennent en plus des variables shell historiques qui devront être réconciliées avec la même règle lors de la migration documentaire.
|
||||
|
||||
### 4.1 Secrets certains
|
||||
|
||||
Les contrats suivants doivent devenir explicitement secrets :
|
||||
|
||||
- `HELIUS_API_KEY` -> cible de famille `KS_SECRET_HELIUS_*` ;
|
||||
- `KB_POSTGRES_MAINNET_URL` -> cible `KS_SECRET_POSTGRES_MAINNET_URL` ;
|
||||
- `KB_POSTGRES_DEVNET_URL` -> cible `KS_SECRET_POSTGRES_DEVNET_URL` ;
|
||||
- `KB_POSTGRES_TEST_URL` -> cible `KS_SECRET_POSTGRES_TEST_URL`.
|
||||
|
||||
Une URL ou un DSN complet contenant l'un de ces secrets hérite de la classification `Secret` après résolution.
|
||||
|
||||
### 4.2 Variables internes
|
||||
|
||||
Les sélecteurs de profil, chemins, opt-ins de tests, confirmations opérateur, paramètres de campagnes et valeurs de fixture ne doivent pas être promus artificiellement en `KS_PUBLIC_*`. Par défaut, ils deviennent des `KS_*` internes.
|
||||
|
||||
`KS_PUBLIC_*` doit rester réservé aux valeurs dont une exposition publique est réellement requise et testée.
|
||||
|
||||
### 4.3 Migration
|
||||
|
||||
`0.5.1` devra fournir une table de migration exhaustive ancien nom -> nouveau nom avant changement du runtime et de `.env.example`.
|
||||
|
||||
La migration ne doit pas laisser le code lire durablement les anciens alias `KB_*`, `TOKEN_2022_*` ou `HELIUS_API_KEY`, car cela contredirait la règle du namespace unique. Si une compatibilité transitoire est nécessaire pendant une prerelease de migration, elle doit être explicitement bornée, détecter les conflits et être supprimée avant clôture de la version propriétaire.
|
||||
|
||||
## 5. Frontières source / runtime / public
|
||||
|
||||
Le futur contrat de `0.5.1` doit distinguer trois représentations conceptuelles.
|
||||
|
||||
### 5.1 Source
|
||||
|
||||
La représentation source conserve les documents utilisateur, les placeholders et les valeurs non résolues nécessaires à la validation/migration.
|
||||
|
||||
Elle ne doit pas être confondue avec un objet sûr à afficher.
|
||||
|
||||
### 5.2 Runtime
|
||||
|
||||
La représentation runtime contient les valeurs effectivement utilisables par les consommateurs backend.
|
||||
|
||||
Elle peut contenir des secrets résolus et ne doit donc pas dériver automatiquement une surface de sérialisation/TS-RS générale. Les champs sensibles connus doivent être encapsulés ou accompagnés d'une classification qui empêche `Debug`, sérialisation ou erreur accidentelle.
|
||||
|
||||
### 5.3 Public/diagnostic
|
||||
|
||||
Les DTO publics sont construits explicitement à partir du runtime :
|
||||
|
||||
- vue publique normale : uniquement les champs autorisés et valeurs `KS_PUBLIC_*` nécessaires ;
|
||||
- diagnostic explicite : peut ajouter des valeurs `KS_*` internes sélectionnées ;
|
||||
- secrets : jamais de valeur, uniquement un état non secret tel que `configured: true` lorsque cela apporte une valeur opérateur.
|
||||
|
||||
Le simple fait qu'une build Rust utilise `debug_assertions` ne doit pas élargir automatiquement la surface Tauri.
|
||||
|
||||
## 6. Propriété du contrat logging
|
||||
|
||||
### 6.1 Duplication actuelle
|
||||
|
||||
`kb-config` et `kb-logging` exposent chacun :
|
||||
|
||||
- `LoggingConfig` ;
|
||||
- `LogTargetConfig` ;
|
||||
- `LogTargetFilterConfig`.
|
||||
|
||||
Leurs champs sont pratiquement identiques. `kb-app-demo-desktop/src/app_state.rs` effectue une conversion champ par champ avant `kb_logging::init_logging`.
|
||||
|
||||
`kb-logging::LogFileRoute` n'a aucun consommateur actif hors de `kb-logging` et constitue un contrat legacy à réévaluer pendant la migration.
|
||||
|
||||
### 6.2 Direction de dépendance à préserver
|
||||
|
||||
`kb-config` ne doit pas dépendre du runtime logging simplement pour réutiliser ses types.
|
||||
|
||||
La solution de `0.5.1` devra choisir un propriétaire unique du contrat source logging et supprimer la conversion manuelle du desktop. Deux solutions restent architecturalement acceptables avant implémentation :
|
||||
|
||||
1. `kb-config` possède le DTO source logging séparé et `kb-logging` le consomme directement ou via un adaptateur propriétaire du runtime ;
|
||||
2. une frontière de configuration logging est déplacée dans une surface dédiée sans faire dépendre la configuration générale de l'initialisation `tracing`.
|
||||
|
||||
Le choix final doit minimiser la duplication sans réintroduire une crate artificielle si elle n'apporte pas de responsabilité autonome.
|
||||
|
||||
## 7. Audit `kb-wallet`
|
||||
|
||||
### 7.1 Points déjà solides
|
||||
|
||||
Le wallet actuel protège correctement plusieurs frontières :
|
||||
|
||||
- `TemporaryWallet` ne dérive ni `Serialize` ni `Clone` ;
|
||||
- son implémentation `Debug` n'affiche que l'alias, la clé publique et le chemin ;
|
||||
- les octets du keypair restent privés ;
|
||||
- les buffers temporaires de lecture/écriture sont zeroized ;
|
||||
- les fichiers existants ne sont pas écrasés ;
|
||||
- les liens symboliques et permissions trop ouvertes sont refusés ;
|
||||
- `as_signer()` et `as_sync_signer()` fournissent la capacité de signature sans exposer les octets.
|
||||
|
||||
### 7.2 Contrat persistant à migrer
|
||||
|
||||
Le format `0.4.8` est un contrat réel :
|
||||
|
||||
```text
|
||||
<alias>.json
|
||||
```
|
||||
|
||||
contient le tableau JSON standard du keypair Solana, sans enveloppe de version et sans chiffrement applicatif.
|
||||
|
||||
`0.5.2` devra donc traiter ce format comme **legacy importable**, et non le modifier in-place sans stratégie.
|
||||
|
||||
### 7.3 Exigences de migration `0.5.2`
|
||||
|
||||
Avant implémentation, le design devra préciser :
|
||||
|
||||
- format versionné du nouveau conteneur ;
|
||||
- détection sûre du format legacy ;
|
||||
- import sans perte de clé publique ;
|
||||
- écriture atomique du nouveau format avant suppression éventuelle de l'ancien ;
|
||||
- rollback après échec ;
|
||||
- corruption et mauvais secret de déverrouillage ;
|
||||
- séparation identité / secret / état verrouillé / capacité de signer ;
|
||||
- absence de secret dans config, logs, erreurs, Tauri et backup metadata ;
|
||||
- politique d'import/export et sauvegarde/restauration si ces capacités sont retenues.
|
||||
|
||||
Aucun mot de passe ou matériau de déchiffrement ne devra être stocké dans la configuration générale. Une automatisation non interactive éventuelle devra utiliser une source secrète dédiée, classée `KS_SECRET_*`.
|
||||
|
||||
## 8. Tests d'API externe manquants
|
||||
|
||||
Le workspace possède des tests d'API externe pour `kb-lib`, `kb-pipeline` et une partie de `kb-pipeline-demo-scenarios`, mais aucun dossier `tests/` équivalent pour `kb-config`, `kb-logging` ou `kb-wallet`.
|
||||
|
||||
Avant les refactors propriétaires, il faudra ajouter des tests de caractérisation externes couvrant au minimum :
|
||||
|
||||
### `kb-config`
|
||||
|
||||
- chargement du format `0.4.8` de référence ;
|
||||
- profil actif et invariants publics ;
|
||||
- contrat de schéma embarqué ;
|
||||
- migration vers les documents séparés ;
|
||||
- refus des variables de projet hors `KS_*` ;
|
||||
- canaris `KS_SECRET_*` absents de toute vue publique, erreur et diagnostic.
|
||||
|
||||
Ces tests ne doivent pas figer la sérialisation dangereuse actuelle d'une configuration résolue complète.
|
||||
|
||||
### `kb-logging`
|
||||
|
||||
- initialisation depuis le futur contrat source canonique ;
|
||||
- conservation des routes/niveaux/filtres/formats ;
|
||||
- migration sans dépendance au desktop.
|
||||
|
||||
### `kb-wallet`
|
||||
|
||||
- lecture d'une fixture legacy `0.4.8` ;
|
||||
- identité de clé publique après migration ;
|
||||
- corruption, permissions et atomicité ;
|
||||
- absence de secret dans `Debug` et surfaces publiques ;
|
||||
- tests de lock/unlock seulement après choix du format chiffré.
|
||||
|
||||
## 9. Audit du possible renommage `kb-*` -> `ks-*`
|
||||
|
||||
La demande de namespace `KS_` pour l'environnement ouvre légitimement la question du nom des crates généralistes. Cette question ne doit cependant pas être traitée par remplacement global.
|
||||
|
||||
### 9.1 Crates candidates
|
||||
|
||||
Les responsabilités actuelles rendent les crates suivantes plausiblement généralistes Solana et donc candidates à un préfixe `ks-*` si le renommage est retenu :
|
||||
|
||||
- `kb-core` ;
|
||||
- `kb-config` ;
|
||||
- `kb-lib` ;
|
||||
- `kb-logging` ;
|
||||
- `kb-program-ids` ;
|
||||
- `kb-pipeline` ;
|
||||
- `kb-onchain-transport` ;
|
||||
- `kb-store` ;
|
||||
- `kb-wallet`.
|
||||
|
||||
`kb-pipeline-demo-scenarios` doit être classée séparément : sa logique est réutilisable et non spécifique au frontend, mais son rôle de validation/scénarios peut justifier un nom différent de la simple substitution de préfixe.
|
||||
|
||||
`kb-app-demo-desktop` reste clairement une application Khadhroony Bot et n'est pas candidate au même renommage automatique.
|
||||
|
||||
### 9.2 Namespaces à ne pas confondre
|
||||
|
||||
Un éventuel renommage de packages Cargo touche plusieurs espaces de noms distincts :
|
||||
|
||||
1. nom de répertoire ;
|
||||
2. nom `[package]` Cargo ;
|
||||
3. identifiant Rust (`kb_config` -> éventuellement `ks_config`) ;
|
||||
4. chemins TS-RS/bindings ;
|
||||
5. targets `tracing` ;
|
||||
6. noms de binaires/CLI ;
|
||||
7. identités persistées de décodeurs, matérialiseurs et exécuteurs ;
|
||||
8. préfixes SQL et noms de tables.
|
||||
|
||||
Ces couches ne doivent pas être renommées en bloc.
|
||||
|
||||
En particulier :
|
||||
|
||||
- les tables `kb_sol_*` sont des contrats SQL publiés et ne doivent pas changer de nom du seul fait d'un renommage Cargo ;
|
||||
- les identités telles que `kb-lib.decoder.*`, `kb-lib.materializer.*` et `kb-lib.executor.*` peuvent être persistées dans le ledger, les événements ou les clés d'idempotence ; leur changement exige un audit de migration propre ;
|
||||
- les targets `tracing` peuvent être renommés séparément, mais cela impose une migration du document logging et de ses filtres.
|
||||
|
||||
### 9.3 Décision à prendre avant implémentation structurelle
|
||||
|
||||
Avant de lancer `0.5.1`, la clôture de `0.5.0` devra statuer sur l'une des stratégies suivantes :
|
||||
|
||||
- conserver `kb-*` comme namespace historique pour toutes les crates ;
|
||||
- renommer uniquement les packages/libs réellement généralistes en `ks-*`, en laissant les applications `kb-*` ;
|
||||
- planifier un chantier de renommage dédié dans le ROADMAP si l'impact est trop transversal pour être absorbé proprement par `0.5.1`.
|
||||
|
||||
Aucun renommage n'est livré par `pre.002`.
|
||||
|
||||
## 10. Dossier de migration préparé pour `0.5.1`
|
||||
|
||||
`0.5.1` devra au minimum :
|
||||
|
||||
1. introduire le namespace `KS_*` et la classification Secret/Public/Internal ;
|
||||
2. fournir la table exhaustive de renommage des variables actuelles ;
|
||||
3. remplacer le resolver non typé par une résolution conservant la sensibilité ;
|
||||
4. séparer la configuration générale et la configuration logging en deux documents et deux schémas ;
|
||||
5. supprimer `logging` de chaque `ProfileConfig` généraliste ;
|
||||
6. rendre la sélection du profil logging indépendante du profil général ;
|
||||
7. supprimer la duplication de types logging ou la conversion manuelle desktop ;
|
||||
8. séparer source, runtime et DTO publics/diagnostics ;
|
||||
9. retirer `AppConfig`/`ProfileConfig` complets des payloads Tauri ;
|
||||
10. ajouter les tests de migration `0.4.8` -> nouveau format et les canaris de non-divulgation.
|
||||
|
||||
Le détail des noms de fichiers et types Rust sera fixé dans la première prerelease d'implémentation de `0.5.1`, après décision sur le namespace de crates.
|
||||
|
||||
## 11. Dossier de migration préparé pour `0.5.2`
|
||||
|
||||
`0.5.2` devra :
|
||||
|
||||
1. caractériser le format legacy `0.4.8` par fixture externe ;
|
||||
2. définir un conteneur wallet versionné avant chiffrement ;
|
||||
3. séparer identité, secret, état de verrouillage et capacité de signer ;
|
||||
4. définir migration/rollback atomiques ;
|
||||
5. conserver les capacités `Signer` nécessaires aux exécuteurs sans exposer le secret ;
|
||||
6. interdire toute propagation de secret vers config/logging/Tauri ;
|
||||
7. ajouter import/export, backup/restore et multi-wallet uniquement avec contrats de sécurité et tests correspondants.
|
||||
|
||||
## 12. Critère de sortie de `pre.002`
|
||||
|
||||
La prerelease peut être considérée comme cadrée lorsque :
|
||||
|
||||
- le split logging document + schéma séparés est accepté comme cible ;
|
||||
- la convention `KS_SECRET_*` / `KS_PUBLIC_*` / `KS_*` est normative pour la migration ;
|
||||
- la propagation de sensibilité des valeurs composées est requise ;
|
||||
- les surfaces source/runtime/public sont distinctes ;
|
||||
- le format wallet legacy et sa stratégie de migration sont explicitement bornés ;
|
||||
- les tests externes manquants sont identifiés ;
|
||||
- le possible renommage `kb-*` -> `ks-*` est isolé comme décision transversale, sans toucher les identités persistées ou SQL par accident.
|
||||
|
||||
La prochaine prerelease prévue reste `0.5.0-pre.003`, consacrée à `kb-store`, aux scénarios et au desktop.
|
||||
@@ -1,367 +0,0 @@
|
||||
<!-- file: docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Audit `0.5.0-pre.003` — store, scénarios, desktop et complétude d'exécution
|
||||
|
||||
## 1. Objet et frontière
|
||||
|
||||
`0.5.0-pre.003` reste une prerelease de cadrage. Elle n'introduit ni nouvelle migration SQL, ni table trading, ni nouvel exécuteur, ni déplacement de logique runtime.
|
||||
|
||||
Elle ferme quatre sujets nécessaires avant les versions d'implémentation :
|
||||
|
||||
- état réel de `kb-store` et contraintes de migration vers `0.5.3` ;
|
||||
- frontière entre scénarios réutilisables et adaptation desktop en préparation de `0.5.4` ;
|
||||
- état de complétude réel des décodeurs/exécuteurs déjà actifs ;
|
||||
- positionnement du futur namespace `ks-*` dans la fondation `0.5.x`.
|
||||
|
||||
Les migrations `kb-store/migrations/0001` à `0004` restent immuables. Les preuves réseau `0.4.8` ne sont pas rejouées puisque cette prerelease ne modifie aucune frontière qu'elles couvrent.
|
||||
|
||||
## 2. Positionnement de la fondation `ks-*`
|
||||
|
||||
L'orientation de projet est désormais la suivante :
|
||||
|
||||
- **Khadhroony Project** est destiné à devenir l'umbrella de plusieurs projets liés au trading et aux crypto-actifs ;
|
||||
- **Khadhroony Solana** regroupe les bibliothèques généralistes dédiées à Solana ;
|
||||
- ces bibliothèques doivent converger vers les namespaces Cargo `ks-*`, Rust `ks_*` et environnement `KS_*` ;
|
||||
- **Khadhroony Bot / bot3** devient l'application de trading consommatrice de ces bibliothèques, avec à terme une partie d'analyse/création de stratégies et un exécutable de trading automatique ;
|
||||
- `kb-app-demo-desktop` reste pour l'instant un banc opérateur de démonstration et de validation des composants généralistes ; il ne préjuge pas de l'architecture applicative finale du bot après `1.0`.
|
||||
|
||||
Cette orientation générale est aussi conservée dans `docs/IDEA_REMINDERS.md`. Le renommage concret des bibliothèques généralistes est préparé pour `0.5.1`, mais les identités persistées et SQL sont traitées séparément.
|
||||
|
||||
### 2.1 Candidats au namespace `ks-*`
|
||||
|
||||
Les crates suivantes sont des bibliothèques ou composants de support Solana généralistes et sont donc candidates au renommage direct en `0.5.1` :
|
||||
|
||||
| Actuel | Cible de travail |
|
||||
|------------------------------|------------------------------------------------------------------------------------------|
|
||||
| `kb-core` | `ks-core` |
|
||||
| `kb-config` | `ks-config` |
|
||||
| `kb-lib` | `ks-lib` |
|
||||
| `kb-logging` | `ks-logging` |
|
||||
| `kb-program-ids` | `ks-program-ids` |
|
||||
| `kb-pipeline` | `ks-pipeline` |
|
||||
| `kb-onchain-transport` | `ks-onchain-transport` |
|
||||
| `kb-store` | `ks-store` |
|
||||
| `kb-wallet` | `ks-wallet` |
|
||||
| `kb-pipeline-demo-scenarios` | `ks-pipeline-demo-scenarios` à confirmer comme composant de validation Khadhroony Solana |
|
||||
|
||||
`kb-app-demo-desktop` reste hors de cette substitution automatique : c'est une application Khadhroony Bot, même si son rôle courant est surtout de tester les composants `ks-*`.
|
||||
|
||||
### 2.2 Ce qui ne doit pas suivre mécaniquement le renommage
|
||||
|
||||
Le changement de nom d'une crate ne justifie pas à lui seul de modifier :
|
||||
|
||||
- les tables SQL `kb_sol_*` déjà publiées ;
|
||||
- les clés d'idempotence existantes ;
|
||||
- les identités de processeurs persistées ;
|
||||
- les noms historiques `kb-lib.decoder.*`, `kb-lib.materializer.*` et `kb-lib.executor.*` lorsqu'ils sont enregistrés dans le store ;
|
||||
- les données déjà persistées dans le processing ledger ;
|
||||
- les identités de validation historiques présentes dans les preuves `0.4.x`.
|
||||
|
||||
Les targets de tracing peuvent être renommés avec les crates, mais uniquement avec une migration synchronisée du futur document logging et de ses filtres.
|
||||
|
||||
## 3. Audit actuel de `kb-store`
|
||||
|
||||
### 3.1 Structure et contrats publiés
|
||||
|
||||
`kb-store` possède déjà une séparation interne exploitable :
|
||||
|
||||
- `contracts/dto/*` pour les entrées et filtres ;
|
||||
- `contracts/entity/*` pour les lignes persistées ;
|
||||
- `contracts/repository.rs` pour les frontières async ;
|
||||
- `postgres/query/*` pour le SQL ;
|
||||
- `postgres/repository/*` pour les implémentations ;
|
||||
- `postgres/migrations.rs` et quatre migrations SQL publiées.
|
||||
|
||||
Le schéma actif contient **13 tables** :
|
||||
|
||||
- 2 raw/observation ;
|
||||
- 6 Core ;
|
||||
- 1 processing ledger ;
|
||||
- 3 tables decode/coverage ;
|
||||
- 1 table de matérialisation générique.
|
||||
|
||||
La crate expose neuf familles principales de repository : health, raw, Core transaction, Core extraction, decode pipeline, observation de programme, événements décodés, événements matérialisés et processing ledger.
|
||||
|
||||
La structure n'est donc pas à remplacer. `0.5.3` doit normaliser ce qui gêne les futures requêtes et réduire les gros modules internes lorsque cela améliore la lisibilité, tout en conservant les façades publiques tant qu'une rupture n'est pas justifiée.
|
||||
|
||||
### 3.2 Propriétés déjà solides
|
||||
|
||||
Plusieurs contrats doivent être conservés :
|
||||
|
||||
- signature comme identité canonique de transaction raw ;
|
||||
- slot explicitement séparé des timestamps ;
|
||||
- observation d'acquisition distincte de la transaction canonique ;
|
||||
- provenance d'acquisition détaillée (`provider`, protocole, méthode, origin, session, filtre) ;
|
||||
- timestamps locaux d'acquisition distincts (`detected_at`, `received_at`, `normalized_at`, `persisted_at`) ;
|
||||
- identités de processeur et versions explicites ;
|
||||
- `input_key`, `input_hash`, `event_key` et `output_key` pour l'idempotence ;
|
||||
- transactions atomiques decode/materialization ;
|
||||
- index uniques empêchant le double effet d'un même processeur/version/input/output ;
|
||||
- conversion bornée `u64` vers `BIGINT` avec refus des valeurs non représentables ;
|
||||
- JSON canonique raw conservant actuellement le `block_time` même lorsque celui-ci n'est pas une colonne SQL de premier rang.
|
||||
|
||||
### 3.3 Lacune temporelle réelle
|
||||
|
||||
Le modèle canonique `MdCanonicalTransaction` contient :
|
||||
|
||||
```text
|
||||
slot
|
||||
block_time: Option<i64>
|
||||
```
|
||||
|
||||
et le transport HTTP conserve cette valeur depuis `getTransaction`.
|
||||
|
||||
En revanche :
|
||||
|
||||
- `kb_sol_raw_transactions` possède `slot`, `created_at`, `updated_at`, mais pas `block_time` ;
|
||||
- `kb_sol_core_transactions` et les tables Core portent `slot` et des timestamps de persistance, mais pas le temps on-chain ;
|
||||
- `kb_sol_decode_events` et `kb_sol_mat_events` portent `slot`, mais pas `block_time` ;
|
||||
- les observations d'acquisition ont des timestamps locaux riches, ce qui ne remplace pas le temps on-chain.
|
||||
|
||||
Le contrat `0.5.3` doit donc imposer la distinction suivante :
|
||||
|
||||
| Dimension | Sens |
|
||||
|-------------------------------------------------|----------------------------------------------------------|
|
||||
| `slot` | ordre/position Solana ; jamais assimilé à un temps civil |
|
||||
| `block_time` | temps on-chain Unix optionnel observé depuis le cluster |
|
||||
| `detected_at` / `received_at` / `normalized_at` | temps locaux d'acquisition |
|
||||
| `persisted_at` | instant d'écriture de l'observation |
|
||||
| `created_at` / `updated_at` | cycle de vie de la ligne SQL |
|
||||
|
||||
Une requête de prix ou série temporelle ne doit jamais prendre `created_at` comme substitut implicite de `block_time`.
|
||||
|
||||
### 3.4 Limites de la matérialisation générique pour le futur trading
|
||||
|
||||
`kb_sol_mat_events` est aujourd'hui volontairement générique. Il contient notamment :
|
||||
|
||||
- identité/version du matérialiseur ;
|
||||
- identité de l'input et de l'output ;
|
||||
- provenance vers l'événement décodé ;
|
||||
- signature et slot ;
|
||||
- `materialized_family` ;
|
||||
- `payload_jsonb`.
|
||||
|
||||
Ce contrat est adapté au replay et à l'audit, mais il ne suffit pas encore à des requêtes trading efficaces. Il manque en colonnes de premier rang plusieurs dimensions qui pourront être nécessaires selon le contrat de faits retenu :
|
||||
|
||||
- temps on-chain ;
|
||||
- programme/surface/event d'origine ;
|
||||
- identités d'entités métier stables ;
|
||||
- actifs concernés ;
|
||||
- pool/market/route lorsqu'ils existent ;
|
||||
- dimensions permettant des index temporels multi-entités.
|
||||
|
||||
Il ne faut pas résoudre ce manque par une accumulation d'index JSONB spécifiques à Meteora/Raydium/Pump/Orca/Jupiter. `0.5.3` doit d'abord définir **l'enveloppe stable des faits produits par les matérialisateurs**.
|
||||
|
||||
### 3.5 Faits stables à spécifier avant toute table trading
|
||||
|
||||
La spécification `0.5.3` doit déterminer comment représenter, indépendamment du protocole :
|
||||
|
||||
- création et identité d'un pool/marché ;
|
||||
- paire ou ensemble d'actifs ;
|
||||
- comptes de réserve et état de réserves observé ;
|
||||
- ajout/retrait/variation de liquidité ;
|
||||
- swap avec actifs entrée/sortie et montants bruts ;
|
||||
- prix observé avec unité et base de calcul explicites ;
|
||||
- snapshot d'état et événement de mutation ;
|
||||
- relation d'un fait à plusieurs pools ou à une route ;
|
||||
- provenance complète jusqu'à signature, slot, `block_time`, instruction et processeur ;
|
||||
- clé d'idempotence stable par projection.
|
||||
|
||||
Les tables spécialisées ne seront choisies qu'après ce contrat. Le but est d'autoriser des matérialisateurs futurs pour plusieurs DEX sans figer leur wire ou leur architecture dans `ks-store`.
|
||||
|
||||
### 3.6 Migrations et tests à préparer pour `0.5.3`
|
||||
|
||||
Les migrations `0001` à `0004` sont publiées et ne doivent jamais être réécrites.
|
||||
|
||||
Avant toute migration `0005+`, il faut :
|
||||
|
||||
1. un test d'API externe de `kb-store` caractérisant les principaux DTO/repositories actuels ;
|
||||
2. une fixture de schéma `0.4.8` permettant de tester la migration réelle ;
|
||||
3. une politique de backfill de `block_time` explicitant que la valeur peut rester inconnue ;
|
||||
4. des tests d'idempotence sur une migration réexécutée ;
|
||||
5. des tests de données existantes et de rollback/échec ;
|
||||
6. une justification de chaque nouvel index par une requête cible ;
|
||||
7. un test prouvant que `created_at` et `block_time` ne sont pas interchangeables ;
|
||||
8. une décision sur le maintien de `kb_sol_mat_events` comme journal générique parallèlement aux futures projections normalisées.
|
||||
|
||||
Aucune modification SQL n'est livrée dans `pre.003`.
|
||||
|
||||
## 4. Audit scénarios / desktop
|
||||
|
||||
### 4.1 Frontière normative corrigée
|
||||
|
||||
Une ancienne règle disait que les scénarios UI Devnet/Testnet devaient rester dans le desktop. Cette formulation est devenue trop large et contredit la trajectoire `0.5.4`.
|
||||
|
||||
La frontière retenue est désormais :
|
||||
|
||||
- orchestration générique : `kb-pipeline` ;
|
||||
- fixture, séquence, simulation/soumission, postconditions et qualification réutilisables de Devnet/Testnet : `kb-pipeline-demo-scenarios` ;
|
||||
- état Tauri, sélection opérateur, progression UI, TS-RS et présentation : `kb-app-demo-desktop`.
|
||||
|
||||
Un preset purement visuel ou une séquence réellement spécifique à une interaction UI peut rester dans le desktop, mais une campagne réutilisable ne doit pas y avoir une seconde implémentation.
|
||||
|
||||
### 4.2 État réel de la couverture des exécuteurs actifs
|
||||
|
||||
L'inventaire statique de `kb-lib` trouve :
|
||||
|
||||
- **8 exécuteurs fonctionnels non réservés** ;
|
||||
- **103 exécuteurs réservés** servant de placeholders de surfaces futures ;
|
||||
- les placeholders ne sont pas des exécuteurs manquants à compléter en `0.5.0`.
|
||||
|
||||
Les huit exécuteurs actifs sont :
|
||||
|
||||
| Exécuteur actif | Scénario réutilisable actuel | Qualification |
|
||||
|------------------------------|------------------------------|-----------------------------------------------------------------|
|
||||
| Solana Core | oui | plusieurs parcours Devnet ; matrice native existante |
|
||||
| SPL Memo v4 | oui | Devnet ; v1/v3 restent decode-only |
|
||||
| SPL Associated Token Account | oui | scénario Devnet |
|
||||
| SPL Token classique | oui | scénarios et lifecycle Devnet |
|
||||
| SPL Token-2022 | oui | scénarios Devnet et campagne Token Metadata |
|
||||
| SPL ElGamal registry | non | implémenté + synthétique seulement ; preuve réseau indisponible |
|
||||
| Metaplex Token Metadata | oui | matrice `15 confirmed / 5 unavailable` |
|
||||
| Solana Program Metadata | oui | 9 opérations confirmées Devnet |
|
||||
|
||||
Le seul exécuteur actif sans scénario réseau réutilisable est donc ElGamal, et son absence est **`unavailable`/report conditionnel**, pas `implement`, tant qu'une nouvelle possibilité de preuve n'existe pas.
|
||||
|
||||
Deux autres exclusions importantes restent intentionnelles :
|
||||
|
||||
- Memo v1 et v3 : `decode-only` ;
|
||||
- Token-2022 `Batch` : `decode-only` tant que l'interface officielle ne publie pas de builder correspondant.
|
||||
|
||||
Les 103 exécuteurs réservés appartiennent aux surfaces futures du ROADMAP. Ils doivent être classés `deferred`, sauf audit futur démontrant qu'une surface est obsolète, non applicable ou doit changer de statut.
|
||||
|
||||
### 4.3 Le desktop n'instancie plus directement les exécuteurs actifs
|
||||
|
||||
Aucune des huit structures d'exécuteur actives n'est directement instanciée dans `kb-app-demo-desktop/src`.
|
||||
|
||||
C'est une bonne frontière : le desktop appelle déjà `kb-pipeline-demo-scenarios` pour l'exécution réseau. `0.5.4` ne doit donc pas entreprendre une réécriture totale du desktop ; il doit cibler les morceaux d'orchestration qui restent autour de ces runners.
|
||||
|
||||
### 4.4 Orchestration encore résiduelle dans le desktop
|
||||
|
||||
Les principaux candidats identifiés sont :
|
||||
|
||||
#### Metaplex Token Metadata
|
||||
|
||||
`demo_execution_metadata_metaplex_token_metadata.rs` reste très volumineux et contient encore :
|
||||
|
||||
- inventaire/presets de campagnes qualifiées ;
|
||||
- préparation conditionnelle de fixtures ;
|
||||
- dispatch d'une campagne vers plusieurs runners réutilisables ;
|
||||
- calcul de critères `completed` ;
|
||||
- classification de probes confirmées/unavailable ;
|
||||
- construction de projections intermédiaires avant mapping UI.
|
||||
|
||||
La sérialisation TS-RS et la présentation JSON doivent rester desktop. Le dispatch, les critères de complétion et la projection de preuve commune sont candidats à `kb-pipeline-demo-scenarios` en `0.5.4`.
|
||||
|
||||
#### Solana Core, Memo, ATA, Token classique et Token-2022
|
||||
|
||||
Les runners réutilisables acceptent encore, selon les cas, des slices de décodeurs et matérialisateurs fournis par l'appelant. Le desktop assemble donc lui-même une partie de la pile de validation attendue.
|
||||
|
||||
`0.5.4` devra déterminer si la crate scénario doit fournir des bundles qualifiés par défaut, par exemple une composition canonique de décodeurs/matérialisateurs pour un scénario donné, afin que le desktop n'ait pas à connaître cette composition.
|
||||
|
||||
Le desktop peut continuer à :
|
||||
|
||||
- choisir un profil ;
|
||||
- demander l'autorisation opérateur ;
|
||||
- ouvrir la connexion/store via l'état applicatif lorsqu'il s'agit d'une responsabilité d'application ;
|
||||
- fournir un observer de progression/annulation ;
|
||||
- mapper le résultat vers un DTO TS-RS.
|
||||
|
||||
Il ne doit pas être le propriétaire de la liste métier exacte de décodeurs/matérialisateurs requise pour qualifier une campagne réutilisable.
|
||||
|
||||
#### Token-2022 Metadata et Solana Program Metadata
|
||||
|
||||
Ces panneaux sont déjà proches de la cible : ils appellent une campagne réutilisable et transforment principalement son résultat pour le frontend. Ils servent de référence pour la réduction des autres panneaux.
|
||||
|
||||
#### Journaux SQL et diagnostics
|
||||
|
||||
Les requêtes de journal et les filtres destinés à l'affichage ne sont pas automatiquement des « scénarios ». Ils peuvent rester dans le desktop tant qu'ils ne dupliquent pas une règle métier ou une requête générique qui devrait appartenir à `kb-store`.
|
||||
|
||||
## 5. Méthode de complétude à appliquer en `0.5.4`
|
||||
|
||||
La future matrice transversale doit comparer uniquement les **surfaces actives ou explicitement ouvertes par le ROADMAP**. La présence d'un fichier réservé ne suffit pas à créer une dette.
|
||||
|
||||
Pour chaque capacité, enregistrer :
|
||||
|
||||
| Dimension | Valeur attendue |
|
||||
|-------------------|---------------------------------------------------------------------------------------|
|
||||
| decoder | actif / réservé / absent |
|
||||
| materializer | actif / state-only / réservé / non applicable |
|
||||
| executor | actif / decode-only / deprecated / réservé / absent |
|
||||
| synthetic | présent / absent / non applicable |
|
||||
| reusable scenario | présent / absent / unavailable / non applicable |
|
||||
| simulation | prouvée / non exécutée / unavailable |
|
||||
| submission | confirmed / non exécutée / unsafe / unavailable |
|
||||
| postcondition | stateful / replay/materialization / non applicable |
|
||||
| desktop | adaptateur / logique réutilisable résiduelle / absent |
|
||||
| final status | `implement`, `decode-only`, `deprecated`, `unavailable`, `not-applicable`, `deferred` |
|
||||
|
||||
### Classification actuelle de départ
|
||||
|
||||
- huit exécuteurs actifs : aucun « exécuteur manquant » de niveau surface ;
|
||||
- Memo v1/v3 : `decode-only` ;
|
||||
- Token-2022 Batch : `decode-only` ;
|
||||
- ElGamal réseau : `unavailable` tant qu'aucune nouvelle preuve n'est possible ;
|
||||
- 103 exécuteurs réservés : `deferred` par défaut selon les versions `0.6.x+` ;
|
||||
- scénarios desktop avec orchestration résiduelle : `implement` en `0.5.4` uniquement pour le déplacement de logique réutilisable, pas pour rejouer des campagnes déjà qualifiées.
|
||||
|
||||
## 6. Validations réseau à ne pas rejouer automatiquement
|
||||
|
||||
Cette prerelease ne modifie aucune frontière d'exécution. Il n'y a donc pas de raison de rejouer :
|
||||
|
||||
- les 9 opérations Solana Program Metadata ;
|
||||
- les 5 opérations Token-2022 Token Metadata ;
|
||||
- les 15 opérations Metaplex confirmées ;
|
||||
- les probes Metaplex déjà classées `unavailable` ;
|
||||
- les validations SPL/Core qui ne changent pas de contrat.
|
||||
|
||||
En `0.5.4`, un rerun réseau ne devient nécessaire que si le déplacement d'un scénario change réellement :
|
||||
|
||||
- la construction d'intent ;
|
||||
- l'ordre des instructions ;
|
||||
- les signers/comptes ;
|
||||
- les paramètres de simulation/soumission ;
|
||||
- les postconditions ;
|
||||
- la composition decoder/materializer utilisée pour la preuve.
|
||||
|
||||
Un simple déplacement de mapping TS-RS ou de dispatch sans changement sémantique doit être couvert par tests synthétiques/contractuels et comparaison de sortie, pas par dépense réseau systématique.
|
||||
|
||||
## 7. Dossiers préparés pour les versions suivantes
|
||||
|
||||
### `0.5.1`
|
||||
|
||||
- migration `KB_*`/variables historiques vers `KS_*` ;
|
||||
- split configuration générale / logging ;
|
||||
- protection Secret/Public/Internal ;
|
||||
- renommage coordonné des crates généralistes `kb-*` vers `ks-*` ;
|
||||
- adaptation des imports Rust, manifests, bindings, targets de tracing et documentation ;
|
||||
- maintien ou migration séparée des identités persistées et tables SQL.
|
||||
|
||||
### `0.5.3`
|
||||
|
||||
- contrat temporel incluant `block_time` ;
|
||||
- enveloppe de provenance des faits ;
|
||||
- définition des projections trading génériques ;
|
||||
- nouvelle migration seulement après caractérisation `0.4.8` ;
|
||||
- index justifiés par les requêtes cibles multi-pools/multi-routes.
|
||||
|
||||
### `0.5.4`
|
||||
|
||||
- centralisation de l'orchestration réutilisable restante ;
|
||||
- composition qualifiée decoder/materializer par scénario lorsque justifiée ;
|
||||
- matrice de complétude active/réservée ;
|
||||
- conservation du desktop comme adaptateur opérateur.
|
||||
|
||||
## 8. Critère de sortie de `pre.003`
|
||||
|
||||
`pre.003` peut être considérée comme cadrée lorsque :
|
||||
|
||||
- le modèle temporel du store distingue sans ambiguïté temps on-chain et temps de persistance ;
|
||||
- aucune table DEX n'est inventée avant le contrat de faits ;
|
||||
- les migrations `0001` à `0004` restent explicitement immuables ;
|
||||
- la frontière scénario réutilisable / desktop est corrigée dans les règles actives ;
|
||||
- les huit exécuteurs réellement actifs et leurs niveaux de scénario/preuve sont caractérisés ;
|
||||
- ElGamal reste une exception conditionnelle et non une tâche implicite ;
|
||||
- le renommage des bibliothèques généralistes vers `ks-*` est retenu comme partie de `0.5.1`, avec exclusion des migrations SQL/identités persistées automatiques ;
|
||||
- `0.5.0-pre.004` peut se concentrer sur réconciliation, décisions finales, validations et préparation du prompt `0.5.1`.
|
||||
Reference in New Issue
Block a user