v0.2.9-pre.014

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

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
-<!-- version: 21 -->
+<!-- version: 22 -->
 
 # Utilisation de `ksp-onchain-transport-lib`
 
@@ -270,14 +270,26 @@ let grpc_url = match ksp_onchain_transport_lib::YellowstoneGrpcEndpointUrl::pars
     Ok(value) => value,
     Err(error) => return Err(error),
 };
-let grpc_endpoint = ksp_onchain_transport_lib::YellowstoneGrpcEndpointSettings::new(
+let x_token_metadata = match ksp_onchain_transport_lib::YellowstoneGrpcMetadataEntry::secret(
+    "x-token",
+    x_token,
+) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let grpc_endpoint = match ksp_onchain_transport_lib::YellowstoneGrpcEndpointSettings::new(
     "publicnode_mainnet_yellowstone",
     true,
     ksp_onchain_transport_lib::YellowstoneGrpcProviderName::new("publicnode"),
     ksp_onchain_transport_lib::YellowstoneGrpcClusterName::new("mainnet-beta"),
     grpc_url,
     ksp_onchain_transport_lib::YellowstoneGrpcSessionSettings::default(),
-);
+)
+.with_metadata(vec![x_token_metadata])
+{
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
 let grpc_channel = match ksp_onchain_transport_lib::YellowstoneGrpcChannel::connect(&grpc_endpoint).await {
     Ok(value) => value,
     Err(error) => return Err(error),
@@ -289,7 +301,7 @@ let slot = grpc
     .await;
 ```
 
-L’URL reste sensible : `Debug`, erreurs KSP et snapshots n’en exposent pas la valeur. Les metadata publiques/secrètes se construisent avec `YellowstoneGrpcMetadataEntry`; Transport ne lit jamais l’environnement.
+L’URL reste sensible : `Debug`, erreurs KSP et snapshots n’en exposent pas la valeur. Les metadata publiques/secrètes se construisent avec `YellowstoneGrpcMetadataEntry`; Transport ne lit jamais l’environnement. PublicNode requiert actuellement une metadata secrète `x-token` pour les endpoints Yellowstone validés ; ici `x_token` représente une valeur déjà obtenue par un caller sécurisé. En usage normal, Config construit cette metadata depuis les variables `KSP_SECRET_PUBLICNODE_MAINNET_GRPC_X_TOKEN` ou `KSP_SECRET_PUBLICNODE_TESTNET_GRPC_X_TOKEN`. Les appels unary montrés ci-dessus illustrent la surface KSP standard ; le smoke PublicNode de release ne prétend pas valider leur entitlement provider et gate uniquement `Subscribe` slots.
 
 ### Config Transport V3
 
@@ -482,13 +494,30 @@ cargo test -p ksp-onchain-transport-lib --test websocket_devnet_smoke -- --ignor
 
 Il n'utilise ni `blockSubscribe`, ni `slotsUpdatesSubscribe`, ni `voteSubscribe` : ces familles restent unstable et leur disponibilité dépend des capabilities du validator. Le smoke live n'est donc pas un gate de disponibilité de ces extensions.
 
-Le smoke **Transport Yellowstone gRPC PublicNode** ne dépend d’aucun secret ni de Config. Il construit l’endpoint Mainnet programmatiquement, ouvre TLS puis exerce deux unary standards peu coûteux : `GetVersion` et `GetSlot` avec commitment `confirmed` :
+Le smoke **Transport Yellowstone gRPC PublicNode** reste indépendant de Config mais nécessite un personal token opérateur. Il teste Mainnet et Testnet en ouvrant `Subscribe`, en demandant les updates `slots`, en attendant un `YellowstoneSubscribeUpdate::Slot` non nul puis en fermant la session de manière bornée.
+
+Pour éviter de placer les secrets dans les arguments ou l'URL, le harness lit deux lignes sur stdin : Mainnet puis Testnet. Elles peuvent contenir la même valeur ; l'opérateur a validé un même personal token sur les deux réseaux.
 
 ```bash
-cargo test -p ksp-onchain-transport-lib --test yellowstone_publicnode_smoke -- --ignored --nocapture
+read -rsp 'PublicNode Mainnet Yellowstone x-token: ' PUBLICNODE_MAINNET_TOKEN
+echo
+read -rsp 'PublicNode Testnet Yellowstone x-token: ' PUBLICNODE_TESTNET_TOKEN
+echo
+printf '%s\n%s\n' "$PUBLICNODE_MAINNET_TOKEN" "$PUBLICNODE_TESTNET_TOKEN" \
+  | cargo test -p ksp-onchain-transport-lib \
+      --test yellowstone_publicnode_smoke \
+      -- --ignored --nocapture
+unset PUBLICNODE_MAINNET_TOKEN PUBLICNODE_TESTNET_TOKEN
 ```
 
-Le hostname Mainnet provient directement de la page PublicNode. Le hostname Testnet n’est pas versionné dans le smoke tant qu’une source PublicNode suffisamment autoritative et exploitable ne l’a pas confirmé ; une convention de nommage ou une source tierce ne suffit pas.
+Endpoints validés :
+
+```text
+Mainnet https://solana-yellowstone-grpc.publicnode.com:443
+Testnet https://solana-testnet-yellowstone-grpc.publicnode.com:443
+```
+
+Les profils Config conservent deux variables secrètes distinctes afin d'autoriser des credentials différents si nécessaire ; cette séparation ne signifie pas que PublicNode impose actuellement un token différent par réseau. Un timeout KSP de half-close après réception du slot est accepté par le smoke comme fermeture bornée du provider ; aucune absence de slot ni autre erreur n'est masquée.
 
 Le smoke de **composition Config -> Transport** reste également disponible :