<!-- file: docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md -->
<!-- version: 3 -->

# Validation `0.2.9` — moteur Yellowstone + standard Solana + PublicNode

> **Statut : matrice ouverte par `0.2.9-pre.001` et corrigée par `pre.001-fix.001`. Le scope distingue désormais moteur Yellowstone, façade Solana standard et première intégration PublicNode. OrbitFlare/Helius/eRPC sont reportés dans des releases provider dédiées.**

## 1. Autorités du gate

Base interne :

```text
v0.2.8 / archive Gitea stable fournie
workspace.package.version initial = 0.2.8
deltas/0.2.8/rel.001.md
prompts/014-V0_2_9_START_PROMPT.md
```

Sources upstream auditées le `2026-08-23` :

```text
https://github.com/rpcpool/yellowstone-grpc/releases
https://github.com/rpcpool/yellowstone-grpc/blob/master/CHANGELOG.md
https://github.com/rpcpool/yellowstone-grpc/blob/master/LICENSING.md
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/geyser.proto
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/solana-storage.proto
https://docs.rs/crate/yellowstone-grpc-client/latest
https://docs.rs/crate/yellowstone-grpc-proto/latest
```

Divergence enregistrée :

```text
snapshot du prompt : GitHub release v14.2.2+solana.4.1.0
réaudit courant    : GitHub release v15.1.2+solana.4.2.0 (2026-08-18)
crate client       : 13.3.0
crate proto        : 12.6.0
```

## 2. Baseline stable

| Gate                                      | Preuve                 | État |
|-------------------------------------------|------------------------|------|
| `cargo fmt --all`                         | log opérateur `v0.2.8` | DONE |
| audit Rust workspace                      | clean                  | DONE |
| `cargo check --workspace`                 | log opérateur          | DONE |
| `cargo clippy --workspace --all-targets`  | log opérateur          | DONE |
| `cargo test --workspace`                  | log opérateur          | DONE |
| Transport unit                            | 335 passed             | DONE |
| Transport public API                      | 41 passed              | DONE |
| Transport release completeness            | 34 passed              | DONE |
| Transport doctests                        | 4 passed               | DONE |
| `cargo tree -p ksp-onchain-transport-lib` | log opérateur          | DONE |
| `cargo tree --duplicates`                 | log opérateur          | DONE |

## 3. Matrice service `Geyser`

| RPC                   | Forme | Classification                                       | Scope | Preuve cible          | État |
|-----------------------|-------|------------------------------------------------------|-------|-----------------------|------|
| `Subscribe`           | bidi  | standard                                             | IN    | fixture locale + live | TODO |
| `SubscribeDeshred`    | bidi  | Triton extension/pré-exécution malgré présence proto | OUT   | canari d'absence/API  | TODO |
| `SubscribeReplayInfo` | unary | standard                                             | IN    | fixture unary         | TODO |
| `Ping`                | unary | standard                                             | IN    | fixture unary         | TODO |
| `GetLatestBlockhash`  | unary | standard                                             | IN    | fixture unary         | TODO |
| `GetBlockHeight`      | unary | standard                                             | IN    | fixture unary         | TODO |
| `GetSlot`             | unary | standard                                             | IN    | fixture unary         | TODO |
| `IsBlockhashValid`    | unary | standard                                             | IN    | fixture unary         | TODO |
| `GetVersion`          | unary | standard                                             | IN    | fixture unary         | TODO |

## 4. `SubscribeRequest` — coverage normative

### 4.1 Top-level

