khadhroony-solana-project/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md

Validation 0.2.8 — Helius LaserStream WebSocket

Statut : pre.004 + fix.001 + fix.002 validés par checkpoint opérateur complet. pre.005 est préparé : contrat public typed de requête Helius transaction, validations 50k/version, tokenAccounts, wire subscribe/unsubscribe et canari actor local ; le handle live reste volontairement différé à pre.006.

1. Références

prompt                     prompts/013-V0_2_8_START_PROMPT.md
plan                       docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
base stable                v0.2.7 / deltas/0.2.7/rel.001.md
pre.001                    deltas/0.2.8/pre.001.md
fix architecture           deltas/0.2.8/pre.001-fix.001.md
fix forecast/nomenclature  deltas/0.2.8/pre.001-fix.002.md
pre.002                     deltas/0.2.8/pre.002.md
pre.002 Clippy/docs fix     deltas/0.2.8/pre.002-fix.001.md
pre.003                     deltas/0.2.8/pre.003.md
pre.004                     deltas/0.2.8/pre.004.md
pre.004 redaction/devnet fix deltas/0.2.8/pre.004-fix.001.md
pre.004 provenance fix       deltas/0.2.8/pre.004-fix.002.md
pre.005                     deltas/0.2.8/pre.005.md
validation standard WS     docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
HTTP compliance            docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md
KSP-TRANSPORT-007          docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md

Audit Helius initial : 2026-08-23.

2. Gate pre.001 fermé

Baseline opérateur acquise :

cargo fmt --all                               OK
python3 scripts/audit_rust_workspace_rules.py clean
cargo check --workspace                       OK
cargo clippy --workspace --all-targets        OK
cargo test --workspace                        OK

Graphes requis reçus :

cargo tree -p ksp-onchain-transport-lib               OK / inspecté
cargo tree -p ksp-onchain-transport-lib --duplicates  OK / inspecté

Versions résolues observées :

futures-util       0.3.34
tokio              1.53.1
tokio-tungstenite  0.30.0
reqwest             0.13.4

Doublons ciblés visibles :

syn            2.0.119 / 3.0.3
webpki-roots   0.26.11 / 1.0.9

Verdict : doublons transitifs, aucune nouvelle dépendance Helius, aucune anomalie bloquante du gate.

2.1 Checklist de fermeture pre.001

[x] base stable inspectée
[x] baseline opérateur disponible
[x] sources Helius courantes relues
[x] terminologie/endpoints/auth clarifiés
[x] surface standard supportée/non supportée inventoriée
[x] transactionSubscribe/unsubscribe inventoriés
[x] tokenAccounts inventorié
[x] notifyOn classé deprecated/no-op
[x] divergence slotsUpdates enregistrée et arbitrée explicitement
[x] architecture corrigée : surfaces protocolaires séparées
[x] moteur WsSession/actor unique préservé
[x] stratégie de compatibilité WsSession 0.2.7 définie
[x] heartbeat ownership décidé
[x] Config shape décidée
[x] credential strategy décidée
[x] aucune nouvelle dépendance justifiée
[x] forecast recalibré au format compact historique et fixes groupés sous `pre.001`
[x] namespace `helius_laserstream` explicitement WebSocket-owned
[x] futur LaserStream gRPC maintenu distinct et hors contrat WS
[x] cargo tree direct exécuté par opérateur
[x] cargo tree duplicates exécuté par opérateur
[x] doublons ciblés analysés comme transitifs/non bloquants

Verdict : gate 0.2.8-pre.001 positif ; pre.002 + fix.001 et pre.003 sont entièrement verts et fermés. pre.004 est ouvert.

3. Matrice provider normative

