<!-- file: docs/validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md -->
<!-- version: 3 -->

# Validation `0.2.10` — OrbitFlare Yellowstone gRPC

**Statut courant : `0.2.10-pre.002` est commité et son gate statique/workspace est vert. Son live sans metadata a atteint OrbitFlare mais `SubscribeOpen` a été rejeté `Unauthenticated`. `0.2.10-pre.002-fix.001` corrige l’auth en License Key `ORBIT-*` transmise comme secret `x-token`, sans modification N1/N2. Le rerun authentifié `Subscribe -> Slot + Ping` reste `PENDING OPERATOR`.**

## 1. Autorités

```text
RULES.md + docs/rules/*
archive stable v0.2.9
plan 016 et validation 012 pour N1/N2
plan 017 courant
prompt 015 pour les contraintes non supersédées
deltas/0.2.10/*
OrbitFlare docs/pricing/SDK/CLI actuels
Yellowstone upstream actuel
```

## 2. Baseline stable

| Gate                                     | Résultat                         |
|------------------------------------------|----------------------------------|
| version de base                          | `0.2.9` PASS                     |
| `deltas/0.2.9/rel.001.md`                | PASS                             |
| prompt `015`                             | PASS                             |
| `cargo fmt --all`                        | PASS                             |
| audit Rust                               | PASS                             |
| audit Markdown                           | PASS                             |
| `cargo check --workspace`                | PASS                             |
| `cargo clippy --workspace --all-targets` | PASS                             |
| `cargo test --workspace`                 | PASS                             |
| Transport unit                           | 383 sur 383 PASS                 |
| Transport public API                     | 49 sur 49 PASS                   |
| Transport release completeness           | 43 sur 43 PASS                   |
| Config unit                              | 113 sur 113 PASS                 |
| graph duplicates Transport               | fourni, aucun conflit N1 visible |
| graph complet Transport                  | fourni sur `0.2.10-pre.1` PASS   |

## 3. Invariant architecture

| Exigence                               | Verdict  |
|----------------------------------------|----------|
| moteur gRPC N1 modifié pour OrbitFlare | **NO**   |
| standard Yellowstone N2 modifié        | **NO**   |
| second client Tonic                    | **NO**   |
| SDK OrbitFlare runtime                 | **NO**   |
| provider séparé du protocol            | **PASS** |
| Config -> Transport seulement          | **PASS** |
| Transport -> Config/env                | **PASS** |
| façade provider sans divergence        | **NO**   |

Toute modification de `grpc_stream.rs`, `grpc_channel.rs`, `grpc_settings.rs`, `grpc_unary.rs` ou `grpc_subscribe.rs` motivée uniquement par OrbitFlare invalide ce gate.

## 4. Pricing et réseau

| Point                | Preuve actuelle                          | Verdict       |
|----------------------|------------------------------------------|---------------|
| plan Solana Free     | 0 USD par mois                           | **PASS**      |
| gRPC Free            | Devnet only                              | **PASS**      |
| RPS Free             | 10                                       | INFO          |
| TPS Free             | 1                                        | INFO          |
| crédit               | unlimited dans le RPS                    | INFO          |
| Devnet gRPC endpoint | `http://devnet.rpc.orbitflare.com:10000` | **PASS**      |
| Devnet live KSP      | service atteint, Subscribe auth rejeté   | **AUTH GATE** |
| Mainnet gratuit      | non documenté                            | **OUT**       |
| Testnet endpoint     | non prouvé                               | **UNKNOWN**   |

Sources :

```text
https://orbitflare.com/pricing
https://orbitflare.com/products/rpc-nodes
https://docs.orbitflare.com/cli
```

## 5. Transport security

| Forme endpoint                        | Classification        | Verdict  |
|---------------------------------------|-----------------------|----------|
| `http://*.rpc.orbitflare.com:10000`   | HTTP/2 plaintext      | **PASS** |
| `https://*.grpc.orbitflare.com`       | HTTP/2 TLS            | **PASS** |
| transformation automatique http/https | interdite             | **PASS** |
| endpoint Dashboard                    | autoritaire si fourni | **PASS** |

KSP ne prétend pas qu'un canal gRPC plaintext bénéficie d'une sécurité TLS implicite.

## 6. Auth classification