| Champ                 | Sémantique                             | Scope | Preuve                   |
|-----------------------|----------------------------------------|-------|--------------------------|
| `accounts`            | map filter-name -> account filter      | IN    | exact wire + bounds      |
| `slots`               | map -> slot filter                     | IN    | exact wire               |
| `transactions`        | map -> transaction filter              | IN    | exact wire + bounds      |
| `transactions_status` | map -> transaction filter              | IN    | exact wire + bounds      |
| `blocks`              | map -> block filter                    | IN    | exact wire + bounds      |
| `blocks_meta`         | map -> empty filter                    | IN    | presence/empty semantics |
| `entry`               | map -> empty filter                    | IN    | presence/empty semantics |
| `commitment`          | optional Processed/Confirmed/Finalized | IN    | omitted/value exact      |
| `accounts_data_slice` | repeated offset/length                 | IN    | order + bounds           |
| `ping`                | optional id                            | IN    | Ping/Pong lifecycle      |
| `from_slot`           | optional u64                           | IN    | reconnect/replay tests   |

### 4.2 Accounts

| Capacité                  | Scope | Preuve                               |
|---------------------------|-------|--------------------------------------|
| `account[]`               | IN    | order/cardinality/address validation |
| `owner[]`                 | IN    | order/cardinality/address validation |
| `filters[]`               | IN    | AND semantics preserved structurally |
| `nonempty_txn_signature?` | IN    | omitted/false/true                   |
| `cuckoo_accounts_filter?` | IN    | exact wire + dimension/data bounds   |
| memcmp bytes              | IN    | exact bytes + bounds                 |
| memcmp base58             | IN    | exact string + validation            |
| memcmp base64             | IN    | exact string + validation            |
| `datasize`                | IN    | exact u64                            |
| `token_account_state`     | IN    | bool                                 |
| lamports `eq/ne/lt/gt`    | IN    | oneof exact                          |

### 4.3 Slots

| Capacité                                         | Scope | Preuve                   |
|--------------------------------------------------|-------|--------------------------|
| `filter_by_commitment?`                          | IN    | optional semantics       |
| `interslot_updates?`                             | IN    | optional semantics       |
| processed/confirmed/finalized                    | IN    | enum decode              |
| first_shred_received/completed/created_bank/dead | IN    | enum decode + dead_error |

### 4.4 Transactions / transaction_status

| Capacité                            | Scope | Preuve              |
|-------------------------------------|-------|---------------------|
| `vote?`                             | IN    | optional semantics  |
| `failed?`                           | IN    | optional semantics  |
| `signature?`                        | IN    | exact/validated     |
| `account_include[]`                 | IN    | order/bounds        |
| `account_exclude[]`                 | IN    | order/bounds        |
| `account_required[]`                | IN    | order/bounds        |
| `cuckoo_account_include?`           | IN    | exact wire + bounds |
| `token_accounts? = ALL`             | IN    | optional enum       |
| `token_accounts? = BALANCE_CHANGED` | IN    | optional enum       |

### 4.5 Blocks

| Capacité                  | Scope | Preuve              |
|---------------------------|-------|---------------------|
| `account_include[]`       | IN    | order/bounds        |
| `include_transactions?`   | IN    | optional semantics  |
| `include_accounts?`       | IN    | optional semantics  |
| `include_entries?`        | IN    | optional semantics  |
| `cuckoo_account_include?` | IN    | exact wire + bounds |

## 5. `SubscribeUpdate` — coverage normative

| Variante             | Champs structurants                                           | Scope | Preuve                |
|----------------------|---------------------------------------------------------------|-------|-----------------------|
| `account`            | account info, slot, is_startup                                | IN    | exact decode          |
| `slot`               | slot, parent?, status, dead_error?                            | IN    | exact decode          |
| `transaction`        | signature, vote, transaction, meta, index, slot               | IN    | exact decode          |
| `transaction_status` | slot, signature, vote, index, err                             | IN    | exact decode          |
| `block`              | hash/rewards/time/height/parents/counts + tx/accounts/entries | IN    | exact decode + bounds |
| `ping`               | marker                                                        | IN    | lifecycle             |
| `pong`               | id                                                            | IN    | lifecycle             |
| `block_meta`         | metadata/counts                                               | IN    | exact decode          |
| `entry`              | slot/index/hash/counts                                        | IN    | exact decode          |

Top-level à préserver :

```text
filters[]
created_at
oneof absent/inconnu -> comportement explicitement testé
```

