Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.11-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-25 19:45:06 +02:00
parent f42fa8f4f1
commit 4f92fb03f1
17 changed files with 1610 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Plan `0.2.11` — Off-chain price transport SOL/USD multi-provider
**Statut courant : `0.2.11-pre.001-fix.001` conserve intégralement le cadrage technique de `pre.001` et corrige uniquement la forme du forecast souple afin de rendre chaque tranche éditable par statut et extensible par sous-sections `####` pour ses fixes. Aucun client provider n'est encore implémenté. Le scope V1 reste limité à SOL/USD via HTTP REST `reqwest`, sans SDK provider, avec huit providers gratuits retenus pour implémentation progressive.**
**Statut courant : `0.2.11-pre.002` matérialise la fondation de `ksp-offchain-transport-lib` sans encore ajouter de client HTTP ou d'adapter provider. Le contrat public V1 possède désormais un décimal exact SOL/USD, des observations/provenances/timestamps sûrs, des identifiants/descriptors provider opaques, des capacités auth/rate-limit/quota descriptives, des settings communs minimaux et des états d'availability provider-neutral.**
## 1. Base et autorité
@@ -304,15 +304,16 @@ Le choix d'une paire explicite évite d'introduire silencieusement une politique
Le gate rejette `f64` comme représentation canonique publique du prix.
Direction retenue pour `pre.002` : type décimal KSP borné, sérialisable sans perte, construit depuis la représentation textuelle du provider.
Décision matérialisée en `pre.002` : `PriceDecimal` est le type décimal KSP borné, sérialisable sans perte et construit depuis la représentation textuelle du provider.
Forme de travail :
Contrat V1 exact :
```text
coefficient positif u128
scale bornée
scale bornée à 18 décimales
entrée textuelle bornée à 96 octets
normalisation des zéros terminaux
parsing décimal et notation scientifique bornés
parsing décimal et notation scientifique bornés sans passage par f64
aucun NaN
aucun Inf
overflow rejeté
@@ -322,6 +323,8 @@ serialization canonique décimale en chaîne
Le wire d'un provider peut être JSON number ou string. L'adapter le convertit vers le type KSP sans utiliser `as_f64()` comme vérité canonique.
`PriceDecimal` sérialise toujours sa valeur canonique sous forme de chaîne décimale non scientifique. Le zéro est invalide pour ce type puisqu'il représente exclusivement un prix réussi ; l'absence de prix reste donc hors de la valeur numérique elle-même.
Cette solution évite d'ajouter une crate decimal uniquement pour V1 et prépare le passage frontend sans perte IEEE-754.
## 11. Observation commune et fraîcheur
@@ -338,6 +341,8 @@ instant provider optionnel lorsqu'il existe réellement
provenance provider sûre et bornée
```
`pre.002` matérialise ce contrat avec `SolUsdPriceObservation`, `PriceTimestamp` (millisecondes UTC depuis Unix epoch) et `PriceProvenance` bornée à 256 octets sans caractères de contrôle. Le constructeur d'observation rejette un instant de réception antérieur au départ de requête.
Règles :
```text
@@ -370,6 +375,8 @@ limitation générique
support SOL/USD
```
`pre.002` fixe `PriceProviderId`, `PriceProviderDescriptor`, `PriceProviderAuthMode`, `PriceProviderRateLimit`, `PriceProviderLongTermQuota` et leurs enums de scope/période/unité. Les limites fixes exigent un budget et une fenêtre non nuls ; les limites dynamiques restent explicitement distinctes. Les quotas longs termes sont descriptifs et ne deviennent jamais un compteur local de quota restant.
L'état runtime peut représenter au minimum :
```text
@@ -382,7 +389,9 @@ misconfigured
disabled
```
Les noms Rust finaux sont à fixer avec le code, mais aucun consumer ne doit parser des strings d'erreur pour connaître cet état.
`PriceProviderAvailability` et `PriceProviderState` matérialisent cette projection générique dès `pre.002`; le registry et les transitions runtime effectives restent prévus en `pre.007`.
Les noms Rust de cette fondation sont désormais matérialisés ; aucun consumer ne doit parser des strings d'erreur pour connaître cet état.
## 13. Rate limiting et refresh multiple
@@ -616,9 +625,9 @@ Remplacement du forecast tabulaire par des sous-sections éditables, clarificati
### `pre.002` — Fondation de `ksp-offchain-transport-lib`
**Statut : planifié.**
**Statut : réalisé.**
Création de la crate, modèle SOL/USD, type décimal KSP, descriptors, settings et états provider-neutral.
Création de la crate et de sa façade publique initiale : `PriceDecimal`, paire SOL/USD, observation/provenance/timestamps, identifiants/descriptors provider, capacités auth/rate-limit/quota, settings communs minimaux et états d'availability provider-neutral. Aucun HTTP, limiter actif, credential provider ou adapter wire n'est avancé depuis `pre.003+`.
### `pre.003` — HTTP REST commun et rate limiting