| Élément               | Usage prouvé                | Verdict                      |
|-----------------------|-----------------------------|------------------------------|
| `X-ORBIT-KEY`         | Customer API                | **CONTROL-PLANE**            |
| Bearer Device Flow    | Customer API v2             | **CONTROL-PLANE**            |
| RPC `api_key`         | Solana HTTP RPC             | **HTTP ONLY**                |
| License Key `ORBIT-*` | produit Solana Free         | **DATA-PLANE PROVIDER**      |
| metadata `x-token`    | Yellowstone gRPC OrbitFlare | **REQUIRED / PROVEN DOC**    |
| sans metadata         | live KSP `pre.002`          | **REJECTED UNAUTHENTICATED** |
| IP whitelist          | autre mode produit          | **NOT ACTIVE FOR OPERATOR**  |

Preuve live `pre.002` :

```text
grpc_operation = SubscribeOpen
grpc_status    = Unauthenticated
grpc_code      = The request does not have valid authentication credentials
```

Preuve provider : la référence Yellowstone OrbitFlare construit le client avec `X_TOKEN = ORBITFLARE_LICENSE_KEY` et indique que le token est porté par la metadata gRPC `x-token`.

Le Dashboard opérateur classe le produit `Solana Free` en `API Key Mode Active`. La License Key est donc le secret data-plane à utiliser ; elle n’est pas une `X-ORBIT-KEY` Customer API.

Le CLI OrbitFlare courant n’est pas utilisé comme oracle positif pour l’auth gRPC : après stockage de la License Key, `orbitflare ping --service grpc --network devnet` retourne `invalid x-token: api key not found`, et son implémentation courante n’injecte pas le secret dans le canal gRPC.

## 7. Heartbeat

| Point                                  | Preuve                                   | Verdict     |
|----------------------------------------|------------------------------------------|-------------|
| OrbitFlare idle timeout partagé        | environ 10 minutes                       | **PASS**    |
| OrbitFlare recommande client Ping      | 30 secondes                              | **PASS**    |
| Yellowstone serveur Ping périodique    | upstream documenté                       | **PASS**    |
| KSP auto reply au serveur Ping         | test N1 `0.2.9`                          | **PASS**    |
| moteur N1 à modifier                   | non                                      | **PASS**    |
| Ping serveur OrbitFlare Devnet observé | live non encore exécuté                  | **PENDING** |
| heartbeat provider additionnel         | non justifié tant que live non contraire | **NO**      |

Critère de fermeture : observer le Ping standard sur OrbitFlare Devnet ou qualifier précisément pourquoi il n'est pas observable et quelle divergence provider existe.

## 8. Capabilities streaming

| Capability          | Docs OrbitFlare | KSP N2 | Live provider |
|---------------------|-----------------|--------|---------------|
| accounts            | oui             | PASS   | PENDING       |
| slots               | oui             | PASS   | PENDING       |
| transactions        | oui             | PASS   | PENDING       |
| transactions_status | partiel         | PASS   | PENDING       |
| blocks              | oui             | PASS   | PENDING       |
| blocks_meta         | oui             | PASS   | PENDING       |
| entry               | oui             | PASS   | PENDING       |
| commitment          | oui             | PASS   | PENDING       |
| accounts_data_slice | oui             | PASS   | PENDING       |
| Subscribe Ping/Pong | oui             | PASS   | PENDING       |

Le premier smoke n'a pas besoin de démontrer chaque famille. Il doit prouver que le provider exécute le standard KSP sur Devnet ; les capacités supplémentaires sont sondées sans élargir N2.

## 9. Unary et replay

| Capability          | N2 KSP | OrbitFlare docs | Live    |
|---------------------|--------|-----------------|---------|
| SubscribeReplayInfo | PASS   | non prouvé      | PENDING |
| Ping unary          | PASS   | non prouvé      | PENDING |
| GetLatestBlockhash  | PASS   | non prouvé      | PENDING |
| GetBlockHeight      | PASS   | non prouvé      | PENDING |
| GetSlot             | PASS   | non prouvé      | PENDING |
| IsBlockhashValid    | PASS   | non prouvé      | PENDING |
| GetVersion          | PASS   | non prouvé      | PENDING |
| from_slot           | PASS   | non prouvé      | PENDING |
| retention           | N/A    | non documentée  | UNKNOWN |

Une restriction provider ne rétrograde jamais la disponibilité de la méthode dans le standard global KSP.

## 10. Limits provider

