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

v0.2.8-pre.005

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 14:49:56 +02:00
parent cbb4e7b0de
commit 92224e5ac6
10 changed files with 1238 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
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: 12 -->
<!-- version: 13 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `0.2.8-pre.003` est validé ; `pre.004` est fonctionnellement implémenté mais son gate Config a nécessité deux corrections de canari. `pre.004-fix.001` a corrigé la redaction segmentaire et ajouté Devnet ; son checkpoint a ensuite révélé une seconde hypothèse de test erronée sur la provenance d'une chaîne composée. `pre.004-fix.002` corrige uniquement cette cardinalité/provenance et reste préparé.** Le runtime Config/Transport, les profils mainnet/devnet, le schema et le mapping Helius restent inchangés.
> **Statut : `pre.004` et ses deux fixes sont validés par checkpoint opérateur complet. `0.2.8-pre.005` est préparé : contrat typed `transactionSubscribe`, filtres/options Helius, `tokenAccounts`, limites 50k et wire `transactionUnsubscribe`, sans exposer encore de handle transaction avant l'intégration actor de `pre.006`.**
## 1. Objet, base et état courant
@@ -27,12 +27,13 @@ pre.001-fix.002 forecast compact + namespace LaserStream WS/gRPC
pre.002 socle protocolaire validé
pre.002-fix.001 correction Clippy + normalisation structure documentaire validées
pre.003 six familles standard Helius validées
pre.004 Config V2 Helius implémenté ; checkpoint bloqué par un faux négatif de test
pre.004-fix.001 correction safe_value + couverture Devnet Helius ; checkpoint bloqué par provenance
pre.004-fix.002 correction du canari de provenance composée préparée
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 préparé
workspace.package.version courant = 0.2.8-pre.4.fix.2
commit attendu = v0.2.8-pre.004-fix.002
workspace.package.version courant = 0.2.8-pre.5
commit attendu = v0.2.8-pre.005
aucun tag prerelease
```
@@ -52,14 +53,12 @@ pre.002 DONE — socle protocolaire : WsProtocolKind::HeliusLaserStream + faça
fix.001 DONE — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003 DONE — 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 CHECKPOINT — Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
+ stratégie de secret Helius et redaction URL ; runtime/check/clippy/Transport verts
fix.001 CHECKPOINT — redaction segmentaire corrigée + représentation Devnet Helius ajoutée
+ gate Config bloqué uniquement par une attente de provenance `1` au lieu de `2`
fix.002 PREPARED — provenance composée attend `DocumentLiteral` + `EnvironmentProcess`
+ aucun changement runtime/schema/fixture/profil
pre.005 transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
+ bounds 50k + maxSupportedTransactionVersion conditionnel
pre.004 DONE — Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
+ 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 PREPARED — transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
+ bounds 50k + maxSupportedTransactionVersion conditionnel ; live handle différé à pre.006
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
@@ -897,7 +896,7 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 13. Checkpoints `pre.004`, `fix.001` et `fix.002`
## 13. Checkpoints `pre.004`, fixes et préparation `pre.005`
Le checkpoint `pre.003` est fermé par preuve opérateur :
@@ -962,16 +961,37 @@ provenance attendue = 1 segment
Pour une URL composée `littéral + ${KSP_SECRET_HELIUS_API_KEY}`, le contrat Config enregistre correctement deux provenances ordonnées : `DocumentLiteral`, puis `EnvironmentProcess(KSP_SECRET_HELIUS_API_KEY)`. `pre.004-fix.002` corrige seulement cette attente pour mainnet et devnet ; aucune donnée Config ni logique runtime n'est modifiée.
Le checkpoint à rejouer avant de déclarer `pre.004` + `fix.001` + `fix.002` `DONE` est :
Le checkpoint opérateur reçu après `pre.004-fix.002` ferme cette tranche :
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-config-lib
cargo test -p ksp-onchain-transport-lib
cargo test --workspace
```text
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-config-lib OK 110/110 + ownership/public API
cargo test -p ksp-onchain-transport-lib OK 314 unit + 38 public + 26 completeness + 4 doctests
cargo test --workspace OK
```
Si ce checkpoint est vert, `pre.004` et ses deux fixes peuvent être fermés, puis `pre.005` peut ouvrir la requête typed `transactionSubscribe` / `transactionUnsubscribe`, ses filtres/options et validations déterministes.
Les profils Helius mainnet/devnet, la redaction segmentaire, la provenance composée, le mapping Config -> Transport et l'absence de nouvelle dépendance sont donc acquis avant `pre.005`.
`pre.005` prépare maintenant :
```text
HeliusTransactionSubscribeFilter vote/failed/signature/accountInclude/accountExclude/accountRequired/tokenAccounts
HeliusTokenAccountsFilter none / balanceChanged / all
HeliusTransactionSubscribeOptions commitment/encoding/transactionDetails/showRewards/maxSupportedTransactionVersion
HeliusTransactionSubscribeRequest validation déterministe + params exacts
accountInclude/Exclude/Required <= 50_000 chacun
transactionDetails accounts/full maxSupportedTransactionVersion obligatoire
transactionSubscribe ack remote id numérique décodé en interne
transactionUnsubscribe méthode/params/résultat bool exacts
Debug filtre/request signature et valeurs d'adresses non rendues
actor/socket chemin physique existant réutilisé dans fixture locale
live transaction handle volontairement absent jusqu'à pre.006
transactionNotification toujours hors scope pre.005
heartbeat toujours hors scope pre.005
new dependency aucune
```
La séparation `pre.005` / `pre.006` est normative : publier dès maintenant un `transaction_subscribe()` public sans registry de notification/reconnect produirait un handle transitoire qui perdrait les notifications. Le contrat public de requête est donc stable dès `pre.005`, tandis que l'abonnement live est ajouté atomiquement avec l'actor integration en `pre.006`.

103
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: 12 -->
<!-- version: 13 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.003` validé ; `pre.004` est implémenté mais son gate Config a exposé deux hypothèses de test incorrectes. `pre.004-fix.001` a corrigé `safe_value` et ajouté Devnet ; son checkpoint est vert sur `fmt`, audit, `check`, `clippy` et Transport mais échoue encore sur la cardinalité de provenance. `pre.004-fix.002` corrige uniquement ce canari : une URL composée porte `DocumentLiteral` puis `EnvironmentProcess`.**
> **Statut : `pre.004` + `fix.001` + `fix.002` validés par checkpoint opérateur complet. `pre.005` est préparé : contrat public typed de requête Helius transaction, validations 50k/version, `tokenAccounts`, wire subscribe/unsubscribe et canari actor local ; le handle live reste volontairement différé à `pre.006`.**
## 1. Références
@@ -20,6 +20,7 @@ pre.003 deltas/0.2.8/pre.003.md
pre.004 deltas/0.2.8/pre.004.md
pre.004 redaction/devnet fix deltas/0.2.8/pre.004-fix.001.md
pre.004 provenance fix deltas/0.2.8/pre.004-fix.002.md
pre.005 deltas/0.2.8/pre.005.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
@@ -133,22 +134,22 @@ 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é |
| 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 | pre.004 préparé |
| LaserStream gRPC | backend/type/Config distincts, hors `0.2.8` | absence de réutilisation WS | décidé |
| namespace LaserStream WS | `WsProtocolKind` + `ws_endpoints` possèdent `helius_laserstream` | API/Config/docs canary | pre.004 validé |
| 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 validé |
| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 validé |
| DTO duplication | seulement si wire/sémantique divergent | public/source audit | décidé |
| Config direction | Config -> Transport uniquement | ownership tests | pre.004 préparé |
| heartbeat | Helius-only, actor commun | deterministic timers | décidé |
| secret | query URL derrière `WsEndpointUrl` | redaction canaries | pre.004 préparé |
| new Rust dependency | aucune | manifest/tree audit | décidé |
| Helius unsupported | absent de la façade | compile-fail/API absence canary | pre.003 validé |
| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 validé |
| DTO duplication | seulement si wire/sémantique divergent | public/source audit | décidé |
| Config direction | Config -> Transport uniquement | ownership tests | pre.004 validé |
| heartbeat | Helius-only, actor commun | deterministic timers | décidé |
| secret | query URL derrière `WsEndpointUrl` | redaction canaries | pre.004 validé |
| new Rust dependency | aucune | manifest/tree audit | décidé |
## 5. Contrat `transactionSubscribe` à valider
@@ -206,8 +207,8 @@ 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
[ ] transaction unsubscribe/result exact
[ ] 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
[ ] notification decode failure isole la logical subscription
[ ] provider RPC application error ne tue pas la session
@@ -262,7 +263,7 @@ 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.003` et préparation `pre.004`
## 10. Preuves `pre.003` et `pre.004`
Checkpoint `pre.003` reçu :
@@ -299,18 +300,18 @@ Surface `pre.004` préparée :
[x] schema `ws_endpoints[].kind` accepte `helius_laserstream`
[x] adapter Config mappe `helius_laserstream` vers `WsProtocolKind::HeliusLaserStream`
[x] fixture Config matérialise un endpoint Helius mainnet typé
[ ] fixture Config matérialise un profil Helius devnet distinct — ajouté par fix.001, checkpoint à rejouer
[x] fixture Config matérialise un profil Helius devnet distinct — fix.001/fix.002 validés
[x] exemple Transport matérialise Helius mainnet sans credential réel
[ ] exemple Transport matérialise Helius devnet dans un profil distinct — ajouté par fix.001, checkpoint à rejouer
[x] exemple Transport matérialise Helius devnet dans un profil distinct — fix.001/fix.002 validés
[x] `.env.example` inventorie `KSP_SECRET_HELIUS_API_KEY`
[x] interpolation du secret produit l'URL runtime Helius attendue
[ ] safe_value conserve les littéraux Helius mainnet/devnet et redige uniquement l'api-key (`...api-key=********`) — fix.001 à rejouer
[ ] Debug de `ResolvedTransportConfig` n'expose pas la clé — assertion à rejouer après fix.001
[x] safe_value conserve les littéraux Helius mainnet/devnet et redige uniquement l'api-key (`...api-key=********`)
[x] Debug de `ResolvedTransportConfig` n'expose pas la clé
[x] Config produit un endpoint composable avec `HeliusLaserStreamWsSession`
[x] `config/std.transport.json` canonique reste standard-only
```
Aucun `transactionSubscribe`, heartbeat, changement du moteur WebSocket ou nouvelle dépendance n'est introduit dans cette tranche.
`pre.004` n'introduisait aucun `transactionSubscribe`, heartbeat, changement du moteur WebSocket ou nouvelle dépendance ; son checkpoint final est désormais vert.
## 11. Audit structurel des documents actifs
@@ -338,7 +339,6 @@ 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. Gates opérateur `pre.004` / `fix.001` / `fix.002`
Premier passage `pre.004` reçu le 2026-08-23 :
@@ -389,16 +389,69 @@ Le comportement runtime est correct. Une chaîne `wss://...api-key=${KSP_SECRET_
`pre.004-fix.002` modifie uniquement le canari mainnet/devnet pour vérifier ces deux segments. Les profils, URLs, redaction, schema et mapping restent inchangés.
À rejouer après `pre.004-fix.002` :
Checkpoint reçu après `pre.004-fix.002` :
```text
[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace
[x] cargo clippy --workspace --all-targets
[x] cargo test -p ksp-config-lib — 110/110 + ownership/public API
[x] cargo test -p ksp-onchain-transport-lib — 314 unit + 38 public + 26 completeness + 4 doctests
[x] cargo test --workspace
```
Verdict : **`pre.004` DONE ; `pre.004-fix.001` DONE ; `pre.004-fix.002` DONE.**
## 13. Préparation `pre.005` — contrat Helius transaction
Sources matérialisées :
```text
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
```
Contrats préparés :
```text
[x] HeliusTransactionSubscribeFilter couvre vote/failed/signature/accountInclude/accountExclude/accountRequired/tokenAccounts
[x] accountInclude/accountExclude/accountRequired conservent omission vs [] explicite
[x] chacune des trois listes est bornée localement à 50_000
[x] HeliusTokenAccountsFilter = none/balanceChanged/all
[x] HeliusTransactionSubscribeEncoding = base58/base64/jsonParsed
[x] transactionDetails réutilise SolanaTransactionDetails = full/signatures/accounts/none
[x] maxSupportedTransactionVersion est exigé pour accounts/full
[x] options absentes vs objet {} explicite restent distinctes
[x] transactionSubscribe ack numérique et transactionUnsubscribe booléen ont des décodeurs stricts
[x] transactionUnsubscribe encode exactement [remoteSubscriptionId]
[x] Debug filtre/request expose des comptes et indicateurs, jamais signature/adresses
[x] fixture locale route subscribe/unsubscribe via le WsSession actor existant
[x] aucun second actor/socket
[x] aucun transaction_subscribe public avant pre.006
[x] aucune nouvelle dépendance
```
Validation statique disponible dans l'environnement de préparation :
```text
python3 scripts/audit_rust_workspace_rules.py
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
```
Gates opérateur `pre.005` à exécuter :
```text
[ ] cargo fmt --all
[ ] python3 scripts/audit_rust_workspace_rules.py = clean
[ ] cargo check --workspace
[ ] cargo clippy --workspace --all-targets
[ ] cargo test -p ksp-config-lib
[ ] cargo test -p ksp-onchain-transport-lib
[ ] cargo test --workspace
```
Verdict courant : **`pre.003` DONE ; `pre.004` fonctionnellement implémenté mais non fermé ; `pre.004-fix.001` CHECKPOINT ; `pre.004-fix.002` PREPARED.**
Verdict courant : **`pre.004` et ses fixes DONE ; `pre.005` PREPARED.**