Capability	Standard KSP	Helius doc actuelle	Décision 0.2.8	Surface Helius attendue	Preuve finale attendue
accountSubscribe pair	oui	supporté	réutiliser wire standard	présente	exact wire + no regression
logsSubscribe pair	oui	supporté	réutiliser wire standard	présente	exact wire + no regression
programSubscribe pair	oui	supporté	réutiliser wire standard	présente	exact wire + no regression
rootSubscribe pair	oui	supporté	réutiliser standard	présente	exact wire + no regression
signatureSubscribe pair	oui	supporté	réutiliser standard	présente	one-shot conservé
slotSubscribe pair	oui	supporté	réutiliser standard	présente	exact wire + no regression
blockSubscribe pair	oui, unstable	non supporté	ne pas exposer Helius	absente	API absence + guard interne avant I/O
slotsUpdatesSubscribe pair	oui, unstable	docs divergentes ; index exhaustif = non supporté	ne pas exposer Helius	absente	API absence + divergence documentée
voteSubscribe pair	oui, unstable	non supporté	ne pas exposer Helius	absente	API absence + guard interne avant I/O
transactionSubscribe	non standard	extension Helius	ajouter typed	présente	request/ack/notification fixtures
transactionUnsubscribe	non standard	documenté dans référence transaction	ajouter via handle	présente	exact method + late-message race
tokenAccounts	non standard	none/balanceChanged/all	ajouter typed	présente dans filter	enum + serialization
notifyOn account	non standard	deprecated, no-op Agave 4.2	ne pas exposer	absente	absence DTO public
notifyOn program	non standard	deprecated, no-op Agave 4.2	ne pas exposer	absente	absence DTO public
enhanced account extra	non standard	mentionné, wire exact non publié	report explicite	absente	réaudit final
proactive heartbeat	absent standard	10 min idle, ping recommandé	Helius-only actor policy	interne	deterministic timer tests
replay historique	absent standard	pas de contrat WS KSP	interdit	absent	docs/canary no promise

4. Matrice des façades protocolaires

4.1 Surface attendue

Famille	SolanaStandardWsSession	HeliusLaserStreamWsSession	DTO/wire
Account	oui	oui	partagé standard
Block	oui	non	standard seulement
Logs	oui	oui	partagé standard
Program	oui	oui	partagé standard
Root	oui	oui	partagé standard
Signature	oui	oui	partagé standard
Slot	oui	oui	partagé standard
SlotsUpdates	oui	non	standard seulement
Vote	oui	non	standard seulement
Helius Transaction	non	oui	provider-specific

4.2 Invariants architecture

Critère	Décision	Preuve cible	État
actor physique	un seul WsSession actor partagé	source/runtime canary	pre.002 implémenté
façade standard	SolanaStandardWsSession	public API canary	pre.002 implémenté
façade Helius	HeliusLaserStreamWsSession	public API canary	pre.002 implémenté
namespace LaserStream WS	WsProtocolKind + ws_endpoints possèdent helius_laserstream	API/Config/docs canary	pre.004 validé
LaserStream gRPC	backend/type/Config distincts, hors 0.2.8	absence de réutilisation WS	décidé
escape hatch Helius	aucun inner()/into_inner() public	compile-fail/source canary	pre.002 implémenté
generic Helius WsSession::connect	ne doit pas permettre de contourner la façade	invalid protocol pre-I/O canary	pre.002 implémenté
Helius unsupported	absent de la façade	compile-fail/API absence canary	pre.003 validé
standard Helius commun	délégation vers le même wire/actor	exact fixture	pre.003 validé
DTO duplication	seulement si wire/sémantique divergent	public/source audit	décidé
Config direction	Config -> Transport uniquement	ownership tests	pre.004 validé
heartbeat	Helius-only, actor commun	deterministic timers	décidé
secret	query URL derrière WsEndpointUrl	redaction canaries	pre.004 validé
new Rust dependency	aucune	manifest/tree audit	décidé

5. Contrat transactionSubscribe à valider

5.1 Filter

Champ	Type	Limite/état	Statut
vote	bool optionnel	pas de limite locale supplémentaire	audit fermé
failed	bool optionnel	pas de limite locale supplémentaire	audit fermé
signature	string optionnelle	provider valide la signature	audit fermé
accountInclude	string[]	<= 50 000	audit fermé
accountExclude	string[]	<= 50 000	audit fermé
accountRequired	string[]	<= 50 000	audit fermé
tokenAccounts	enum string	none, balanceChanged, all	audit fermé

5.2 Options

Champ	Valeurs	Règle	Statut
commitment	processed/confirmed/finalized	réutilisation possible à vérifier	audit fermé
encoding	base58/base64/jsonParsed	enum Helius restreint	audit fermé
transactionDetails	full/signatures/accounts/none	complet	audit fermé
showRewards	bool	optionnel	audit fermé
maxSupportedTransactionVersion	integer	requis pour accounts/full	audit fermé

