From 7d456b41dc8b95ad9bba457977435109009cc9b7 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 25 Aug 2026 15:43:15 +0200 Subject: [PATCH] v0.2.10-pre.005 --- CHANGELOG.md | 10 +- Cargo.toml | 4 +- ROADMAP.md | 14 +- deltas/0.2.10/pre.005.md | 132 +++++ prompts/016-V0_2_11_START_PROMPT.md | 878 ++++++++++++++++++++++++++++ 5 files changed, 1028 insertions(+), 10 deletions(-) create mode 100644 deltas/0.2.10/pre.005.md create mode 100644 prompts/016-V0_2_11_START_PROMPT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 159f256..d636580 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,16 @@ - + # 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/`. ## 0.2.9 — Yellowstone gRPC standard/provider-neutral — 2026-08-24 diff --git a/Cargo.toml b/Cargo.toml index aa8f1ad..5c64c6f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 266 +# version: 267 [workspace] 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"] [workspace.package] -version = "0.2.10-pre.4" +version = "0.2.10-pre.5" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 2228500..70001ee 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # 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.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. -- [ ] `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. -- [ ] `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.12` — Introduire `ksp-offchain-transport-lib` avec un premier lecteur de prix, au minimum SOL/USD et SOL/EUR. -- [ ] `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.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.15` — Introduire `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet. +- [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` — 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 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 `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet. ### 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** — 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. diff --git a/deltas/0.2.10/pre.005.md b/deltas/0.2.10/pre.005.md new file mode 100644 index 0000000..835a1d3 --- /dev/null +++ b/deltas/0.2.10/pre.005.md @@ -0,0 +1,132 @@ + + + +# 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. diff --git a/prompts/016-V0_2_11_START_PROMPT.md b/prompts/016-V0_2_11_START_PROMPT.md new file mode 100644 index 0000000..a9acf6b --- /dev/null +++ b/prompts/016-V0_2_11_START_PROMPT.md @@ -0,0 +1,878 @@ + + + +# 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 +``` + +### 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-.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.