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

v0.2.8-pre.001-fix.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 12:53:13 +02:00
parent df95f2f558
commit 315e7e67e5
3 changed files with 274 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
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: 3 -->
<!-- version: 5 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : gate `0.2.8-pre.001` positif, architecture rectifiée par `0.2.8-pre.001-fix.001`.** Le moteur physique `WsSession` de `0.2.7` reste unique et partagé, mais les surfaces publiques de protocole sont désormais séparées : `SolanaStandardWsSession` expose la surface Solana standard, tandis que `HeliusLaserStreamWsSession` n'expose que les opérations réellement supportées par Helius et les extensions Helius retenues. Le fix est documentaire et conserve `workspace.package.version = 0.2.8-pre.1`.
> **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`.
## 1. Objet, base et état du gate
@@ -26,12 +26,15 @@ workspace.package.version = 0.2.8-pre.1
livraison = 0.2.8-pre.001
```
Le correctif documentaire courant est :
Correctifs documentaires appliqués à `pre.001` :
```text
livraison = 0.2.8-pre.001-fix.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.001
commit attendu = v0.2.8-pre.001-fix.002
aucun tag prerelease
```
@@ -46,7 +49,7 @@ Constat : aucune dépendance Helius/SDK ajoutée ; les doublons visibles sont tr
**Verdict courant : gate `pre.001` positif.** `pre.002` peut commencer après commit de ce fix.
## 2. Décision structurante de `pre.001-fix.001` — séparer les surfaces, pas le moteur
## 2. Décisions structurantes de `pre.001-fix.001` / `fix.002` — séparer les surfaces, qualifier le protocole
La première version du plan prévoyait un unique `WsSession` public exposant toutes les méthodes standard et une matrice de capabilities rejetant à l'exécution les méthodes incompatibles avec Helius.
@@ -211,37 +214,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.
## 3. Prévision souple courante — vue immédiate
## 3. Forecast souple recalibré
Cette section est la **source visible du forecast courant**. Elle est mise à jour à chaque recalibrage important. Les détails de progression restent dans les deltas ; ce tableau n'est ni une deadline ni un changelog.
| Livraison | Objectif principal | Preuves/gates attendus | Budget nominal | Split si… |
|-------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------:|--------------------------------------------------------------|
| `pre.001` | Audit Helius, matrice, threat model, dépendances, sizing | sources actuelles rapprochées ; baseline ; Cargo trees ; plan/validation | 15–20 min | audit normatif non fermable |
| `pre.001-fix.001` | Corriger l'architecture : façades séparées + forecast visible | plan/validation corrigés ; gate Cargo fermé ; aucun runtime | doc-only | — |
| `pre.002` | Socle protocolaire : `HeliusLaserStream`, façades standard/Helius, connexion physique partagée, guards | un seul actor ; constructeurs protocolaires ; compatibilité `WsSession` ; API canaries | 15–20 min | extraction du connect/lifecycle devient indépendante |
| `pre.003` | Surface Helius standard réellement supportée : 6 familles communes, absence des 3 unsupported | 6 wrappers Helius exacts ; `block/slotsUpdates/vote` absents de la façade ; standard 9/9 intact | 15–20 min | une famille commune diverge réellement du wire standard |
| `pre.004` | Config V2 `helius_laserstream` + schema/fixtures + secret mapping | V1/V2 backward ; Config -> façade correcte ; URL secret redacted ; aucune dépendance inverse | 15–20 min | stratégie secret/config exige un changement transversal |
| `pre.005` | `transactionSubscribe` request typed + filters/options/`tokenAccounts` + unsubscribe | wire exact ; limites 50k ; max version conditionnel ; ack/error ; API typed | 15–20 min | filtres/options cachent plusieurs contrats indépendants |
| `pre.006` | `transactionNotification` + actor integration + reconnect/resubscribe/unsubscribe races | formes prouvées ; remapping ; late notifications ; backpressure ciblée | 15–20 min | plusieurs modes de notification exigent un audit séparé |
| `pre.007` | Heartbeat Helius/idle + interaction reconnect/control frames/shutdown | timer déterministe ; cancellation ; échec Ping -> lifecycle existant ; budget reconnect fini | 15–20 min | timer/lifecycle révèle une modification générique du moteur |
| `pre.008` | Adversarial provider/security/backpressure | provider errors isolées ; oversized ; queue overflow ; secret/filter redaction | 15–20 min | un défaut générique `WsSession` mérite un fix/tranche propre |
| `pre.009` | Compliance Helius + non-régressions WS standard/HTTP/Config/API | matrice finale rapprochée ; standard 18/18 ; HTTP 52/14 ; firewall dépendances | 15–20 min | surface Helius change pendant la release |
| `pre.010` | Smoke Helius opt-in si sûr + README/USAGE + dependency audit | aucun secret versionné ; docs version-neutral ; `cargo tree` direct/duplicates | 15–20 min | surface d'intégration live sûre manque encore |
| `pre.011` | Validation workspace finale + fermeture docs/indexes + prompt `0.2.9` | workspace vert ; validation fermée ; prompt suivant autonome | 15–20 min | un gate reste rouge |
| `rel.001` | Publication stable stricte | tous critères de clôture verts | n/a | jamais forcé par le numéro |
Règles de granularité :
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.
```text
chaque tranche vise environ 15–20 minutes de travail effectif
une tranche > 20 minutes est normalement scindée
une ambiguïté normative nouvelle peut créer une tranche supplémentaire
un fix peut être inséré après n'importe quelle prerelease
pre.011 n'est pas une deadline
la release continue en pre.012+ si un gate l'exige
pre.001 DONE — audit Helius actuel + matrice + architecture + threat model + dependencies + sizing
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
+ 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
pre.004 Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
+ stratégie de secret Helius et redaction URL
pre.005 transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
+ bounds 50k + maxSupportedTransactionVersion conditionnel
pre.006 transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races
+ late notifications + backpressure ciblée
pre.007 heartbeat Helius WebSocket/idle + timers + interaction reconnect/control frames/shutdown
pre.008 provider adversarial lifecycle + capability guards + payload/backpressure + security/redaction
pre.009 compliance Helius WebSocket + non-régressions Solana standard 18/18 + HTTP 52/14
+ Config/API/dependency-firewall canaries
pre.010 smoke Helius WebSocket live opt-in si stratégie sûre + README/USAGE
+ cargo tree direct/duplicates final
pre.011 validation workspace finale + fermeture plan/matrice/indexes + prompt 0.2.9
rel.001 publication stable stricte
```
Règles de lecture et de recalibrage :
- une ligne `pre.NNN` représente une tranche de travail planifiée ; ses `fix.MMM` éventuels sont regroupés dessous et n'augmentent pas artificiellement le forecast initial ;
- l'état (`DONE`, puis si utile un état intermédiaire explicite) peut être mis à jour directement dans ce bloc lorsque la tranche évolue ;
- chaque nouvelle prerelease vise nominalement environ **15–20 minutes** de travail effectif ;
- un `fix` reste insérable après n'importe quelle prerelease ;
- une tranche qui cache plusieurs problèmes indépendants ou dépasse réellement le budget est scindée ;
- une nouvelle ambiguïté normative peut ajouter une prerelease ;
- `pre.011` n'est ni une deadline ni un critère de clôture : `pre.012+` reste autorisé ;
- les détails d'exécution restent dans les deltas ; ce bloc sert de forecast courant et de vue d'état, pas de changelog détaillé.
Critères de split déjà identifiés : notification decoding multiforme non documenté, refactor générique du lifecycle nécessaire, évolution Helius normative en cours de release, ou stratégie live nécessitant une surface d'intégration séparée.
## 4. Sources internes relues et hiérarchie appliquée
Les sources internes obligatoires du prompt ont été relues depuis la base stable, notamment :
@@ -553,17 +567,23 @@ La compliance standard KSP reste **18/18** pour `SolanaStandard`.
## 9. Décisions d'architecture détaillées
### 9.1 Protocol kind
### 9.1 Protocol kind et namespace LaserStream
Retenir :
Retenir pour **WebSocket uniquement** :
```text
WsProtocolKind::HeliusLaserStream
as_str() = "helius_laserstream"
provider metadata attendu = "helius"
Config owner = profiles[].ws_endpoints[].kind
façade publique = HeliusLaserStreamWsSession
```
Le discriminateur est nécessaire car la surface de méthodes et la policy heartbeat diffèrent du standard.
`helius_laserstream` n'est donc pas un nom de transport générique Helius : il est possédé par le namespace WebSocket (`WsProtocolKind` / `ws_endpoints`). Dans toute prose, log safe metadata, documentation ou API où ce contexte n'est pas déjà évident, employer **Helius LaserStream WebSocket** et non le raccourci ambigu « Helius LaserStream ».
Le futur **Helius LaserStream gRPC** reste un backend/provider distinct, hors `0.2.8`. Il ne doit jamais être représenté par `WsProtocolKind`, `WsEndpointSettings`, `HeliusLaserStreamWsSession` ni `ws_endpoints`. Son éventuel protocol kind, discriminateur Config et façade seront décidés par l'audit de la release gRPC concernée ; ils devront porter un ownership gRPC explicite et ne pourront pas réutiliser le contrat WebSocket par simple alias de nom produit.
Cette règle permet de conserver le code court `helius_laserstream` dans son conteneur WS sans créer d'ambiguïté future entre les deux produits portant le nom LaserStream.
### 9.2 Connexion et propriété du moteur
@@ -605,7 +625,7 @@ Cette matrice sert aux guards de constructor/descriptor, aux canaries et à la p
Helius annonce un timeout d'inactivité de 10 minutes et recommande des pings périodiques.
Décision : heartbeat provider-owned dans l'actor existant, activé pour `HeliusLaserStream`, sans champ public générique ajouté à `WsSessionSettings` dans cette release.
Décision : heartbeat provider-owned dans l'actor existant, activé pour `WsProtocolKind::HeliusLaserStream` (LaserStream **WebSocket**), sans champ public générique ajouté à `WsSessionSettings` dans cette release.
Politique cible :
@@ -811,7 +831,7 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 16. Verdict après `pre.001-fix.001`
## 16. Verdict après `pre.001-fix.002`
Décisions fermées :
@@ -820,6 +840,7 @@ base stable autoritaire confirmé
surface Helius actuelle auditée
Cargo graph audité, non bloquant
protocol kind HeliusLaserStream / helius_laserstream
namespace WebSocket-owned ; gRPC explicitement distinct/hors 0.2.8
moteur physique WsSession actor unique, partagé
façade standard SolanaStandardWsSession
façade Helius HeliusLaserStreamWsSession
@@ -834,7 +855,7 @@ Config V2 kind addition, même conteneur
credential URL Secret résolue par Config
new dependency aucune
historical/lossless replay aucune promesse
forecast visible et recalibré pre.001 -> pre.011
forecast format compact KSP, fixes groupés, pre.001 -> pre.011
```
**Gate `pre.001` positif. Prochaine tranche : `0.2.8-pre.002` — socle protocolaire et façades séparées.**

74
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: 3 -->
<!-- version: 5 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : gate `0.2.8-pre.001` positif ; architecture corrigée par `0.2.8-pre.001-fix.001`.** Les graphes Cargo opérateur sont reçus et non bloquants. La validation runtime à venir doit prouver deux façades protocolaires distinctes partageant un seul moteur `WsSession`, et non un `WsSession` Helius générique exposant des méthodes provider non supportées.
> **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.
## 1. Références
@@ -13,6 +13,7 @@ plan docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PL
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
@@ -98,20 +99,22 @@ Verdict : doublons transitifs, aucune nouvelle dépendance Helius, aucune anomal
### 4.2 Invariants architecture
| 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é |
| 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é |
| 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é |
| 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é |
| 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é |
| 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
@@ -159,6 +162,8 @@ aucun payload brut dans logs/snapshots
[ ] 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
@@ -221,27 +226,28 @@ Contrat cible : opt-in, Config résout l'api-key, Transport ne lit pas l'environ
## 10. Forecast courant
Le forecast détaillé et normatif est visible dans la section 3 du plan. Résumé :
Le plan est la source normative du forecast. La validation reprend la même forme compacte et groupe les fixes sous leur prerelease :
```text
pre.001 audit/sizing
pre.001-fix.001 façades séparées + gate Cargo fermé
pre.002 socle protocolaire/façades/connect partagé
pre.003 6 wrappers Helius communs + absence 3 unsupported
pre.004 Config V2 + secrets
pre.005 transaction request/unsubscribe
pre.006 transaction notification + lifecycle
pre.007 heartbeat
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
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.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 ; le numéro final n'est jamais un critère de clôture.
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 fix
## 11. Gate initial après `pre.001-fix.002`
```text
[x] base stable inspectée
@@ -260,7 +266,9 @@ Le forecast reste souple ; le numéro final n'est jamais un critère de clôture
[x] Config shape décidée
[x] credential strategy décidée
[x] aucune nouvelle dépendance justifiée
[x] forecast recalibré et rendu visible dans le plan
[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