5.3 Notification

method = transactionNotification
full documented result = transaction + signature + slot + transactionIndex

Validation finale :

aucune forme inventée
types précis pour les formes prouvées
fallback borné si une forme officielle reste insuffisamment explicitée
aucun payload brut dans logs/snapshots

6. Validation lifecycle/provider

[x] un seul actor/socket implementation path dans le code `pre.002`
[x] SolanaStandardWsSession public et constructible — test Transport opérateur vert
[x] HeliusLaserStreamWsSession public et constructible — test Transport opérateur vert
[x] `helius_laserstream` reste possédé par le namespace WebSocket
[x] aucune API/Config gRPC n'est anticipée ou aliasée sur le contrat WS
[x] WsSession historique reste public et son constructeur devient explicitement standard-only
[x] Helius facade n'expose pas blockSubscribe en `pre.002`
[x] Helius facade n'expose pas slotsUpdatesSubscribe en `pre.002`
[x] Helius facade n'expose pas voteSubscribe en `pre.002`
[x] SolanaStandard facade n'expose pas transactionSubscribe
[x] Helius facade n'expose aucun escape hatch vers le handle générique
[x] protocol mismatch rejeté avant I/O — fixture opérateur verte
[x] 6 familles standard Helius utilisent le wire standard exact — fixture `pre.003` opérateur verte
[ ] transaction subscribe/ack exact — fixture `pre.005` préparée, gate opérateur requis
[ ] transaction unsubscribe/result exact — fixture `pre.005` préparée, gate opérateur requis
[ ] transaction notification dispatch exact
[ ] notification decode failure isole la logical subscription
[ ] provider RPC application error ne tue pas la session
[ ] late notification après unsubscribe ne réactive rien
[ ] reconnect invalide/remappe remote ids
[ ] resubscribe garde local id
[ ] unsubscribe pendant reconnect gagne
[ ] heartbeat n'écrit qu'en Active
[ ] heartbeat est annulé au close
[ ] heartbeat write failure suit reconnect borné
[ ] shutdown interrompt heartbeat/backoff
[ ] oversized inbound frame reste borné
[ ] queue overflow d'une transaction subscription n'affecte pas les autres
[ ] payload/filters/api-key absents de Debug/snapshots sûrs

7. Non-régressions

[x] standard WebSocket 18/18 toujours comptabilisé pour SolanaStandard — release completeness vert
[x] partition standard unstable 3/9 inchangée — tests hérités verts
[x] signature one-shot inchangée — tests hérités verts
[x] HTTP current 52/52 inchangé — workspace/release completeness verts
[x] HTTP historical 14/14 inchangé — workspace/release completeness verts
[x] KSP-TRANSPORT-007 inchangé — tests Transport/workspace verts
[x] Config V1 HTTP-only backward readable — tests Config workspace verts
[x] Config V2 solana_standard backward readable — tests Config workspace verts
[x] Config V2 helius_laserstream mappe vers WsProtocolKind::HeliusLaserStream — test pre.004 atteint cette assertion avant l'échec safe_value
[x] schema V2 accepte helius_laserstream sans relâcher les autres contraintes — fixture chargée par le test pre.004
[x] no Transport -> Config/Wallet/Store/Program/tracing direct — audits/tests ownership verts

8. Sécurité/redaction

[x] api-key absente de Debug WsEndpointUrl — canaries héritées + pre.002 vert
[ ] KSP_SECRET_HELIUS_API_KEY redacted dans safe_value Config — comportement correct observé, attente du test corrigée par fix.001, checkpoint à rejouer
[ ] KSP_SECRET_HELIUS_API_KEY absente de ResolvedTransportConfig Debug — assertion située après le faux négatif, checkpoint fix.001 à rejouer
[ ] api-key absente de Debug settings/session/subscription
[ ] api-key absente des KspError safe contexts
[ ] URL complète absente des snapshots
[ ] remote subscription id absent des snapshots publics
[ ] raw transaction payload absent des logs/snapshots
[ ] large filter addresses non loggées
[ ] provider error payload arbitraire non copié dans context
[x] façade Helius ne permet pas de contourner les capabilities par exposition du inner — source + doctest compile_fail verts

