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

v0.2.8-pre.006

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 15:41:54 +02:00
parent 8e739b9e55
commit 1c8d69778b
13 changed files with 862 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
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: 15 -->
<!-- version: 16 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.004` et ses deux fixes sont validés. `pre.005-fix.001` corrige les erreurs de type et la visibilité test/private, mais son checkpoint reste non fermable à cause de neuf warnings `dead_code` sur des helpers wire strictement privés qui n'ont pas encore de consommateur de production. `0.2.8-pre.005-fix.002` les borne à `#[cfg(test)]` jusqu'à leur consommation réelle par l'actor en `pre.006`, sans `allow(dead_code)` ni élargissement de visibilité.**
> **Statut : `pre.005` + `fix.001` + `fix.002` sont validés sans warning. `0.2.8-pre.006` prépare maintenant le handle live Helius `transactionSubscribe`, le décodage `transactionNotification` et son intégration au registry/reconnect/backpressure de l'actor WebSocket unique.**
## 1. Objet, base et état courant
@@ -30,12 +30,13 @@ pre.003 six familles standard Helius validées
pre.004 Config V2 Helius validé
pre.004-fix.001 redaction segmentaire + couverture Devnet Helius validées
pre.004-fix.002 provenance composée validée
pre.005 contrat typed transactionSubscribe/unsubscribe ; fix requis après checkpoint
pre.005-fix.001 correction types de canaris + visibilité/tests/règles appliquée
pre.005-fix.002 suppression warnings dead_code via cfg(test) des helpers wire préparée
pre.005 contrat typed transactionSubscribe/unsubscribe validé
pre.005-fix.001 correction types de canaris + visibilité/tests/règles validée
pre.005-fix.002 suppression warnings dead_code via cfg(test) validée
pre.006 transactionNotification + lifecycle actor préparé
workspace.package.version courant = 0.2.8-pre.5.fix.2
commit attendu = v0.2.8-pre.005-fix.002
workspace.package.version courant = 0.2.8-pre.6
commit attendu = v0.2.8-pre.006
aucun tag prerelease
```
@@ -59,12 +60,12 @@ pre.004 DONE — Config V2 helius_laserstream + schema/fixtures + mapping Confi
+ secret/redaction Helius mainnet/devnet validés
fix.001 DONE — redaction segmentaire corrigée + représentation Devnet Helius ajoutée
fix.002 DONE — provenance composée `DocumentLiteral` + `EnvironmentProcess` corrigée
pre.005 FIX REQUIRED — transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
pre.005 DONE — transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
+ bounds 50k + maxSupportedTransactionVersion conditionnel ; live handle différé à pre.006
fix.001 APPLIED — assertions Vec<Value>/Value corrigées + helpers test-only privés + audit super/crate durci
fix.002 PREPARED — helpers wire non consommés en production bornés à #[cfg(test)] ; zéro allow/dead-code compensatoire
pre.006 transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races
+ late notifications + backpressure ciblée
fix.001 DONE — assertions Vec<Value>/Value corrigées + helpers test-only privés + audit super/crate durci
fix.002 DONE — helpers wire non consommés en production bornés à #[cfg(test)] ; zéro warning dead_code
pre.006 PREPARED — transactionNotification + handle live + actor registry/reconnect/resubscribe/unsubscribe races
+ late notifications + backpressure ciblée, sans second actor/socket
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
@@ -1024,3 +1025,57 @@ Ces éléments ne sont pas encore consommés par un chemin de production en `pre
Leur promotion éventuelle en code de production est différée à `pre.006`, exactement au moment où l'actor WebSocket les consommera réellement ; si cette promotion exige `pub(crate)`, elle suivra alors la façade crate-root et les appels `crate::Item`.
## 14. Fermeture `pre.005` et préparation `pre.006`
Le checkpoint opérateur reçu après `pre.005-fix.002` ferme entièrement la tranche transaction-request :
```text
cargo fmt --all OK
python3 scripts/audit_rust_workspace_rules.py clean
cargo check --workspace OK, sans warning
cargo clippy --workspace --all-targets OK, sans warning
cargo test -p ksp-onchain-transport-lib OK 322 unit + 39 public API + 27 completeness + 4 doctests
cargo test --workspace OK
```
`pre.006` promeut uniquement les helpers désormais réellement consommés par le chemin live. Ils restent strictement privés dans leur module lorsque leur consommation est locale ; aucun élargissement de visibilité n'est effectué pour les tests. Les tests continuent d'accéder aux privés du parent via `super::Item`, tandis que les types publics passent par la façade crate-root `crate::Item`.
La tranche ajoute :
```text
WsSubscriptionKind::HeliusTransaction
subscribe method transactionSubscribe
unsubscribe method transactionUnsubscribe
notification method transactionNotification
HeliusLaserStreamWsSession::transaction_subscribe(request)
-> WsSubscription<HeliusTransactionNotification>
HeliusTransactionNotification
Full transaction + signature + slot + transactionIndex
Signature signature + slot + transactionIndex + champs optionnels conservés
Unknown payload provider futur/none conservé sans faire tomber la souscription
```
Le variant `Unknown` est volontairement borné à la valeur `result` de `transactionNotification` : KSP ne publie ni l'enveloppe JSON-RPC complète ni l'identifiant remote de subscription. Le remote ID reste propriété exclusive de l'actor et peut donc être remappé après reconnexion sans changer l'identité locale du handle.
Les canaris locaux `pre.006` doivent prouver ensemble :
```text
[ ] requête live exacte via HeliusLaserStreamWsSession::transaction_subscribe
[ ] transactionNotification Full décodée par le handle public
[ ] formes Signature et Unknown préservées
[ ] transactionUnsubscribe utilise le remote ID courant
[ ] reconnexion renvoie le même params transactionSubscribe
[ ] remote ID 41 -> 99 remappé sans changer WsSubscriptionId
[ ] notification tardive après demande unsubscribe ignorée
[ ] overflow transaction échoue seulement la souscription lente
[ ] cleanup overflow appelle transactionUnsubscribe
[ ] une souscription Helius root saine continue de recevoir ses notifications
[ ] standard 9 familles / 18 opérations non régressées
[ ] aucun heartbeat ajouté avant pre.007
[ ] aucun second actor/socket/registry/queue
[ ] aucune nouvelle dépendance
```
Hors scope inchangé : heartbeat/idle (`pre.007`), adversarial provider/security élargi (`pre.008`), smoke Helius live (`pre.010`) et LaserStream gRPC.

