Files
khadhroony-bot3/ROADMAP.md

300 lines
23 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- file: ROADMAP.md -->
<!-- version: 44 -->
# ROADMAP — khadhroony-bot3
Le roadmap décrit les objectifs fonctionnels par version mineure. Il ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé des travaux terminés.
## 0.4.6 — alignement fonctionnel et clôture de la migration principale
Version clôturée : architecture en onze crates, alignement bot2 `0.4.6`, validations workspace et scénarios applicatifs. Le registre ElGamal reste implémenté et validé synthétiquement sans preuve réseau réelle.
## 0.4.7 — Metaplex Token Metadata
Version clôturée : surface Metaplex Token Metadata indépendante, bornée et intégrée aux couches de décodage, matérialisation, exécution, pipeline et démonstration.
### Périmètre réalisé
- décodeur dinstructions et de comptes, PDA, owners et variantes historiques ;
- matérialisation metadata, administration, lifecycle et risques applicables ;
- intents typés, builders, exécuteur, préflights, simulation exacte et postconditions ;
- intégration généraliste dans `ks-pipeline` ;
- scénarios synthétiques NFT, SFT, fungible, collection et pNFT ;
- runner Devnet réutilisable et panneau `kb-app-demo-desktop` ;
- fixtures Rust natives sans dépendance à une CLI externe ;
- validation réelle de parcours représentatifs sur Devnet.
Les validations complémentaires de la surface courante ont ensuite été fermées pendant `0.4.8` : la matrice Devnet des 20 opérations courantes contient 15 opérations `confirmed`, 5 `unavailable` et 0 `not_run`. Les matrices historiques de `0.4.7` restent figées à leur milestone.
### Hors périmètre
- metadata incorporées Token-2022 et SPL Token Metadata ;
- Metaplex Core, Bubblegum et autres programmes Metaplex ;
- fetch HTTP/IPFS/Arweave des URI off-chain.
## 0.4.8 — Solana Program Metadata et complétude Token-2022
Version clôturée et validée.
### Périmètre réalisé
- implémentation de la surface indépendante Solana Program Metadata `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S` : IDL, comptes, neuf instructions stables, PDA, modèles, décodeur, matérialiseur, exécuteur, pipeline, scénarios et desktop ;
- complétude des cinq opérations Token-2022 Token Metadata de `spl-token-metadata-interface``Initialize`, `UpdateField`, `Emit`, `RemoveKey`, `UpdateAuthority` — dans les modules Token-2022 existants, sans créer de Program ID autonome artificiel ;
- réaudit fonctionnel Metaplex Token Metadata des 20 opérations courantes et fermeture des campagnes spécialisées ;
- panneau desktop Metadata séparant explicitement Metaplex Token Metadata, Token-2022 Token Metadata et Solana Program Metadata ;
- réconciliation transversale du stockage, des matrices, registres runtime, exports publics, IDL, TODO et guides ;
- conservation du store générique de décodage/matérialisation : aucune migration PostgreSQL spécialisée Metadata nest nécessaire.
### Qualification réseau
- Solana Program Metadata : 9 opérations `confirmed` sur Devnet ;
- Token-2022 Token Metadata : 5 opérations `confirmed` sur Devnet ;
- Metaplex Token Metadata : 15 opérations `confirmed`, 5 `unavailable`, 0 `not_run` sur les 20 opérations courantes ;
- desktop Metadata : campagnes des trois domaines validées, avec résultats structurés et journal pleine largeur.
### Décision off-chain
- aucun fetch HTTP, IPFS ou Arweave nest intégré aux décodeurs canoniques ;
- les URI restent des données on-chain observées ;
- `ks-offchain-transport` est reportée à `0.16.x+`, lorsque les workers et consommateurs réels permettront de définir précisément cache, provenance, hash, redirections, MIME, taille, timeout et protection SSRF.
## 0.5.x — consolidation des fondations avant lextension fonctionnelle
La série `0.5.x` corrige et stabilise les fondations transversales avant l'ouverture des grands programmes Anchor/DEX. Elle formalise aussi la séparation entre le domaine applicatif `khadhroony-bot` et les bibliothèques généralistes `khadhroony-solana`.
La politique de namespace et d'ownership adoptée pendant `0.5.0` est documentée dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md).
### 0.5.0 — cadrage et plan de restructuration
Cadrage clôturé avant toute restructuration majeure :
- audit des responsabilités et couplages de `ks-config`, `ks-logging`, `ks-wallet`, `ks-store`, `ks-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
- inventaire des contrats publics, formats persistés, migrations, dépendances, scénarios et preuves de validation ;
- confirmation du split futur entre configuration généraliste et configuration logging ;
- définition de la politique de secrets et des namespaces d'environnement `KS_*` pour Khadhroony Solana et `KB_*` pour les futurs contrats réellement spécifiques au Bot ;
- décision de migrer les dix bibliothèques Solana généralistes vers `ks-*` / `ks_*` ;
- décision de migrer les identités techniques généralistes `kb-lib.decoder.*`, `kb-lib.materializer.*` et `kb-lib.executor.*` vers `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ;
- confirmation que `kb-app-demo-desktop` reste côté Bot et peut héberger à terme des démos Solana généralistes et des démos spécifiques au bot ;
- préparation de la normalisation future du store, notamment `block_time`, provenance, idempotence et migration des tables Solana `kb_sol_*` vers `k_sol_*` ;
- maintien de l'exception ElGamal dans son statut synthétique actuel tant qu'aucune nouvelle preuve réseau n'est disponible.
`0.5.0` n'introduit pas de nouvelle surface protocolaire ni de restructuration runtime importante.
### 0.5.1 — `ks-*`, `KS_*` et configuration sûre
Version clôturée : les frontières de namespace et de configuration prévues par le cadrage `0.5.0` sont désormais actives.
- les dix crates Solana généralistes sont nommées `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` reste dans le domaine Bot ;
- les identités techniques généralistes utilisent `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ;
- les variables possédées par Khadhroony Solana utilisent `KS_*`, avec `KS_SECRET_*`, `KS_PUBLIC_*` et valeurs internes, tandis que `KB_*` est réservé aux contrats réellement applicatifs ;
- les configurations partagées sont séparées en logging, transport, listeners, store, wallet et execution, avec schémas sous `config/schemas/`, exemples sous `config/exemples/` et defaults autonomes ;
- les binaires peuvent composer ces documents via `<binary>.default.config.json` sans que `ks-config` connaisse leur structure applicative ;
- les contrats runtime sensibles restent backend-only et les DTO Tauri sont construits explicitement, sans URL résolue, DSN, chemin wallet/SQLite ou autre secret ;
- TS-RS appartient aux applications consommatrices et nest plus généré par `ks-config` ou `ks-lib`.
Les préfixes SQL historiques `kb_sol_*` restent volontairement inchangés jusquà `0.5.3`, qui traitera leur migration avec les contrats temporels, de provenance, didempotence et dindex.
### 0.5.2 — `ks-wallet`
Version clôturée fonctionnellement : la frontière wallet Solana générale est désormais séparée entre identité publique, secret persistant, mot de passe et capacité de signature.
- plusieurs `.kswallet` persistants sont découverts et sélectionnés par alias dans `wallets/`, tandis que les fixtures/keypairs temporaires restent sous `wallets/temporary/**` ;
- le format natif v1 est binaire, versionné, protégé par Argon2id v19 + XChaCha20-Poly1305 et publié atomiquement/no-clobber avec permissions privées ;
- `WalletPassword` et `UnlockedWallet` bornent respectivement l'acquisition du mot de passe et la capacité de signature, tandis que `ks-lib` continue de dépendre uniquement d'une capacité `Signer` ;
- le changement de mot de passe conserve exactement la même keypair/pubkey et son cycle A → B → rejet de A → B → A est validé par `ks-wallet-demo-scenarios` ;
- le legacy Solana CLI JSON peut être inspecté ou migré sans destruction vers `.kswallet` ;
- `SolanaCliJson` et `SolanaPrivateKeyBase58` disposent d'import/export testés, tout export secret exigeant un mot de passe valide ;
- les exports opérateur issus du desktop sont confinés sous `data/wallets/` ;
- `ks-config` ne transporte qu'un `wallet_alias` optionnel et aucun secret ;
- `kb-app-demo-desktop` peut sélectionner en session un `.kswallet` par profil Devnet, prioritaire sur l'alias configuré, et les logs runtime ont confirmé `persistence="persistent"` avec le signer choisi ;
- les chemins locaux inutiles sont retirés des logs/erreurs/`Debug` du store legacy et les collisions concurrentes de création native sont couvertes ;
- les détails normatifs restent dans `docs/NATIVE_FORMAT.md`, `docs/WALLET_FORMAT_COMPATIBILITY.md`, `docs/guides/WALLETS.md` et `docs/validation/V0_5_2_WALLET_VALIDATION_REPORT.md`.
### 0.5.3 — audit, gel de schéma et abstraction de `ks-store`
- conserver `ks-store` comme frontière de persistance **généraliste Solana** pour les faits matérialisés par `ks-lib`; le trading est la priorité court terme, pas le périmètre exclusif du stockage ;
- migrer les tables Solana du préfixe historique `kb_sol_*` vers `k_sol_*` et réserver `kb_*` au domaine réellement Bot ;
- auditer DTO, models, repositories, migrations, index, requêtes, idempotence et provenance ;
- vérifier table par table que le contrat structurel est complet **avant gel** : colonnes, types, nullabilité, clés, contraintes, provenance, replay et temporalités ;
- corriger pendant `0.5.3` les omissions structurelles déjà identifiées, notamment la conservation du temps on-chain/`block_time` lorsqu'il existe et qu'il est pertinent ;
- considérer après clôture les tables stabilisées comme des contrats à ne plus remodeler : les nouvelles fonctionnalités doivent préférer de nouvelles tables reliées aux anciennes ;
- distinguer explicitement `slot`, `block_time` ou timestamp de transaction des timestamps d'acquisition, d'insertion, de mise à jour et de matérialisation ;
- mettre `ks-store` aux conventions du workspace avant l'extension massive des matérialisations ;
- supprimer des autres crates toute dépendance aux fonctions/modules/types PostgreSQL : elles consomment uniquement les DTO/models et opérations génériques de `ks-store` ;
- encapsuler dans `ks-store` la sélection du backend, l'interprétation des paramètres de connexion, la création des pools/connexions et les implémentations spécifiques ;
- conserver PostgreSQL comme backend opérationnel actuel tout en définissant une frontière réimplémentable plus tard avec MySQL, SQLite, RocksDB, Oracle ou un autre moteur sans modifier les consommateurs ;
- profiter de la fenêtre pré-`0.6.x` pour reconstruire ou migrer proprement les bases Devnet/Mainnet avant de figer les contrats ;
- auditer les modèles canoniques par **nature de fait** : core/transactions, comptes/balances/lifecycle, token/SPL, metadata, staking/vote, administration/autorités, programmes, audit/compliance, risques, trading/marchés et autres domaines justifiés par les Program IDs couverts ;
- faire des matérialiseurs la frontière de normalisation des comptes/événements/champs/unités spécifiques à chaque programme vers les DTO/models canoniques de `ks-store` ;
- pour la priorité trading, préparer les contrats canoniques nécessaires aux marchés/paires, pools de liquidité/AMM, order books lorsque leurs invariants ne peuvent pas être unifiés proprement, réserves, positions, swaps/trades, prix, volumes et séries temporelles ;
- autoriser de nouvelles tables génériques futures, par exemple candles/OHLC ou des tables dédiées par concept `liquidity_pool` / `order_book`, lorsque leur contrat est suffisamment durable ;
- conserver le Program ID/protocole/version comme provenance sans en faire le propriétaire par défaut du schéma ;
- permettre des extractions et analyses efficaces pour les futurs consommateurs de trading, metadata, recherche historique et autres usages Solana.
Le schéma ne doit pas être organisé en familles de tables par protocole ou Program ID. `meteora_*`, `raydium_*`, `pump_*`, `orca_*`, `jupiter_*`, etc. illustrent ce qui doit être évité : les différences protocolaires sont normalisées par les matérialiseurs. Lorsqu'une séparation est nécessaire, elle est définie par un concept/fait réellement distinct et durable, qu'il concerne le trading, les metadata, le staking ou un autre domaine.
### 0.5.4 — scénarios, exécuteurs et validations
- réconcilier le cas de decode CPI Metaplex Token Metadata observé en `0.5.3-pre.004` (`transfer`, chemin `2/0`, diagnostic `transfer account 9 lacks required signer/writable privileges`) afin de déterminer si le contrat daccounts du décodeur doit accepter les privilèges runtime observés ; ce point relève du décodeur/scénario, pas de `ks-store` ;
- diagnostiquer et corriger la régression observée dans `demo_execution_spl_token_2022` lors du chargement de fixture (`unable to read configured Token-2022 fixture`) après séparation des racines wallet/fixtures ;
- inventorier non destructivement les keypairs historiques sous `wallets/temporary/**`, extraire les pubkeys des formats supportés et préparer une migration sélective des seuls signers devant devenir persistants ;
- garder toute classification on-chain éventuelle chez le consommateur/scénario, à partir de la pubkey et du profil réseau, sans dépendance `ks-wallet -> ks-onchain-transport` ni rôle métier inventé depuis les bytes du secret ;
- auditer les scénarios encore déclarés ou assemblés directement dans `kb-app-demo-desktop` ;
- déplacer toute logique de scénario réutilisable vers `ks-pipeline-demo-scenarios` et laisser le desktop comme adaptateur UI/Tauri ;
- comparer les décodeurs existants aux exécuteurs disponibles et identifier les exécuteurs réellement manquants ;
- comparer les exécuteurs aux scénarios synthétiques, campagnes Devnet/Testnet et validations existantes ;
- identifier les capacités présentes dans le desktop sans scénario réutilisable ;
- classer chaque absence comme à implémenter, decode-only, deprecated, unavailable, non applicable ou explicitement reportée ;
- ne pas transformer les surfaces réservées ni l'exception ElGamal en dette implicite sans changement de possibilité de validation.
## 0.6.x — infrastructure Anchor générique et prérequis prioritaires
La série `0.6.x` prépare directement laccélération sur les protocoles suivants. Elle ne cherche pas à terminer immédiatement toute la couverture Solana.
- implémenter un décodeur Anchor générique réutilisable : discriminants dinstructions et de comptes, événements, erreurs, conventions IDL, bornes et diagnostics ;
- définir la stratégie générique de matérialisation des informations Anchor communes lorsque cela apporte une valeur stable ;
- conserver et classifier les IDL comme références statiques sans transformer automatiquement une IDL en vérité runtime ;
- implémenter uniquement les programmes/interfaces SPL ou autres prérequis dont Meteora, Raydium, Pump, Orca, Jupiter ou les couches de trading suivantes ont réellement besoin ;
- reporter à `0.15.x` les programmes SPL non prioritaires, les compléments Metaplex non nécessaires à court terme et, plus généralement, les autres Program IDs déjà recensés ou découverts ultérieurement qui ne bloquent pas la séquence trading prioritaire.
Le report vers `0.15.x` est un choix dordre de développement, pas une réduction du périmètre de `ks-lib` après la migration `0.5.1`. Lobjectif à long terme reste de décoder et matérialiser le maximum de Program IDs Solana utiles, quils soient liés ou non au trading.
## 0.7.x — Meteora
### 0.7.0 — cadrage Meteora
- inventorier les Program IDs, IDL, comptes, instructions, événements et dépendances communes ;
- vérifier les primitives Anchor/SPL nécessaires avant code ;
- fixer les matrices de couverture et les scénarios réseau possibles.
### 0.7.1 — DLMM decode + materialize
Décoder la surface DLMM prioritaire et produire les matérialisations stables nécessaires au suivi des pools, positions, liquidité, swaps et évolutions de prix observables.
### 0.7.2 — DLMM executor + scénarios
Ajouter les exécuteurs justifiés et les scénarios Devnet/Testnet lorsque le programme et les fixtures le permettent, sans inventer de validation réseau impossible.
### 0.7.3 — DAMM v1 decode + materialize
Décoder DAMM v1 et matérialiser les faits de pool/trading utiles selon les mêmes frontières que DLMM.
### 0.7.4 — DAMM v1 executor + scénarios
Ajouter les exécuteurs et campagnes réseau sûres et représentatives lorsque disponibles.
### 0.7.5 — DAMM v2 decode + materialize
Décoder DAMM v2 et matérialiser ses faits stables sans réutiliser artificiellement les contrats DAMM v1 lorsquils diffèrent.
### 0.7.6 — DAMM v2 executor + scénarios
Ajouter les exécuteurs et scénarios Devnet/Testnet réellement justifiés.
### 0.7.7 — DBC decode + materialize
Décoder Dynamic Bonding Curve et matérialiser création, progression, liquidité, migrations et faits de prix réellement observables.
### 0.7.8 — DBC executor + scénarios
Ajouter les exécuteurs et scénarios réseau possibles avec les mêmes règles simulation-first et postconditions.
### 0.7.9 — Vault et audit des autres programmes Meteora
- couvrir Meteora Vault selon la valeur des comptes/instructions réellement utilisés ;
- auditer les autres Program IDs Meteora découverts pendant les versions précédentes ;
- classer chaque surface restante comme prioritaire, reportée, decode-only ou non applicable avant de clôturer `0.7.x`.
## 0.8.x — Raydium
Appliquer la même discipline que pour Meteora : cadrage, puis pour chaque surface prioritaire une version decode + materialize suivie dune version executor + scénarios lorsque lexécution réseau est possible.
### 0.8.0 — cadrage Raydium
- inventorier Program IDs, IDL, générations actives/historiques, comptes, instructions et dépendances ;
- confirmer lordre des surfaces à partir de leur valeur trading réelle et de leur disponibilité réseau ;
- définir les matrices et fixtures réutilisables avant implémentation.
### 0.8.1 — AMM v4 decode + materialize
Décoder AMM v4 et matérialiser les faits stables de pools, réserves, swaps, liquidité et prix observables.
### 0.8.2 — AMM v4 executor + scénarios
Ajouter les exécuteurs justifiés et les scénarios Devnet/Testnet lorsque les opérations peuvent être exécutées de manière sûre et reproductible.
### 0.8.3 — CPMM decode + materialize
Décoder CPMM et matérialiser ses faits de pool et de trading sans le confondre avec les générations AMM historiques.
### 0.8.4 — CPMM executor + scénarios
Ajouter les exécuteurs et campagnes réseau représentatives lorsque disponibles.
### 0.8.5 — CLMM decode + materialize
Décoder CLMM et matérialiser pools concentrés, positions, liquidité, ticks et faits de prix nécessaires aux analyses futures.
### 0.8.6 — CLMM executor + scénarios
Ajouter les exécuteurs justifiés et les scénarios réseau avec postconditions observables.
### 0.8.7 — LaunchLab decode + materialize
Décoder LaunchLab et matérialiser les faits de lancement, progression et transition vers les pools lorsquils sont observables on-chain.
### 0.8.8 — LaunchLab executor + scénarios
Ajouter les exécuteurs et scénarios réellement disponibles sans inventer de fixture ou de preuve réseau.
### 0.8.9 — Stable Swap, Lock, legacy et audit des autres programmes Raydium
- couvrir les surfaces encore pertinentes après audit ;
- maintenir les générations remplacées en decode-only lorsque leur exécution nest plus justifiée ;
- auditer les autres Program IDs Raydium découverts et classer explicitement leur priorité ou leur report.
## 0.9.x — Pump
Prioriser les surfaces Pump utiles au cycle de vie dun token et au trading : Pump.fun, Pump AMM, Pump Fees et autres Program IDs vérifiés. Commencer par un audit de la famille, puis alterner decode + materialize et executor + scénarios comme pour Meteora/Raydium. Auditer notamment les Program IDs déjà recensés dont lappartenance ou la fonction exacte reste à confirmer avant implémentation.
## 0.10.x — Orca
Prioriser Whirlpool, puis auditer Orca v1/v2, Wavebreak et les autres surfaces vérifiées. Conserver la séparation decode + materialize / executor + scénarios et ne maintenir les générations historiques en exécution que lorsquelles sont encore réellement utilisables.
## 0.11.x — Jupiter
Prioriser les surfaces nécessaires au routing et au trading : routers/agrégateurs, DCA, ordres, perpetuals, lockers et autres Program IDs vérifiés. Séparer les contrats de routing, de marché et de gestion afin de ne pas concentrer Jupiter dans un seul module monolithique.
## 0.12.x — autres protocoles trading prioritaires
Traiter les autres Program IDs ayant une valeur directe pour le trading, le routing, les launchpads, la liquidité ou les dépendances nécessaires aux consommateurs trading. Leur ordre précis doit être décidé à partir des Program IDs réellement recensés à ce stade, et non figé artificiellement plusieurs versions à lavance.
## 0.13.x — transports temps réel
WebSocket Helius, LaserStream, Yellowstone gRPC, continuité, backpressure, reconnexion, métriques et sélection de transport selon les rôles configurés.
## 0.14.x — workers et applications consommatrices
- W1 acquisition temps réel vers les raw ;
- W2 décodage et matérialisation temps réel ;
- rattrapage historique séparé ;
- application de contrôle ;
- application de trading et applications de visualisation.
## 0.15.x — reprise de la couverture généraliste différée
Reprendre les Program IDs volontairement différés pour accélérer la séquence trading :
- programmes et interfaces SPL non prioritaires ;
- compléments Metaplex qui nétaient pas nécessaires aux versions précédentes ;
- Program IDs non-trading déjà recensés ou découverts au fil des audits ;
- Program IDs trading secondaires qui nétaient pas bloquants ;
- autres surfaces Solana dont le décodage/matérialisation apporte une valeur durable.
Cette phase réaffirme la vocation généraliste de `ks-lib` : la priorité trading des versions précédentes ne transforme pas la bibliothèque en moteur exclusivement DEX.
## 0.16.x+ — extensions futures et off-chain
- nouveaux protocoles, transports, backfills, observabilité, administration et optimisations validés par des contrats bornés ;
- étudier puis créer `ks-offchain-transport` seulement lorsquun consommateur réel le justifie, avec premiers modules metadata HTTP(S), IPFS et Arweave, cache et provenance bornés, hash, contrôle des redirections, limites MIME/taille/timeout et protection SSRF IPv4/IPv6.