9. Smoke live

Statut initial : non exécuté.

Contrat cible : opt-in, Config résout l'api-key, Transport ne lit pas l'environnement. Aucun secret n'est versionné ou affiché. Un échec lié au plan/credential provider doit rester distinguable d'une panne du moteur.

10. Preuves pre.003 et pre.004

Checkpoint pre.003 reçu :

cargo fmt --all                                OK
python3 scripts/audit_rust_workspace_rules.py  clean
cargo check --workspace                        OK
cargo clippy --workspace --all-targets         OK
cargo test -p ksp-onchain-transport-lib        OK
cargo test --workspace                         OK

Preuves spécifiques acquises :

[x] Helius accountSubscribe/accountUnsubscribe
[x] Helius programSubscribe/programUnsubscribe
[x] Helius logsSubscribe/logsUnsubscribe
[x] Helius signatureSubscribe/signatureUnsubscribe
[x] Helius slotSubscribe/slotUnsubscribe
[x] Helius rootSubscribe/rootUnsubscribe
[x] compile-fail Helius blockSubscribe
[x] compile-fail Helius slotsUpdatesSubscribe
[x] compile-fail Helius voteSubscribe
[x] public API canary des six wrappers
[x] release completeness canary

La fixture Transport rapporte 314 tests unitaires verts, 38 tests public API verts, 26 tests release-completeness verts et 4 doctests compile-fail verts. pre.003 est donc DONE.

Surface pre.004 préparée :

[x] schema `ws_endpoints[].kind` accepte `helius_laserstream`
[x] adapter Config mappe `helius_laserstream` vers `WsProtocolKind::HeliusLaserStream`
[x] fixture Config matérialise un endpoint Helius mainnet typé
[x] fixture Config matérialise un profil Helius devnet distinct — fix.001/fix.002 validés
[x] exemple Transport matérialise Helius mainnet sans credential réel
[x] exemple Transport matérialise Helius devnet dans un profil distinct — fix.001/fix.002 validés
[x] `.env.example` inventorie `KSP_SECRET_HELIUS_API_KEY`
[x] interpolation du secret produit l'URL runtime Helius attendue
[x] safe_value conserve les littéraux Helius mainnet/devnet et redige uniquement l'api-key (`...api-key=********`)
[x] Debug de `ResolvedTransportConfig` n'expose pas la clé
[x] Config produit un endpoint composable avec `HeliusLaserStreamWsSession`
[x] `config/std.transport.json` canonique reste standard-only

pre.004 n'introduisait aucun transactionSubscribe, heartbeat, changement du moteur WebSocket ou nouvelle dépendance ; son checkpoint final est désormais vert.

11. Audit structurel des documents actifs

Contrats appliqués :

