v0.2.9-pre.012

crates/ksp-onchain-transport-lib/README.md

@@ -1,9 +1,9 @@
 <!-- file: crates/ksp-onchain-transport-lib/README.md -->
-<!-- version: 20 -->
+<!-- version: 21 -->
 
 # `ksp-onchain-transport-lib`
 
-`ksp-onchain-transport-lib` est la bibliothèque KSP propriétaire du transport on-chain Solana. Elle fournit le transport HTTP JSON-RPC complet et le moteur WebSocket Solana standard ; les extensions provider-specific et gRPC sont ajoutées séparément lorsqu’une release les cible.
+`ksp-onchain-transport-lib` est la bibliothèque KSP propriétaire du transport on-chain Solana. Elle fournit le transport HTTP JSON-RPC complet, le moteur WebSocket Solana standard et la foundation Yellowstone gRPC standard/provider-neutral. Les extensions provider-specific restent ajoutées séparément lorsqu’une release les cible.
 
 ## Responsabilités
 
@@ -21,6 +21,8 @@ La crate possède :
 - l'exécution générique des méthodes standard supportées ;
 - les wrappers typés HTTP et WebSocket explicitement livrés par KSP ;
 - les sessions physiques WebSocket, subscriptions logiques, reconnect/resubscribe et backpressure bornés ;
+- les settings, channels, unary et sessions `Subscribe` Yellowstone gRPC standard ;
+- le reconnect/replay Yellowstone prudent avec observabilité de gaps/duplicates sans promesse lossless ;
 - les snapshots runtime sûrs ;
 - l'observabilité Transport via `ksp-logging-lib`.
 
@@ -37,6 +39,7 @@ ksp-config-lib
         -> ksp-logging-lib
         -> reqwest / tokio / serde
         -> tokio-tungstenite / futures-util
+        -> tonic / tonic-prost / yellowstone-grpc-proto
 ```
 
 La direction inverse est interdite :
@@ -217,6 +220,32 @@ Pour Helius, l’actor envoie automatiquement un control frame WebSocket `Ping`
 
 LaserStream **gRPC** reste un backend distinct, hors de cette façade, de `WsProtocolKind` et de la Config WebSocket `helius_laserstream`.
 
+
+## Yellowstone gRPC standard
+
+La foundation `0.2.9` ajoute un troisième backend réseau distinct de HTTP et WebSocket. Le moteur est KSP-owned : `yellowstone-grpc-proto` fournit le wire publié, tandis que Tonic reste encapsulé derrière les types crate-root KSP. Aucun client Tonic brut ni type protobuf upstream n’est réexporté.
+
+La surface publique principale comprend :
+
+```text
+YellowstoneGrpcEndpointUrl / YellowstoneGrpcEndpointSettings
+YellowstoneGrpcSessionSettings / YellowstoneGrpcReconnectSettings
+YellowstoneGrpcTransportSettings
+YellowstoneGrpcChannel
+SolanaYellowstoneGrpcUnaryClient
+YellowstoneSubscribeRequest
+SolanaYellowstoneGrpcSubscribeSession
+YellowstoneGrpcSubscribeSnapshot
+```
+
+Les sept unary standards retenus sont `SubscribeReplayInfo`, `Ping`, `GetLatestBlockhash`, `GetBlockHeight`, `GetSlot`, `IsBlockhashValid` et `GetVersion`. `Subscribe` couvre accounts, slots, transactions, transaction status, blocks, block metadata et entries, avec `commitment`, `accounts_data_slice`, `ping` et `from_slot`. `SubscribeDeshred` reste hors scope de la foundation standard.
+
+Le stream bidirectionnel est borné : request/update queues, tailles inbound/outbound, half-close, close timeout et reconnect budget sont explicites. Après reconnect, KSP rejoue la dernière requête complète acceptée et avance prudemment `from_slot` selon le dernier slot observé et `SubscribeReplayInfo.first_available`. Les compteurs de gap et duplicate sont de l’observabilité ; ils ne constituent jamais une garantie exactly-once ou lossless.
+
+Config Transport V3 peut mapper des `grpc_endpoints` vers ces settings sans inverser la dépendance. `protocol = solana_yellowstone` décrit le wire standard, tandis que `provider` reste un descripteur distinct. Le profil committé `publicnode_mainnet` utilise le standard sans credential ni façade PublicNode spécifique.
+
+Un smoke live opt-in vérifie directement PublicNode Mainnet via `GetVersion` puis `GetSlot`. Le hostname PublicNode Testnet Yellowstone n’est pas versionné tant qu’une source officielle exploitable ne l’a pas confirmé ; KSP ne déduit pas un endpoint à partir d’une convention de nommage.
+
 ## Résilience
 
 L'admission est calculée par couple endpoint/rôle. Le pool applique :
@@ -253,7 +282,7 @@ La configuration Logging de référence conserve un fichier dédié Transport à
 
 Les tests par défaut sont déterministes et n'exigent pas Internet : fixtures JSON et serveur HTTP local couvrent requêtes, réponses, retry, 429, timeout, redaction et routing.
 
-Trois smokes Devnet opt-in sont séparés par responsabilité :
+Quatre smokes réseau opt-in sont séparés par responsabilité :
 
 ```text
 Transport HTTP pur : settings programmatiques -> HttpTransportPool
