Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.8-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 13:15:42 +02:00
parent 315e7e67e5
commit 0871b85df9
12 changed files with 767 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : gate `0.2.8-pre.001` positif, architecture rectifiée par `pre.001-fix.001` puis planification/nomenclature normalisées par `pre.001-fix.002`.** Le moteur physique `WsSession` de `0.2.7` reste unique et partagé ; les surfaces publiques sont séparées entre `SolanaStandardWsSession` et `HeliusLaserStreamWsSession`. Le forecast reprend le format compact des plans KSP précédents et les corrections `fix.*` sont regroupées sous leur prerelease d'origine. Les deux fixes sont documentaires et conservent `workspace.package.version = 0.2.8-pre.1`.
> **Statut : `0.2.8-pre.002` matérialise le socle protocolaire décidé par le gate `pre.001`.** Le moteur physique `WsSession` de `0.2.7` reste unique et partagé ; `SolanaStandardWsSession` devient la façade standard explicite et `HeliusLaserStreamWsSession` ouvre le lifecycle Helius LaserStream WebSocket sans encore exposer ses subscriptions. Le constructeur historique `WsSession::connect` reste standard-only et les six wrappers Helius communs restent réservés à `pre.003`.
## 1. Objet, base et état du gate
@@ -32,9 +32,10 @@ Correctifs documentaires appliqués à `pre.001` :
0.2.8-pre.001-fix.001 séparation des façades protocolaires + fermeture du gate Cargo
0.2.8-pre.001-fix.002 normalisation du forecast + clarification LaserStream WebSocket/gRPC
livraison courante = 0.2.8-pre.001-fix.002
workspace.package.version = 0.2.8-pre.1 # inchangé : documentation uniquement
commit attendu = v0.2.8-pre.001-fix.002
livraison précédente = 0.2.8-pre.001-fix.002
livraison courante = 0.2.8-pre.002
workspace.package.version = 0.2.8-pre.2
commit attendu = v0.2.8-pre.002
aucun tag prerelease
```
@@ -47,7 +48,7 @@ cargo tree -p ksp-onchain-transport-lib --duplicates exécuté
Constat : aucune dépendance Helius/SDK ajoutée ; les doublons visibles sont transitifs (`syn` 2/3 et `webpki-roots` 0.26/1.0) et ne constituent pas une anomalie bloquante de `pre.001`.
**Verdict courant : gate `pre.001` positif.** `pre.002` peut commencer après commit de ce fix.
**Verdict courant : gate `pre.001` positif ; socle `pre.002` implémenté dans la présente livraison.** Les validations compilées restent à exécuter par l'opérateur avant commit.
## 2. Décisions structurantes de `pre.001-fix.001` / `fix.002` — séparer les surfaces, qualifier le protocole
@@ -117,9 +118,9 @@ vote
Les 18 opérations standard restent donc présentes et testées : 9 subscribe + 9 unsubscribe.
### 2.2 Surface `HeliusLaserStreamWsSession`
### 2.2 Surface cible `HeliusLaserStreamWsSession`
La façade Helius expose uniquement :
À partir de `pre.003`, la façade Helius doit exposer uniquement les familles de subscription suivantes :
```text
account
@@ -131,7 +132,7 @@ slot
transaction
```
Elle **n'expose pas** :
Même après `pre.003`, elle **n'expose pas** :
```text
block
@@ -214,6 +215,48 @@ le registry/actor interne reste unique et provider-neutral
Si `pre.002` montre qu'un descriptor interne distinct rend le snapshot plus propre sans rupture publique, cette forme peut être retenue. Aucun refactor ne doit toutefois remplacer une séparation de façade simple par une hiérarchie générique lourde.
### 2.6 Réalisation de `pre.002`
Le socle concret retient une séparation minimale sans dupliquer les wrappers wire ni l'actor :
```text
WsSession::connect(endpoint)
-> accepte uniquement WsProtocolKind::SolanaStandard
-> compatibilité publique 0.2.7 conservée
SolanaStandardWsSession::connect(endpoint)
-> guard SolanaStandard
-> WsSession::connect_for_protocol(...) interne
-> même connect_physical / même run_ws_session_actor
-> délègue les 9 wrappers standard existants
HeliusLaserStreamWsSession::connect(endpoint)
-> guard HeliusLaserStream
-> WsSession::connect_for_protocol(...) interne
-> même connect_physical / même run_ws_session_actor
-> lifecycle seulement en pre.002
-> aucune subscription Helius exposée avant pre.003
```
`WsProtocolKind` possède désormais :
```text
SolanaStandard -> solana_standard
HeliusLaserStream -> helius_laserstream
```
Les mismatches de constructeur sont rejetés avec `ERROR_CODE_INVALID_SETTINGS` et des contextes sûrs `expected_protocol` / `actual_protocol`, avant toute tentative réseau. Aucune URL ni credential n'entre dans cette erreur.
La façade Helius conserve son `WsSession` interne privé et ne fournit ni `inner()` ni `into_inner()`. Des canaries `compile_fail` verrouillent l'absence de `block_subscribe` et de l'escape hatch à ce stade. Une canary source confirme aussi que le module de façade ne contient ni second `tokio::spawn`, ni `tokio_tungstenite`, ni `WsSessionCommand`.
La façade standard délègue déjà les neuf familles existantes sans recopier leurs encoders/decoders :
```text
account block logs program root signature slot slotsUpdates vote
```
La façade Helius ne recevra les six délégations communes qu'en `pre.003`, afin de garder la tranche actuelle limitée au socle protocolaire et aux guards.
## 3. Forecast souple recalibré
Le forecast suit le format historique des plans KSP `0.2.5` et `0.2.7` : un bloc compact, directement révisable, qui porte aussi l'état courant des tranches. Les `fix.*` sont rattachés à leur prerelease d'origine au lieu d'être présentés comme des tranches planifiées autonomes.
@@ -223,7 +266,7 @@ pre.001 DONE — audit Helius actuel + matrice + architecture + threat model +
fix.001 DONE — séparation des façades standard/Helius + moteur unique + gate Cargo fermé
fix.002 DONE — forecast normalisé + namespace LaserStream WebSocket/gRPC clarifié
pre.002 socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
pre.002 PREPARED — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
+ connexion physique partagée + guards, sans duplication de l'actor
pre.003 surface Helius standard supportée : account/logs/program/root/signature/slot
+ absence typée de block/slotsUpdates/vote sur Helius + non-régression standard 9/9
@@ -831,7 +874,7 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 16. Verdict après `pre.001-fix.002`
## 16. Verdict après `pre.002`
Décisions fermées :
@@ -856,6 +899,12 @@ credential URL Secret résolue par Config
new dependency aucune
historical/lossless replay aucune promesse
forecast format compact KSP, fixes groupés, pre.001 -> pre.011
pre.002 protocol kind matérialisé : SolanaStandard + HeliusLaserStream
pre.002 standard facade 9 wrappers existants délégués, aucun wire dupliqué
pre.002 Helius facade lifecycle seulement, inner privé
pre.002 generic WsSession constructeur public standard-only
pre.002 physical connection chemin unique partagé, aucun second actor
pre.002 Config/transaction/heartbeat non commencés conformément au forecast
```
**Gate `pre.001` positif. Prochaine tranche : `0.2.8-pre.002` — socle protocolaire et façades séparées.**
**`pre.002` est préparé ; après validations opérateur vertes, la prochaine tranche est `0.2.8-pre.003` — six familles standard supportées sur la façade Helius et absence typée durable des trois familles non supportées.**

82
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : gate `0.2.8-pre.001` positif ; architecture corrigée par `pre.001-fix.001`, forecast et nomenclature clarifiés par `pre.001-fix.002`.** Les graphes Cargo opérateur sont reçus et non bloquants. La validation runtime doit prouver deux façades protocolaires distinctes partageant un seul moteur `WsSession` et préserver une distinction explicite entre Helius LaserStream **WebSocket** et le futur LaserStream gRPC.
> **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
@@ -101,13 +101,13 @@ Verdict : doublons transitifs, aucune nouvelle dépendance Helius, aucune anomal
| Critère | Décision | Preuve cible | État |
|-------------------------------------|------------------------------------------------------------------|---------------------------------|--------|
| actor physique | un seul `WsSession` actor partagé | source/runtime canary | décidé |
| façade standard | `SolanaStandardWsSession` | public API canary | décidé |
| façade Helius | `HeliusLaserStreamWsSession` | public API canary | décidé |
| 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 | API/source canary | décidé |
| generic Helius `WsSession::connect` | ne doit pas permettre de contourner la façade | invalid protocol pre-I/O canary | 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é |
@@ -159,19 +159,19 @@ aucun payload brut dans logs/snapshots
## 6. Validation lifecycle/provider à construire
```text
[ ] un seul actor/socket implementation path
[ ] SolanaStandardWsSession public et constructible
[ ] HeliusLaserStreamWsSession public et constructible
[ ] `helius_laserstream` reste possédé par le namespace WebSocket
[ ] aucune API/Config gRPC n'est anticipée ou aliasée sur le contrat WS
[ ] WsSession historique standard reste compatible
[ ] Helius facade n'expose pas blockSubscribe
[ ] Helius facade n'expose pas slotsUpdatesSubscribe
[ ] Helius facade n'expose pas voteSubscribe
[ ] SolanaStandard facade n'expose pas transactionSubscribe
[ ] Helius facade n'expose aucun escape hatch vers le handle générique
[ ] protocol mismatch rejeté avant I/O
[ ] 6 familles standard Helius utilisent le wire standard exact
[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
@@ -232,7 +232,7 @@ Le plan est la source normative du forecast. La validation reprend la même form
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 socle protocolaire/façades/connect partagé
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
@@ -274,4 +274,42 @@ Le forecast reste souple ; les fixes ne sont pas comptés comme des prereleases
[x] doublons ciblés analysés comme transitifs/non bloquants
```
Verdict : **gate `0.2.8-pre.001` positif. `pre.002` peut ouvrir le socle protocolaire/façades sans commencer prématurément `transactionSubscribe`.**
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 :
```text
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 :
```text
[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 :
```text
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.