docs/plans/*.md       = planification, décisions, audit de scope, forecast, stratégie de validation
docs/validation/*.md  = matrices, critères, états et preuves réellement exécutées
deltas/0.2.8/*.md     = journal immuable de chaque livraison

Constats pre.002-fix.001 :

[x] docs/plans est ordonné : 000-README puis 001..015 sans collision
[x] docs/validation est ordonné : 000-README puis 001..011 sans collision
[x] aucun nouveau répertoire documentaire n'est nécessaire pour Helius WebSocket
[x] le plan 015 garde une seule responsabilité : organiser la release 0.2.8
[x] la validation 011 garde une seule responsabilité : rapprocher critères et preuves 0.2.8
[x] le delta du fix reste le seul journal détaillé de la livraison
[x] le forecast détaillé n'est plus dupliqué dans la validation
[x] les sections architecture auparavant séparées sont regroupées dans le plan
[x] l'ordre du plan suit désormais : état/forecast -> sources/baseline -> héritage -> audit -> matrice -> architecture -> risques -> validation -> clôture

Aucun split en fichiers supplémentaires n'est retenu : les plans historiques 0.2.5–0.2.7 sont de taille comparable ou supérieure, et le contenu du plan 015 reste entièrement centré sur une seule release. Le problème identifié était l'ordre interne et la duplication de responsabilités, pas la nécessité d'un nouveau type de document.

12. Gates opérateur pre.004 / fix.001 / fix.002

Premier passage pre.004 reçu le 2026-08-23 :

[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace
[x] cargo clippy --workspace --all-targets
[ ] cargo test -p ksp-config-lib — 109/110 ; faux négatif safe_value Helius
[x] cargo test -p ksp-onchain-transport-lib — vert
[ ] cargo test --workspace — échoue uniquement sur le même test Config

Observation exacte :

observé  = wss://mainnet.helius-rpc.com/?api-key=********
attendu  = ********

L'observé est conforme au contrat historique du résolveur Config : dans une chaîne composée, les littéraux non sensibles restent visibles dans la projection sûre tandis que chaque placeholder secret est remplacé par ********. Le fix ne modifie donc pas le runtime ; il corrige le canari pour attendre l'URL sûre segmentaire exacte. La revue du même checkpoint complète également la couverture Config avec un profil Helius Devnet distinct utilisant wss://devnet.helius-rpc.com/?api-key=..., afin que mainnet et devnet soient tous deux prouvés sans mélange de clusters.

Second passage reçu après pre.004-fix.001 :

[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace
[x] cargo clippy --workspace --all-targets
[ ] cargo test -p ksp-config-lib — 109/110 ; provenance Helius composée attendue à tort sur 1 segment
[x] cargo test -p ksp-onchain-transport-lib — vert

Observation exacte :

provenance.len() observé = 2
provenance.len() attendu = 1

Le comportement runtime est correct. Une chaîne wss://...api-key=${KSP_SECRET_HELIUS_API_KEY} contient un segment littéral suivi d'un segment issu de l'environnement ; la provenance ordonnée doit donc être :

0 = DocumentLiteral
1 = EnvironmentProcess(KSP_SECRET_HELIUS_API_KEY)

pre.004-fix.002 modifie uniquement le canari mainnet/devnet pour vérifier ces deux segments. Les profils, URLs, redaction, schema et mapping restent inchangés.

Checkpoint reçu après pre.004-fix.002 :

[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace
[x] cargo clippy --workspace --all-targets
[x] cargo test -p ksp-config-lib — 110/110 + ownership/public API
[x] cargo test -p ksp-onchain-transport-lib — 314 unit + 38 public + 26 completeness + 4 doctests
[x] cargo test --workspace

Verdict : pre.004 DONE ; pre.004-fix.001 DONE ; pre.004-fix.002 DONE.

13. Préparation pre.005 — contrat Helius transaction

Sources matérialisées :

crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs

Contrats préparés :

[x] HeliusTransactionSubscribeFilter couvre vote/failed/signature/accountInclude/accountExclude/accountRequired/tokenAccounts
[x] accountInclude/accountExclude/accountRequired conservent omission vs [] explicite
[x] chacune des trois listes est bornée localement à 50_000
[x] HeliusTokenAccountsFilter = none/balanceChanged/all
[x] HeliusTransactionSubscribeEncoding = base58/base64/jsonParsed
[x] transactionDetails réutilise SolanaTransactionDetails = full/signatures/accounts/none
[x] maxSupportedTransactionVersion est exigé pour accounts/full
[x] options absentes vs objet {} explicite restent distinctes
[x] transactionSubscribe ack numérique et transactionUnsubscribe booléen ont des décodeurs stricts
[x] transactionUnsubscribe encode exactement [remoteSubscriptionId]
[x] Debug filtre/request expose des comptes et indicateurs, jamais signature/adresses
[x] fixture locale route subscribe/unsubscribe via le WsSession actor existant
[x] aucun second actor/socket
[x] aucun transaction_subscribe public avant pre.006
[x] aucune nouvelle dépendance

Validation statique disponible dans l'environnement de préparation :

python3 scripts/audit_rust_workspace_rules.py
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean

Gates opérateur pre.005 à exécuter :

[ ] cargo fmt --all
[ ] python3 scripts/audit_rust_workspace_rules.py = clean
[ ] cargo check --workspace
[ ] cargo clippy --workspace --all-targets
[ ] cargo test -p ksp-onchain-transport-lib
[ ] cargo test --workspace

Verdict courant : pre.004 et ses fixes DONE ; pre.005 PREPARED.