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

v0.2.10-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-25 15:26:04 +02:00
parent be5e3464ee
commit 0edeed1c48
8 changed files with 493 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -365,11 +365,10 @@ Par défaut :
0.2.8 Helius LaserStream WebSocket
0.2.9 Yellowstone gRPC engine + Solana standard + PublicNode
0.2.10 OrbitFlare Yellowstone gRPC
0.2.11 Helius LaserStream gRPC
0.2.12 off-chain price transport
0.2.13 price visualization desk + intégration prix dans Wallet Desk
0.2.14 interface/wire foundation
0.2.15 program-api foundation
0.2.11 off-chain price transport
0.2.12 price visualization desk + intégration prix dans Wallet Desk
0.2.13 interface/wire foundation
0.2.14 program-api foundation
```
`0.2.1-pre.001` a appliqué le gate de sizing et refusé le scope HTTP monolithique initial : l'inventaire du 2026-08-17 contient 52 méthodes courantes et 14 méthodes Deprecated historiques. Ce premier delta avait réparti la couverture typée sur `0.2.1`–`0.2.6`. `0.2.1-pre.001-fix.001` recalibre ensuite les 48 méthodes restantes sur trois releases complémentaires `0.2.2`–`0.2.4`, soit trois sessions nominales au maximum si chaque release utilise sa session complète. Si une release se clôt plus vite que prévu, la même session peut enchaîner la suivante après clôture complète de la précédente et nouveau gate de sizing positif. Un Wallet Desk utile doit pouvoir lire le solde du wallet : `getBalance` fait donc partie des quatre canaris de la foundation `0.2.1`, avant Wallet. Les transports live arrivent ensuite ; Interface/Program restent préparés avant les couches de données décodées.
@@ -487,15 +486,12 @@ Mission active : obtenir en priorité un provider Yellowstone gratuit sur **Devn
Le plan actif est [`017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et la matrice active [`../validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](../validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md).
### `0.2.11` — Helius LaserStream gRPC
Cette release réauditera Helius indépendamment après fermeture stable de `0.2.10`. Elle réutilisera le même moteur N1 et le standard N2 sans les modifier ; seules les capacités, restrictions, auth et policies provider démontrées pourront être ajoutées au-dessus.
### TODO/IDEAS — providers Yellowstone en attente
Aucune release n'est réservée pour :
```text
TODO Helius LaserStream gRPC — réauditer lorsque l'accès live gRPC est disponible
TODO eRPC
TODO Triton
TODO Alchemy
@@ -508,23 +504,25 @@ IDEAS NodeFlare
IDEAS autres providers à réauditer
```
Helius LaserStream gRPC est explicitement reporté : l'audit 2026-08-25 indique une compatibilité wire Yellowstone élevée et une intégration KSP probablement légère au-dessus de N1/N2, mais aucun accès live Helius gRPC n'est actuellement disponible sans plan payant. Il ne reçoit donc plus de numéro de release tant que l'auth, les endpoints, le Subscribe, le Ping, le replay/from_slot et les erreurs provider ne peuvent pas être validés live. Les extensions Helius non standard, notamment les preprocessed transactions, restent un sujet provider séparé.
Ces providers ne déplacent pas la séquence active et ne reçoivent ni façade, ni Config profile, ni smoke tant qu'une décision explicite d'implémentation n'est pas prise.
### `0.2.12` / `0.2.13` — Off-chain price + app
### `0.2.11` / `0.2.12` — Off-chain price + app
`0.2.12` introduit `ksp-offchain-transport-lib` avec au minimum SOL/USD et SOL/EUR via une abstraction indépendante du premier provider.
`0.2.11` introduit `ksp-offchain-transport-lib` avec au minimum SOL/USD et SOL/EUR via une abstraction indépendante du premier provider.
`0.2.13` ajoute une petite application desk de visualisation/validation. Après stabilisation de cette application spécialisée, la même release doit intégrer la capacité de prix offchain dans `ksp-app-wallet-desk` sans dupliquer la récupération/normalisation appartenant au composant spécialisé.
`0.2.12` ajoute une petite application desk de visualisation/validation. Après stabilisation de cette application spécialisée, la même release doit intégrer la capacité de prix offchain dans `ksp-app-wallet-desk` sans dupliquer la récupération/normalisation appartenant au composant spécialisé.
Metadata HTTP/IPFS/Arweave viendra au premier besoin Metadata réel.
### `0.2.14` — Interface foundation
### `0.2.13` — Interface foundation
`ksp-interface-lib` devient la façade wire officielle et expose une API publique wire utilisable par les implementations officielles et externes.
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant.
### `0.2.15` — Program API foundation
### `0.2.14` — Program API foundation
Introduire `ksp-program-api`, sans suffixe `-lib`, comme contrat d'extension Program.

192
docs/plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Plan `0.2.10` — OrbitFlare Yellowstone gRPC
**Statut courant : `0.2.10-pre.002-fix.001` corrige l’hypothèse d’auth de `pre.002`. Le live sans metadata a atteint OrbitFlare puis `SubscribeOpen` a été rejeté `Unauthenticated`. Le Dashboard opérateur et la référence Yellowstone OrbitFlare établissent désormais que la License Key `ORBIT-*` du produit Solana Free doit être envoyée comme metadata secrète `x-token`. Config V3 et le smoke sont corrigés sans aucune modification N1/N2 ; le rerun authentifié `Slot + Ping` reste le gate live.**
**Statut courant : le gate technique/live final `0.2.10-pre.003` est vert. OrbitFlare Devnet est validé avec la License Key `ORBIT-*` portée par la metadata secrète `x-token` ; le smoke final observe un Slot non nul puis le `SubscribeUpdate::Ping` Yellowstone standard et ferme proprement la session. N1 et N2 restent inchangés, aucune façade provider ni heartbeat N3 n’est nécessaire. `0.2.10-pre.004` est exclusivement la réconciliation documentaire finale.**
## 1. Base et autorité
@@ -326,23 +326,31 @@ Cette propriété est testée déterministiquement par le moteur N1.
### 8.4 Décision `pre.001`
**Aucun heartbeat OrbitFlare supplémentaire n'est retenu à ce stade.**
La décision initiale de ne pas modifier le moteur est confirmée par le live final.
Le premier smoke Devnet doit vérifier que l'endpoint OrbitFlare émet bien le `SubscribeUpdate::Ping` standard. Si ce Ping live est observé, la combinaison suivante suffit :
Le smoke authentifié `pre.002-fix.001`, puis son rerun dans `pre.003`, ont observé le `SubscribeUpdate::Ping` standard sur OrbitFlare Devnet :
```text
OrbitFlare server Ping live
+
KSP N1 automatic Ping reply deterministic test
=
client-side activity périodique sans code provider supplémentaire
activité bidirectionnelle standard suffisante sans code provider supplémentaire
```
Il est interdit d'ajouter un timer dans `grpc_stream.rs` ou `YellowstoneGrpcSessionSettings` pour OrbitFlare.
Résultat final :
Si le live montre qu'OrbitFlare ne produit pas le Ping standard ou exige réellement un heartbeat proactif indépendant, cela ouvre un **gate provider spécifique séparé**. La solution doit alors être composée au-dessus de N1 sans modifier le moteur et sans corrompre la requête de reconnect mémorisée.
```text
heartbeat OrbitFlare N3 non nécessaire
façade provider non nécessaire
YellowstoneGrpcSessionSettings inchangé
grpc_stream.rs inchangé
latest_request reconnect sémantique N1 préservée
```
Point de sécurité important : appeler naïvement la mutation standard avec un request `ping` seul n'est pas acceptable, car le moteur mémorise la dernière mutation complète pour le replay/reconnect. Une éventuelle façade provider doit préserver cette sémantique au lieu de contourner N1.
Il reste interdit d'ajouter un timer dans `grpc_stream.rs` ou `YellowstoneGrpcSessionSettings` pour OrbitFlare. La recommandation provider d’un ping client périodique ne devient pas une policy globale tant que le chemin standard serveur Ping -> réponse automatique N1 satisfait le service live.
Le point de sécurité initial reste durable : envoyer naïvement une requête `ping` seule via la mutation publique remplacerait la dernière subscription mémorisée pour reconnect. Si un futur provider exige un heartbeat proactif indépendant, cette policy doit être composée au-dessus de N1 sans corrompre cette sémantique.
## 9. Capabilities OrbitFlare
@@ -366,7 +374,7 @@ Le CLI/SDK montre également les filtres account/transaction/slot/block standard
### 9.2 Surface non encore prouvée provider
Ces capacités existent dans N2 KSP mais ne sont pas déclarées supportées sur OrbitFlare sans preuve supplémentaire :
Ces capacités existent dans N2 KSP mais n'ont pas été exhaustivement sondées sur le plan OrbitFlare Free pendant `0.2.10` :
```text
SubscribeReplayInfo
@@ -381,16 +389,18 @@ transactions_status complet
champs récents compressed/cuckoo/token expansion selon endpoint déployé
```
L'absence de documentation n'est pas une preuve d'absence. Le live provider doit distinguer :
La clôture de `0.2.10` ne transforme pas l'absence de probe en absence de support. Le live final requis portait sur le chemin opérationnel utile à la release : authentification, standard Subscribe, Slot, Ping serveur et close borné.
Classification durable :
```text
standard KSP disponible
provider support prouvé
provider entitlement éventuel
unknown non testé
standard KSP disponible oui dans N2
provider support live prouvé Subscribe slots + commitment + Ping
provider entitlement éventuel provider-owned
reste unknown / non exhaustivement testé
```
Aucune capacité N2 n'est supprimée du standard global à cause d'une restriction OrbitFlare.
Aucune capacité N2 n'est supprimée du standard global à cause d'une restriction ou d'un inconnu OrbitFlare.
## 10. Limits et quotas utiles
@@ -401,7 +411,7 @@ La documentation actuelle des services partagés indique :
| connexions gRPC simultanées | 50 par IP | information provider, pas borne N1 |
| portée du cap | globale par IP et régions gRPC partagées | éviter les reconnect storms |
| subscriptions par connexion | unlimited | ne pas convertir en garantie universelle |
| idle timeout | environ 10 minutes | gate heartbeat live |
| idle timeout | environ 10 minutes | chemin Ping standard validé live |
| dépassement | gRPC `RESOURCE_EXHAUSTED` | status distant safe existant |
| reconnect conseillé | exponential backoff | KSP N1 possède déjà un budget/backoff borné |
@@ -459,35 +469,50 @@ cluster = devnet
protocol = solana_yellowstone
auth = x-token <- License Key lue sur stdin
request = Subscribe slots à commitment confirmed
preuve = au moins un Slot non nul
preuve = au moins un Slot non nul + SubscribeUpdate::Ping
close = borné
```
La valeur secrète ne doit apparaître ni dans Debug ni dans la ligne de commande.
La valeur secrète n'apparaît ni dans Debug ni dans la ligne de commande.
Résultats opérateur :
```text
pre.002-fix.001 Subscribe -> Slot + Ping PASS en 5.10 s
pre.003 final Subscribe -> Slot + Ping PASS en 5.19 s
```
Le second passage ferme le gate live sur la version `0.2.10-pre.3` utilisée pour la clôture technique.
### 12.3 Preuve heartbeat
Le smoke corrigé attend encore suffisamment pour observer :
Le `SubscribeUpdate::Ping` standard est observé live sur OrbitFlare Devnet avec l'auth correcte.
La combinaison suivante est donc prouvée :
```text
SubscribeUpdate::Ping
Subscribe authentifié
-> Slot non nul
-> SubscribeUpdate::Ping serveur
-> chemin de réponse automatique N1 déjà couvert déterministiquement
-> close borné
```
Un `Ping` serveur live, combiné au test déterministe N1 qui prouve la réponse automatique, ferme le besoin heartbeat sans code OrbitFlare. Si aucun Ping serveur n’est observé après authentification, cette divergence est traitée dans une tranche provider dédiée au-dessus de N1/N2.
Le smoke final durable peut rester court après cette caractérisation ; il n’a pas besoin de patienter 10 minutes à chaque workspace run.
Verdict final : aucune divergence heartbeat OrbitFlare ne justifie une façade ou une policy provider. Le moteur gRPC et le standard Yellowstone restent inchangés.
### 12.4 Unary et replay
Après le canari Subscribe authentifié :
Les sept unary N2, `SubscribeReplayInfo` et la retention `from_slot` n'ont pas été rendus obligatoires pour le gate OrbitFlare Free.
Cette décision évite de confondre :
```text
probe 7 unary N2
probe SubscribeReplayInfo
probe from_slot si support observable
complétude du standard KSP N2
support/entitlement d'un provider particulier
preuve minimale nécessaire à la mission Devnet de 0.2.10
```
Les probes provider ne doivent pas rendre indisponible le smoke minimal `Subscribe -> Slot` si le plan gratuit restreint certaines unary.
Le moteur N1 reste capable d'utiliser `SubscribeReplayInfo` quand il est disponible et tolère son indisponibilité pendant reconnect en poursuivant avec le `from_slot` conservateur demandé. Aucun comportement provider n'est introduit pour combler un inconnu de service.
## 13. Threat model recalibré
@@ -541,44 +566,25 @@ README/USAGE dans la tranche documentaire finale
## 15. Forecast recalibré
Le fix d’auth ne change pas l’ordre des couloirs finaux.
Le chemin effectif de `0.2.10` est désormais figé :
```text
pre.001 audit actuel + architecture immuable N1/N2 + auth/endpoints + free Devnet + heartbeat + sizing
preuve : plan 017 + validation 013 + delta + baseline
pre.002 profil Config V3 OrbitFlare Devnet + smoke de caractérisation standard N2
hypothèse initiale sans metadata ; live classifie Unauthenticated au SubscribeOpen
pre.002-fix.001
corrige l’auth par License Key -> secret x-token
adapte .env.example, Config test et smoke stdin
live : Subscribe -> Slot + observation Ping serveur ; aucune modification moteur gRPC
pre.003 soit gate technique/live final si le rerun authentifié reste 100 pourcent standard,
soit tranche provider-specific minimale uniquement si le live démontre une divergence heartbeat réelle
pre.004 gate technique/live final si pre.003 a porté une divergence ; sinon réconciliation documentaire finale
pre.005 publication minimale si pre.004 est documentaire ; sinon réconciliation documentaire finale
pre.006 publication minimale uniquement si la divergence a décalé les couloirs précédents
rel.001 publication stable stricte
pre.001 audit actuel + architecture immuable N1/N2 + auth/endpoints + Free Devnet + heartbeat + sizing
pre.002 profil Config V3 OrbitFlare Devnet + smoke de caractérisation sans metadata
pre.002-fix.001 auth corrigée : License Key -> secret x-token ; live Subscribe -> Slot + Ping PASS
pre.003 gate technique/live final ; workspace + graphes + rerun OrbitFlare PASS
pre.004 réconciliation documentaire finale
pre.005 publication minimale après décision explicite sur la release suivante
rel.001 publication stable stricte
```
Chemins effectifs :
La branche de divergence heartbeat n'a pas été déclenchée. Aucun couloir supplémentaire n'est requis.
```text
standard pre.001 -> pre.002 -> pre.002-fix.001 -> pre.003 technique -> pre.004 docs -> pre.005 publication -> rel.001
divergence pre.001 -> pre.002 -> pre.002-fix.001 -> pre.003 provider -> pre.004 technique -> pre.005 docs -> pre.006 publication -> rel.001
```
Le numéro n’est jamais le critère de clôture ; l’ordre technique, documentaire, publication reste obligatoire.
Le numéro n'est jamais le critère de clôture ; l'ordre technique, documentaire puis publication reste obligatoire.
## 16. Critères de split
Ouvrir une tranche provider dédiée avant le gate final si et seulement si le live démontre l'un de ces cas :
Les critères de split définis pendant l'audit étaient :
```text
OrbitFlare n'émet pas le Ping standard et exige un Ping client proactif
@@ -589,39 +595,65 @@ le replay/from_slot exige une policy provider visible au consumer
un failover provider impose une sémantique que N1 ne peut pas composer sans modification
```
Dans le dernier cas, ne pas modifier N1 dans `0.2.10` : qualifier le blocker et replanifier l'architecture.
**Aucun de ces critères n'a été déclenché par le gate live final.**
Le principe reste durable pour les providers futurs : si une divergence ne peut pas être composée proprement au-dessus de N1/N2, ne pas modifier le moteur pour le provider ; qualifier le blocker et replanifier l'architecture.
## 17. Critères de clôture
`0.2.10` est stable seulement si :
État à l'entrée de `pre.004` :
```text
Devnet OrbitFlare Free réellement atteint par KSP ou bloc externe qualifié
N1 gRPC inchangé
N2 Yellowstone inchangé
aucun SDK OrbitFlare runtime
provider/auth correctement classifiés
aucune Customer API key sur le data-plane Yellowstone
heartbeat live classifié
Config V3 cohérente sans nouveau format inutile
smoke provider architecture-safe
PublicNode non régressé
Yellowstone standard non régressé
HTTP 52+14 non régressé
WebSocket standard 18/18 non régressé
Helius WebSocket non régressé
workspace complet vert
graphes Cargo inspectés
réconciliation documentaire séparée
publication minimale séparée
Devnet OrbitFlare Free atteint par KSP PASS
N1 gRPC inchangé PASS
N2 Yellowstone inchangé PASS
aucun SDK OrbitFlare runtime PASS
provider/auth correctement classifiés PASS
aucune Customer API key sur le data-plane Yellowstone PASS
heartbeat live classifié PASS
Config V3 cohérente sans nouveau format PASS
smoke provider architecture-safe PASS
PublicNode non régressé déterministiquement PASS
Yellowstone standard non régressé PASS
HTTP 52+14 non régressé PASS
WebSocket standard 18/18 non régressé PASS
Helius WebSocket non régressé PASS
workspace complet vert PASS
graphes Cargo inspectés PASS
réconciliation documentaire séparée EN COURS pre.004
publication minimale séparée À FAIRE pre.005
```
Le gate technique est donc fermé. La stabilité `0.2.10` reste conditionnée à la validation documentaire `pre.004`, au couloir publication-minimal `pre.005`, puis à `rel.001`.
## 18. Release suivante
La release suivante reste :
La décision préalable à `pre.005` est désormais prise. L'ancien forecast :
```text
0.2.11 — Helius LaserStream gRPC
```
Elle doit appliquer le même invariant : le moteur gRPC `0.2.9` est une fondation stable ; Helius ne peut ajouter que des fonctionnalités provider au-dessus.
est reporté dans les TODO Yellowstone sans numéro de release. L'audit du 2026-08-25 conclut que la surface Helius reste largement wire-compatible Yellowstone et pourrait probablement se composer au-dessus de N1/N2, mais l'accès gRPC Helius exige actuellement un plan payant que l'opérateur ne retient pas uniquement pour ce test. La release provider est donc différée jusqu'à disponibilité d'un accès live permettant de valider réellement auth, endpoints, Subscribe, Ping, replay/from_slot et erreurs provider. Les extensions Helius non standard restent un sujet séparé.
La séquence active avance d'un cran :
```text
0.2.11 — off-chain price transport
0.2.12 — Price Desk + intégration prix Wallet Desk
0.2.13 — interface/wire foundation
0.2.14 — program-api foundation
```
Décision de publication :
```text
aucun prompt suivant dans pre.004
aucun changement CHANGELOG/ROADMAP dans pre.004
Helius gRPC -> TODO futur sans numéro
0.2.11 -> off-chain price transport
pre.005 préparera seulement le prompt 0.2.11 + CHANGELOG + ROADMAP
```
Quel que soit le provider futur, l'invariant reste le même : N1 gRPC et N2 Yellowstone sont des fondations stables ; les différences provider se composent au-dessus et ne modifient jamais le moteur pour satisfaire un fournisseur.