## 6. `solana-storage.proto` — nested wire utile

Le backend doit préserver les champs nécessaires des structures imbriquées actuelles, sans exposer les types upstream comme contrat public :

```text
ConfirmedBlock
ConfirmedTransaction
Transaction
Message
MessageHeader
MessageAddressTableLookup
TransactionStatusMeta
TransactionError
InnerInstructions / InnerInstruction
CompiledInstruction
TokenBalance / UiTokenAmount
ReturnData
Reward / Rewards
UnixTimestamp
BlockHeight
NumPartitions
```

États optionnels/legacy particulièrement sensibles :

```text
compute_units_consumed?
cost_units?
inner_instructions_none
log_messages_none
return_data_none
loaded writable/readonly addresses
commission / commission_bps
```

Preuve cible : fixtures issues du wire Protobuf + cas old/current + malformed/oversized, sans conversion JSON arbitraire.

## 7. Unary RPC matrix

| RPC              | Request exact             | Response exact              | État |
|------------------|---------------------------|-----------------------------|------|
| ReplayInfo       | empty                     | `first_available?`          | TODO |
| Ping             | `count`                   | `count`                     | TODO |
| LatestBlockhash  | `commitment?`             | slot/hash/last_valid_height | TODO |
| BlockHeight      | `commitment?`             | block_height                | TODO |
| Slot             | `commitment?`             | slot                        | TODO |
| IsBlockhashValid | blockhash + `commitment?` | slot + bool                 | TODO |
| Version          | empty                     | version                     | TODO |

## 8. Dépendances / licence

| Gate                        | Décision `pre.001`             | Preuve suivante         |
|-----------------------------|--------------------------------|-------------------------|
| repository default          | AGPL-3.0-only                  | `LICENSING.md`          |
| client subtree              | Apache-2.0                     | `LICENSING.md`          |
| proto subtree               | Apache-2.0                     | `LICENSING.md`          |
| strategy A client+proto     | rejetée comme default          | documenté               |
| strategy B proto+Tonic KSP  | **retenue**                    | `pre.002` compile/tree  |
| strategy C vendored proto   | fallback seulement             | aucun vendoring pre.001 |
| system protoc               | non attendu avec crate publiée | vérifier build réel     |
| raw upstream types public   | interdit par défaut            | public API canary       |
| executable Yellowstone deps | interdit                       | dependency firewall     |

Versions observées :

```text
yellowstone-grpc-client 13.3.0
yellowstone-grpc-proto  12.6.0
tonic                   0.14.x (0.14.6 latest observé)
prost/prost-types       0.14.x (0.14.4 latest observé)
```

## 9. Architecture / ownership

| Invariant                                                                      | Preuve cible             | État |
|--------------------------------------------------------------------------------|--------------------------|------|
| backend gRPC distinct HTTP/WS                                                  | source/API canary        | TODO |
| aucun `WsProtocolKind` gRPC                                                    | source scan              | TODO |
| Transport owns gRPC                                                            | dependency graph         | TODO |
| Config -> Transport seulement                                                  | ownership test           | TODO |
| Transport -X-> Config                                                          | ownership test           | TODO |
| Transport -X-> std::env KSP_*                                                  | ownership test           | TODO |
| Logging façade KSP only                                                        | logging ownership        | TODO |
| no raw Tonic client escape hatch                                               | public API canary        | TODO |
| moteur Yellowstone partagé sans duplication provider                           | source/API canary        | TODO |
| façade Solana Yellowstone standard distincte du moteur                         | public API canary        | TODO |
| PublicNode représenté comme provider/capabilities, pas comme nouveau protocole | public API/config canary | TODO |
| façade provider spécialisée seulement si delta réel                            | completeness review      | TODO |

## 10. Settings, bounds et redaction

À fermer par tests :