72
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: 15 -->
<!-- version: 16 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.004` + ses fixes sont validés. `pre.005-fix.001` corrige les erreurs de type et les chemins de visibilité, mais son checkpoint émet encore neuf warnings `dead_code` sur des helpers wire privés non consommés en production. `pre.005-fix.002` les compile uniquement sous `#[cfg(test)]` jusqu'à `pre.006`, sans modifier le contrat public Helius.**
> **Statut : `pre.005` + ses deux fixes sont validés sans warning. `pre.006` est préparé avec `transactionNotification`, handle live, remap reconnect, late-notification handling et backpressure ciblée sur l'actor WebSocket unique.**
## 1. Références
@@ -23,6 +23,7 @@ pre.004 provenance fix deltas/0.2.8/pre.004-fix.002.md
pre.005 deltas/0.2.8/pre.005.md
pre.005 visibility/test fix deltas/0.2.8/pre.005-fix.001.md
pre.005 dead-code fix deltas/0.2.8/pre.005-fix.002.md
pre.006 actor transaction deltas/0.2.8/pre.006.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
@@ -136,7 +137,7 @@ Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `fix.001` et `pre.003` so
### 4.2 Invariants architecture
| Critère | Décision | Preuve cible | État |
| 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é |
@@ -209,21 +210,21 @@ aucun payload brut dans logs/snapshots
[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
[x] 6 familles standard Helius utilisent le wire standard exact — fixture `pre.003` opérateur verte
[ ] transaction subscribe/ack exact — fixture `pre.005` préparée, gate opérateur requis
[ ] transaction unsubscribe/result exact — fixture `pre.005` préparée, gate opérateur requis
[ ] transaction notification dispatch exact
[x] transaction subscribe/ack exact — fixture `pre.005` validée puis consommée par le handle live `pre.006`
[x] transaction unsubscribe/result exact — fixture `pre.005` validée puis registry actor `pre.006`
[ ] transaction notification dispatch exact — canari `pre.006` préparé
[ ] 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
[ ] late notification après unsubscribe ne réactive rien — canari `pre.006` préparé
[ ] reconnect invalide/remappe remote ids — canari `pre.006` 41 -> 99 préparé
[ ] resubscribe garde local id — canari `pre.006` préparé
[ ] 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
[ ] queue overflow d'une transaction subscription n'affecte pas les autres — canari transaction + root `pre.006` préparé
[ ] payload/filters/api-key absents de Debug/snapshots sûrs
```
@@ -519,5 +520,54 @@ Critères `pre.005-fix.002` :
[ ] tests Transport/workspace verts
```
Verdict courant : **`pre.005` FIX REQUIRED ; `pre.005-fix.001` APPLIED ; `pre.005-fix.002` PREPARED.**
Verdict après checkpoint final : **`pre.005` DONE ; `pre.005-fix.001` DONE ; `pre.005-fix.002` DONE.**
## 16. Gate `pre.005-fix.002` fermé et préparation `pre.006`
Checkpoint opérateur final `pre.005` reçu le 2026-08-23 :
```text
[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace = sans warning
[x] cargo clippy --workspace --all-targets = sans warning
[x] cargo test -p ksp-onchain-transport-lib = 322 unit + 39 public API + 27 completeness + 4 doctests
[x] cargo test --workspace = vert
```
Verdict : **`pre.005` et ses deux fixes sont fermés.**
Critères préparés pour `pre.006` :
```text
[ ] WsSubscriptionKind::HeliusTransaction mappe exactement subscribe/unsubscribe/notification
[ ] HeliusLaserStreamWsSession::transaction_subscribe retourne WsSubscription<HeliusTransactionNotification>
[ ] notification Full conserve transaction/signature/slot/transactionIndex
[ ] notification Signature conserve signature/slot/transactionIndex et états optionnels
[ ] forme inconnue reste HeliusTransactionNotification::Unknown sans casser le handle
[ ] l'identité locale du handle reste stable après reconnect/resubscribe
[ ] le remote ID est remappé et jamais exposé publiquement
[ ] notification Helius en vol après transactionUnsubscribe est ignorée après retrait du mapping
[ ] overflow du handle transaction est terminal seulement pour ce handle
[ ] cleanup overflow envoie transactionUnsubscribe avec le remote ID courant
[ ] une souscription Helius root saine reste active pendant l'overflow transaction
[ ] quatre compile-fail Helius block/slotsUpdates/vote/escape-hatch restent verts
[ ] aucun heartbeat avant pre.007
[ ] aucun second actor/socket/registry/queue
[ ] aucun nouvel accès non canonique private/pub/pub(crate) dans unit_tests
```
Gate opérateur `pre.006` :
```text
[ ] cargo fmt --all
[ ] python3 scripts/audit_rust_workspace_rules.py = clean
[ ] cargo check --workspace = sans warning
[ ] cargo clippy --workspace --all-targets = sans warning
[ ] cargo test -p ksp-onchain-transport-lib
[ ] cargo test --workspace
```
Comptages attendus si les nouveaux canaris passent : **325 tests unitaires Transport**, **40 public API**, **28 release-completeness**, **4 doctests compile-fail**.
Verdict courant : **`pre.006` PREPARED.**