@@ -270,13 +299,16 @@ Transport WebSocket pur : settings programmatiques -> WsSession
 
 Composition historique : Config -> std.transport/devnet_public -> HttpTransportPool
                        -> getHealth/getGenesisHash/getVersion/getBalance
+
+Transport Yellowstone gRPC : settings programmatiques -> PublicNode Mainnet
+                          -> TLS -> GetVersion -> GetSlot confirmed
 ```
 
 Le smoke HTTP Transport utilise pour sa branche Token la forme Devnet documentée `getTokenAccountsByOwner(owner, { programId }, { commitment: finalized, encoding: jsonParsed })`. L'owner est une Pubkey ordinaire de l'exemple officiel ; aucune présence de token account n'est exigée, donc une liste vide reste valide.
 
 Le smoke WebSocket Transport cible uniquement la famille stable `slotSubscribe` sur l'endpoint public Devnet `wss://api.devnet.solana.com`. Il borne connexion, attente de notification, unsubscribe et fermeture ; il ne transforme aucune famille unstable en gate live.
 
-Les trois tests sont `ignored` par défaut. Les deux smokes Transport appartiennent durablement à cette crate ; le smoke cross-crates hébergé dans Config reste transitoire jusqu'à l'existence d'une surface KSP d'intégration/orchestration appropriée. Un rate-limit, refus externe ou incident Devnet n'est pas assimilé automatiquement à une régression locale.
+Les quatre tests sont `ignored` par défaut. Les trois smokes Transport appartiennent durablement à cette crate ; le smoke cross-crates hébergé dans Config reste transitoire jusqu'à l'existence d'une surface KSP d'intégration/orchestration appropriée. Un rate-limit, refus externe ou incident Devnet n'est pas assimilé automatiquement à une régression locale.
 
 Aucun smoke Helius live supplémentaire n’est committé en `0.2.8-pre.010`. Un tel test devrait à la fois obtenir `KSP_SECRET_HELIUS_API_KEY` via Config et exercer Transport ; l’ajouter dans Transport violerait l’ownership environnement/secret, tandis que l’ajouter dans Config étendrait l’exception cross-crates que le projet veut au contraire résorber. La première surface KSP d’intégration/orchestration dédiée devra héberger ce smoke. Le scénario live recommandé est alors `helius_devnet -> HeliusLaserStreamWsSession -> slotSubscribe -> notification -> unsubscribe -> close`; `transactionSubscribe` reste un smoke optionnel dépendant des droits provider et ne devient pas un gate stable de release.
 
@@ -290,4 +322,6 @@ Aucun smoke Helius live supplémentaire n’est committé en `0.2.8-pre.010`. Un
 - [`../../docs/validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](../../docs/validation/006-V0_2_3_HTTP_TRANSACTIONS.md) — matrice finale validée Transactions ;
 - [`../../docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](../../docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) — plan Blocks/Economics et compliance HTTP finale ;
 - [`../../docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](../../docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) — matrice finale validée `52/52 + 14/14` et audit `KSP-TRANSPORT-007` global ;
-- [`../../config/std.transport.json`](../../config/std.transport.json) — configuration standard HTTP + WebSocket V2, avec lecture backward V1 HTTP-only.
+- [`../../docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](../../docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) — plan Yellowstone gRPC standard/provider-neutral et PublicNode ;
+- [`../../docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](../../docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md) — matrice de compliance Yellowstone ;
+- [`../../config/std.transport.json`](../../config/std.transport.json) — configuration standard Transport V3 HTTP + WebSocket + gRPC, avec lecture backward V1/V2.