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

Validation 0.2.8 — Helius LaserStream WebSocket

Statut : matrice ouverte par 0.2.8-pre.001. Les lignes normatives/sizing sont fermées ; les preuves runtime restent à matérialiser dans les prereleases suivantes. Le gate initial reste conditionné aux graphes Cargo opérateur absents du sandbox de préparation.

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
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. Matrice provider normative initiale

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

3. Contrat transactionSubscribe à couvrir

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é

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é

Notification

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

Le wire exact de tous les modes n'est pas suffisamment détaillé par la source officielle initiale. La validation finale exige :

• aucune forme inventée ;
• types précis pour les formes prouvées ;
• fallback borné/opaque pour une forme officielle non encore explicitée si nécessaire ;
• aucune projection brute dans logs/snapshots.

4. Matrice architecture

Critère	Décision pre.001	Preuve cible	État
actor unique	réutiliser WsSession	aucun second client dans sources/manifest	décidé
protocol descriptor	HeliusLaserStream / helius_laserstream	public API + Config canary	décidé
provider metadata	helius reste metadata	snapshot sûr	décidé
Helius transaction kind	nouvelle variante provider explicite	registry triplet exact	décidé
capability before I/O	oui	local peer reçoit 0 request interdite	décidé
standard DTO pollution	interdite	public API/source canary	décidé
Config direction	Config -> Transport uniquement	ownership tests	décidé
heartbeat	actor Helius-only, 60s cible	deterministic timers	décidé
secret	URL query derrière WsEndpointUrl	redaction canaries	décidé
new Rust dependency	aucune	manifest/tree audit	décidé, tree pending

5. Validation lifecycle/provider à construire

[ ] 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

6. 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

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

8. Dependencies

Audit web du 2026-08-23 :

futures-util       0.3.34
tokio              1.53.1
tokio-tungstenite  0.30.0
reqwest             0.13.4
new dependency      aucune prévue

Preuve locale pre.001 :

python3 scripts/audit_rust_workspace_rules.py = clean
cargo tree = impossible dans sandbox, cargo absent

Gate opérateur requis :

cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates

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 dû au plan/credential provider doit rester distinguable d'une panne du moteur.

10. Forecast courant

pre.001 audit/sizing
pre.002 protocol + capability model
pre.003 Config V2 + secrets
pre.004 transaction request/unsubscribe
pre.005 transaction notification + lifecycle
pre.006 heartbeat
pre.007 adversarial/security/backpressure
pre.008 compliance/non-regression
pre.009 live smoke/docs/dependency graph
pre.010 final workspace/prompt 0.2.9
rel.001 stable

Le forecast est révisable ; seul le respect des gates autorise la publication.

11. Gate initial

[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] protocol/capability architecture décidée
[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é
[ ] cargo tree direct exécuté par opérateur
[ ] cargo tree duplicates exécuté par opérateur

Verdict : gate normatif/architectural prêt ; gate pre.001 entièrement positif après réception des deux graphes Cargo sans anomalie bloquante.