| Limite                       | Valeur                   | Verdict |
|------------------------------|--------------------------|---------|
| concurrent gRPC connections  | 50 par IP                | INFO    |
| subscriptions par connection | unlimited                | INFO    |
| cap partagé entre régions    | oui                      | INFO    |
| idle timeout                 | environ 10 minutes       | INFO    |
| dépassement                  | `RESOURCE_EXHAUSTED`     | INFO    |
| backoff recommandé           | exponentiel jusqu'à 30 s | INFO    |

Ces valeurs restent provider-owned et ne deviennent pas des validations génériques de `YellowstoneGrpcSessionSettings`.

## 11. Config V3

| Exigence                              | Verdict         |
|---------------------------------------|-----------------|
| nouveau format Config nécessaire      | **NO**          |
| `provider = orbitflare`               | **PASS STATIC** |
| `protocol = solana_yellowstone`       | **PASS STATIC** |
| `cluster = devnet`                    | **PASS STATIC** |
| Devnet URL publique                   | **PASS STATIC** |
| secret metadata `x-token`             | **REQUIRED**    |
| valeur License Key via `KSP_SECRET_*` | **PASS DESIGN** |
| `X-ORBIT-KEY` dans Transport Config   | **FORBID**      |
| heartbeat dans `grpc_defaults`        | **NO**          |

`pre.002-fix.001` corrige le profil en :

```text
secret_metadata = x-token <- ${KSP_SECRET_ORBITFLARE_DEVNET_GRPC_X_TOKEN}
```

La valeur effective doit rester redacted dans toutes les projections safe/debug.

## 12. Smoke Devnet attendu

Smoke corrigé :

```text
License Key lue sur stdin
YellowstoneGrpcMetadataEntry::secret("x-token", ...)
provider = orbitflare
cluster = devnet
url = http://devnet.rpc.orbitflare.com:10000
open standard Subscribe
request slots confirmed
receive Slot non nul
observe Ping serveur pendant fenêtre bornée de caractérisation
close borné
```

Verdicts actuels :

| Preuve                                       | Verdict                        |
|----------------------------------------------|--------------------------------|
| endpoint parsé par N1                        | **PASS STATIC**                |
| sans metadata                                | **FAIL EXPECTED / CLASSIFIED** |
| secret `x-token` représentable par Config V3 | **PASS STATIC**                |
| License Key redacted                         | **PASS STATIC**                |
| connect authentifié                          | **PENDING OPERATOR**           |
| Subscribe authentifié                        | **PENDING OPERATOR**           |
| Slot reçu                                    | **PENDING OPERATOR**           |
| server Ping reçu                             | **PENDING OPERATOR**           |
| auto reply KSP déterministe                  | **PASS N1**                    |
| close borné                                  | **PASS N1 / LIVE PENDING**     |

## 13. Provider overlay gate

La release reste sans façade OrbitFlare si `pre.002` démontre :

```text
standard Subscribe fonctionne
heartbeat standard fonctionne
Config V3 exprime endpoint/auth
aucune restriction consumer-visible ne requiert un type provider
```

Une façade/policy OrbitFlare devient admissible seulement après preuve live d'une divergence. Même dans ce cas :

```text
N1 ne change pas
N2 ne change pas
pas de raw Tonic
pas de SDK OrbitFlare
ownership/close provider bornés
```

## 14. Non-régressions finales

| Surface                           | Baseline     | Final   |
|-----------------------------------|--------------|---------|
| HTTP current typed                | 52 sur 52    | PENDING |
| HTTP historical                   | 14 sur 14    | PENDING |
| WebSocket standard                | 18 sur 18    | PENDING |
| Helius LaserStream WebSocket      | stable 0.2.8 | PENDING |
| Yellowstone N1/N2                 | stable 0.2.9 | PENDING |
| PublicNode Mainnet/Testnet        | stable 0.2.9 | PENDING |
| Config V1/V2/V3 backward readable | stable 0.2.9 | PENDING |
| dependency firewall               | stable 0.2.9 | PENDING |

## 15. Gate `pre.001`

