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

Validation 0.2.8 — Helius LaserStream WebSocket

Statut : pre.002 + pre.002-fix.001 validés ; pre.003 préparé. La façade Helius contient les six wrappers standard supportés sans DTO/wire provider parallèle. Les nouvelles fixtures et canaries doivent encore passer le checkpoint Cargo opérateur avant que pre.003 soit marqué DONE.

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
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 + pre.002-fix.001 sont entièrement verts et fermés. pre.003 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	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	pre.003 implémenté, checkpoint pending
standard Helius commun	délégation vers le même wire/actor	exact fixture	pre.003 implémenté, checkpoint pending
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. 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
[ ] 6 familles standard Helius utilisent le wire standard exact — implémenté en `pre.003`, fixture opérateur pending
[ ] 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

[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] 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
[ ] 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.002 / fix.001 et préparation pre.003

Checkpoint pre.002-fix.001 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

Surface pre.003 préparée :

[ ] Helius accountSubscribe/accountUnsubscribe — wrapper présent, fixture pending
[ ] Helius programSubscribe/programUnsubscribe — wrapper présent, fixture pending
[ ] Helius logsSubscribe/logsUnsubscribe — wrapper présent, fixture pending
[ ] Helius signatureSubscribe/signatureUnsubscribe — wrapper présent, fixture pending
[ ] Helius slotSubscribe/slotUnsubscribe — wrapper présent, fixture pending
[ ] Helius rootSubscribe/rootUnsubscribe — wrapper présent, fixture pending
[ ] compile-fail Helius blockSubscribe — doctest ajouté, exécution pending
[ ] compile-fail Helius slotsUpdatesSubscribe — doctest ajouté, exécution pending
[ ] compile-fail Helius voteSubscribe — doctest ajouté, exécution pending
[ ] public API canary des six wrappers — ajouté, exécution pending
[ ] release completeness canary — ajouté, exécution pending

La fixture Helius locale vérifie les noms de méthodes, paramètres, remote IDs et méthodes d'unsubscribe pour les six familles. Elle réutilise volontairement les DTOs Solana standard ; les tests historiques ws_accounts, ws_transactions et ws_cluster restent la preuve du décodage exact des notifications et de leurs variantes.

Aucun transactionSubscribe, changement Config, heartbeat ou nouvelle dépendance n'est introduit dans cette tranche.

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. Gate opérateur pre.003

[ ] 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.003 préparé, non déclaré DONE avant ce checkpoint.