v0.2.10-pre.005
This commit is contained in:
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