| Critère                             | Verdict                |
|-------------------------------------|------------------------|
| base stable `v0.2.9`                | **PASS**               |
| baseline fmt/audits/check/clippy    | **PASS**               |
| workspace test                      | **PASS**               |
| graph duplicates                    | **PASS**               |
| graph complet Transport             | **PASS**               |
| sources OrbitFlare actuelles        | **PASS**               |
| sources Yellowstone actuelles       | **PASS**               |
| Free Devnet gRPC confirmé           | **PASS**               |
| endpoints classifiés                | **PASS**               |
| auth planes distingués              | **PASS**               |
| heartbeat KSP vs provider classifié | **PASS, LIVE PENDING** |
| capabilities auditées               | **PASS, LIVE PENDING** |
| replay/from_slot                    | **UNKNOWN PROVIDER**   |
| N1 immutable                        | **PASS**               |
| N2 immutable                        | **PASS**               |
| Config V3 shape                     | **PASS**               |
| smoke ownership                     | **PASS**               |
| threat model                        | **PASS**               |
| sizing/forecast                     | **PASS**               |
| provider runtime lourd ajouté       | **NO**                 |

Verdict :

```text
architecture/sizing gate      = POSITIVE
operator pre.001 gate          = PASS
pre.002 static/workspace gate  = PASS
pre.002 live auth hypothesis   = FAIL CLASSIFIED
pre.002-fix.001 static gate    = READY FOR OPERATOR VALIDATION
live provider gate             = PENDING authenticated characterization
```

## 16. Gate `pre.002` commité

Validation opérateur du 2026-08-25 :

| Critère                                  | Verdict                         |
|------------------------------------------|---------------------------------|
| Cargo `0.2.10-pre.2`                     | **PASS**                        |
| `cargo fmt --all`                        | **PASS**                        |
| audit Rust                               | **PASS**                        |
| audit Markdown                           | **PASS / 98 tables / 98 files** |
| `cargo check --workspace`                | **PASS**                        |
| `cargo clippy --workspace --all-targets` | **PASS**                        |
| Config unit                              | **114 sur 114 PASS**            |
| Transport unit                           | **383 sur 383 PASS**            |
| Transport public API                     | **49 sur 49 PASS**              |
| Transport release completeness           | **43 sur 43 PASS**              |
| workspace test                           | **PASS**                        |
| graphes Transport                        | **FOURNIS / PAS DE CONFLIT N1** |
| moteur N1 modifié                        | **NO**                          |
| standard N2 modifié                      | **NO**                          |
| live sans metadata                       | **FAIL CLASSIFIED**             |
| `SubscribeOpen`                          | **UNAUTHENTICATED**             |

Le failure live est un résultat de caractérisation utile et non une régression du moteur. Il impose un fix de configuration/auth provider parce que `pre.002` est déjà commité.

## 17. Gate `pre.002-fix.001`

| Critère                                                         | Verdict              |
|-----------------------------------------------------------------|----------------------|
| Cargo `0.2.10-pre.2.fix.1`                                      | **PASS STATIC**      |
| `.env.example` inventorie le secret OrbitFlare                  | **PASS STATIC**      |
| Config `secret_metadata` contient `x-token`                     | **PASS STATIC**      |
| valeur provenant de `KSP_SECRET_ORBITFLARE_DEVNET_GRPC_X_TOKEN` | **PASS STATIC**      |
| test Config prouve redaction et classification secrète          | **PASS STATIC**      |
| smoke lit la License Key sur stdin                              | **PASS STATIC**      |
| secret absent des arguments CLI                                 | **PASS STATIC**      |
| moteur N1 modifié                                               | **NO**               |
| standard N2 modifié                                             | **NO**               |
| SDK OrbitFlare ajouté                                           | **NO**               |
| connect authentifié                                             | **PENDING OPERATOR** |
| `Subscribe -> Slot` live                                        | **PENDING OPERATOR** |
| `SubscribeUpdate::Ping` live                                    | **PENDING OPERATOR** |
| close live                                                      | **PENDING OPERATOR** |

Commande live dédiée, avec secret saisi sans l’inscrire dans l’historique :

```bash
read -rsp 'OrbitFlare License Key: ' ORBITFLARE_LICENSE_KEY; echo
printf '%s\n' "$ORBITFLARE_LICENSE_KEY" | cargo test -p ksp-onchain-transport-lib --test yellowstone_orbitflare_smoke -- --ignored --nocapture
unset ORBITFLARE_LICENSE_KEY
```

Interprétation :

```text
Slot + Ping PASS
    -> auth et heartbeat standards composables ; pre.003 devient gate technique/live final

Subscribe/Slot PASS mais Ping absent
    -> divergence heartbeat provider à traiter au-dessus de N1/N2 dans pre.003

auth encore rejetée avec la License Key x-token
    -> blocker provider/account à qualifier ; ne jamais modifier N1 pour contourner le gate
```