v0.2.8-pre.010

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

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
-<!-- version: 19 -->
+<!-- version: 20 -->
 
 # Utilisation de `ksp-onchain-transport-lib`
 
@@ -183,6 +183,46 @@ let mut blocks = match session
 
 Les trois familles utilisent le même `WsSubscription::unsubscribe().await`; aucun remote subscription ID n'entre dans l'API publique.
 
+### Façade Helius LaserStream WebSocket
+
+Pour un endpoint Config `kind = "helius_laserstream"`, le consumer doit sélectionner l’endpoint WebSocket résolu puis ouvrir la façade Helius, sans reconstruire ni journaliser l’URL contenant l’API key :
+
+```rust
+let resolved = match engine.load_resolved_transport_config(Some("helius_devnet"), &environment) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let ws_settings = match resolved.ws_settings() {
+    Some(value) => value,
+    None => return Err(ksp_core_lib::Error::new(ksp_onchain_transport_lib::ERROR_CODE_INVALID_SETTINGS, "Helius profile requires WebSocket settings")),
+};
+let endpoint = match ws_settings
+    .endpoints()
+    .iter()
+    .find(|candidate| candidate.enabled() && candidate.protocol() == ksp_onchain_transport_lib::WsProtocolKind::HeliusLaserStream)
+{
+    Some(value) => value.clone(),
+    None => return Err(ksp_core_lib::Error::new(ksp_onchain_transport_lib::ERROR_CODE_INVALID_SETTINGS, "Helius WebSocket endpoint is unavailable")),
+};
+let session = match ksp_onchain_transport_lib::HeliusLaserStreamWsSession::connect(endpoint).await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let mut slots = match session.slot_subscribe().await {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+let notification = slots.recv().await;
+let removed = slots.unsubscribe().await;
+let closed = session.close().await;
+```
+
+La façade Helius réutilise `account`, `logs`, `program`, `root`, `signature`, `slot` et `slotsUpdates`. `slotsUpdates` reste unstable. `block` et `vote` ne sont pas exposés. `transaction_subscribe()` prend `HeliusTransactionSubscribeRequest` et retourne `WsSubscription<HeliusTransactionNotification>` ; son unsubscribe reste porté par le handle et produit `transactionUnsubscribe` sans exposer l’ID distant.
+
+Le heartbeat Helius est automatique : `WsSession` envoie un control frame `Ping` toutes les 60 secondes tant que la session Helius est active. Le consumer ne configure pas un second timer et ne lance pas un task heartbeat parallèle. Cette règle ne vaut pas pour `SolanaStandardWsSession`.
+
+`KSP_SECRET_HELIUS_API_KEY` appartient à Config. Ne pas lire l’environnement dans Transport, ne pas recopier l’URL résolue dans un log et ne pas ajouter un dev-dependency inverse `Transport -> Config`. LaserStream gRPC reste un backend différent et ne doit pas réutiliser `WsProtocolKind::HeliusLaserStream`.
+
 ### Reconnect automatique borné
 
 Les settings de session contrôlent le reconnect physique. Une perte de socket publie `Reconnecting { attempt }`, invalide les remote IDs et incrémente `continuity_gap_count`. Avec la policy par défaut `ActiveSubscriptions`, les handles logiques gardent leur `WsSubscriptionId` et passent temporairement en `Resubscribing`; l'actor recrée leurs subscriptions dans l'ordre local avant de republier `Active`.
@@ -358,7 +398,25 @@ cargo test -p ksp-config-lib --test transport_devnet_smoke -- --ignored --nocapt
 
 Il valide le profil committé `devnet_public` et les quatre canaris foundation. Il reste transitoirement hébergé dans Config : les futurs smokes cross-crates ne doivent pas faire de Config leur destination générale et devront migrer vers une surface d'intégration/orchestration dédiée lorsqu'elle existera.
 
-Les endpoints publics Solana sont rate-limités et non destinés à la production. Un échec réseau externe n'est pas assimilé automatiquement à une régression locale ; les fixtures HTTP et WebSocket locales restent les gates reproductibles.
+### Smoke Helius live
+
+Aucun nouveau test Helius live n’est committé en `0.2.8-pre.010`. La raison est architecturale : Transport ne peut pas lire `KSP_SECRET_HELIUS_API_KEY` ni dépendre de Config, et Config ne doit pas devenir la destination générale des futurs smokes `Config + autre crate`. Créer un quatrième smoke dans l’une de ces deux crates contournerait donc une frontière déjà documentée.
+
+Lorsque la surface KSP d’intégration/orchestration dédiée existera, le smoke live minimal recommandé sera :
+
+```text
+Config helius_devnet
+  -> endpoint helius_laserstream résolu avec KSP_SECRET_HELIUS_API_KEY
+  -> HeliusLaserStreamWsSession::connect
+  -> slotSubscribe
+  -> une slotNotification sous timeout
+  -> slotUnsubscribe
+  -> close
+```
+
+Ce scénario utilise une méthode standard stable sur l’endpoint Helius et teste donc auth + façade provider + actor + unsubscribe sans dépendre d’une entitlement particulière de `transactionSubscribe`. Un smoke `transactionSubscribe` pourra être ajouté séparément comme opt-in provider-specific si l’environnement opérateur possède les droits nécessaires ; il ne doit pas devenir un gate réseau obligatoire de la release.
+
+Les endpoints publics/provider sont des dépendances externes. Un rate-limit, refus d’auth, entitlement absente ou incident réseau n’est pas assimilé automatiquement à une régression locale ; les fixtures HTTP/WebSocket locales et les gates déterministes restent autoritaires.
 
 Pour auditer les dépendances, inspecter également le graphe effectif après résolution Cargo :