732 lines
35 KiB
Markdown
732 lines
35 KiB
Markdown
<!-- file: docs/plans/007-V0_2_0_SERIES_PLANNING.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# Plan `0.2.0` — audit bot3 et planification de la série `0.2.x`
|
||
|
||
> **Statut : plan historique clôturé par `0.2.0-rel.001`.** La première release fonctionnelle suivante est `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation`, ouverte avec `prompts/006-V0_2_1_START_PROMPT.md`.
|
||
|
||
## 1. Statut et objectif
|
||
|
||
`0.2.0` est une release intermédiaire de transition, d'audit et de planification. Elle ne livre pas directement une nouvelle capacité Solana complète ; elle transforme l'expérience de `khadhroony-bot3` en une trajectoire KSP cohérente, bornée et compatible avec les règles stabilisées en `0.1.x`.
|
||
|
||
Base KSP attendue à l'ouverture de `0.2.0` :
|
||
|
||
```text
|
||
v0.1.4
|
||
ksp-core-lib
|
||
ksp-logging-lib
|
||
ksp-config-lib
|
||
ksp-app-config-desk
|
||
```
|
||
|
||
Snapshot bot3 principal audité pendant `0.2.0` :
|
||
|
||
```text
|
||
khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||
```
|
||
|
||
Les fondations déjà refondues en `0.1.x` ne sont pas remigrées. Elles servent de contraintes pour juger les capacités historiques.
|
||
|
||
## 2. Discipline de découpage
|
||
|
||
KSP applique désormais deux garde-fous cumulatifs :
|
||
|
||
1. une prerelease vise environ **15 à 20 minutes de travail effectif** ;
|
||
2. une release fonctionnelle concrète doit être dimensionnée pour pouvoir être **ouverte, développée, validée et clôturée dans une seule session de chat**.
|
||
|
||
Une release fonctionnelle ne doit pas être laissée volontairement ouverte pour être continuée dans une autre session.
|
||
|
||
Le `pre.001` de chaque release sert donc aussi de **gate de dimensionnement**. Si l'inventaire réel montre que la release ne pourra vraisemblablement pas être clôturée dans la session, elle est scindée avant de commencer l'implémentation fonctionnelle lourde.
|
||
|
||
Un nouveau besoin planifié produit une nouvelle prerelease. Un défaut livré dans une tranche existante produit un `fix.NNN` et n'est pas réécrit silencieusement.
|
||
|
||
## 3. Méthode d'audit bot3
|
||
|
||
Chaque capacité historique est étudiée en séparant cinq dimensions :
|
||
|
||
1. **fonctionnalité** — besoin réellement utile ;
|
||
2. **implémentation historique** — code et organisation bot3 ;
|
||
3. **contrat public** — types, traits, invariants et comportements observables utiles ;
|
||
4. **dépendance externe** — crate, protocole ou provider tiers ;
|
||
5. **convention de projet** — choix local qui n'est pas intrinsèque au besoin.
|
||
|
||
Les statuts de décision sont :
|
||
|
||
- `reprendre` — reprendre le besoin/contrat utile ;
|
||
- `adapter` — conserver le besoin avec ajustements de frontière/API ;
|
||
- `refondre` — conserver le besoin mais remplacer l'architecture historique ;
|
||
- `abandonner` — ne pas migrer ;
|
||
- `ajouter` — besoin KSP absent ou insuffisant dans bot3.
|
||
|
||
`reprendre` ne signifie jamais « copier mécaniquement le code ».
|
||
|
||
## 4. Décisions stabilisées par `0.2.0-pre.002` / `pre.003`
|
||
|
||
### 4.1 Ordre fonctionnel initial de la série
|
||
|
||
Le premier besoin Wallet a montré qu'une application Wallet réellement testable doit pouvoir lire le solde d'une adresse. Le transport HTTP Solana doit donc précéder le Wallet.
|
||
|
||
Le début de série est désormais ordonné ainsi :
|
||
|
||
```text
|
||
0.2.1 ksp-onchain-transport-lib — HTTP Solana foundation
|
||
0.2.2 ksp-wallet-lib — format natif .kspwallet
|
||
0.2.3 ksp-app-wallet-desk — Wallet + Config composite + HTTP
|
||
0.2.4 ksp-onchain-transport-lib — WebSocket Solana standard
|
||
0.2.5 ksp-onchain-transport-lib — Helius LaserStream WebSocket
|
||
0.2.6 ksp-onchain-transport-lib — Yellowstone gRPC standard foundation
|
||
0.2.7 ksp-offchain-transport-lib — première surface prix
|
||
0.2.8 application desk de visualisation des prix
|
||
0.2.9 ksp-interface-lib — première surface wire/API publique
|
||
0.2.10 ksp-program-api — première API extensible Program
|
||
```
|
||
|
||
Les providers Yellowstone avancés ou spécifiques ne sont pas prioritaires dans cette première séquence. Ils seront ajoutés plus tard lorsque le besoin opérationnel le justifiera.
|
||
|
||
### 4.2 Frontière Config / Transport
|
||
|
||
`ksp-onchain-transport-lib` **ne dépend pas de `ksp-config-lib`**.
|
||
|
||
Le transport possède ses contrats runtime publics : endpoints, pools, rôles, limites, timeouts, retry/backoff et autres settings réellement nécessaires.
|
||
|
||
Lorsque KSP fournit un document standard Transport, son ownership reste dans `ksp-config-lib`, sur le même principe que Config -> Logging :
|
||
|
||
```text
|
||
config/std.transport.json
|
||
|
|
||
v
|
||
ksp-config-lib
|
||
|
|
||
| adapter vers contrats publics Transport
|
||
v
|
||
ksp-onchain-transport-lib
|
||
```
|
||
|
||
La dépendance inverse est interdite :
|
||
|
||
```text
|
||
ksp-onchain-transport-lib -X-> ksp-config-lib
|
||
```
|
||
|
||
Les applications, workers et jobs peuvent aussi construire directement les settings publics du transport sans utiliser Config.
|
||
|
||
### 4.3 Couverture documentaire complète du transport
|
||
|
||
Pour toute surface de transport officiellement ciblée par une release, KSP doit inventorier puis implémenter **toutes les méthodes/opérations exposées par la documentation normative sélectionnée**, sauf impossibilité technique explicitement documentée.
|
||
|
||
Chaque méthode/opération est classée au minimum :
|
||
|
||
```text
|
||
Stable
|
||
Deprecated / Obsolete mais encore fonctionnelle
|
||
Unstable / Experimental
|
||
```
|
||
|
||
Règles runtime :
|
||
|
||
- `Stable` : comportement normal ;
|
||
- `Deprecated/Obsolete` encore fonctionnelle : API conservée + `warn` via `ksp-logging-lib` lors de son utilisation ;
|
||
- `Unstable/Experimental` : API disponible + `warn` via `ksp-logging-lib` lors de son utilisation.
|
||
|
||
La metadata de statut doit être centralisée afin d'éviter des warnings codés en dur de manière dispersée.
|
||
|
||
Une méthode supprimée du protocole et réellement non utilisable n'est pas simulée artificiellement ; son historique peut rester documenté.
|
||
|
||
### 4.4 HTTP : pools et rôles
|
||
|
||
Le transport HTTP doit reprendre/refondre les besoins utiles de bot3 :
|
||
|
||
- JSON-RPC ;
|
||
- endpoints nommés ;
|
||
- provider/cluster metadata ;
|
||
- activation/désactivation ;
|
||
- pool logique d'endpoints ;
|
||
- rôles ;
|
||
- priorités ;
|
||
- request kinds/capabilities ;
|
||
- rate limits et burst lorsque configurés ;
|
||
- concurrence maximale ;
|
||
- pause/backoff après limitation ;
|
||
- timeouts ;
|
||
- retry transport borné ;
|
||
- health/snapshots utiles ;
|
||
- méthodes read **et** write/execution technique documentées.
|
||
|
||
Le pool HTTP est un pool **logique d'endpoints/clients**. KSP ne réimplémente pas un gestionnaire bas niveau de sockets que la bibliothèque HTTP sait déjà gérer.
|
||
|
||
### 4.5 WebSocket : session avant pool automatique
|
||
|
||
Une URL WebSocket doit pouvoir avoir plusieurs sessions physiques simultanées :
|
||
|
||
```text
|
||
endpoint URL
|
||
1 -> N sessions
|
||
|
||
session
|
||
1 -> N subscriptions
|
||
```
|
||
|
||
Cette capacité est nécessaire pour permettre ultérieurement l'isolation de familles de subscriptions, des limites provider différentes, des reconnects indépendants ou une répartition de charge.
|
||
|
||
En revanche, `0.2.4` ne doit pas créer par anticipation un scheduler/pool automatique complexe de sessions tant qu'un besoin concret ne le démontre pas.
|
||
|
||
Les concepts attendus sont d'abord du type :
|
||
|
||
```text
|
||
WsEndpoint
|
||
WsSession
|
||
WsSessionId
|
||
WsSubscription
|
||
WsSubscriptionId
|
||
```
|
||
|
||
Un éventuel `WsSessionPool`/routing automatique reste need-driven.
|
||
|
||
### 4.6 Helius LaserStream WebSocket
|
||
|
||
`0.2.5` n'est pas une copie du client WebSocket standard.
|
||
|
||
Les extensions Helius doivent réutiliser le moteur/session/lifecycle WebSocket construit en `0.2.4` et ajouter uniquement les contrats, filtres, notifications et capabilities spécifiques nécessaires.
|
||
|
||
Le modèle multi-session d'une même URL reste identique.
|
||
|
||
### 4.7 Yellowstone gRPC
|
||
|
||
`0.2.6` introduit un premier backend/client Yellowstone gRPC standard et provider-neutral.
|
||
|
||
La release ne doit pas figer l'architecture autour de Helius, Triton, ERPC, Chainstack, Shyft ou d'un autre provider. Un provider disponible peut servir à la validation réseau, mais il reste un **environnement de test**, pas le propriétaire du contrat KSP.
|
||
|
||
Le `pre.001` de `0.2.6` devra inventorier la surface normative Yellowstone réellement actuelle et appliquer le gate de dimensionnement. Si la couverture complète de la surface ciblée ne tient pas dans une release clôturable dans la session, elle sera divisée avant implémentation.
|
||
|
||
Les adaptations/provider profiles plus avancés sont reportés après les fondations prioritaires.
|
||
|
||
### 4.8 Fiches de releases `0.2.1+`
|
||
|
||
Ces fiches complètent la simple séquence numérique. Elles sont **souples** : le `pre.001` de chaque release refait le sizing sur les dépendances et documentations réellement actuelles. Une estimation ne justifie jamais d'ouvrir une release dont la clôture dans la même session paraît incertaine.
|
||
|
||
#### `0.2.1` — HTTP Solana foundation
|
||
|
||
- **Mission :** créer `ksp-onchain-transport-lib` avec JSON-RPC HTTP Solana complet, settings publics, pool logique d'endpoints, rôles/capabilities/limites et adapter Config -> Transport.
|
||
- **Périmètre :** index HTTP officiel courant, méthodes deprecated/obsolete encore réellement utilisables, éventuelles méthodes HTTP unstable/experimental documentées, read/write technique, timeouts, retry/backoff, health et observabilité.
|
||
- **Hors périmètre :** Wallet, WebSocket, LaserStream, gRPC, Store, Program, orchestration d'exécution.
|
||
- **Dépendances :** fondations `0.1.x`; `ksp-config-lib` peut dépendre des contrats Transport pour l'adapter, jamais l'inverse.
|
||
- **Clôture :** matrice documentaire exhaustive et testée, ownership propre, warnings de statut, pools/rôles validés, README/USAGE et prompt `0.2.2`.
|
||
- **Estimation souple :** environ 8–12 prereleases courtes **si** le gate `pre.001` confirme qu'elles restent clôturables dans une seule session ; sinon scinder avant implémentation lourde.
|
||
|
||
#### `0.2.2` — Wallet foundation
|
||
|
||
- **Mission :** créer `ksp-wallet-lib` et le format natif `.kspwallet`.
|
||
- **Périmètre :** création/ouverture, protection du secret, identité/pubkey, signature, changement de mot de passe, atomicité/no-clobber, import/export extensible et premiers formats réellement validés.
|
||
- **Hors périmètre :** `WalletPolicy`, wallet JSON temporaire bot2/bot3, UI Tauri, lecture de solde réseau.
|
||
- **Dépendances :** Core/Logging et primitives crypto/signature nécessaires ; aucun besoin de dépendre de Transport pour le cœur Wallet.
|
||
- **Clôture :** format documenté/testé, secret non exposé, import/export round-trip retenu, README/USAGE et prompt Wallet Desk.
|
||
- **Estimation souple :** environ 5–8 prereleases.
|
||
|
||
#### `0.2.3` — `ksp-app-wallet-desk`
|
||
|
||
- **Mission :** valider en Tauri Config composite + Wallet + HTTP.
|
||
- **Périmètre :** sélection/ouverture de wallet, identité/pubkey, affichage du solde réel via `getBalance`, opérations Wallet utiles à la première UI, instrumentation Logging et modèle Tauri Config Desk.
|
||
- **Hors périmètre :** WebSocket, trading, execution policy, duplication de cryptographie ou JSON-RPC dans l'app.
|
||
- **Dépendances :** `0.2.1`, `0.2.2`, Config Desk/Tauri conventions.
|
||
- **Clôture :** flux opérateur bout en bout sur un endpoint réel configurable, secrets protégés, build Tauri final exécuté en dernière opération de validation.
|
||
- **Estimation souple :** environ 5–8 prereleases.
|
||
|
||
#### `0.2.4` — WebSocket Solana standard
|
||
|
||
- **Mission :** ajouter la surface WebSocket Solana standard complète au transport.
|
||
- **Périmètre :** sessions persistantes, subscriptions/unsubscriptions/notifications documentées, reconnexion bornée, plusieurs sessions possibles sur une même URL, plusieurs subscriptions par session.
|
||
- **Hors périmètre :** scheduler/pool automatique complexe de sessions, Helius-specific, Yellowstone.
|
||
- **Dépendances :** `0.2.1` et contrats Transport déjà stabilisés.
|
||
- **Clôture :** matrice WS exhaustive, lifecycle/reconnect/tests réseau opt-in et warnings pour toute surface unstable/deprecated concernée.
|
||
- **Estimation souple :** environ 5–8 prereleases.
|
||
|
||
#### `0.2.5` — Helius LaserStream WebSocket
|
||
|
||
- **Mission :** étendre le moteur WS standard avec la surface Helius ciblée sans dupliquer le client.
|
||
- **Périmètre :** opérations/filtres/notifications/capabilities Helius documentés et réellement disponibles au moment de la release.
|
||
- **Hors périmètre :** gRPC LaserStream, autres providers, shred delivery.
|
||
- **Dépendances :** `0.2.4`.
|
||
- **Clôture :** extensions isolées du moteur commun, matrice Helius, tests opt-in selon credentials disponibles, absence de secret dans les logs.
|
||
- **Estimation souple :** environ 3–5 prereleases.
|
||
|
||
#### `0.2.6` — Yellowstone gRPC standard foundation
|
||
|
||
- **Mission :** introduire un client/backend Yellowstone standard et provider-neutral.
|
||
- **Périmètre :** surface normative retenue à `pre.001`, connexion/auth metadata générique, stream/subscription, filtres et lifecycle nécessaires.
|
||
- **Hors périmètre :** profils commerciaux spécifiques Helius/Triton/ERPC/Chainstack/Shyft, shred/deshred et optimisations provider-only.
|
||
- **Dépendances :** transport foundation ; aucun provider ne devient propriétaire du contrat.
|
||
- **Clôture :** matrice protocolaire, test contre au moins un endpoint réellement accessible lorsque possible, comportement provider-neutral documenté.
|
||
- **Estimation souple :** environ 4–7 prereleases, avec gate de découpage obligatoire si la surface normative courante dépasse ce qui est raisonnablement clôturable dans la session.
|
||
|
||
#### `0.2.7` — Off-chain price transport
|
||
|
||
- **Mission :** créer `ksp-offchain-transport-lib` sur un premier besoin réel de prix.
|
||
- **Périmètre :** abstraction de lecture de prix, premier provider, au minimum SOL/USD et SOL/EUR, erreurs/timeouts/observabilité et settings publics nécessaires.
|
||
- **Hors périmètre :** metadata HTTP/IPFS/Arweave, quotes/routing, agrégation multi-provider complexe.
|
||
- **Dépendances :** fondations Core/Logging ; indépendante du transport on-chain sauf composition applicative.
|
||
- **Clôture :** provider interchangeable derrière le contrat retenu, prix typés/testés, README/USAGE.
|
||
- **Estimation souple :** environ 3–5 prereleases.
|
||
|
||
#### `0.2.8` — Price Desk
|
||
|
||
- **Mission :** valider le transport off-chain dans une petite application Tauri.
|
||
- **Périmètre :** Config, sélection/refresh des paires supportées, affichage des prix et provenance/état utiles.
|
||
- **Hors périmètre :** Market Desk DEX/OHLC, trading et metadata.
|
||
- **Dépendances :** `0.2.7` + conventions Tauri stabilisées.
|
||
- **Clôture :** UI mince fonctionnelle, refresh observable, erreurs sûres et build Tauri final.
|
||
- **Estimation souple :** environ 3–5 prereleases.
|
||
|
||
#### `0.2.9` — `ksp-interface-lib` foundation
|
||
|
||
- **Mission :** ouvrir la façade wire officielle KSP et son API publique utilisable aussi par des crates externes.
|
||
- **Périmètre :** organisation wire, règles réexport/wrapper/réimplémentation compatible, premiers types/interfaces Solana réellement nécessaires et canaries de compatibilité.
|
||
- **Hors périmètre :** inventaire exhaustif de tous les protocoles Solana/SPL/Metaplex, Program implementations complètes.
|
||
- **Dépendances :** Core et dépendances wire externes explicitement retenues/centralisées au workspace.
|
||
- **Clôture :** API publique cohérente avec les implémentations internes, aucune dépendance métier externe inutile dans les couches supérieures, README/USAGE.
|
||
- **Estimation souple :** environ 4–7 prereleases.
|
||
|
||
#### `0.2.10` — `ksp-program-api` foundation
|
||
|
||
- **Mission :** introduire le contrat extensible Program avant les vertical slices réels.
|
||
- **Périmètre :** identité/capabilities, contrats de décodage et préparation d'exécution nécessaires à une implémentation externe, support/deprecation machine-readable et extension ouverte.
|
||
- **Hors périmètre :** `ksp-program-lib` exhaustif, materializers, execution engine, scénarios.
|
||
- **Dépendances :** Core + `ksp-interface-lib` lorsque les contrats wire le nécessitent.
|
||
- **Clôture :** une implémentation externe fictive/test démontre que l'API n'impose pas `ksp-program-lib`; contrats documentés et prompt de la série suivante préparé.
|
||
- **Estimation souple :** environ 3–5 prereleases.
|
||
|
||
### 4.9 Audit final `0.2.0-pre.003`
|
||
|
||
L'audit final de la base Git `0.2.0-pre.002` a relevé et corrige les écarts suivants avant release stable :
|
||
|
||
- collisions d'identifiants normatifs dans `RULES_KSP.md` (`KSP-TRANSPORT-001`, `KSP-DATA-001`, `KSP-DATA-002`) ;
|
||
- ancienne règle `KSP-JOB-009` imposant encore trois jobs de replay globaux incompatibles avec la progression verticale décidée ;
|
||
- ancien diagramme `W1 -> D1 -> W2 -> D2 -> W3 -> D3 -> W4 -> D4` dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`, encore susceptible d'être lu comme quatre workers globaux imposés ; il est remplacé par les frontières durables D1–D4 et une granularité worker need-driven ;
|
||
- entrées `IDEAS.md` encore formulées autour de `generic-materialization` / `domain-projection` et d'un type global `DomainProjector` ;
|
||
- TODO Wallet bot3 utiles non encore reportés explicitement : Backpack, Trust Wallet, Solflare keystore, Base app/ex-Coinbase Wallet et distinction Coinbase Developer Platform ;
|
||
- absence dans le plan directeur des fiches mission/périmètre/hors-périmètre/dépendances/clôture/estimation demandées pour chaque release `0.2.1+`.
|
||
|
||
Un spot-check externe effectué le **2026-08-17** sur la documentation officielle Solana observe 52 méthodes dans l'index HTTP courant et 14 noms dans la section officielle Deprecated Methods. L'inventaire bot3 contient les 52 noms de l'index courant, mais pas la surface deprecated séparée. Cette observation confirme l'intérêt de réutiliser l'inventaire fonctionnel bot3 tout en imposant à `0.2.1-pre.001` un nouvel audit officiel complet ; **les nombres observés ici ne deviennent pas un contrat durable**.
|
||
|
||
## 5. Wallet
|
||
|
||
### 5.1 `0.2.2` — format natif `.kspwallet`
|
||
|
||
Le format KSP devient :
|
||
|
||
```text
|
||
.kspwallet
|
||
```
|
||
|
||
L'ancien `.kswallet` de bot3 est une référence historique, pas le nom KSP final.
|
||
|
||
Les fonctionnalités utiles à reprendre/refondre comprennent :
|
||
|
||
- création ;
|
||
- ouverture/déverrouillage ;
|
||
- identité publique/pubkey sans exposition du secret ;
|
||
- secret chiffré ;
|
||
- signature ;
|
||
- mot de passe ;
|
||
- changement de mot de passe sans changement de keypair ;
|
||
- publication atomique/no-clobber ;
|
||
- redaction/zeroization adaptées ;
|
||
- alias/organisation ;
|
||
- import/export ;
|
||
- inspection d'un format externe sans import lorsque pertinent ;
|
||
- migrations/conversions utiles.
|
||
|
||
### 5.2 Abandon du wallet temporaire JSON
|
||
|
||
Le `TemporaryWalletStore`/wallet JSON temporaire de bot3 est un héritage de bot2 utilisé principalement pour les anciens scénarios.
|
||
|
||
Il n'est pas migré dans KSP.
|
||
|
||
Les futurs scénarios utilisent de vrais `.kspwallet`, y compris des wallets dédiés Devnet/tests si nécessaire.
|
||
|
||
### 5.3 `WalletPolicy`
|
||
|
||
`WalletPolicy` ne fait pas partie de `ksp-wallet-lib`.
|
||
|
||
Les règles de dépense, réseau, programme, simulation, limites ou autorisations appartiennent à la future execution policy :
|
||
|
||
```text
|
||
ksp-execution-policy-api
|
||
```
|
||
|
||
Une policy petite et spécifique à un scenario/orchestrateur peut être implémentée directement dans sa crate. Une ou plusieurs bibliothèques de policies communes ne seront créées que lorsque des comportements réellement réutilisables le justifieront.
|
||
|
||
### 5.4 Import/export extensible
|
||
|
||
`0.2.2` doit conserver une architecture d'import/export extensible et fournir les formats réellement nécessaires à sa validation.
|
||
|
||
Les formats additionnels à étudier restent dans `docs/IDEAS.md` tant qu'ils ne sont pas engagés. Le projet ne doit pas ajouter toutes leurs dépendances « au cas où ».
|
||
|
||
## 6. `0.2.3` — Wallet Desk
|
||
|
||
`ksp-app-wallet-desk` est une application Tauri mince construite selon le modèle validé par Config Desk.
|
||
|
||
Elle doit valider ensemble :
|
||
|
||
```text
|
||
ksp-config-lib
|
||
+ configuration composite
|
||
+ ksp-wallet-lib
|
||
+ ksp-onchain-transport-lib HTTP figé par 0.2.1
|
||
```
|
||
|
||
La première version doit au minimum permettre d'observer l'identité d'un wallet et son solde via le transport HTTP afin que le Wallet ne soit pas validé uniquement hors réseau.
|
||
|
||
L'application ne réimplémente ni cryptographie Wallet, ni JSON-RPC, ni Config.
|
||
|
||
## 7. Off-chain transport
|
||
|
||
### 7.1 Première surface volontairement petite
|
||
|
||
`0.2.7` introduit `ksp-offchain-transport-lib` avec un premier besoin réel : récupération de prix, au minimum :
|
||
|
||
```text
|
||
SOL/USD
|
||
SOL/EUR
|
||
```
|
||
|
||
La bibliothèque doit séparer le besoin « lire un prix » de l'API propriétaire du premier provider retenu.
|
||
|
||
La première release n'a pas à introduire immédiatement IPFS, Arweave, metadata HTTP, quotes/routing ou tous les providers imaginables.
|
||
|
||
### 7.2 Application prix
|
||
|
||
`0.2.8` introduit une petite application desk utilisant Config + `ksp-offchain-transport-lib` pour visualiser les prix et valider la capacité hors chaîne dans une UI réelle.
|
||
|
||
Les readers/retrievers metadata HTTP/IPFS/Arweave arriveront lorsqu'un groupe Metadata en aura réellement besoin.
|
||
|
||
## 8. `ksp-interface-lib`
|
||
|
||
### 8.1 Une seule crate pour l'instant
|
||
|
||
`ksp-interface-lib` reste la façade wire officielle KSP.
|
||
|
||
Aucune crate `ksp-interface-api` séparée n'est décidée actuellement.
|
||
|
||
La bibliothèque doit toutefois exposer une **API publique wire suffisamment propre** pour qu'une crate Program externe puisse utiliser les mêmes contrats que les implémentations officielles KSP.
|
||
|
||
Ainsi :
|
||
|
||
```text
|
||
ksp-interface-lib
|
||
= implémentations/réexports wire officiels
|
||
+ API publique wire réutilisable
|
||
```
|
||
|
||
Une extension externe peut expérimenter contre cette API avant intégration officielle dans KSP.
|
||
|
||
Si une future contrainte de dépendance démontre qu'un split `ksp-interface-api` est réellement nécessaire, la décision pourra être revue selon `KSP-API-007`. La symétrie de nommage ne suffit pas.
|
||
|
||
### 8.2 Interfaces officielles et wires compatibles
|
||
|
||
La politique reste :
|
||
|
||
- réutiliser/réexporter de manière contrôlée une interface officielle suffisamment stable et compatible ;
|
||
- wrapper lorsqu'une frontière publique KSP est nécessaire ;
|
||
- posséder/réimplémenter une définition wire compatible lorsqu'une bibliothèque protocolaire externe est instable, ancienne, lourde ou impose des générations de dépendances incompatibles ;
|
||
- supporter au besoin des anciens wires réellement observables sans forcer le workspace entier à utiliser les anciennes bibliothèques.
|
||
|
||
Metaplex Token Metadata reste un exemple important de wire à posséder/compatibiliser plutôt que d'imposer directement `mpl-token-metadata` aux couches supérieures.
|
||
|
||
## 9. `ksp-program-api`
|
||
|
||
La nomenclature canonique est :
|
||
|
||
```text
|
||
ksp-program-api
|
||
ksp-program-lib
|
||
```
|
||
|
||
et jamais `ksp-program-api-lib`.
|
||
|
||
`ksp-program-api` est la crate de contrats extensibles. `ksp-program-lib` utilisera et implémentera ces contrats.
|
||
|
||
Une future crate externe pourra également implémenter `ksp-program-api` sans dépendre de `ksp-program-lib`.
|
||
|
||
`0.2.10` ouvre uniquement la première API Program ; les implémentations Program réelles sont décalées vers la progression verticale ultérieure.
|
||
|
||
## 10. Architecture de données canonique
|
||
|
||
La progression durable KSP est désormais exprimée comme :
|
||
|
||
```text
|
||
RAW
|
||
↓
|
||
CORE
|
||
↓
|
||
DECODE
|
||
↓
|
||
SPECIALIZED
|
||
```
|
||
|
||
Les aliases durables D1–D4 restent utilisables :
|
||
|
||
```text
|
||
D1 = RAW
|
||
D2 = CORE
|
||
D3 = DECODE / matérialisation générique décodée
|
||
D4 = SPECIALIZED
|
||
```
|
||
|
||
### 10.1 RAW
|
||
|
||
Acquisition suffisamment fidèle et replayable, avec provenance.
|
||
|
||
Aucun décodage Program n'est requis.
|
||
|
||
### 10.2 CORE
|
||
|
||
Normalisation canonique **générique de la blockchain Solana** : blocs, slots, signatures, transactions/messages, comptes, instructions brutes, CPI, logs, meta et relations structurelles générales.
|
||
|
||
CORE ne dépend pas du décodage d'un programme SPL/Metaplex/DEX.
|
||
|
||
La transformation `RAW -> CORE` doit fonctionner même si aucun decoder Program n'existe.
|
||
|
||
### 10.3 DECODE
|
||
|
||
À partir de CORE commencent les interprétations Program/protocole.
|
||
|
||
La frontière couvre successivement, selon le groupe :
|
||
|
||
```text
|
||
decoding
|
||
-> materialisation générique / journal durable
|
||
```
|
||
|
||
D3 conserve suffisamment de provenance/versioning pour rejouer les projections spécialisées sans refaire l'acquisition.
|
||
|
||
### 10.4 SPECIALIZED
|
||
|
||
D4 contient les projections queryables spécialisées : token facts, metadata assets, pools, trades/swaps, positions, liquidité, prix, OHLC, routes et autres faits de domaine.
|
||
|
||
Les modèles spécialisés sont conçus par **faits métier génériques** lorsqu'une normalisation inter-protocoles est pertinente ; ils ne sont pas automatiquement découpés en tables `meteora_*`, `raydium_*`, etc.
|
||
|
||
## 11. Ordre de développement par couches
|
||
|
||
### 11.1 RAW et CORE : progression horizontale
|
||
|
||
Les deux premières couches ne nécessitent pas de décodage Program.
|
||
|
||
KSP peut donc les construire horizontalement jusqu'à disposer, pour chaque couche, de ses outils d'exploitation :
|
||
|
||
```text
|
||
persistence
|
||
replay/backfill
|
||
worker/service lorsque nécessaire
|
||
application de contrôle/validation lorsque utile
|
||
```
|
||
|
||
Le principe est : terminer une couche exploitable avant d'ouvrir la suivante.
|
||
|
||
### 11.2 À partir de DECODE : progression verticale par groupe
|
||
|
||
À partir du premier groupe Program, KSP ne doit pas développer tous les decoders, puis tous les materializers, puis toutes les executions.
|
||
|
||
Chaque groupe progresse verticalement :
|
||
|
||
```text
|
||
interfaces/wires nécessaires
|
||
-> decoding
|
||
-> materialisation générique
|
||
-> materialisation/projection SPECIALIZED si utile
|
||
-> préparation d'exécution
|
||
-> execution policy nécessaire
|
||
-> exécution
|
||
-> scénarios Devnet / validation
|
||
```
|
||
|
||
Puis seulement le groupe prioritaire suivant devient le centre du travail.
|
||
|
||
Cette règle évite une grande surface horizontalement incomplète.
|
||
|
||
## 12. Ordre prioritaire des groupes Program
|
||
|
||
L'ordre fonctionnel pressenti après RAW/CORE est :
|
||
|
||
1. **Solana Core Programs** utilisés transversalement ;
|
||
2. **SPL orienté token/trading** : Token, ATA, Token-2022 et extensions pertinentes ;
|
||
3. **Metadata orientées token** : Metaplex Token Metadata + metadata Token-2022 ;
|
||
4. **Anchor** nécessaire aux protocoles suivants ;
|
||
5. **Meteora** ;
|
||
6. **Raydium** ;
|
||
7. **Pump** ;
|
||
8. **Orca** ;
|
||
9. première **Market Desk** ;
|
||
10. **routing** : Jupiter puis OKX et autres besoins réels ;
|
||
11. enrichissement Market Desk ;
|
||
12. programmes **trading-adjacent** indépendants ;
|
||
13. reste du décodage généraliste Solana.
|
||
|
||
L'ordre exact entre Meteora/Raydium/Pump/Orca pourra être ajusté selon le trafic, les données réellement observées et les possibilités de validation au moment de leur ouverture, sans casser la règle de vertical slice.
|
||
|
||
SPM est volontairement repoussé vers le décodage généraliste ultérieur ; il n'est pas inclus dans le premier groupe metadata token.
|
||
|
||
## 13. Programmes satellites d'un protocole
|
||
|
||
Un composant nécessaire à la compréhension ou au fonctionnement d'un protocole reste **dans le groupe de ce protocole**, même s'il n'est pas lui-même l'AMM/DEX principal.
|
||
|
||
Exemples :
|
||
|
||
```text
|
||
Meteora
|
||
+ vaults nécessaires
|
||
+ fee/state programs nécessaires
|
||
+ positions/bin arrays/auxiliaires
|
||
|
||
Pump
|
||
+ fee program
|
||
+ launch/bonding/pool/state auxiliaire
|
||
```
|
||
|
||
Même principe pour Raydium, Orca et les futurs protocoles.
|
||
|
||
La catégorie `trading-adjacent` ne sert jamais de poubelle pour reporter les satellites d'un protocole déjà ciblé.
|
||
|
||
`trading-adjacent` désigne des programmes indépendants utiles au trading : oracles, vesting/locks indépendants, lifecycle token, signaux/risk ou autres capacités transversales.
|
||
|
||
## 14. Market Desk progressive
|
||
|
||
Une petite application marché spécialisée doit apparaître **après le premier ensemble Meteora/Raydium/Pump/Orca**, avant le routing si le vertical slice DEX fournit déjà suffisamment de données utiles.
|
||
|
||
Nom candidat actuel :
|
||
|
||
```text
|
||
ksp-app-market-desk
|
||
```
|
||
|
||
La V1 pourra visualiser notamment :
|
||
|
||
- tokens ;
|
||
- pools/markets ;
|
||
- protocoles ;
|
||
- liquidité ;
|
||
- swaps/trades ;
|
||
- volumes ;
|
||
- prix ;
|
||
- OHLC/candles ;
|
||
- activité récente/live lorsque disponible ;
|
||
- provenance/diagnostics utiles.
|
||
|
||
L'application consomme les faits KSP normalisés/spécialisés. Elle ne réimplémente pas un client Meteora/Raydium/Pump/Orca dans l'UI.
|
||
|
||
Les OHLC appartiennent aux matérialisations/projections SPECIALIZED : l'application les lit ; elle ne reconstruit pas toutes les candles à chaque rendu.
|
||
|
||
Après Jupiter/OKX, la même application est enrichie avec :
|
||
|
||
- routes ;
|
||
- legs ;
|
||
- DEX utilisés ;
|
||
- quote vs execution lorsque disponible ;
|
||
- fees/slippage ;
|
||
- activité cross-DEX/routée.
|
||
|
||
Plus tard elle pourra accueillir trading-adjacent, anomalies, indicateurs et outputs ML sans devenir prématurément l'application globale de KSP.
|
||
|
||
## 15. Nouvelle trajectoire `0.3.x+`
|
||
|
||
### `0.3.x` — RAW / acquisition persistée
|
||
|
||
Début actuellement retenu :
|
||
|
||
```text
|
||
0.3.1 ksp-store-api + ksp-store-lib — modèles/persistence RAW uniquement
|
||
0.3.2 ksp-interface-lib — extension des wires génériques nécessaires à acquisition/CORE
|
||
0.3.3 ksp-job-api + ksp-job-backfill
|
||
0.3.4 application spécialisée de backfill
|
||
```
|
||
|
||
La suite de `0.3.x` doit terminer la couche RAW avec les workers/services/apps utiles avant l'ouverture de CORE.
|
||
|
||
`0.3.1` ne doit pas introduire prématurément les tables DECODE/SPECIALIZED.
|
||
|
||
### Série suivante — CORE
|
||
|
||
Après RAW :
|
||
|
||
```text
|
||
RAW -> CORE normalization
|
||
persistence CORE
|
||
replay RAW -> CORE
|
||
worker/service CORE
|
||
application de contrôle CORE
|
||
```
|
||
|
||
Cette couche reste indépendante des decoders Program.
|
||
|
||
### Séries suivantes — vertical slices DECODE/SPECIALIZED/EXECUTION
|
||
|
||
À partir de Solana Core Programs puis SPL/Metadata/Anchor/DEX, les séries seront découpées selon la taille réelle de chaque groupe et la règle « une release = une session ».
|
||
|
||
Il est volontairement prématuré de figer maintenant chaque numéro jusqu'aux DEX.
|
||
|
||
## 16. Matrice synthétique de décision
|
||
|
||
| Capacité | Source bot3 | Statut | Propriétaire KSP | Release candidate |
|
||
|---------------------------------|---------------------------------|----------------------|----------------------------------------|------------------------|
|
||
| HTTP JSON-RPC standard | `ks-onchain-transport` | refondre | `ksp-onchain-transport-lib` | `0.2.1` |
|
||
| Config transport standard | `ks-config` transport | adapter/refondre | `ksp-config-lib` -> contrats Transport | `0.2.1` |
|
||
| Pools/rôles HTTP | `ks-onchain-transport` | reprendre/adapter | `ksp-onchain-transport-lib` | `0.2.1` |
|
||
| Wallet natif | `ks-wallet` | adapter/refondre | `ksp-wallet-lib` | `0.2.2` |
|
||
| `.kswallet` | bot3 | abandonner comme nom | `.kspwallet` | `0.2.2` |
|
||
| Temporary wallet JSON | bot2/bot3 | abandonner | aucun | — |
|
||
| `WalletPolicy` | `ks-wallet` | déplacer/refondre | execution policy | plus tard |
|
||
| Wallet Desk | desktop bot3 dispersé | refondre | `ksp-app-wallet-desk` | `0.2.3` |
|
||
| WebSocket standard | `ks-onchain-transport` | refondre | `ksp-onchain-transport-lib` | `0.2.4` |
|
||
| Multi-session même URL | besoin KSP | ajouter | `ksp-onchain-transport-lib` | `0.2.4` |
|
||
| Pool automatique de sessions WS | — | à démontrer | transport si besoin | IDEAS |
|
||
| Helius LaserStream WS | absent/incomplet bot3 | ajouter | `ksp-onchain-transport-lib` | `0.2.5` |
|
||
| Yellowstone gRPC | absent | ajouter | `ksp-onchain-transport-lib` | `0.2.6` |
|
||
| Providers gRPC spécifiques | absent | ajouter plus tard | adapters/capabilities Transport | IDEAS/futur |
|
||
| Prix SOL/USD, SOL/EUR | absent | ajouter | `ksp-offchain-transport-lib` | `0.2.7` |
|
||
| Price Desk | absent | ajouter | app spécialisée | `0.2.8` |
|
||
| Wire officiel | dispersé dans `ks-lib`/deps | refondre | `ksp-interface-lib` | `0.2.9` |
|
||
| API wire publique | absent comme frontière claire | ajouter | `ksp-interface-lib` | `0.2.9` |
|
||
| Program extension contract | `ks-lib` decoder/executor | refondre | `ksp-program-api` | `0.2.10` |
|
||
| Store RAW | `ks-store` | refondre | `ksp-store-api`/`ksp-store-lib` | `0.3.1` |
|
||
| Backfill | bot3 pipelines/jobs historiques | refondre | `ksp-job-api` + job concret | `0.3.3` |
|
||
| Market Desk | absent comme app KSP dédiée | ajouter | app spécialisée | après DEX prioritaires |
|
||
|
||
## 17. Clôture de `0.2.0`
|
||
|
||
`pre.001` a ouvert la méthode et la cartographie.
|
||
|
||
`pre.002` a fixé la direction fonctionnelle principale de `0.2.x`, la stratégie RAW/CORE/DECODE/SPECIALIZED, la progression verticale Program, le dimensionnement de session et le premier prompt `0.2.1`.
|
||
|
||
`pre.003` est la **dernière prerelease planifiée de `0.2.0`**. Elle réalise l'audit de cohérence final, corrige les règles résiduelles supersédées, complète les fiches de release demandées par le prompt d'ouverture, préserve les TODO bot3 utiles et finalise le prompt `0.2.1`.
|
||
|
||
Aucune `pre.004` n'est prévue. Elle ne serait créée que si la validation de `pre.003` révélait un nouveau défaut ou une omission substantielle qui ne peut pas être honnêtement corrigée dans `rel.001`.
|
||
|
||
`0.2.0-rel.001` publie le cadrage sans nouvelle décision architecturale :
|
||
|
||
- `workspace.package.version = 0.2.0` ;
|
||
- `0.2.0` est marqué stable dans ROADMAP/indices/plans ;
|
||
- `CHANGELOG.md` reçoit l'entrée stable `0.2.0` ;
|
||
- `deltas/0.2.0/rel.001.md` enregistre la publication ;
|
||
- les validations finales de `pre.003` communiquées par le user sont reportées dans la matrice de clôture ;
|
||
- le commit attendu est `v0.2.0-rel.001`, puis le tag stable Git `v0.2.0` ;
|
||
- le prompt `0.2.1` reste inchangé et devient le prochain point d'entrée après le tag stable.
|
||
|
||
La matrice de clôture durable est `docs/validation/002-V0_2_0_SERIES_PLANNING.md`.
|
||
|
||
## 18. Première release fonctionnelle décidée : `0.2.1`
|
||
|
||
La première release fonctionnelle de la série est désormais :
|
||
|
||
```text
|
||
0.2.1 — ksp-onchain-transport-lib / Solana HTTP foundation
|
||
```
|
||
|
||
Sa mission est de fournir la première frontière réseau Solana KSP réellement exploitable par Wallet, applications futures, acquisition RAW et execution technique ultérieure.
|
||
|
||
Le prompt finalisé est :
|
||
|
||
```text
|
||
prompts/006-V0_2_1_START_PROMPT.md
|
||
```
|
||
|
||
Son contenu est finalisé par `0.2.0-pre.003`. Il devient le prompt de reprise applicable dès publication/tag stable de `v0.2.0`.
|