80
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Validation `0.2.11` — Off-chain price transport SOL/USD
@@ -44,7 +44,23 @@ Les statuts `PLANNED` restent non validés tant que la tranche correspondante n'
| forecast prereleases établi | PASS | plan 018 |
| code runtime provider ajouté en `pre.001` | N/A | interdit par le gate, aucune crate créée |
## 3. Matrice provider prévue
## 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 |
| `PriceDecimal` exact sans canon `f64` | PASS | coefficient `u128`, scale 18, sérialisation string |
| SOL/USD seule paire publique V1 | PASS | `PricePair::SolUsd` + `SolUsdPriceObservation` |
| identifiant/descripteur provider opaques | PASS | `PriceProviderId` + `PriceProviderDescriptor` |
| auth/rate-limit/quota représentables génériquement | PASS | types provider-neutral dédiés |
| settings communs sans faux endpoint/API key | PASS | `PriceProviderCommonSettings` |
| availability provider-neutral représentable | PASS | `PriceProviderAvailability` + `PriceProviderState` |
| HTTP actif ou adapter provider ajouté | N/A | explicitement réservé à `pre.003+` |
## 4. Matrice provider prévue
| Provider | SOL/USD V1 | Gratuit V1 | Mode auth prévu | Test déterministe | Smoke live | Statut courant |
|-------------------|------------|------------|----------------------|-------------------|------------|----------------|
@@ -61,31 +77,31 @@ Les statuts `PLANNED` restent non validés tant que la tranche correspondante n'
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.
## 4. Contrat public prévu
## 5. Contrat public prévu
| Invariant | Statut |
|------------------------------------------------------------------------|---------|
| surface publique limitée à SOL/USD dans V1 | PLANNED |
| identifiants provider opaques pour les consumers | PLANNED |
| provenance provider toujours observable | PLANNED |
| sémantique de prix observable sans prétendre à une équivalence | PLANNED |
| timestamp requête/réception KSP présents | PLANNED |
| timestamp provider optionnel seulement lorsqu'il est réellement fourni | PLANNED |
| absence de prix distincte de zéro | PLANNED |
| `f64` non utilisé comme canon public | PLANNED |
| aucune structure wire provider exportée | PLANNED |
| aucune URL/header/asset id provider requis côté app | PLANNED |
| 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 |
## 5. Rate limiting et availability
## 6. Rate limiting et availability
| Cas | Statut |
|---------------------------------------------------------------|---------|
| cadence locale fixe représentable | PLANNED |
| burst documenté représentable | PLANNED |
| limite dynamique keyless représentable | PLANNED |
| cadence locale fixe représentable | PASS |
| burst documenté représentable | PASS |
| limite dynamique keyless représentable | PASS |
| `429` classé | PLANNED |
| `Retry-After` honoré lorsqu'exploitable | PLANNED |
| cooldown expose prochain instant admissible | PLANNED |
@@ -96,21 +112,21 @@ Avant la stable, les conditions d'usage et la persistance des offres gratuites d
| quota indisponible distingué d'un transport down | PLANNED |
| quota mensuel local non présenté comme compteur authoritative | PLANNED |
## 6. Numeric safety
## 7. Numeric safety
| Cas | Statut |
|-----------------------------------------------------|---------|
| décimal string valide | PLANNED |
| décimal string valide | PASS |
| JSON number valide sans passage canonique par `f64` | PLANNED |
| notation scientifique bornée | PLANNED |
| coefficient/scale overflow rejeté | PLANNED |
| valeur négative rejetée | PLANNED |
| zéro rejeté pour une observation réussie | PLANNED |
| NaN/Inf impossibles dans le type canonique | PLANNED |
| serialization canonique sans perte | PLANNED |
| round-trip public déterministe | 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 |
## 7. HTTP et sécurité
## 8. HTTP et sécurité
| Invariant | Statut |
|------------------------------------------------|---------|
@@ -130,7 +146,7 @@ Avant la stable, les conditions d'usage et la persistance des offres gratuites d
| 5xx classé transient | PLANNED |
| schema drift classé provider protocol | PLANNED |
## 8. DexScreener V1
## 9. DexScreener V1
| Invariant | Statut |
|----------------------------------------------|---------|
@@ -142,7 +158,7 @@ Avant la stable, les conditions d'usage et la persistance des offres gratuites d
| aucun tri automatique par liquidité | PLANNED |
| aucune moyenne/consensus entre pools | PLANNED |
## 9. Config -> Off-chain Transport
## 10. Config -> Off-chain Transport
| Invariant | Statut |
|------------------------------------------------------------------|---------|
@@ -159,7 +175,7 @@ Avant la stable, les conditions d'usage et la persistance des offres gratuites d
| `.env.example` synchronisé pour les secrets réellement ajoutés | PLANNED |
| aucune cadence provider configurable au-dessus de la limite sûre | PLANNED |
## 10. Frontière future `ksp-app-solprices-desk`
## 11. Frontière future `ksp-app-solprices-desk`
| Invariant | Statut |
|--------------------------------------------------------------------|---------|
@@ -175,7 +191,7 @@ Avant la stable, les conditions d'usage et la persistance des offres gratuites d
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`.
## 11. Non-régression et gates finaux prévus
## 12. Non-régression et gates finaux prévus
| Gate | Statut |
|-------------------------------------------------|---------|
@@ -193,7 +209,7 @@ Cette section valide l'architecture préparée par `0.2.11`; l'application elle-
| smokes keyed gratuits disponibles à l'opérateur | PLANNED |
| réconciliation README/USAGE/plan/validation | PLANNED |
## 12. Hors scope validé
## 13. Hors scope validé
```text
SOL/EUR et autres quotes