```text
endpoint schemes TLS/non-TLS explicitement validés
connect timeout > 0
unary timeout > 0
close timeout > 0
max inbound/outbound > 0 et plafonnés
request/update queue capacities > 0 et plafonnées
reconnect attempt/backoff bornés
filter-group count
filter-name length/uniqueness
metadata key/value count/size
account/owner/include/exclude/required counts
memcmp/data slice bounds
Cuckoo dimensions/data bounds
```

Security canaries :

```text
endpoint URL Debug redacted
secret metadata Debug/Display absent
Status message/details distants non recopiés aveuglément en context
TLS/connect error sans credential/URI sensible
request/update Debug sans payload arbitraire sensible
snapshot sans endpoint secret ni remote internals inutiles
```

## 11. Lifecycle / backpressure / replay

| Cas                                        | Attendu                                  | État |
|--------------------------------------------|------------------------------------------|------|
| stream open                                | session bornée                           | TODO |
| request mutation                           | ordre déterministe                       | TODO |
| server Ping -> client request ping -> Pong | explicite                                | TODO |
| server half-close                          | terminal/reconnect selon policy          | TODO |
| client close                               | cleanup borné                            | TODO |
| receiver drop                              | cleanup capacité                         | TODO |
| slow subscription                          | pas de queue infinie                     | TODO |
| inbound oversized                          | rejet avant allocation excessive         | TODO |
| outbound oversized                         | rejet avant write                        | TODO |
| reconnect budget                           | borné                                    | TODO |
| resubscribe order                          | déterministe                             | TODO |
| `from_slot`                                | utilisé sans promesse lossless           | TODO |
| ReplayInfo                                 | informatif                               | TODO |
| duplicates                                 | observables                              | TODO |
| gaps                                       | observables                              | TODO |
| divergent node history                     | couverture documentée                    | TODO |
| shutdown during reconnect                  | aucune nouvelle connexion après shutdown | TODO |

Claims interdits sans nouvelle preuve :

```text
exactly-once
lossless
historical replay complet
ordre global sans gap
```

## 12. Config V3

Décision de gate :

```text
V1 HTTP reste lisible
V2 HTTP+WS reste lisible
V3 ajoute gRPC explicitement
```

Shape conceptuelle à matérialiser :

```text
globals.grpc_defaults
profiles[].grpc_endpoints[]
endpoint.metadata[]         # public/non-secret
endpoint.secret_metadata[]  # Config-owned secret provenance
```

Canaries :

| Gate                                     | État |
|------------------------------------------|------|
| V1 backward readable                     | TODO |
| V2 backward readable                     | TODO |
| V3 schema strict                         | TODO |
| gRPC endpoint mapping                    | TODO |
| secret provenance enforced               | TODO |
| safe projection redacted                 | TODO |
| no Transport -> Config                   | TODO |
| `.env.example` inventory if new env vars | TODO |

## 13. Providers — validation et séquence

| Provider                         | Accès gratuit/durable observé             | Rôle architectural                                  | Release cible           | Verdict         |
|----------------------------------|-------------------------------------------|-----------------------------------------------------|-------------------------|-----------------|
| **PublicNode / Allnodes-backed** | Mainnet + Testnet Yellowstone gRPC        | première intégration concrète du standard           | **0.2.9**               | **IN provider** |
| **OrbitFlare**                   | Devnet Free                               | provider authentifié réutilisant standard           | **0.2.10**              | **REPORT**      |
| **Helius LaserStream gRPC**      | accès dépendant du plan                   | compat Yellowstone + sémantiques provider à auditer | **0.2.11**              | **REPORT**      |
| **eRPC**                         | gratuit durable non confirmé au gate      | provider à réauditer                                | **0.2.12 conditionnel** | **REPORT**      |
| Tatum                            | Free durable mais crédits lifetime bornés | candidat ultérieur                                  | non réservé             | REPORT          |
| Triton/Chainstack/Shyft/autres   | selon accès/capabilities                  | candidats ultérieurs                                | non réservé             | REPORT          |

### PublicNode `0.2.9`

Cible principale officiellement affichée :

```text
solana-yellowstone-grpc.publicnode.com:443
```

Gates :

