v0.2.10-pre.005
This commit is contained in:
10
CHANGELOG.md
10
CHANGELOG.md
@@ -1,8 +1,16 @@
|
|||||||
<!-- file: CHANGELOG.md -->
|
<!-- file: CHANGELOG.md -->
|
||||||
<!-- version: 13 -->
|
<!-- version: 14 -->
|
||||||
|
|
||||||
# Changelog KSP
|
# Changelog KSP
|
||||||
|
|
||||||
|
## 0.2.10 — OrbitFlare Yellowstone gRPC — 2026-08-25
|
||||||
|
|
||||||
|
`0.2.10` ajoute OrbitFlare comme provider Yellowstone gRPC sur le moteur N1 et le standard N2 acquis dans `0.2.9`, sans modifier le moteur gRPC ni créer de façade provider inutile. L'audit et le smoke live ont établi le contrat réel du service Solana Free Devnet : endpoint `http://devnet.rpc.orbitflare.com:10000`, authentification par metadata gRPC secrète `x-token` portant la License Key OrbitFlare, et émission du Ping Yellowstone standard. Config Transport V3 représente ce provider avec `provider = orbitflare`, `cluster = devnet`, `protocol = solana_yellowstone` et `secret_metadata`, tandis que `.env.example` inventorie `KSP_SECRET_ORBITFLARE_DEVNET_GRPC_X_TOKEN` sans valeur réelle.
|
||||||
|
|
||||||
|
La première tentative live sans metadata a volontairement échoué avec `Unauthenticated`, ce qui a conduit à `pre.002-fix.001` après audit des sources OrbitFlare actuelles. Le smoke corrigé reçoit la License Key uniquement par stdin opérateur, ouvre `Subscribe`, observe un Slot non nul et un `SubscribeUpdate::Ping`, puis ferme la session proprement. Le même smoke est repassé au gate technique final `pre.003`. La clôture conserve donc N1/N2 inchangés, n'ajoute ni heartbeat OrbitFlare, ni SDK provider, ni Config V4, et confirme que la réponse automatique au Ping standard existante suffit.
|
||||||
|
|
||||||
|
Le gate final conserve l'ensemble du workspace vert : audits Rust/Markdown, `cargo check`, Clippy, tests Config et Transport, `cargo test --workspace`, canaris de dépendances et graphes Cargo. Helius LaserStream gRPC, audité comme largement wire-compatible Yellowstone mais non raisonnablement live-testable sans abonnement payant, est reporté dans les TODO provider sans numéro de release. La séquence active passe donc à `0.2.11 — off-chain price transport`; `prompts/016-V0_2_11_START_PROMPT.md` l'ouvre exclusivement depuis le tag stable `v0.2.10` avec audit actuel des sources de prix, de leurs sémantiques et de leur testabilité avant toute implémentation lourde.
|
||||||
|
|
||||||
Ce changelog résume uniquement les releases KSP considérées comme stables, dans l'ordre chronologique décroissant. Les détails de chaque livraison restent dans `deltas/`.
|
Ce changelog résume uniquement les releases KSP considérées comme stables, dans l'ordre chronologique décroissant. Les détails de chaque livraison restent dans `deltas/`.
|
||||||
|
|
||||||
## 0.2.9 — Yellowstone gRPC standard/provider-neutral — 2026-08-24
|
## 0.2.9 — Yellowstone gRPC standard/provider-neutral — 2026-08-24
|
||||||
|
|||||||
@@ -1,12 +1,12 @@
|
|||||||
# file: Cargo.toml
|
# file: Cargo.toml
|
||||||
# version: 266
|
# version: 267
|
||||||
|
|
||||||
[workspace]
|
[workspace]
|
||||||
resolver = "3"
|
resolver = "3"
|
||||||
members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"]
|
members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"]
|
||||||
|
|
||||||
[workspace.package]
|
[workspace.package]
|
||||||
version = "0.2.10-pre.4"
|
version = "0.2.10-pre.5"
|
||||||
edition = "2024"
|
edition = "2024"
|
||||||
license = "MIT"
|
license = "MIT"
|
||||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||||
|
|||||||
14
ROADMAP.md
14
ROADMAP.md
@@ -1,5 +1,5 @@
|
|||||||
<!-- file: ROADMAP.md -->
|
<!-- file: ROADMAP.md -->
|
||||||
<!-- version: 86 -->
|
<!-- version: 87 -->
|
||||||
|
|
||||||
# Roadmap KSP
|
# Roadmap KSP
|
||||||
|
|
||||||
@@ -54,15 +54,15 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U
|
|||||||
- [X] `0.2.7` — WebSocket Solana standard stable : 9 familles subscribe/unsubscribe typées (18/18 opérations), sessions physiques multiples explicites, subscriptions logiques typées, lifecycle/reconnect/resubscribe/backpressure/shutdown bornés, Config V2, non-régression HTTP 52+14, compliance finale, smoke WebSocket Devnet et audit de dépendances validés ; publication `rel.001` et prompt `0.2.8` prêts.
|
- [X] `0.2.7` — WebSocket Solana standard stable : 9 familles subscribe/unsubscribe typées (18/18 opérations), sessions physiques multiples explicites, subscriptions logiques typées, lifecycle/reconnect/resubscribe/backpressure/shutdown bornés, Config V2, non-régression HTTP 52+14, compliance finale, smoke WebSocket Devnet et audit de dépendances validés ; publication `rel.001` et prompt `0.2.8` prêts.
|
||||||
- [X] `0.2.8` — Helius LaserStream WebSocket stable : façade provider dédiée sur l’actor WebSocket partagé, sept familles standard réutilisées (`account/logs/program/root/signature/slot/slotsUpdates`) + `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s Helius-only, Config V2/secrets redacted, lifecycle adversarial, compliance HTTP 52+14 / Standard WS 18/18 et graphes Cargo finaux validés ; prompt `0.2.9` prêt.
|
- [X] `0.2.8` — Helius LaserStream WebSocket stable : façade provider dédiée sur l’actor WebSocket partagé, sept familles standard réutilisées (`account/logs/program/root/signature/slot/slotsUpdates`) + `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s Helius-only, Config V2/secrets redacted, lifecycle adversarial, compliance HTTP 52+14 / Standard WS 18/18 et graphes Cargo finaux validés ; prompt `0.2.9` prêt.
|
||||||
- [X] `0.2.9` — Yellowstone gRPC standard/provider-neutral stable : moteur Tonic/Protobuf KSP partagé, sept unary standard retenues, `Subscribe` bidi et neuf variantes d’update, lifecycle/backpressure/reconnect/replay bornés sans promesse lossless, Config Transport V3 backward V1/V2 avec provider/protocol séparés, profils PublicNode Mainnet/Testnet authentifiés par `x-token`, smoke live `Subscribe -> Slot` 2/2 PASS et graphes Cargo finaux inspectés ; `SubscribeDeshred` reste hors scope.
|
- [X] `0.2.9` — Yellowstone gRPC standard/provider-neutral stable : moteur Tonic/Protobuf KSP partagé, sept unary standard retenues, `Subscribe` bidi et neuf variantes d’update, lifecycle/backpressure/reconnect/replay bornés sans promesse lossless, Config Transport V3 backward V1/V2 avec provider/protocol séparés, profils PublicNode Mainnet/Testnet authentifiés par `x-token`, smoke live `Subscribe -> Slot` 2/2 PASS et graphes Cargo finaux inspectés ; `SubscribeDeshred` reste hors scope.
|
||||||
- [ ] `0.2.10` — Ajouter l’intégration Yellowstone gRPC OrbitFlare sur le moteur/standard acquis, avec audit explicite des auth/capabilities/restrictions/extensions et Devnet comme cible gratuite prioritaire.
|
- [X] `0.2.10` — OrbitFlare Yellowstone gRPC stable : profil Config V3 Devnet, License Key injectée comme metadata secrète `x-token`, smoke live `Subscribe -> Slot + Ping` validé deux fois, sans modification du moteur N1/N2 ni heartbeat provider.
|
||||||
- [ ] `0.2.11` — Ajouter l’intégration Helius LaserStream gRPC sur le moteur Yellowstone partagé, avec audit de compatibilité/replay/auth/extensions, sans confondre cette surface avec LaserStream WebSocket.
|
- [ ] `0.2.11` — Introduire `ksp-offchain-transport-lib` avec un premier lecteur de prix provider-neutral, au minimum SOL/USD et SOL/EUR, après audit actuel des sémantiques provider et de la testabilité live.
|
||||||
- [ ] `0.2.12` — Introduire `ksp-offchain-transport-lib` avec un premier lecteur de prix, au minimum SOL/USD et SOL/EUR.
|
- [ ] `0.2.12` — Introduire une petite application desk de visualisation/validation des prix offchain, puis intégrer cette capacité dans `ksp-app-wallet-desk` sans dupliquer la logique de récupération/normalisation possédée par le composant spécialisé.
|
||||||
- [ ] `0.2.13` — Introduire une petite application desk de visualisation/validation des prix offchain, puis intégrer cette capacité dans `ksp-app-wallet-desk` sans dupliquer la logique de récupération/normalisation possédée par le composant spécialisé.
|
- [ ] `0.2.13` — Introduire la première surface de `ksp-interface-lib`, comprenant une API wire publique utilisable par les implémentations officielles et externes.
|
||||||
- [ ] `0.2.14` — Introduire la première surface de `ksp-interface-lib`, comprenant une API wire publique utilisable par les implémentations officielles et externes.
|
- [ ] `0.2.14` — Introduire `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet.
|
||||||
- [ ] `0.2.15` — Introduire `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet.
|
|
||||||
|
|
||||||
### TODO/IDEAS — providers Yellowstone non planifiés
|
### TODO/IDEAS — providers Yellowstone non planifiés
|
||||||
|
|
||||||
|
- [ ] **TODO** — Helius LaserStream gRPC : réauditer lorsque l'accès live gRPC est raisonnablement disponible ; conserver N1/N2 Yellowstone inchangés, vérifier auth/endpoints/Subscribe/Ping/replay/from_slot/erreurs provider et traiter les preprocessed transactions comme extension Helius séparée.
|
||||||
- [ ] **TODO** — eRPC : réauditer accès, auth/IP policy, capabilities et produits complémentaires avant toute décision d’implémentation.
|
- [ ] **TODO** — eRPC : réauditer accès, auth/IP policy, capabilities et produits complémentaires avant toute décision d’implémentation.
|
||||||
- [ ] **TODO** — Triton : réauditer la frontière Yellowstone upstream / extensions Triton, notamment Deshred et futures extensions.
|
- [ ] **TODO** — Triton : réauditer la frontière Yellowstone upstream / extensions Triton, notamment Deshred et futures extensions.
|
||||||
- [ ] **TODO** — Alchemy : réauditer auth, replay, limites et capabilities Yellowstone avant toute intégration.
|
- [ ] **TODO** — Alchemy : réauditer auth, replay, limites et capabilities Yellowstone avant toute intégration.
|
||||||
|
|||||||
132
deltas/0.2.10/pre.005.md
Normal file
132
deltas/0.2.10/pre.005.md
Normal file
@@ -0,0 +1,132 @@
|
|||||||
|
<!-- file: deltas/0.2.10/pre.005.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Delta `0.2.10-pre.005` — préparation de publication minimale
|
||||||
|
|
||||||
|
## 1. Base
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.10-pre.004
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette tranche est exclusivement le couloir de préparation de publication. Elle ne modifie aucun code, test, schema, config, README, USAGE, plan, validation ou règle normative.
|
||||||
|
|
||||||
|
## 2. Gate `pre.003` et réconciliation `pre.004`
|
||||||
|
|
||||||
|
Le gate technique final `pre.003` a confirmé :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Rust workspace audit PASS
|
||||||
|
Markdown audit PASS
|
||||||
|
cargo check --workspace PASS
|
||||||
|
cargo clippy --workspace --all-targets PASS
|
||||||
|
cargo test --workspace PASS
|
||||||
|
OrbitFlare live Subscribe -> Slot+Ping PASS en 5.19 s
|
||||||
|
graphes Cargo inspectés
|
||||||
|
```
|
||||||
|
|
||||||
|
`pre.004` a ensuite réconcilié les documents durables : plan/validation OrbitFlare, README/USAGE Transport, index documentaire et séquence fonctionnelle. Helius LaserStream gRPC a été reporté dans les TODO faute d'accès live raisonnable sans abonnement payant, sans remise en cause de sa compatibilité wire Yellowstone largement observée.
|
||||||
|
|
||||||
|
## 3. Version technique
|
||||||
|
|
||||||
|
```text
|
||||||
|
workspace.package.version = 0.2.10-pre.5
|
||||||
|
```
|
||||||
|
|
||||||
|
La modification est mécanique ; aucune sémantique runtime ne change.
|
||||||
|
|
||||||
|
## 4. `CHANGELOG.md`
|
||||||
|
|
||||||
|
Le changelog stable est préparé pour `0.2.10 — OrbitFlare Yellowstone gRPC` avec les faits consolidés :
|
||||||
|
|
||||||
|
```text
|
||||||
|
N1/N2 Yellowstone inchangés
|
||||||
|
Config V3 orbitflare_devnet
|
||||||
|
x-token = License Key via secret_metadata
|
||||||
|
premier live sans metadata -> Unauthenticated
|
||||||
|
fix auth documenté
|
||||||
|
live Subscribe -> Slot + standard Ping PASS
|
||||||
|
second live final PASS
|
||||||
|
aucun heartbeat/provider SDK/Config V4 ajouté
|
||||||
|
workspace + graphes finaux verts
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. `ROADMAP.md`
|
||||||
|
|
||||||
|
`0.2.10` passe à l'état réalisé. Helius LaserStream gRPC quitte la séquence numérotée et rejoint les TODO Yellowstone. La séquence active devient :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.11 off-chain price transport
|
||||||
|
0.2.12 Price Desk + intégration prix Wallet Desk
|
||||||
|
0.2.13 interface/wire foundation
|
||||||
|
0.2.14 program-api foundation
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Audit préparatoire de la future `0.2.11`
|
||||||
|
|
||||||
|
Avant de rédiger le prompt suivant, un audit externe rapide au 2026-08-25 a comparé plusieurs familles de sources :
|
||||||
|
|
||||||
|
```text
|
||||||
|
CoinGecko agrégateur, REST Demo, multi quote USD/EUR
|
||||||
|
Jupiter V3 prix Solana heuristique issu des swaps, USD seulement
|
||||||
|
Pyth Hermes oracle, REST/SSE, publish_time/confidence, auth en transition immédiate
|
||||||
|
Birdeye market data Solana, spot/batch/historique, API key
|
||||||
|
DexScreener prix DEX par pair/pool, accès public courant
|
||||||
|
```
|
||||||
|
|
||||||
|
Ce snapshot ne choisit pas le provider. Il démontre surtout que les sémantiques diffèrent et que `0.2.11-pre.001` doit auditer/choisir explicitement le contrat prix, le modèle numérique, la fraîcheur et le provider initial avant code lourd.
|
||||||
|
|
||||||
|
Pyth annonce un changement d'authentification le 2026-08-26 à 16:00 UTC ; le prompt exige donc un réaudit immédiat de Pyth à l'ouverture et interdit de figer le snapshot de `pre.005`.
|
||||||
|
|
||||||
|
## 7. Prompt `0.2.11`
|
||||||
|
|
||||||
|
Ajout de :
|
||||||
|
|
||||||
|
```text
|
||||||
|
prompts/016-V0_2_11_START_PROMPT.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Le prompt ouvre `0.2.11 — Off-chain price transport` uniquement depuis `v0.2.10` et impose `pre.001 = lecture + audit actuel providers + matrice sémantique + numeric model + threat model + sizing + planification`.
|
||||||
|
|
||||||
|
Le scope initial reste volontairement borné :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-offchain-transport-lib
|
||||||
|
prix SOL/USD + SOL/EUR
|
||||||
|
premier provider live-testable sans abonnement payant dédié
|
||||||
|
Config -> Off-chain Transport
|
||||||
|
pas de Price Desk
|
||||||
|
pas de Wallet Desk
|
||||||
|
pas d'OHLCV/historique/quotes/metadata/multi-provider complexe
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. Fichiers modifiés/ajoutés
|
||||||
|
|
||||||
|
```text
|
||||||
|
Cargo.toml
|
||||||
|
CHANGELOG.md
|
||||||
|
ROADMAP.md
|
||||||
|
prompts/016-V0_2_11_START_PROMPT.md
|
||||||
|
deltas/0.2.10/pre.005.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun autre fichier ne doit changer dans cette tranche.
|
||||||
|
|
||||||
|
## 9. Gate opérateur
|
||||||
|
|
||||||
|
Comme cette tranche ne modifie aucun code/runtime/config/schema :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo fmt --all
|
||||||
|
python3 scripts/audit_rust_workspace_rules.py
|
||||||
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.10
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets
|
||||||
|
cargo test --workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun smoke live ni `cargo tree` n'est à rejouer si le delta est appliqué exactement.
|
||||||
|
|
||||||
|
## 10. Suite
|
||||||
|
|
||||||
|
Si ce gate est vert, `0.2.10-rel.001` est la seule étape restante. Elle est limitée à la mécanique de publication stable : version Cargo `0.2.10`, delta `rel.001`, commit final et tag stable `v0.2.10`, sans rattrapage technique ou documentaire.
|
||||||
878
prompts/016-V0_2_11_START_PROMPT.md
Normal file
878
prompts/016-V0_2_11_START_PROMPT.md
Normal file
@@ -0,0 +1,878 @@
|
|||||||
|
<!-- file: prompts/016-V0_2_11_START_PROMPT.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Prompt de démarrage `0.2.11` — Off-chain price transport
|
||||||
|
|
||||||
|
## 1. Identité de la release et base exacte requise
|
||||||
|
|
||||||
|
La base attendue est **exclusivement** la release stable :
|
||||||
|
|
||||||
|
```text
|
||||||
|
v0.2.10
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne pas ouvrir `0.2.11` depuis `0.2.10-pre.*`, depuis un ZIP intermédiaire ou depuis un souvenir de session. Si une archive opérateur de `v0.2.10` est fournie, cette archive réelle est l'autorité première devant les snippets, anciens prompts, anciens ZIP et mémoire de conversation.
|
||||||
|
|
||||||
|
La release à ouvrir est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.11 — Off-chain price transport
|
||||||
|
```
|
||||||
|
|
||||||
|
La première tranche est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.11-pre.001
|
||||||
|
```
|
||||||
|
|
||||||
|
`pre.001` est obligatoirement une tranche **lecture + audit externe actuel + comparaison des sémantiques de prix + brainstorming + threat model + sizing + planification**. Elle ne commence pas par coder un client CoinGecko, Jupiter, Pyth, Birdeye ou DexScreener, ni par figer un type numérique ou une API provider-neutral avant l'audit.
|
||||||
|
|
||||||
|
À l'ouverture, vérifier au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
git describe / tag stable si metadata Git disponible
|
||||||
|
workspace.package.version = 0.2.10
|
||||||
|
deltas/0.2.10/rel.001.md présent
|
||||||
|
prompts/016-V0_2_11_START_PROMPT.md présent
|
||||||
|
```
|
||||||
|
|
||||||
|
État fonctionnel attendu depuis `v0.2.10` :
|
||||||
|
|
||||||
|
```text
|
||||||
|
HTTP Solana standard 52/52 current typed + 14 historiques
|
||||||
|
WebSocket Solana standard 9 familles / 18 opérations
|
||||||
|
Helius LaserStream WebSocket façade provider existante
|
||||||
|
Yellowstone gRPC N1/N2 moteur + standard provider-neutral stables
|
||||||
|
PublicNode Yellowstone Mainnet/Testnet validés
|
||||||
|
OrbitFlare Yellowstone Devnet validé avec License Key x-token
|
||||||
|
Config Transport V3 backward-readable
|
||||||
|
Wallet .kspwallet V1/V2 + Wallet Desk stables
|
||||||
|
ksp-offchain-transport-lib absent au démarrage
|
||||||
|
Price Desk hors scope de cette release
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Mission et résultat attendu
|
||||||
|
|
||||||
|
`0.2.11` doit créer `ksp-offchain-transport-lib` à partir d'un premier besoin métier réel : **lire des prix off-chain**, au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
SOL/USD
|
||||||
|
SOL/EUR
|
||||||
|
```
|
||||||
|
|
||||||
|
La release doit séparer le contrat KSP « lire un prix » de l'API propriétaire du premier provider retenu, sans créer de `ksp-offchain-transport-api` globale ni de trait universel artificiel couvrant prix, metadata, quotes, IPFS, Arweave et autres domaines hétérogènes.
|
||||||
|
|
||||||
|
Résultat attendu à la clôture :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-offchain-transport-lib créée
|
||||||
|
surface prix publique petite, typée et documentée
|
||||||
|
sémantique du prix explicitement définie
|
||||||
|
représentation numérique auditée et non choisie par facilité
|
||||||
|
settings runtime publics possédés par Off-chain Transport
|
||||||
|
premier provider réellement audité et live-testable
|
||||||
|
SOL/USD + SOL/EUR disponibles selon un contrat explicite
|
||||||
|
provenance/fraîcheur/absence de prix représentées sans ambiguïté
|
||||||
|
timeout + erreurs + observabilité sûrs
|
||||||
|
Config -> Off-chain Transport composé sans dépendance inverse
|
||||||
|
aucun secret provider dans code/logs/debug
|
||||||
|
smoke live opt-in contre un accès non payant raisonnable
|
||||||
|
README/USAGE + plan/validation finalisés
|
||||||
|
```
|
||||||
|
|
||||||
|
Le principe directeur est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
contrat prix KSP minimal
|
||||||
|
!=
|
||||||
|
modèle universel de toute donnée de marché
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Sources de vérité internes obligatoires — ordre de lecture
|
||||||
|
|
||||||
|
### 3.1 Règles globales
|
||||||
|
|
||||||
|
Lire d'abord :
|
||||||
|
|
||||||
|
```text
|
||||||
|
RULES.md
|
||||||
|
docs/000-README.md
|
||||||
|
|
||||||
|
docs/rules/RULES_GENERAL.md
|
||||||
|
docs/rules/RULES_KSP.md
|
||||||
|
docs/rules/RULES_RUST.md
|
||||||
|
docs/rules/RULES_DEPENDENCIES.md
|
||||||
|
docs/rules/RULES_DOCUMENTATION.md
|
||||||
|
docs/rules/FILE_CONTRACTS.md
|
||||||
|
docs/rules/VERSION_WORKFLOW.md
|
||||||
|
docs/rules/PROMPT_STRUCTURE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Rappels directement applicables :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Rust 2024
|
||||||
|
unsafe / unwrap / expect / panic interdits selon les règles KSP
|
||||||
|
retours explicites et audit structurel KSP
|
||||||
|
third-party deps déclarées une seule fois au workspace
|
||||||
|
ksp-logging-lib propriétaire du tracing
|
||||||
|
ksp-config-lib propriétaire config/env/secrets
|
||||||
|
aucune lecture directe de KSP_* par Off-chain Transport
|
||||||
|
pas de pub mod ; exports crate-root explicites
|
||||||
|
```
|
||||||
|
|
||||||
|
Après toute modification Rust :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo fmt --all
|
||||||
|
python3 scripts/audit_rust_workspace_rules.py
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour les Markdown touchés :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/audit_markdown_tables.py <fichiers-ou-répertoires-ciblés>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 Architecture durable à préserver
|
||||||
|
|
||||||
|
Lire ensuite :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/architecture/000-README.md
|
||||||
|
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
|
||||||
|
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||||
|
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||||
|
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Frontières acquises :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-offchain-transport-lib est distinct de ksp-onchain-transport-lib
|
||||||
|
aucune ksp-offchain-transport-api globale
|
||||||
|
Off-chain Transport -X-> Config
|
||||||
|
Config -> Off-chain Transport autorisé via adapter/composition
|
||||||
|
Off-chain Transport peut contenir à terme plusieurs modules/APIs distincts
|
||||||
|
la première surface engagée est le prix
|
||||||
|
metadata HTTP/IPFS/Arweave et quotes attendent leur besoin réel
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 Plans et historique fonctionnel
|
||||||
|
|
||||||
|
Lire :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||||
|
docs/plans/007-V0_2_0_SERIES_PLANNING.md
|
||||||
|
docs/plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md
|
||||||
|
|
||||||
|
docs/validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md
|
||||||
|
deltas/0.2.10/rel.001.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Références historiques utiles, sans reprendre leurs anciens numéros de release :
|
||||||
|
|
||||||
|
```text
|
||||||
|
sections Off-chain price transport de docs/plans/007-V0_2_0_SERIES_PLANNING.md
|
||||||
|
ancienne préparation 0.2.x dans prompts/014-V0_2_9_START_PROMPT.md
|
||||||
|
TODO Wallet Desk demandant la future réutilisation de la capacité prix
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 Code réel à inventorier
|
||||||
|
|
||||||
|
Avant design, inspecter au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Cargo.toml workspace
|
||||||
|
crates/ksp-core-lib
|
||||||
|
crates/ksp-logging-lib
|
||||||
|
crates/ksp-config-lib
|
||||||
|
crates/ksp-onchain-transport-lib uniquement comme référence de patterns, pas comme dépendance automatique
|
||||||
|
.env.example
|
||||||
|
config/
|
||||||
|
config/schemas/
|
||||||
|
```
|
||||||
|
|
||||||
|
Vérifier notamment les primitives déjà disponibles : `reqwest`, `serde`, `serde_json`, `tokio`, `http`, les contrats Error KSP et les adapters Config existants. Ne pas ajouter un SDK provider si `reqwest` + types KSP suffisent.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Sources externes à réauditer en `pre.001`
|
||||||
|
|
||||||
|
La fraîcheur est importante. Les faits ci-dessous sont un snapshot informatif au **2026-08-25**, jamais un contrat à recopier sans vérification.
|
||||||
|
|
||||||
|
### 4.1 CoinGecko
|
||||||
|
|
||||||
|
Sources primaires :
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://docs.coingecko.com/reference/simple-price
|
||||||
|
https://docs.coingecko.com/docs/data-delivery-methods
|
||||||
|
https://docs.coingecko.com/reference/endpoint-overview
|
||||||
|
```
|
||||||
|
|
||||||
|
Snapshot :
|
||||||
|
|
||||||
|
```text
|
||||||
|
REST disponible y compris sur plan Demo
|
||||||
|
/simple/price accepte plusieurs vs_currencies, dont usd et eur
|
||||||
|
API Demo utilise typiquement x-cg-demo-api-key
|
||||||
|
la sémantique est celle d'un agrégateur de marché CoinGecko, pas d'un oracle on-chain
|
||||||
|
```
|
||||||
|
|
||||||
|
Vérifier limites réelles, auth, fraîcheur/cache, IDs d'actifs, disponibilité SOL/USD et SOL/EUR et conditions d'usage.
|
||||||
|
|
||||||
|
### 4.2 Jupiter Price API V3
|
||||||
|
|
||||||
|
Sources primaires :
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://developers.jup.ag/docs/price
|
||||||
|
https://developers.jup.ag/docs/api-reference/price
|
||||||
|
```
|
||||||
|
|
||||||
|
Snapshot :
|
||||||
|
|
||||||
|
```text
|
||||||
|
GET https://api.jup.ag/price/v3
|
||||||
|
x-api-key requis
|
||||||
|
jusqu'à 50 mint addresses par requête
|
||||||
|
usdPrice unique par token
|
||||||
|
prix heuristique dérivé des swaps/liquidité/activité Solana
|
||||||
|
V2 deprecated
|
||||||
|
```
|
||||||
|
|
||||||
|
Jupiter est naturellement intéressant pour les SPL tokens mais son `usdPrice` ne satisfait pas à lui seul SOL/EUR. Ne pas introduire une conversion EUR externe silencieuse simplement pour forcer ce provider en premier.
|
||||||
|
|
||||||
|
### 4.3 Pyth Hermes
|
||||||
|
|
||||||
|
Sources primaires :
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://docs.pyth.network/price-feeds/core/how-pyth-works/hermes
|
||||||
|
https://docs.pyth.network/price-feeds/core/fetch-price-updates
|
||||||
|
https://docs.pyth.network/price-feeds/core/api-instances-and-providers/hermes
|
||||||
|
```
|
||||||
|
|
||||||
|
Snapshot très sensible à la date :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Hermes expose REST + SSE
|
||||||
|
prix = entier + exponent + confidence + publish_time
|
||||||
|
endpoint public soumis à rate limit
|
||||||
|
une transition Pyth Core est annoncée le 2026-08-26 à 16:00 UTC
|
||||||
|
authentication API key devient obligatoire selon la documentation courante
|
||||||
|
```
|
||||||
|
|
||||||
|
Comme cette transition intervient immédiatement après la préparation de ce prompt, `pre.001` doit **réauditer Pyth en priorité** et ne jamais utiliser le snapshot ci-dessus comme vérité actuelle.
|
||||||
|
|
||||||
|
Pyth représente une sémantique oracle différente d'un prix DEX/agrégateur. Cette différence doit rester visible dans le design.
|
||||||
|
|
||||||
|
### 4.4 Birdeye
|
||||||
|
|
||||||
|
Sources primaires :
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://docs.birdeye.so/reference/get-defi-price
|
||||||
|
https://docs.birdeye.so/reference/get-defi-multi_price
|
||||||
|
https://docs.birdeye.so/reference/birdeye-api-authentication
|
||||||
|
```
|
||||||
|
|
||||||
|
Snapshot :
|
||||||
|
|
||||||
|
```text
|
||||||
|
X-API-KEY requis
|
||||||
|
x-chain = solana
|
||||||
|
spot single + batch jusqu'à 100 tokens
|
||||||
|
prix, liquidité et surfaces historiques/OHLCV plus larges disponibles
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne pas élargir `0.2.11` vers OHLCV/historique simplement parce que le provider les offre.
|
||||||
|
|
||||||
|
### 4.5 DexScreener
|
||||||
|
|
||||||
|
Source primaire :
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://docs.dexscreener.com/api/reference
|
||||||
|
```
|
||||||
|
|
||||||
|
Snapshot :
|
||||||
|
|
||||||
|
```text
|
||||||
|
API publique sans credential pour les endpoints DEX courants
|
||||||
|
prix porté par des paires/pools
|
||||||
|
jusqu'à 30 token addresses sur l'endpoint tokens courant
|
||||||
|
limite documentée autour de 300 requêtes/minute pour les endpoints DEX/pairs
|
||||||
|
```
|
||||||
|
|
||||||
|
La sémantique est pair/pool/DEX. Un `priceUsd` DexScreener ne doit pas être confondu sans audit avec un prix oracle ou le prix agrégé canonique d'un token.
|
||||||
|
|
||||||
|
### 4.6 Autres candidats
|
||||||
|
|
||||||
|
Coinbase, Kraken, Binance, CoinMarketCap et autres sources peuvent être audités si cela aide à satisfaire SOL/USD + SOL/EUR avec un accès stable et testable. Ils ne sont pas automatiquement dans le scope.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. État validé à préserver depuis `v0.2.10`
|
||||||
|
|
||||||
|
### 5.1 Core / Logging / Config
|
||||||
|
|
||||||
|
Préserver :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Error/Result central KSP
|
||||||
|
Pubkey via Core lorsque nécessaire
|
||||||
|
Logging facade KSP uniquement
|
||||||
|
Config seul propriétaire des fichiers/env/secrets
|
||||||
|
.env.example comme inventaire versionné
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 On-chain Transport
|
||||||
|
|
||||||
|
`ksp-onchain-transport-lib` reste indépendant et inchangé sauf nécessité architecturale démontrée. `0.2.11` n'est pas l'occasion de déplacer HTTP générique Solana, WebSocket ou Yellowstone dans une abstraction réseau universelle.
|
||||||
|
|
||||||
|
### 5.3 Wallet et prochaine Price Desk
|
||||||
|
|
||||||
|
La future `0.2.12` doit pouvoir consommer la surface prix dans une Price Desk puis dans Wallet Desk sans dupliquer récupération/normalisation. Cela justifie une API publique propre dès `0.2.11`, mais **pas** une UI ou une intégration Wallet anticipée.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Décisions acquises — ne pas redébattre sans contradiction réelle
|
||||||
|
|
||||||
|
```text
|
||||||
|
nom de crate : ksp-offchain-transport-lib
|
||||||
|
aucune ksp-offchain-transport-api globale
|
||||||
|
première surface : prix
|
||||||
|
minimum fonctionnel : SOL/USD + SOL/EUR
|
||||||
|
pas de Price Desk dans 0.2.11
|
||||||
|
pas d'intégration Wallet Desk dans 0.2.11
|
||||||
|
pas de metadata HTTP/IPFS/Arweave dans cette release
|
||||||
|
pas de quotes/routing dans cette release
|
||||||
|
pas d'agrégation multi-provider complexe dans cette release
|
||||||
|
Off-chain Transport ne dépend pas de Config
|
||||||
|
Config peut adapter ses documents vers les settings publics Off-chain Transport
|
||||||
|
premier provider doit être raisonnablement live-testable sans abonnement payant dédié
|
||||||
|
```
|
||||||
|
|
||||||
|
Helius LaserStream gRPC est en TODO provider Yellowstone et ne doit pas être réintroduit dans `0.2.11`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Questions réellement ouvertes à trancher pendant `pre.001`
|
||||||
|
|
||||||
|
### 7.1 Sémantique du prix KSP
|
||||||
|
|
||||||
|
Décider ce que signifie précisément le résultat commun minimal :
|
||||||
|
|
||||||
|
```text
|
||||||
|
spot courant ou snapshot provider
|
||||||
|
base asset / quote asset
|
||||||
|
provider/source
|
||||||
|
instant de requête KSP
|
||||||
|
instant de publication/update provider lorsqu'il existe
|
||||||
|
fraîcheur/staleness
|
||||||
|
absence de prix
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne pas inventer un champ commun `confidence`, `liquidity`, `block_id` ou `market_cap` si tous les providers ne partagent pas réellement cette sémantique. Les données provider spécifiques peuvent rester dans un DTO/provider API séparé ou un sous-contrat explicitement typé.
|
||||||
|
|
||||||
|
### 7.2 Représentation numérique
|
||||||
|
|
||||||
|
Auditer explicitement :
|
||||||
|
|
||||||
|
```text
|
||||||
|
f64 interdit ou accepté seulement comme wire temporaire ?
|
||||||
|
fixed-point / decimal string / mantissa + exponent ?
|
||||||
|
arrondis
|
||||||
|
comparaisons
|
||||||
|
conversion quote currency
|
||||||
|
serialization publique
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour une future logique de trading, ne pas figer `f64` comme canon uniquement parce que certaines API renvoient un JSON number.
|
||||||
|
|
||||||
|
### 7.3 Identité des assets
|
||||||
|
|
||||||
|
Décider la forme minimale :
|
||||||
|
|
||||||
|
```text
|
||||||
|
SOL natif
|
||||||
|
mint SPL
|
||||||
|
symbol/provider id
|
||||||
|
quote fiat USD/EUR
|
||||||
|
```
|
||||||
|
|
||||||
|
Le contrat doit éviter les collisions de symboles. Si le premier provider utilise un ID propriétaire (`solana` chez CoinGecko, mint chez Jupiter/Birdeye, feed ID chez Pyth), ce mapping appartient au provider/adaptateur et ne devient pas automatiquement l'identité canonique KSP.
|
||||||
|
|
||||||
|
### 7.4 Provider initial
|
||||||
|
|
||||||
|
Comparer au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
CoinGecko Demo
|
||||||
|
Jupiter Price V3
|
||||||
|
Pyth Hermes
|
||||||
|
Birdeye
|
||||||
|
DexScreener
|
||||||
|
```
|
||||||
|
|
||||||
|
Critères :
|
||||||
|
|
||||||
|
```text
|
||||||
|
SOL/USD + SOL/EUR réalisables proprement
|
||||||
|
accès gratuit/live raisonnable
|
||||||
|
auth et secret ownership
|
||||||
|
fraîcheur et limites
|
||||||
|
batching
|
||||||
|
stabilité/documentation
|
||||||
|
sémantique du prix
|
||||||
|
surface Rust nécessaire
|
||||||
|
risque de lock-in
|
||||||
|
```
|
||||||
|
|
||||||
|
Le provider initial peut être CoinGecko si l'audit actuel confirme qu'il satisfait directement les deux quotes avec un accès Demo raisonnable. Ce n'est pas une décision pré-écrite : `pre.001` doit le démontrer.
|
||||||
|
|
||||||
|
### 7.5 Conversion SOL/EUR
|
||||||
|
|
||||||
|
Priorité : utiliser une source qui expose directement la quote EUR lorsque possible.
|
||||||
|
|
||||||
|
Si un provider ne donne que USD, ne pas calculer SOL/EUR à partir d'un FX externe non tracé. Toute dérivation doit être explicitement décidée, avec provenance complète et sans franchir le hors-périmètre multi-provider complexe.
|
||||||
|
|
||||||
|
### 7.6 HTTP, retry, cache et fraîcheur
|
||||||
|
|
||||||
|
Décider :
|
||||||
|
|
||||||
|
```text
|
||||||
|
request timeout
|
||||||
|
retry safe GET
|
||||||
|
traitement 429 / Retry-After
|
||||||
|
eventuel cache local minimal ou aucun cache
|
||||||
|
TTL/staleness contract
|
||||||
|
batch size
|
||||||
|
concurrency
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne pas copier mécaniquement le moteur de résilience on-chain si le besoin prix est plus petit. Réutiliser des patterns, pas une dépendance injustifiée.
|
||||||
|
|
||||||
|
### 7.7 Config
|
||||||
|
|
||||||
|
Auditer la forme documentaire nécessaire pour la future Price Desk :
|
||||||
|
|
||||||
|
```text
|
||||||
|
nouveau document offchain ?
|
||||||
|
extension d'un document existant ?
|
||||||
|
provider id
|
||||||
|
base URL
|
||||||
|
API key/header secret
|
||||||
|
timeouts
|
||||||
|
profil par environnement
|
||||||
|
```
|
||||||
|
|
||||||
|
Toute variable ajoutée doit respecter `KSP_SECRET_*` / `KSP_PUBLIC_*` et être inventoriée dans `.env.example`.
|
||||||
|
|
||||||
|
### 7.8 Live smoke
|
||||||
|
|
||||||
|
Définir un smoke opt-in qui :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ne hardcode aucun secret
|
||||||
|
n'affiche aucun secret
|
||||||
|
interroge réellement SOL/USD + SOL/EUR
|
||||||
|
vérifie valeurs positives/plausibles sans figer un cours exact
|
||||||
|
vérifie les identités/quotes/provenance
|
||||||
|
reste borné par timeout
|
||||||
|
```
|
||||||
|
|
||||||
|
Si un secret gratuit est requis, préférer un chemin operator-safe cohérent avec l'ownership Config et les smokes KSP existants.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Objectifs et livrables de `0.2.11`
|
||||||
|
|
||||||
|
Livrables attendus, sous réserve du sizing `pre.001` :
|
||||||
|
|
||||||
|
```text
|
||||||
|
crates/ksp-offchain-transport-lib/
|
||||||
|
Cargo workspace member
|
||||||
|
price module/API publique provider-neutral
|
||||||
|
settings runtime publics
|
||||||
|
provider initial + wire DTOs privés ou bornés
|
||||||
|
unit/integration tests
|
||||||
|
adapter Config -> Off-chain Transport
|
||||||
|
config/schema/example nécessaires
|
||||||
|
.env.example si secret/provider config
|
||||||
|
smoke live opt-in
|
||||||
|
README.md
|
||||||
|
USAGE.md
|
||||||
|
plan 0.2.11
|
||||||
|
validation 0.2.11
|
||||||
|
deltas complets
|
||||||
|
prompt 0.2.12 à la fermeture seulement
|
||||||
|
```
|
||||||
|
|
||||||
|
Noms documentaires recommandés :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
|
||||||
|
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Hors périmètre explicite
|
||||||
|
|
||||||
|
```text
|
||||||
|
Price Desk Tauri
|
||||||
|
modification Wallet Desk
|
||||||
|
OHLCV/candles
|
||||||
|
historique/backfill prix complet
|
||||||
|
order books
|
||||||
|
DEX routing/quotes
|
||||||
|
swap execution
|
||||||
|
metadata token
|
||||||
|
IPFS/Arweave
|
||||||
|
news/sentiment
|
||||||
|
agrégation/consensus multi-provider complexe
|
||||||
|
fallback automatique multi-provider avant besoin démontré
|
||||||
|
WebSocket/SSE streaming sauf si pre.001 démontre qu'il est indispensable au minimum de release
|
||||||
|
nouvelle abstraction réseau universelle partagée avec ksp-onchain-transport-lib
|
||||||
|
Helius gRPC
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Contraintes sécurité, erreurs et API
|
||||||
|
|
||||||
|
### 10.1 Secrets
|
||||||
|
|
||||||
|
```text
|
||||||
|
aucune API key en source/config versionnée/delta/log/debug
|
||||||
|
Config possède la résolution des secrets
|
||||||
|
Off-chain Transport reçoit des settings déjà résolus
|
||||||
|
redaction des URLs/headers/DTO Debug
|
||||||
|
les erreurs remote ne recopient pas des payloads arbitraires dans KspError context
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10.2 Numeric safety
|
||||||
|
|
||||||
|
Les prix et conversions doivent avoir des limites de taille/format déterministes. Un provider malveillant ou cassé ne doit pas provoquer allocations non bornées, NaN/Inf silencieux ou overflow.
|
||||||
|
|
||||||
|
### 10.3 API provider-neutral
|
||||||
|
|
||||||
|
Le contrat commun ne doit pas prétendre que toutes les sources sont équivalentes. La provenance provider et le type de donnée doivent rester observables. Les extensions propres à un provider ne gonflent pas le DTO commun sans justification.
|
||||||
|
|
||||||
|
### 10.4 Observabilité
|
||||||
|
|
||||||
|
Logging via `ksp-logging-lib` uniquement. Les logs peuvent exposer provider, opération, pair, latence, status/catégorie d'erreur et fraîcheur sûre ; jamais credential, URL secrète ou réponse brute non bornée.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Première mission `0.2.11-pre.001` — gate obligatoire
|
||||||
|
|
||||||
|
### 11.1 Baseline stable
|
||||||
|
|
||||||
|
Avant modification lourde :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo fmt --all
|
||||||
|
python3 scripts/audit_rust_workspace_rules.py
|
||||||
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.11
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets
|
||||||
|
cargo test --workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
Si `deltas/0.2.11` n'existe pas encore, adapter seulement le chemin de l'audit Markdown ; ne pas considérer son absence comme erreur.
|
||||||
|
|
||||||
|
### 11.2 Audit interne
|
||||||
|
|
||||||
|
Inventorier :
|
||||||
|
|
||||||
|
```text
|
||||||
|
frontières architecture Off-chain Transport
|
||||||
|
patterns settings/errors/logging existants
|
||||||
|
adapter Config actuel
|
||||||
|
features reqwest/tokio déjà disponibles
|
||||||
|
aucune crate/naming collision
|
||||||
|
besoins futurs Price Desk/Wallet Desk qui imposent une API durable
|
||||||
|
```
|
||||||
|
|
||||||
|
### 11.3 Audit externe actuel
|
||||||
|
|
||||||
|
Pour chaque candidat retenu, consigner :
|
||||||
|
|
||||||
|
```text
|
||||||
|
source primaire
|
||||||
|
endpoint(s)
|
||||||
|
auth
|
||||||
|
plan gratuit réellement utilisable
|
||||||
|
rate limits
|
||||||
|
batch limit
|
||||||
|
quotes disponibles
|
||||||
|
freshness/cache/update time
|
||||||
|
identifiants d'actifs
|
||||||
|
wire types
|
||||||
|
null/missing/error semantics
|
||||||
|
historique/streaming seulement comme inventaire, pas comme scope automatique
|
||||||
|
```
|
||||||
|
|
||||||
|
Réauditer spécialement Pyth après le changement annoncé du 2026-08-26 16:00 UTC.
|
||||||
|
|
||||||
|
### 11.4 Matrice sémantique
|
||||||
|
|
||||||
|
Comparer séparément :
|
||||||
|
|
||||||
|
```text
|
||||||
|
market aggregator
|
||||||
|
Solana swap-derived heuristic price
|
||||||
|
oracle price + confidence
|
||||||
|
DEX pair/pool price
|
||||||
|
```
|
||||||
|
|
||||||
|
Identifier quelles données peuvent partager un contrat KSP sans perte de sens.
|
||||||
|
|
||||||
|
### 11.5 Threat model
|
||||||
|
|
||||||
|
Au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
credential leak
|
||||||
|
provider spoof/redirect
|
||||||
|
hostile JSON / huge body
|
||||||
|
NaN/Inf/extreme exponent
|
||||||
|
stale price
|
||||||
|
wrong asset mapping
|
||||||
|
symbol collision
|
||||||
|
wrong quote currency
|
||||||
|
partial batch response
|
||||||
|
rate-limit storm
|
||||||
|
retry amplification
|
||||||
|
provider returns null/missing
|
||||||
|
silent USD->EUR conversion error
|
||||||
|
```
|
||||||
|
|
||||||
|
### 11.6 Sizing
|
||||||
|
|
||||||
|
Estimer chaque tranche pour rester sous environ 15–20 minutes de travail effectif. Si l'intégration Config + provider + numeric model + live smoke dépasse une session raisonnable, scinder avant code lourd.
|
||||||
|
|
||||||
|
### 11.7 Documents de sortie
|
||||||
|
|
||||||
|
`pre.001` doit produire au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
|
||||||
|
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
|
||||||
|
deltas/0.2.11/pre.001.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun README final n'est requis avant que le contrat réel soit stabilisé.
|
||||||
|
|
||||||
|
### Critères de sortie de `pre.001`
|
||||||
|
|
||||||
|
Le gate est vert seulement si :
|
||||||
|
|
||||||
|
```text
|
||||||
|
baseline stable comprise
|
||||||
|
sources externes actuelles citées
|
||||||
|
auth/limites/testabilité des providers comparées
|
||||||
|
sémantique de prix explicitée
|
||||||
|
représentation numérique décidée ou question bloquante clairement isolée
|
||||||
|
provider initial choisi avec justification
|
||||||
|
SOL/USD + SOL/EUR faisables sans conversion opaque
|
||||||
|
surface Config envisagée
|
||||||
|
threat model écrit
|
||||||
|
forecast prerelease recalibré
|
||||||
|
aucun code provider lourd commencé prématurément
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Prévision souple initiale des prereleases
|
||||||
|
|
||||||
|
Prévision initiale, à recalibrer à `pre.001` :
|
||||||
|
|
||||||
|
```text
|
||||||
|
pre.001 audit actuel providers + sémantique prix + numeric model + threat model + sizing + plan
|
||||||
|
pre.002 crate foundation + contrats prix/settings/errors provider-neutral + tests canaris
|
||||||
|
pre.003 premier provider + parsing/batching/fraîcheur + tests déterministes
|
||||||
|
pre.004 composition Config + profil/secret éventuel + smoke live provider
|
||||||
|
pre.005 gate technique/live final + graphes si dépendances changées
|
||||||
|
pre.006 réconciliation documentaire finale plan/validation/README/USAGE
|
||||||
|
pre.007 publication minimale : prompt 0.2.12 + CHANGELOG + ROADMAP
|
||||||
|
rel.001 publication stable
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette numérotation est **souple**. Si `pre.001` démontre que Config peut être inclus proprement dans `pre.003`, fusionner plutôt que créer une tranche artificielle. Si un défaut nécessite un fix ou une tranche supplémentaire, l'insérer sans mélanger les couloirs finaux.
|
||||||
|
|
||||||
|
La séparation de fermeture reste normative :
|
||||||
|
|
||||||
|
```text
|
||||||
|
gate technique/live
|
||||||
|
puis réconciliation documentaire
|
||||||
|
puis publication minimale
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Versionnement, deltas, commits, archives et tags
|
||||||
|
|
||||||
|
Rappels :
|
||||||
|
|
||||||
|
```text
|
||||||
|
workspace.package.version suit chaque prerelease non-fix
|
||||||
|
0.2.11-pre.001 -> Cargo 0.2.11-pre.1
|
||||||
|
fix -> 0.2.11-pre.1.fix.1
|
||||||
|
```
|
||||||
|
|
||||||
|
Deltas :
|
||||||
|
|
||||||
|
```text
|
||||||
|
deltas/0.2.11/pre.001.md
|
||||||
|
deltas/0.2.11/pre.001-fix.001.md
|
||||||
|
...
|
||||||
|
deltas/0.2.11/rel.001.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Commit identifiers :
|
||||||
|
|
||||||
|
```text
|
||||||
|
v0.2.11-pre.001
|
||||||
|
v0.2.11-pre.001-fix.001
|
||||||
|
...
|
||||||
|
v0.2.11-rel.001
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun tag Git prerelease. Seule la publication stable crée :
|
||||||
|
|
||||||
|
```text
|
||||||
|
v0.2.11
|
||||||
|
```
|
||||||
|
|
||||||
|
Les archives d'échange restent des deltas minimaux `ksp-general-<delivery-id>.zip` contenant uniquement les fichiers ajoutés/modifiés et le delta correspondant.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Validation opérateur et application
|
||||||
|
|
||||||
|
Après chaque tranche Rust :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo fmt --all
|
||||||
|
python3 scripts/audit_rust_workspace_rules.py
|
||||||
|
cargo check --workspace
|
||||||
|
cargo clippy --workspace --all-targets
|
||||||
|
```
|
||||||
|
|
||||||
|
Puis tests ciblés. Aux gates finaux :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.11
|
||||||
|
cargo test --workspace
|
||||||
|
cargo tree -p ksp-offchain-transport-lib
|
||||||
|
cargo tree -p ksp-offchain-transport-lib --duplicates
|
||||||
|
cargo tree --duplicates
|
||||||
|
```
|
||||||
|
|
||||||
|
Ne jamais déclarer une commande PASS si elle n'a pas été exécutée.
|
||||||
|
|
||||||
|
Si un live smoke nécessite une clé gratuite, ne pas la fournir en argument CLI visible et ne jamais la recopier dans les deltas.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Tests attendus selon le scope retenu
|
||||||
|
|
||||||
|
Au minimum :
|
||||||
|
|
||||||
|
```text
|
||||||
|
construction/validation settings
|
||||||
|
redaction Debug
|
||||||
|
asset/quote identity
|
||||||
|
numeric decode and bounds
|
||||||
|
missing/null price semantics
|
||||||
|
partial batch response
|
||||||
|
provider wire fixtures
|
||||||
|
HTTP status/timeout/429 mapping
|
||||||
|
secret non-leak errors
|
||||||
|
Config adapter/provenance si secret
|
||||||
|
public API canaries
|
||||||
|
live SOL/USD + SOL/EUR opt-in
|
||||||
|
```
|
||||||
|
|
||||||
|
Tester aussi les cas adversariaux du provider choisi : prix à zéro/négatif si wire possible, valeur exponentielle énorme, timestamp absent/futur, token inconnu et corps de réponse oversized selon les capacités HTTP retenues.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 16. Critères de clôture de `0.2.11`
|
||||||
|
|
||||||
|
La release ne peut être clôturée que si :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-offchain-transport-lib existe et respecte les frontières
|
||||||
|
surface prix provider-neutral petite et documentée
|
||||||
|
premier provider réellement intégré sans SDK inutile
|
||||||
|
SOL/USD + SOL/EUR validés
|
||||||
|
représentation numérique déterministe
|
||||||
|
provenance/fraîcheur explicites
|
||||||
|
Config compose sans dépendance inverse
|
||||||
|
secrets redacted
|
||||||
|
smoke live accessible et vert
|
||||||
|
workspace complet vert
|
||||||
|
README/USAGE/plan/validation réconciliés
|
||||||
|
prompt 0.2.12 préparé seulement dans la dernière prerelease
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucune obligation de supporter plusieurs providers dans cette release. L'interchangeabilité doit être démontrée par la séparation du contrat et de l'adapter, pas par l'ajout prématuré de cinq implémentations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 17. Release/session suivante envisagée
|
||||||
|
|
||||||
|
Sous réserve du sizing futur :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.12 — Price Desk + intégration prix Wallet Desk
|
||||||
|
```
|
||||||
|
|
||||||
|
Mission envisagée :
|
||||||
|
|
||||||
|
```text
|
||||||
|
petite app Tauri spécialisée pour visualiser/rafraîchir les prix
|
||||||
|
provenance/état/fraîcheur observables
|
||||||
|
Config + ksp-offchain-transport-lib réutilisés
|
||||||
|
puis intégration de la même capacité dans ksp-app-wallet-desk
|
||||||
|
aucune duplication de récupération/normalisation dans les apps
|
||||||
|
```
|
||||||
|
|
||||||
|
Puis :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.2.13 — interface/wire foundation
|
||||||
|
0.2.14 — program-api foundation
|
||||||
|
```
|
||||||
|
|
||||||
|
Helius LaserStream gRPC reste en TODO jusqu'à disponibilité d'un accès live raisonnable.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 18. Instruction d'ouverture
|
||||||
|
|
||||||
|
Au démarrage de la nouvelle session :
|
||||||
|
|
||||||
|
1. vérifier que la base réelle est exactement `v0.2.10` ;
|
||||||
|
2. lire les sources internes dans l'ordre imposé ;
|
||||||
|
3. exécuter la baseline avant modification lourde ;
|
||||||
|
4. réauditer les providers de prix depuis leurs sources primaires actuelles, **avec priorité au changement Pyth du 2026-08-26** ;
|
||||||
|
5. comparer les sémantiques agrégateur / swap-derived / oracle / DEX pair ;
|
||||||
|
6. trancher numeric model, asset identity, freshness et provider initial ;
|
||||||
|
7. produire plan + validation + sizing `pre.001` ;
|
||||||
|
8. **ne pas commencer le provider lourd avant que ce gate soit vert**.
|
||||||
|
|
||||||
|
Le premier message de la session doit donc commencer par l'audit et le sizing, pas par une proposition de code déjà figée.
|
||||||
Reference in New Issue
Block a user