23 KiB
Validation 0.2.11 — Off-chain price transport SOL/USD
1. Objet
Cette matrice suit la release 0.2.11 — Off-chain price transport ouverte par pre.001.
Le contrat fonctionnel V1 est :
SOL/USD uniquement
plusieurs providers gratuits admis
HTTP REST reqwest uniquement
aucun SDK provider
provider/rate-limit/availability possédés par ksp-offchain-transport-lib
Config -> Off-chain Transport sans dépendance inverse
future ksp-app-solprices-desk purement HID et provider-agnostic
Les statuts PLANNED restent non validés tant que la tranche correspondante n'est pas exécutée.
2. Gate 0.2.11-pre.001
| Critère | Statut | Preuve |
|---|---|---|
archive stable v0.2.10 utilisée |
PASS | archive Gitea fournie par l'opérateur |
workspace.package.version = 0.2.10 à l'entrée |
PASS | inspection Cargo.toml |
deltas/0.2.10/rel.001.md présent |
PASS | inspection archive |
prompts/016-V0_2_11_START_PROMPT.md présent |
PASS | inspection archive |
.git absent de l'archive |
PASS | inspection filesystem |
ksp-offchain-transport-lib absent à l'entrée |
PASS | inventaire workspace |
| primitives reqwest/serde/serde_json/tokio/http déjà présentes | PASS | inventaire [workspace.dependencies] |
| audit providers gratuit/live actuel | PASS | sources officielles CoinGecko, CMC, CoinPaprika, Kraken, Coinbase, Jupiter, Birdeye, DS |
| conditions d'usage gratuites distinguées du transport | PASS | plan 018, gratuité technique distincte de licence commerciale durable |
| SOL/USD retenu comme seule paire V1 | PASS | décision opérateur + plan 018 |
| aucun SDK provider retenu | PASS | décision opérateur + plan 018 |
| huit providers retenus pour implémentation | PASS | plan 018 section provider |
| DexScreener V1 limité à une paire SOL/USD configurée | PASS | décision opérateur + plan 018 |
future ksp-app-solprices-desk purement HID |
PASS | décision opérateur + architecture |
| ownership rate limits/availability dans Off-chain Transport | PASS | décision opérateur + plan 018 |
| threat model V1 établi | PASS | plan 018 |
| forecast prereleases établi | PASS | plan 018 |
code runtime provider ajouté en pre.001 |
N/A | interdit par le gate, aucune crate créée |
3. Gate 0.2.11-pre.002
| Critère | Statut | Preuve |
|---|---|---|
crate ksp-offchain-transport-lib créée |
PASS | membre workspace + package dédié |
version workspace synchronisée sur 0.2.11-pre.2 |
PASS | Cargo.toml racine |
| dépendance inverse vers Config absente | PASS | manifest crate |
reqwest et SDK providers absents de la fondation |
PASS | manifest crate |
MarketPriceDecimal exact sans canon f64 |
PASS | coefficient u128, scale 18, sérialisation string |
| SOL/USD seule paire publique V1 | PASS | MarketPricePair::SolUsd + MarketPriceObservation |
| identifiant/descripteur provider opaques | PASS | MarketPriceProviderId + MarketPriceProviderDescriptor |
| auth/rate-limit/quota représentables génériquement | PASS | types provider-neutral dédiés |
| settings communs sans faux endpoint/API key | PASS | MarketPriceProviderCommonSettings |
| availability provider-neutral représentable | PASS | MarketPriceProviderAvailability + MarketPriceProviderState |
| HTTP actif ou adapter provider ajouté | N/A | explicitement réservé à pre.003+ |
3.1 Taxonomie Off-chain et observabilité
| Invariant | Statut |
|---|---|
crate ksp-offchain-transport-lib non assimilée à une crate price-only |
PASS |
capacité V1 classée sous modules privés market_price_* |
PASS |
modules partagés constants.rs et error.rs restent crate-wide |
PASS |
futures quotes prévues sous famille distincte swap_quote_* |
PASS |
| aucune abstraction future créée sans responsabilité réellement partagée | PASS |
market_price V1 strictement read-only |
PASS |
| verbe HTTP distinct de la sémantique métier read/write | PASS |
| soumission/signature Solana reste hors d'Off-chain Transport | PASS |
ksp-logging-lib utilisé pour les événements KSP de la crate |
PASS |
src/constants.rs possède TRACING_TARGET = ksp-offchain-transport-lib |
PASS |
aucune dépendance directe à tracing |
PASS |
| crate-rustdocs présentes dans les tests d'intégration | PASS |
3.2 Correctif 0.2.11-pre.002-fix.002
Le gate cargo clippy --workspace --all-targets de pre.002-fix.001 a détecté un unique écart clippy::implicit-return dans le canari tests/dependency_boundary.rs. Le correctif ajoute le return explicite attendu dans la closure de Iterator::any et synchronise workspace.package.version sur 0.2.11-pre.2.fix.2. Aucun contrat public, comportement runtime ou scope provider n'est modifié.
Les validations opérateur du 2026-08-25 sur pre.002-fix.002 sont : cargo fmt --all PASS, audit Rust PASS, audit Markdown PASS, cargo check --workspace PASS, cargo test -p ksp-offchain-transport-lib PASS avec 13 tests exécutés, et cargo clippy --workspace --all-targets PASS. cargo test --workspace n'a pas été rejoué après ce fix et n'est donc pas déclaré PASS pour cet état exact.
3.3 Correctif 0.2.11-pre.002-fix.003
Le nommage public initial Price* restait trop générique alors que les modules qui possèdent ces contrats sont explicitement la famille market_price_*. Le correctif synchronise workspace.package.version sur 0.2.11-pre.2.fix.3 et renomme sans alias de compatibilité toute la surface publique spécifique à cette famille en MarketPrice* / MARKET_PRICE_*.
Le contrat attendu après application est :
MarketPriceDecimal
MarketPriceObservation
MarketPriceTimestamp
MarketPriceProvenance
MarketPricePair
MarketPriceSemantics
MarketPriceProvider*
MARKET_PRICE_*
ERROR_CODE_MARKET_PRICE_*
Cette correction reste dans la responsabilité de pre.002 : elle stabilise la fondation et sa façade avant l'introduction du HTTP runtime en pre.003.
3.4 Gate 0.2.11-pre.003
| Critère | Statut | Preuve |
|---|---|---|
version workspace 0.2.11-pre.3 |
PASS | Cargo.toml racine |
reqwest utilisé directement, sans SDK provider |
PASS | manifest ksp-offchain-transport-lib |
primitives HTTP communes sous modules http_* crate-private |
PASS | http_client, http_settings, http_admission |
| client HTTP générique non exporté aux consumers | PASS | façade lib.rs |
| redirects, Referer, proxy système et retries reqwest désactivés | PASS | construction HttpRestClient |
| connect/request timeouts bornés | PASS | HttpClientSettings |
| body borné pendant lecture chunked avant désérialisation | PASS | HttpRestClient::get_json |
| JSON syntaxiquement validé sans normalisation numérique intermédiaire | PASS | serde::de::IgnoredAny sur bytes bruts |
| 401/403, 429, 408/5xx et autres statuts distingués | PASS | codes d'erreur HTTP dédiés |
| URL reqwest supprimée des sources d'erreur | PASS | reqwest::Error::without_url |
| body remote non recopié dans les erreurs | PASS | erreurs construites uniquement depuis metadata safe |
| limiter fixe lissé et burst absent traité conservativement | PASS | HttpAdmissionController |
| limite dynamique n'invente pas de cadence locale | PASS | HttpAdmissionPolicy::Dynamic |
cooldown Retry-After borné et admission non bloquante |
PASS | record_rate_limited + try_admit |
| adapters CoinGecko/Jupiter/etc. ajoutés | N/A | explicitement réservés à pre.004+ |
gate Cargo complet sur pre.003-fix.001 |
PENDING | à rejouer par l'opérateur après le correctif |
Les tests déterministes de pre.003 couvrent en particulier le body chunked dépassant la limite, le refus des redirects, un 429 avec Retry-After, la non-propagation d'un body distant canari, le JSON invalide et le refill/cooldown du limiter.
3.5 Correctif 0.2.11-pre.003-fix.001
Le gate opérateur de pre.003 a révélé quatre classes d'écarts avant poursuite vers pre.004 : six violations RUST-FMT-104 dans src/error.rs, six réexports pub(crate) HTTP inutilisés dans le build normal, un test de burst rejeté par la validation burst > requests, et la non-utilisation de la façade crate-root dans les impl des items HTTP partagés. cargo check et cargo clippy terminaient avec les warnings de réexports, tandis que cargo test -p ksp-offchain-transport-lib échouait sur documented_burst_is_consumed_atomically_before_refill.
Le correctif applique les règles suivantes :
RUST-FMT-005 / RUST-FMT-104 : constantes homogènes triées alphabétiquement
RUST-IMPORT-009 / RUST-API-004 : items HTTP partagés consommés via crate::Item, y compris dans leurs impl
RUST-API-008 : helpers préparatoires sans consumer production sous #[cfg(test)], aucun #[allow(dead_code)] compensatoire
contrat limiter : burst documenté indépendant de la cadence moyenne et autorisé à la dépasser
Le cas 1 req/s avec burst 2 devient un canari déterministe ; il protège notamment la représentabilité du cas Coinbase documenté dans le plan à 10 req/s, burst 15. Les modules http_* restent donc testés et prêts en pre.003, mais leur compilation normale sera activée en pre.004 lorsque les premiers adapters de production les consommeront réellement.
La version Cargo du correctif est 0.2.11-pre.3.fix.1. Les audits statiques du sandbox sont propres ; le gate Cargo complet doit être rejoué par l'opérateur.
4. Matrice provider prévue
| Provider | SOL/USD V1 | Gratuit V1 | Mode auth prévu | Test déterministe | Smoke live | Statut courant |
|---|---|---|---|---|---|---|
| CoinGecko | Oui | Oui | keyless ou Demo key | PLANNED | PLANNED | AUDITED |
| CoinMarketCap | Oui | Oui | keyless ou Basic key | PLANNED | PLANNED | AUDITED |
| CoinPaprika | Oui | Oui | aucune | PLANNED | PLANNED | AUDITED |
| Kraken | Oui | Oui | aucune | PLANNED | PLANNED | AUDITED |
| Coinbase Exchange | Oui | Oui | aucune | PLANNED | PLANNED | AUDITED |
| Jupiter Price V3 | Oui | Oui | keyless ou Free key | PLANNED | PLANNED | AUDITED |
| Birdeye | Oui | Oui | API key Standard | PLANNED | PLANNED | AUDITED |
| DexScreener | Oui | Oui | aucune | PLANNED | PLANNED | AUDITED |
AUDITED signifie uniquement que la documentation officielle actuelle satisfait le gate d'entrée. Ce statut ne vaut pas preuve d'un smoke réseau KSP.
Avant la stable, les conditions d'usage et la persistance des offres gratuites doivent être réauditées ; un provider peut rester techniquement supporté tout en nécessitant un plan différent pour certains usages.
5. Contrat public prévu
| Invariant | Statut |
|---|---|
| surface publique limitée à SOL/USD dans V1 | PASS |
| identifiants provider opaques pour les consumers | PASS |
| provenance provider toujours observable | PASS |
| sémantique de prix observable sans prétendre à une équivalence | PASS |
| timestamp requête/réception KSP présents | PASS |
| timestamp provider optionnel seulement lorsqu'il est réellement fourni | PASS |
| absence de prix distincte de zéro | PASS |
f64 non utilisé comme canon public |
PASS |
| aucune structure wire provider exportée | PASS |
| aucune URL/header/asset id provider requis côté app | PASS |
| registry provider et état runtime possédés par Off-chain Transport | PLANNED |
| refresh provider par identifiant générique | PLANNED |
| refresh multiple sans connaissance provider côté consumer | PLANNED |
6. Rate limiting et availability
| Cas | Statut |
|---|---|
| cadence locale fixe représentable | PASS |
| burst documenté supérieur à la cadence moyenne représentable | PASS |
| limite dynamique keyless représentable | PASS |
429 classé |
PLANNED |
Retry-After honoré lorsqu'exploitable |
PLANNED |
| cooldown expose prochain instant admissible | PLANNED |
| refresh all ne lance que les providers éligibles | PLANNED |
| provider en cooldown ne bloque pas les autres | PLANNED |
| provider down ne rend pas le service global inutilisable | PLANNED |
| auth manquante distinguée d'un transport down | PLANNED |
| quota indisponible distingué d'un transport down | PLANNED |
| quota mensuel local non présenté comme compteur authoritative | PLANNED |
7. Numeric safety
| Cas | Statut |
|---|---|
| décimal string valide | PASS |
JSON number valide sans passage canonique par f64 |
PLANNED |
| notation scientifique bornée | PASS |
| coefficient/scale overflow rejeté | PASS |
| valeur négative rejetée | PASS |
| zéro rejeté pour une observation réussie | PASS |
| NaN/Inf impossibles dans le type canonique | PASS |
| serialization canonique sans perte | PASS |
| round-trip public déterministe | PASS |
8. HTTP et sécurité
| Invariant | Statut |
|---|---|
reqwest seul client provider |
PLANNED |
| aucun SDK provider | PLANNED |
| endpoint provider officiel fixe en V1 | PLANNED |
| redirects désactivés | PLANNED |
| proxy implicite désactivé selon policy KSP | PLANNED |
| connect timeout borné | PLANNED |
| request timeout borné | PLANNED |
| body réponse borné avant parsing | PLANNED |
| URL retirée des erreurs reqwest | PLANNED |
| réponse remote brute absente des KspError/logs | PLANNED |
| API key absente de Debug/log/error | PLANNED |
| 401/403 classés auth/access | PLANNED |
| 429 classé rate limit | PLANNED |
| 5xx classé transient | PLANNED |
| schema drift classé provider protocol | PLANNED |
9. DexScreener V1
| Invariant | Statut |
|---|---|
| pair address SOL/USD explicite dans settings | PLANNED |
chainId = solana vérifié |
PLANNED |
| identité SOL de la paire vérifiée | PLANNED |
priceUsd utilisé comme prix commun |
PLANNED |
| aucune recherche automatique de pool | PLANNED |
| aucun tri automatique par liquidité | PLANNED |
| aucune moyenne/consensus entre pools | PLANNED |
10. Config -> Off-chain Transport
| Invariant | Statut |
|---|---|
| Off-chain Transport ne dépend pas de Config | PLANNED |
| document standard offchain dédié | PLANNED |
| branches provider conditionnelles dans schema | PLANNED |
| CoinGecko keyless/Demo représentés | PLANNED |
| CoinMarketCap keyless/Basic représentés | PLANNED |
| Jupiter keyless/Free représentés | PLANNED |
| Birdeye exige credential lorsqu'activé | PLANNED |
| DexScreener exige pair address lorsqu'activé | PLANNED |
| providers sans auth n'exposent pas de faux champ API key | PLANNED |
| secrets via Config uniquement | PLANNED |
.env.example synchronisé pour les secrets réellement ajoutés |
PLANNED |
| aucune cadence provider configurable au-dessus de la limite sûre | PLANNED |
11. Frontière future ksp-app-solprices-desk
| Invariant | Statut |
|---|---|
nom de l'application fixé à ksp-app-solprices-desk |
DECIDED |
| rôle HID uniquement | DECIDED |
| aucun enum/provider spécifique requis dans l'UI | PLANNED |
| aucun endpoint/header/provider id propriétaire dans l'app | PLANNED |
| table construite depuis l'inventaire générique Off-chain Transport | PLANNED |
| refresh row appelle une opération générique | PLANNED |
| refresh multiple appelle une opération générique | PLANNED |
| cooldown/availability affichables depuis état générique | PLANNED |
| aucune logique de rate limiting dans Tauri/frontend | PLANNED |
Cette section valide l'architecture préparée par 0.2.11; l'application elle-même reste hors scope et sera testée en 0.2.12.
12. Non-régression et gates finaux prévus
| Gate | Statut |
|---|---|
cargo fmt --all |
PLANNED |
| audit Rust workspace | PLANNED |
| audit Markdown tables | PLANNED |
cargo check --workspace |
PLANNED |
cargo clippy --workspace --all-targets |
PLANNED |
cargo test --workspace |
PLANNED |
tests ksp-offchain-transport-lib |
PLANNED |
| tests Config | PLANNED |
| cargo tree Off-chain Transport | PLANNED |
| absence de dépendances provider SDK | PLANNED |
| smokes keyless gratuits | PLANNED |
| smokes keyed gratuits disponibles à l'opérateur | PLANNED |
| réconciliation README/USAGE/plan/validation | PLANNED |
13. Hors scope validé
SOL/EUR et autres quotes
SPL token price générique
OHLCV/historique
streaming price
fallback automatique
consensus/moyenne/médiane
pool discovery DexScreener
Price Desk dans 0.2.11
Wallet Desk dans 0.2.11
Pyth V1
Binance SOL/USDT assimilé à SOL/USD