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

v0.2.8-pre.003

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 13:52:57 +02:00
parent c94a54f3e3
commit b3363073c4
13 changed files with 715 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
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: 7 -->
<!-- version: 8 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `0.2.8-pre.002` est appliqué et testé, mais son gate Clippy requiert `pre.002-fix.001`.** Les tests Transport et workspace sont verts ; le fix corrige cinq `clippy::implicit_return` dans la nouvelle fixture protocolaire, passe Cargo à `0.2.8-pre.2.fix.1` et réorganise les documents actifs pour garder une séparation nette entre plan, validation et delta. Le moteur physique `WsSession` reste unique et partagé.
> **Statut : `0.2.8-pre.002` + `pre.002-fix.001` sont validés ; `0.2.8-pre.003` est préparé.** La façade `HeliusLaserStreamWsSession` expose désormais uniquement les six familles standard documentées comme supportées par Helius (`account`, `logs`, `program`, `root`, `signature`, `slot`) en réutilisant le wire standard existant. `block`, `slotsUpdates` et `vote` restent absents de la façade Helius. Le checkpoint Cargo opérateur de `pre.003` reste à exécuter.
## 1. Objet, base et état courant
@@ -24,15 +24,16 @@ prompts/013-V0_2_8_START_PROMPT.md présent
pre.001 gate audit/sizing Helius
pre.001-fix.001 séparation des façades + fermeture gate Cargo
pre.001-fix.002 forecast compact + namespace LaserStream WS/gRPC
pre.002 socle protocolaire appliqué ; tests verts, Clippy en échec ciblé
pre.002-fix.001 correction Clippy + audit/normalisation structure documentaire
pre.002 socle protocolaire validé
pre.002-fix.001 correction Clippy + normalisation structure documentaire validées
pre.003 six familles standard Helius préparées ; checkpoint opérateur pending
workspace.package.version courant = 0.2.8-pre.2.fix.1
commit attendu = v0.2.8-pre.002-fix.001
workspace.package.version courant = 0.2.8-pre.3
commit attendu = v0.2.8-pre.003
aucun tag prerelease
```
Le log opérateur de `pre.002` confirme : `cargo fmt`, audit Rust et `cargo check --workspace` verts ; `cargo test -p ksp-onchain-transport-lib` et `cargo test --workspace` verts ; `cargo clippy --workspace --all-targets` bloque uniquement sur cinq `clippy::implicit_return` dans `unit_tests/ws_protocol_session.rs`. Les résultats détaillés restent dans la matrice de validation et le delta du fix, pas dans le plan.
Le checkpoint opérateur de `pre.002-fix.001` est intégralement vert : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. `pre.003` peut donc ouvrir la surface standard Helius sans reporter de dette de gate.
## 2. Forecast souple courant
@@ -43,10 +44,10 @@ 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 FIX REQUIRED — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
pre.002 DONE — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
+ connexion physique partagée + guards, sans duplication de l'actor
fix.001 PREPARED — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003 surface Helius standard supportée : account/logs/program/root/signature/slot
fix.001 DONE — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003 PREPARED — 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
@@ -454,7 +455,7 @@ Les 18 opérations standard restent donc présentes et testées : 9 subscribe +
### 7.2 Surface cible `HeliusLaserStreamWsSession`
À partir de `pre.003`, la façade Helius doit exposer uniquement les familles de subscription suivantes :
À terme dans `0.2.8`, la façade Helius doit exposer uniquement les familles de subscription suivantes :
```text
account
@@ -466,7 +467,9 @@ slot
transaction
```
Même après `pre.003`, elle **n'expose pas** :
`pre.003` matérialise exactement les six familles standard ; `transaction` reste réservé aux tranches provider-specific ultérieures du forecast.
La façade Helius **n'expose jamais dans le scope courant** :
```text
block
@@ -591,7 +594,34 @@ 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.
### 7.7 Protocol kind et namespace LaserStream
### 7.7 Réalisation de `pre.003`
`pre.003` ajoute uniquement les six wrappers standard que la matrice Helius autorise :
```text
accountSubscribe / accountUnsubscribe
programSubscribe / programUnsubscribe
logsSubscribe / logsUnsubscribe
signatureSubscribe / signatureUnsubscribe
slotSubscribe / slotUnsubscribe
rootSubscribe / rootUnsubscribe
```
Aucun encoder, decoder ou DTO Helius parallèle n'est créé : chaque méthode de `HeliusLaserStreamWsSession` délègue au même wrapper `WsSession` standard déjà validé en `0.2.7`. Pour éviter que le module de façade devienne un fichier fourre-tout, les implémentations sont rangées auprès de leur propriétaire wire :
```text
ws_accounts.rs -> account / program, façades standard + Helius
ws_transactions.rs -> logs / signature, façades standard + Helius
ws_cluster.rs -> root / slot, plus unstable standard uniquement
ws_blocks.rs -> block, façade standard uniquement
ws_protocol_session.rs -> lifecycle des façades + accès crate-private au moteur partagé
```
`block_subscribe`, `slots_updates_subscribe` et `vote_subscribe` restent absents du type Helius et sont verrouillés par doctests `compile_fail`. L'accès interne au `WsSession` physique est `pub(crate)` seulement ; aucun `inner()`/`into_inner()` public n'est introduit. Une fixture locale Helius dédiée vérifie les six méthodes subscribe/unsubscribe et leurs paramètres exacts ; les tests standard existants restent propriétaires du décodage des notifications.
`transactionSubscribe`, Config Helius et heartbeat restent hors scope de `pre.003`.
### 7.8 Protocol kind et namespace LaserStream
Retenir pour **WebSocket uniquement** :
@@ -609,7 +639,7 @@ Le futur **Helius LaserStream gRPC** reste un backend/provider distinct, hors `0
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.
### 7.8 Connexion et propriété du moteur
### 7.9 Connexion et propriété du moteur
Cible de `pre.002` :
@@ -629,7 +659,7 @@ pas de second snapshot model
pas de public escape hatch Helius -> raw standard WsSession
```
### 7.9 Capability validation defense-in-depth
### 7.10 Capability validation defense-in-depth
La séparation de façade est la première barrière. Une matrice interne reste utile :
@@ -645,7 +675,7 @@ HeliusLaserStream:
Cette matrice sert aux guards de constructor/descriptor, aux canaries et à la protection interne ; elle ne remplace plus la séparation de l'API publique.
### 7.10 Heartbeat/idle ownership
### 7.11 Heartbeat/idle ownership
Helius annonce un timeout d'inactivité de 10 minutes et recommande des pings périodiques.
@@ -663,7 +693,7 @@ write failure = chemin disconnect/reconnect existant
budget reconnect = fini, inchangé
```
### 7.11 Config V2
### 7.12 Config V2
Évolution :
@@ -675,7 +705,7 @@ profiles[].ws_endpoints[].kind:
Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config.
### 7.12 Credentials
### 7.13 Credentials
L'api-key reste uniquement dans l'URL résolue :
@@ -854,35 +884,37 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 13. Checkpoint `pre.002` / `pre.002-fix.001`
## 13. Checkpoint `pre.003`
Le socle `pre.002` est matériellement en place :
```text
WsProtocolKind::HeliusLaserStream -> helius_laserstream
SolanaStandardWsSession
HeliusLaserStreamWsSession
WsSession::connect historique standard-only
connect_for_protocol / connect_physical partagés
aucun second actor/socket/registry
aucun Config Helius / transactionSubscribe / heartbeat anticipé
```
Preuves opérateur déjà reçues pour `pre.002` :
Le checkpoint précédent est fermé par preuve opérateur :
```text
pre.002 + pre.002-fix.001
cargo fmt --all OK
python3 scripts/audit_rust_workspace_rules.py clean
cargo check --workspace OK
cargo clippy --workspace --all-targets FAIL ciblé : 5 implicit_return dans ws_protocol_session.rs
cargo clippy --workspace --all-targets OK
cargo test -p ksp-onchain-transport-lib OK
313 unit tests + 37 public API + 25 release completeness + 2 doctests compile_fail
cargo test --workspace OK
```
`pre.002-fix.001` corrige uniquement ce défaut Clippy dans la fixture, sans modifier le runtime protocolaire. Le fix réorganise aussi les deux documents actifs : le **plan** conserve décisions, audit, forecast et stratégie ; la **validation** conserve matrices, critères et preuves exécutées ; les détails de livraison restent dans les **deltas**.
`pre.003` prépare maintenant :
Après application du fix, le gate opérateur à rejouer est :
```text
HeliusLaserStreamWsSession::account_subscribe
HeliusLaserStreamWsSession::program_subscribe
HeliusLaserStreamWsSession::logs_subscribe
HeliusLaserStreamWsSession::signature_subscribe
HeliusLaserStreamWsSession::slot_subscribe
HeliusLaserStreamWsSession::root_subscribe
block / slotsUpdates / vote -> toujours absents de la façade Helius
transactionSubscribe -> toujours absent
moteur/actor -> inchangé et partagé
new dependency -> aucune
```
La validation locale disponible au moment de préparer l'overlay est l'audit Rust workspace, qui reste `clean`. Le checkpoint opérateur requis avant de déclarer `pre.003` `DONE` est :
```bash
cargo fmt --all
@@ -893,4 +925,4 @@ cargo test -p ksp-onchain-transport-lib
cargo test --workspace
```
Si ce checkpoint est vert, `pre.002` + `fix.001` peuvent être considérés `DONE` et `pre.003` ouvre les six familles standard supportées sur `HeliusLaserStreamWsSession`.
Si ce checkpoint est vert, `pre.004` ouvre uniquement Config V2 `helius_laserstream`, schema/fixtures, mapping Config -> Transport et stratégie de secret/redaction.

79
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: 7 -->
<!-- version: 8 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.002` testé avec succès sauf Clippy ; `pre.002-fix.001` préparé.** La matrice conserve les critères et preuves exécutées ; le forecast détaillé reste exclusivement dans le plan actif afin que ce fichier ne devienne pas un second plan.
> **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
@@ -16,6 +16,7 @@ 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
@@ -86,7 +87,7 @@ Verdict : doublons transitifs, aucune nouvelle dépendance Helius, aucune anomal
[x] doublons ciblés analysés comme transitifs/non bloquants
```
Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` testé par l’opérateur avec un unique échec Clippy ciblé, corrigé par `pre.002-fix.001`.**
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
@@ -138,8 +139,8 @@ Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` testé par l’opérateur a
| 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é |
| 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é |
@@ -201,7 +202,7 @@ aucun payload brut dans logs/snapshots
[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 — `pre.003`
[ ] 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
@@ -254,46 +255,38 @@ 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. Preuve `pre.002` et fix Clippy
## 10. Preuves `pre.002` / `fix.001` et préparation `pre.003`
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
[x] les deux façades ouvrent/ferment une connexion contre un peer local via le même actor — test opérateur vert
[x] Debug Helius ne projette pas une query api-key canary — test opérateur vert
[x] source de façade sans second spawn/socket/command actor
[x] compile-fail Helius blockSubscribe — doctest opérateur vert
[x] compile-fail Helius into_inner — doctest opérateur vert
[ ] six wrappers standard Helius — `pre.003`
```
Validation opérateur reçue pour `pre.002` :
Checkpoint `pre.002-fix.001` reçu :
```text
cargo fmt --all OK
python3 scripts/audit_rust_workspace_rules.py clean
cargo check --workspace OK
cargo clippy --workspace --all-targets FAIL : 5 `implicit_return` dans unit_tests/ws_protocol_session.rs
cargo clippy --workspace --all-targets OK
cargo test -p ksp-onchain-transport-lib OK
cargo test --workspace OK
```
`pre.002-fix.001` ajoute les retours explicites exigés par la politique Clippy KSP et ne change aucun contrat runtime. Le fix doit être revalidé par le même checkpoint avant passage à `pre.003`.
Surface `pre.003` préparée :
```text
[ ] 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
@@ -320,3 +313,17 @@ Constats `pre.002-fix.001` :
```
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`
```text
[ ] 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.**