10 KiB
Delta 0.2.11-pre.001 — audit/sizing Off-chain price SOL/USD multi-provider
1. Base requise et vérifiée
Archive autoritaire fournie :
khadhroony-solana-project-v0.2.10-full-from-gitea.zip
État vérifié :
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
ksp-offchain-transport-lib absente
metadata .git absente de l'archive Gitea
Cette livraison ouvre :
workspace.package.version = 0.2.11-pre.1
commit attendu = v0.2.11-pre.001
aucun tag prerelease
2. Objet
pre.001 exécute exclusivement le gate de cadrage obligatoire :
lecture base/règles/architecture
inventaire primitives HTTP existantes
réaudit actuel des providers de prix
comparaison des sémantiques
scope SOL/USD
choix multi-provider gratuit
absence de SDK provider
numeric safety
provider registry et availability
rate limiting et refresh multiple
Config provider-capability-aware
cas DexScreener SOL/USD
frontière future ksp-app-solprices-desk
threat model
sizing et forecast
Aucun client provider, crate Off-chain Transport, Config runtime ou secret n'est ajouté dans cette tranche.
3. Décisions opérateur supersédant le prompt préparatoire
Le prompt 016 préparait SOL/USD + SOL/EUR et laissait le provider initial ouvert. Le brainstorming d'ouverture fixe désormais :
V1 = SOL/USD uniquement
0.2.11 peut et doit implémenter plusieurs providers gratuits
HTTP REST via reqwest uniquement
aucun SDK provider
SOL/EUR reporté
aucun consensus/fallback automatique
future app = ksp-app-solprices-desk
future app = HID pure sans connaissance provider
Off-chain Transport possède limits/exceptions/availability
DexScreener V1 = paire SOL/USD explicite uniquement
Ces décisions sont répercutées dans le plan, la validation, l'architecture durable, la séquence fonctionnelle et le ROADMAP global d'ouverture.
4. Providers retenus
Audit officiel du 2026-08-25 :
| Provider | Gratuit V1 | Auth possible V1 | Contrainte principale | Verdict |
|---|---|---|---|---|
| CoinGecko | Oui | keyless ou Demo key | dynamic IP ou Demo 100/min et 10k/mois | IN |
| CoinMarketCap | Oui | keyless ou Basic key | dynamic IP ou Basic 50/min et 15k/mois | IN |
| CoinPaprika | Oui | aucune | 10/s IP, 20k/mois, refresh Free moyen 5 min | IN |
| Kraken | Oui | aucune | 1/s ou moins recommandé sur public REST | IN |
| Coinbase Exchange | Oui | aucune | 10/s IP, burst 15 | IN |
| Jupiter Price V3 | Oui | keyless ou Free key | 0.5 RPS keyless, 1 RPS Free | IN |
| Birdeye | Oui | API key | Standard 1 RPS, 30k CU, Price Single 3 CU | IN |
| DexScreener | Oui | aucune | 300/min endpoints pair/token | IN |
Pyth est écarté de V1 à cause de la transition d'accès imminente et de l'absence de gratuité durable confirmée après trial. Binance est écarté tant que KSP n'a pas retenu un vrai marché SOL/USD ; SOL/USDT n'est pas assimilé à SOL/USD.
5. Sémantique et numérique
Décisions :
une observation conserve provider + sémantique + timestamps KSP
provider update timestamp reste optionnel
aucune fraîcheur provider inventée
f64 n'est pas le canon public
prix canonique = décimal KSP borné sans nouvelle crate decimal
wire JSON number/string -> parser textuel sûr
zéro/négatif/overflow/forme invalide rejetés
Les classes de sémantique distingueront notamment agrégateur, exchange last trade, heuristique Solana, spot Solana et paire DEX.
6. Registry, availability et refresh
ksp-offchain-transport-lib sera propriétaire de :
inventory/registry provider
descriptors/capabilities
adapters/wires privés
rate limits/cooldowns
classification 401/403/429/5xx/transport/schema
état provider ready/unavailable/misconfigured/quota/auth
refresh provider générique
refresh multiple/all générique
Un refresh multiple lance les providers actuellement éligibles sans attendre ceux en cooldown et retourne un outcome par provider. La future UI ne contient aucune logique de scheduling.
7. DexScreener V1
Décision :
pair address Solana configurée
endpoint pair direct
chain et identité SOL validées
lecture de priceUsd uniquement pour le contrat commun
aucune découverte/selection automatique de pool
aucun tri liquidité
aucun consensus entre pools
Cette policy pourra être changée dans une release ultérieure sans exposer DexScreener à l'application.
8. Config et sécurité
Config reste propriétaire des fichiers/env/secrets et adaptera un document standard Off-chain Transport futur.
Les branches seront provider-capability-aware :
providers keyless sans faux credential obligatoire
modes keyless/keyed représentés quand les deux existent
Birdeye credential obligatoire si activé
DexScreener pair address obligatoire si activé
origines HTTP provider fixes en V1
aucun base_url arbitraire
aucune limite provider librement augmentable par Config/UI
Le threat model couvre credential exfiltration, SSRF, redirects, proxy implicite, body non borné, numeric abuse, wrong pair, stale data, rate limit, provider outage et schema drift.
9. Future ksp-app-solprices-desk
Architecture fixée pour 0.2.12 :
HID pure
aucune connaissance provider
aucune requête HTTP provider
aucun rate limit provider côté UI
liste issue du registry générique
prix/état/cooldown issus du service générique
refresh row générique
refresh multiple générique
0.2.11 ne crée pas l'application.
10. Forecast
Chemin souple retenu :
pre.001 audit/sizing
pre.002 crate + contrats + décimal
pre.003 HTTP commun + errors + rate limiter
pre.004 CoinGecko + CMC + CoinPaprika
pre.005 Kraken + Coinbase
pre.006 Jupiter + DexScreener
pre.007 Birdeye + registry availability
pre.008 refresh single/multiple cross-provider
pre.009 Config std.offchain_transport
pre.010 hardening/API/tests + docs techniques draft
pre.011 gate technique/live final
pre.012 réconciliation documentaire finale
pre.013 publication minimale prompt 0.2.12 + CHANGELOG + ROADMAP
rel.001 stable
11. Fichiers ajoutés
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
12. Fichiers modifiés
Cargo.toml
ROADMAP.md
docs/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
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/validation/000-README.md
13. Fichiers supprimés
aucun
14. Fichiers volontairement inchangés
CHANGELOG.md
prompts/016-V0_2_11_START_PROMPT.md
.env.example
config/**
crates/**
README/USAGE de crates existantes
Le prompt d'ouverture reste historique ; les supersessions sont portées par le plan/delta de la release active.
15. Sources externes réauditées
CoinGecko keyless/simple-price/pricing
CoinMarketCap keyless/simple-price/pricing
CoinPaprika REST/ticker/plans
Kraken public market REST/rate limits
Coinbase Exchange ticker/rate limits
Jupiter Developer Platform/Price V3
Birdeye pricing/rate limiting/Price Single
DexScreener API reference
Pyth Core transition pour décision OUT V1
Les URLs détaillées sont conservées dans le plan 018.
Le gate distingue désormais explicitement accès gratuit technique et conditions d'usage : CoinGecko/CMC keyless sont orientés évaluation/prototypage selon leurs documents actuels et CoinPaprika Free est annoncé pour usage personnel. Ces points n'empêchent pas l'implémentation V1 mais seront réaudités avant la stable ; KSP ne promet aucune gratuité commerciale durable.
16. Validations exécutées dans le sandbox
inspection archive/version/rel/prompt PASS
inspection absence metadata .git PASS
inspection absence ksp-offchain-transport-lib PASS
inventaire workspace dependencies PASS
python3 scripts/audit_rust_workspace_rules.py PASS / clean / 0 candidate export
audit Markdown ciblé des 12 fichiers touchés PASS / 16 tables
audit Markdown scope session complet PASS / 115 tables / 100 files
Le sandbox ne fournit ni cargo ni rustc. Aucun cargo fmt/check/clippy/test n'est donc déclaré exécuté localement. Aucun smoke provider live KSP n'est déclaré PASS dans pre.001 puisque la crate n'existe pas encore.
17. Validations non exécutées dans pre.001
cargo fmt --all non exécuté, Cargo absent du sandbox
cargo check --workspace non exécuté, Cargo absent du sandbox
cargo clippy --workspace --all-targets non exécuté, Cargo absent du sandbox
cargo test --workspace non exécuté, Cargo absent du sandbox
aucun test adapter provider code absent
aucun smoke live provider KSP code absent
aucun test Config Off-chain document absent
aucun build ksp-app-solprices-desk application hors scope
18. Validation opérateur attendue avant commit
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
Aucun smoke réseau provider n'est attendu pour cette tranche documentaire de cadrage.
19. Questions ouvertes
Les questions fonctionnelles majeures sont closes pour démarrer l'implémentation. Restent à fixer au niveau du code dans les prereleases prévues :
noms Rust exacts des descriptors/outcomes/status
bornes exactes coefficient/scale du décimal KSP
body limit et timeouts par défaut
forme exacte du rate limiter générique
noms des variables KSP_SECRET provider keyed
pair address DexScreener opérateur à configurer et live-valider
endpoint/version CMC exact à figer après canari live courant
Ces points ne remettent pas en cause le gate de sizing.