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

v0.2.10-pre.002-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-25 14:17:40 +02:00
parent af807afff5
commit 1967e845b0
8 changed files with 464 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
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: 2 -->
<!-- version: 3 -->
# Plan `0.2.10` — OrbitFlare Yellowstone gRPC
**Statut courant : `0.2.10-pre.002` matérialise le profil Config V3 `orbitflare_devnet` et un smoke opt-in de caractérisation `Subscribe -> Slot + Ping` construit exclusivement sur le standard Yellowstone existant. Le moteur gRPC N1 et le standard N2 restent inchangés ; le verdict live Devnet est un gate opérateur de cette tranche.**
**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.**
## 1. Base et autorité
@@ -235,30 +235,40 @@ https://docs.orbitflare.com/data-streaming/yellowstone-quickstart
L'endpoint Dashboard opérateur reste autoritaire lorsqu'il existe. KSP ne transforme jamais automatiquement une URL `http` en `https`, ne change pas de région et ne construit pas un hostname provider non documenté.
## 7. Auth OrbitFlare : classification actuelle
## 7. Auth OrbitFlare : classification live corrigée
Les sources officielles restent hétérogènes, mais leur rôle peut être séparé sans supposition.
Le live `pre.002` et les sources OrbitFlare permettent désormais de séparer les credentials sans supposition.
| Credential ou mécanisme | Plan observé | Classification `pre.001` |
|-------------------------|-----------------------------------------|-------------------------------------------------------|
| `X-ORBIT-KEY` | Customer API | control-plane, jamais injecté automatiquement en gRPC |
| Bearer Customer API | Customer API v2 | control-plane |
| `api_key` RPC | Solana HTTP RPC | data-plane HTTP, pas Yellowstone |
| API key du compte | login CLI / Customer API | ne prouve pas une auth Yellowstone |
| token gRPC Dashboard | certains endpoints/licences gRPC | possible data-plane Yellowstone |
| `x-token` Yellowstone | mécanisme standard upstream | utiliser seulement si le service OrbitFlare le prouve |
| aucune metadata | SDK Go / endpoints régionaux documentés | premier mode à tester sur Devnet Free |
| IP/network entitlement | certains services partagés/dédiés | provider/account dependent |
| Credential ou mécanisme | Usage observé | Classification après `pre.002` |
|-------------------------|---------------------------|------------------------------------------------------|
| `X-ORBIT-KEY` | Customer API | control-plane, interdit sur Yellowstone |
| Bearer Device Flow | Customer API v2 | control-plane |
| `api_key` RPC | Solana HTTP RPC | data-plane HTTP |
| License Key `ORBIT-*` | produit Solana Free | data-plane provider |
| metadata `x-token` | Yellowstone gRPC | transport prouvé de la License Key |
| aucune metadata | premier smoke KSP | rejetée `Unauthenticated` au `SubscribeOpen` |
| IP whitelist | autre mode d’auth produit | non retenu pour le service opérateur en API Key Mode |
Le quickstart TypeScript OrbitFlare demande un endpoint + token de licence et passe ce token au client Yellowstone. Le client upstream Yellowstone utilise classiquement la metadata `x-token`. Cela rend `x-token` plausible pour cette classe de service, mais **ne transforme pas la clé Customer API du compte en token gRPC**.
La référence Yellowstone OrbitFlare donne explicitement le modèle suivant :
```text
ORBITFLARE_LICENSE_KEY
-> metadata gRPC x-token
-> Yellowstone
```
Le Dashboard opérateur confirme parallèlement que le produit `Solana Free` est en `API Key Mode Active`, donc utilisable depuis toute IP avec la License Key. Le `X-ORBIT-KEY` et le Bearer issus du Device Flow restent réservés au Customer API.
Le CLI OrbitFlare courant ne constitue pas un canari gRPC d’auth fiable : son `ping` ouvre le canal sans injecter la License Key et reçoit `invalid x-token: api key not found`. Ce défaut du CLI ne modifie pas le contrat provider documenté.
Décision :
```text
ne jamais demander ou versionner la clé opérateur Customer API
ne jamais versionner la License Key réelle
ne jamais injecter X-ORBIT-KEY dans Yellowstone
commencer le smoke Devnet Free sans metadata secrète
si le Dashboard fournit un token gRPC distinct, classifier son wire avant Config
représenter la License Key par secret_metadata x-token dans Config V3
faire lire le secret du smoke par stdin, jamais par argument CLI
ne modifier ni N1 ni N2 pour cette auth provider
```
## 8. Heartbeat : réconciliation KSP / Yellowstone / OrbitFlare
@@ -399,7 +409,7 @@ Ces valeurs commerciales/opérationnelles ne deviennent pas des constantes du st
## 11. Config V3
Le schéma V3 existant sait déjà représenter le besoin minimal :
Le schéma V3 existant représente directement le contrat live corrigé :
```text
provider = orbitflare
@@ -407,76 +417,69 @@ cluster = devnet
protocol = solana_yellowstone
url = http://devnet.rpc.orbitflare.com:10000
metadata = []
secret_metadata = []
secret_metadata = x-token <- ${KSP_SECRET_ORBITFLARE_DEVNET_GRPC_X_TOKEN}
```
La variable porte la License Key `ORBIT-*` du produit Solana Free. Elle ne porte jamais `X-ORBIT-KEY`.
Décision :
```text
pas de format_version 4
pas de champ region si l'URL suffit
pas de champ region si l’URL suffit
pas de heartbeat dans grpc_defaults
pas de secret tant que le Devnet Free n'en exige pas
secret provider géré par Config V3 existante
redaction KSP obligatoire dans safe/debug projections
```
Profil matérialisé en `pre.002` :
```text
orbitflare_devnet
```
Le profil conserve les companions HTTP/WS Solana Devnet standards et ajoute exactement un endpoint gRPC :
```text
name = orbitflare_solana_devnet_yellowstone
provider = orbitflare
cluster = devnet
protocol = solana_yellowstone
url = http://devnet.rpc.orbitflare.com:10000
metadata = []
secret = []
```
Si le service opérateur réel impose ensuite un token gRPC :
```text
secret_metadata = x-token <- ${KSP_SECRET_ORBITFLARE_DEVNET_GRPC_X_TOKEN}
```
Cette variable n'est ajoutée à `.env.example` qu'après preuve qu'un secret data-plane est réellement requis.
Le profil `orbitflare_devnet` conserve les companions HTTP/WS Solana Devnet standards et ajoute exactement un endpoint gRPC authentifié par secret metadata `x-token`.
## 12. Stratégie live Devnet
### 12.1 Premier canari
### 12.1 Résultat du premier canari `pre.002`
`pre.002` ajoute `tests/yellowstone_orbitflare_smoke.rs`. Ce canari opt-in utilise **le standard N2 existant directement** et ne dépend pas de Config, conformément à la frontière Transport -> Config interdite :
Le smoke initial utilisait le standard N2 directement, sans Config et sans metadata. Le canal physique a atteint le service OrbitFlare, puis l’ouverture du Subscribe a retourné :
```text
grpc_operation = SubscribeOpen
grpc_status = Unauthenticated
grpc_code = The request does not have valid authentication credentials
```
Cette preuve ferme l’hypothèse « Devnet Free sans metadata ».
### 12.2 Canari corrigé `pre.002-fix.001`
Le même test reste provider-neutral et ne dépend toujours pas de Config. Il lit une seule License Key sur stdin puis construit la metadata secrète standard :
```text
endpoint = http://devnet.rpc.orbitflare.com:10000
provider = orbitflare
cluster = devnet
protocol = solana_yellowstone
auth = aucune metadata en première tentative
auth = x-token <- License Key lue sur stdin
request = Subscribe slots à commitment confirmed
preuve = au moins un Slot non nul
close = borné
```
### 12.2 Preuve heartbeat
La valeur secrète ne doit apparaître ni dans Debug ni dans la ligne de commande.
Le smoke de caractérisation doit aussi attendre suffisamment pour observer :
### 12.3 Preuve heartbeat
Le smoke corrigé attend encore suffisamment pour observer :
```text
SubscribeUpdate::Ping
```
Un `Ping` serveur live, combiné au test déterministe N1 qui prouve la réponse automatique, ferme le besoin heartbeat sans code OrbitFlare.
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.
Le smoke final durable peut rester court après cette caractérisation ; il n’a pas besoin de patienter 10 minutes à chaque workspace run.
### 12.3 Unary et replay
### 12.4 Unary et replay
Après le canari Subscribe :
Après le canari Subscribe authentifié :
```text
probe 7 unary N2
@@ -538,38 +541,40 @@ README/USAGE dans la tranche documentaire finale
## 15. Forecast recalibré
Le chemin nominal est plus court que le forecast du prompt.
Le fix d’auth ne change pas l’ordre des couloirs finaux.
```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
statique : profil sans metadata + canari Subscribe slots confirmed + fenêtre Ping 45 s + close borné
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 final si OrbitFlare reste 100 pourcent standard,
soit tranche provider-specific minimale uniquement si pre.002 démontre une divergence réelle
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 cette responsabilité est absorbée par pre.003
pre.004 gate technique/live final si pre.003 a porté une divergence ; sinon réconciliation documentaire finale
pre.005 réconciliation documentaire finale après dernier gate technique
plan + validation + README + USAGE + références durables
pre.005 publication minimale si pre.004 est documentaire ; sinon réconciliation documentaire finale
pre.006 préparation de publication minimale si une pre.005 documentaire existe à ce numéro
prompt 0.2.11 + CHANGELOG + ROADMAP seulement, hors Cargo/delta mécaniques
pre.006 publication minimale uniquement si la divergence a décalé les couloirs précédents
rel.001 publication stable stricte
```
Numérotation effective :
Chemins effectifs :
```text
chemin standard probable pre.001 -> pre.002 -> pre.003 technique -> pre.004 docs -> pre.005 publication -> rel.001
chemin divergence pre.001 -> pre.002 -> pre.003 provider -> pre.004 technique -> pre.005 docs -> pre.006 publication -> rel.001
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 des couloirs finaux reste obligatoire.
Le numéro n’est jamais le critère de clôture ; l’ordre technique, documentaire, publication reste obligatoire.
## 16. Critères de split
@@ -577,7 +582,7 @@ Ouvrir une tranche provider dédiée avant le gate final si et seulement si le l
```text
OrbitFlare n'émet pas le Ping standard et exige un Ping client proactif
le token gRPC ne peut pas être représenté par secret_metadata V3 existant
l’auth x-token fonctionne mais révèle une exigence provider supplémentaire non composable au-dessus de N1/N2
le service requiert un mécanisme TLS/channel absent du moteur stable
un method/filter standard est remplacé par une extension wire OrbitFlare
le replay/from_slot exige une policy provider visible au consumer