```text
utilise le moteur Yellowstone partagé
utilise la façade standard Solana
provider/capabilities/profile explicitement identifiables
aucune duplication actor/channel/stream
aucun wire PublicNode inventé si le provider reste standard
Mainnet smoke opt-in
Testnet smoke opt-in si endpoint exact confirmé
```

### Providers suivants

OrbitFlare, Helius et eRPC ne sont plus des smokes secondaires de `0.2.9`. Chacun est audité dans sa release dédiée et ne reçoit une façade/type spécialisé que si l'authentification, les capabilities, le wire, le keepalive, le replay ou le lifecycle diffèrent réellement du standard.

## 14. Non-régressions obligatoires

| Surface héritée    | Attendu final                                      | État       |
|--------------------|----------------------------------------------------|------------|
| HTTP current       | 52 typed                                           | TODO final |
| HTTP historical    | 14 Deprecated/Removed                              | TODO final |
| Standard WS        | 18 opérations / 9 familles                         | TODO final |
| Helius WS          | 7 standard + transaction                           | TODO final |
| Helius heartbeat   | Ping 60 s                                          | TODO final |
| Config V1/V2       | backward read                                      | TODO final |
| Wallet/Wallet Desk | aucune dépendance protocolaire Yellowstone directe | TODO final |

## 15. Forecast / preuve par tranche — **15–20 min max ; release <= une session**

```text
pre.001 DONE  audit/sizing/architecture                                      15–20 min nominal
pre.002 TODO  moteur: deps/settings/errors/channel                            15–20 min
pre.003 TODO  moteur: TLS/metadata + fixture + 7 unary                        15–20 min
pre.004 TODO  standard: Subscribe common/from_slot/bounds                     15–20 min
pre.005 TODO  standard: accounts + slots                                      15–20 min
pre.006 TODO  standard: transactions + transaction_status                     15–20 min
pre.007 TODO  standard: blocks + block_meta + entry                           15–20 min
pre.008 TODO  moteur: bidi/backpressure/half-close/shutdown                   15–20 min
pre.009 TODO  moteur: reconnect/replay/gap/duplicate                          15–20 min
pre.010 TODO  Config V3 + protocol/provider + profils PublicNode              15–20 min
pre.011 TODO  PublicNode live + compliance + docs/prompt 0.2.10               15–20 min
rel.001 TODO stable
```

Gate de sizing : une prerelease estimée à plus de 20 minutes est scindée ; si `0.2.9` ne paraît plus clôturable dans la session courante, la release est scindée avant implémentation supplémentaire.

## 16. Gate `pre.001`

| Critère du prompt                        | Verdict                        |
|------------------------------------------|--------------------------------|
| base stable `v0.2.8` confirmée           | PASS                           |
| baseline opérateur enregistrée           | PASS                           |
| upstream courant relu                    | PASS                           |
| divergence snapshot/latest enregistrée   | PASS                           |
| service/proto exhaustif inventorié       | PASS                           |
| standard vs provider extension classifié | PASS                           |
| `SubscribeDeshred` classifié             | PASS / OUT                     |
| unary RPCs classifiés                    | PASS / 7 IN                    |
| replay/from_slot audités                 | PASS                           |
| strategy dependency choisie              | PASS / B                       |
| licence auditée avant ajout              | PASS                           |
| features/build/transitifs audit initial  | PASS / matérialisation pre.002 |
| architecture distincte WS                | PASS                           |
| metadata/auth neutral                    | PASS                           |
| Config shape décidée                     | PASS / V3                      |
| resource/backpressure policy décidée     | PASS                           |
| smoke ownership décidé                   | PASS                           |
| providers gratuits audités               | PASS                           |
| release dimensionnée                     | PASS                           |
| forecast recalibré                       | PASS                           |
| split criteria écrits                    | PASS                           |
| aucune implémentation lourde prématurée  | PASS                           |

**Verdict `pre.001` : gate positif ; `pre.002` peut matérialiser la stratégie B sous validation Cargo.**