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

Validation 0.2.8 — Helius LaserStream WebSocket

Statut : 0.2.8-pre.002 implémente le socle des deux façades protocolaires sur le moteur WsSession unique. Le protocol kind Helius LaserStream WebSocket, les guards de constructeur, la compatibilité standard historique et l'absence d'escape hatch Helius sont matérialisés. Les six subscriptions standard supportées par Helius restent volontairement ouvertes pour pre.003.

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
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 et dependency graph

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.

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	décidé
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	décidé
standard Helius commun	délégation vers le même wire/actor	exact fixture	décidé
DTO duplication	seulement si wire/sémantique divergent	public/source audit	décidé
Config direction	Config -> Transport uniquement	ownership tests	décidé
heartbeat	Helius-only, actor commun	deterministic timers	décidé
secret	query URL derrière WsEndpointUrl	redaction canaries	décidé
new Rust dependency	aucune	manifest/tree audit	décidé

5. transactionSubscribe à couvrir

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 à construire

[x] un seul actor/socket implementation path dans le code `pre.002`
[ ] SolanaStandardWsSession public et constructible — canary ajoutée, exécution opérateur requise
[ ] HeliusLaserStreamWsSession public et constructible — canary ajoutée, exécution opérateur requise
[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
[ ] protocol mismatch rejeté avant I/O — fixtures ajoutées, exécution opérateur requise
[ ] 6 familles standard Helius utilisent le wire standard exact — `pre.003`
[ ] transaction subscribe/ack exact
[ ] transaction unsubscribe/result exact
[ ] 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 obligatoires

[ ] standard WebSocket 18/18 toujours comptabilisé pour SolanaStandard
[ ] partition standard unstable 3/9 inchangée
[ ] signature one-shot inchangée
[ ] HTTP current 52/52 inchangé
[ ] HTTP historical 14/14 inchangé
[ ] KSP-TRANSPORT-007 inchangé
[ ] Config V1 HTTP-only backward readable
[ ] Config V2 solana_standard backward readable
[ ] no Transport -> Config/Wallet/Store/Program/tracing direct

8. Security/redaction

[ ] api-key absente de Debug WsEndpointUrl
[ ] 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
[ ] façade Helius ne permet pas de contourner les capabilities par exposition du inner

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. Forecast courant

Le plan est la source normative du forecast. La validation reprend la même forme compacte et groupe les fixes sous leur prerelease :

pre.001  DONE — audit/sizing/matrice/dependencies
         fix.001 DONE — façades séparées + gate Cargo fermé
         fix.002 DONE — forecast compact + namespace LaserStream WS/gRPC
pre.002  PREPARED — socle protocolaire/façades/connect partagé
pre.003  6 familles Helius communes + absence 3 unsupported
pre.004  Config V2 + secrets
pre.005  transaction request/unsubscribe
pre.006  transaction notification + lifecycle
pre.007  heartbeat Helius WebSocket
pre.008  adversarial/security/backpressure
pre.009  compliance/non-regression
pre.010  live smoke/docs/dependency graph
pre.011  final workspace/prompt 0.2.9
rel.001  stable

Le forecast reste souple ; les fixes ne sont pas comptés comme des prereleases planifiées supplémentaires et le numéro final n'est jamais un critère de clôture.

11. Gate initial après pre.001-fix.002

[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 ; socle pre.002 matérialisé, validations compilées opérateur encore requises avant commit.

12. Preuve spécifique pre.002

Surface introduite :

WsProtocolKind::HeliusLaserStream -> "helius_laserstream"
SolanaStandardWsSession
HeliusLaserStreamWsSession
WsSession::connect_for_protocol   -> crate-internal
WsSession::connect_physical       -> unique physical spawn path

Canaries ajoutées/prévues dans la livraison :

[x] protocol descriptors distincts
[x] façade standard publique + 9 délégations vers les wrappers 0.2.7
[x] façade Helius publique + lifecycle partagé
[x] generic WsSession::connect rejette Helius avant I/O
[x] chaque façade rejette le mauvais protocol kind avant I/O
[ ] les deux façades ouvrent/ferment une connexion contre un peer local via le même actor — test ajouté
[ ] Debug Helius ne projette pas une query api-key canary — test ajouté
[x] source de façade sans second spawn/socket/command actor
[ ] compile-fail Helius blockSubscribe — doctest ajouté
[ ] compile-fail Helius into_inner — doctest ajouté
[ ] six wrappers standard Helius — `pre.003`

Validation du sandbox de préparation :

python3 scripts/audit_rust_workspace_rules.py = clean
cargo fmt/check/clippy/test = non exécutables dans le sandbox de préparation

Les gates compilés opérateur de pre.002 restent requis avant commit.