312 lines
10 KiB
Markdown
312 lines
10 KiB
Markdown
<!-- file: deltas/0.2.11/pre.001.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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 :
|
|
|
|
```text
|
|
khadhroony-solana-project-v0.2.10-full-from-gitea.zip
|
|
```
|
|
|
|
État vérifié :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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` :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
## 12. Fichiers modifiés
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## 14. Fichiers volontairement inchangés
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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`
|
|
|
|
```text
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
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 :
|
|
|
|
```text
|
|
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.
|