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

v0.2.8-pre.004-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 14:20:24 +02:00
parent f2a3ec62aa
commit 38fd62c256
8 changed files with 402 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
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: 9 -->
<!-- version: 11 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **Statut : `0.2.8-pre.003` est validé ; `0.2.8-pre.004` est préparé.** La façade `HeliusLaserStreamWsSession` possède désormais sa surface standard 6/6 validée. `pre.004` étend uniquement Config V2 au discriminateur WebSocket `helius_laserstream`, ajoute la fixture/exemple Helius et verrouille la résolution/redaction de `KSP_SECRET_HELIUS_API_KEY`, sans ouvrir `transactionSubscribe`.
> **Statut : `0.2.8-pre.003` est validé ; le checkpoint `0.2.8-pre.004` a révélé un faux négatif de test, puis la revue du fix a identifié l'omission d'une représentation Devnet Helius déterministe. `pre.004-fix.001` corrige les deux points et reste préparé.** Le runtime Config/Transport est inchangé : pour une chaîne composée, `safe_value` conserve les segments littéraux non sensibles et remplace uniquement le segment secret par `********`. Le fix couvre désormais mainnet et devnet sans ouvrir `transactionSubscribe`.
## 1. Objet, base et état courant
@@ -27,10 +27,11 @@ 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 + secret/redaction préparés
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 préparées
workspace.package.version courant = 0.2.8-pre.4
commit attendu = v0.2.8-pre.004
workspace.package.version courant = 0.2.8-pre.4.fix.1
commit attendu = v0.2.8-pre.004-fix.001
aucun tag prerelease
```
@@ -50,8 +51,10 @@ 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 PREPARED — Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
+ stratégie de secret Helius et redaction URL
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 PREPARED — corrige le faux négatif `safe_value` + complète la représentation Devnet Helius
+ mainnet/devnet dans des profils distincts, même secret, sans changement runtime
pre.005 transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
+ bounds 50k + maxSupportedTransactionVersion conditionnel
pre.006 transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races
@@ -709,17 +712,18 @@ profiles[].ws_endpoints[].kind:
helius_laserstream -> WsProtocolKind::HeliusLaserStream
```
La fixture Config contient un endpoint Helius typé et l'exemple versionné montre la composition de l'URL mainnet. `config/std.transport.json` reste standard-only pour ne pas imposer de provider/credential dans la configuration par défaut. Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config.
La fixture Config contient un endpoint Helius mainnet typé ainsi qu'un profil Helius devnet distinct. L'exemple versionné matérialise lui aussi un profil mainnet et un profil devnet séparés ; aucun profil logique ne mélange les deux clusters. `config/std.transport.json` reste standard-only pour ne pas imposer de provider/credential dans la configuration par défaut. Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config.
### 7.13 Credentials
L'api-key reste uniquement dans l'URL résolue :
```text
wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me}
mainnet = wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me}
devnet = wss://devnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me}
```
`KSP_SECRET_HELIUS_API_KEY` est inventorié dans `.env.example` sous forme commentée/placeholder. Config résout la clé au sein de l'URL effective, marque la valeur comme `Secret`, conserve l'URL réelle uniquement pour le runtime légitime et redige la projection sûre ainsi que `Debug`. Transport ne lit jamais `std::env` et reçoit uniquement un `WsEndpointUrl`.
`KSP_SECRET_HELIUS_API_KEY` est inventorié dans `.env.example` sous forme commentée/placeholder et est réutilisé pour les deux réseaux Helius. Config résout la clé au sein de chaque URL effective, marque le segment résolu comme `Secret` et conserve l'URL réelle uniquement pour le runtime légitime. Le contrat Config existant de redaction **segmentaire** s'applique aux chaînes composées : les littéraux sûrs sont conservés et le segment secret devient `********`, soit `wss://mainnet.helius-rpc.com/?api-key=********` ou `wss://devnet.helius-rpc.com/?api-key=********`. `Debug` n'expose jamais la clé réelle. Transport ne lit jamais `std::env` et reçoit uniquement un `WsEndpointUrl`.
## 8. Threat model provider
@@ -890,7 +894,7 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 13. Checkpoint `pre.004`
## 13. Checkpoint `pre.004` et `fix.001`
Le checkpoint `pre.003` est fermé par preuve opérateur :
@@ -910,8 +914,8 @@ Les preuves spécifiques `pre.003` sont acquises : fixture Helius 6/6, 38 tests
```text
WsProtocolKind Config mapping helius_laserstream -> HeliusLaserStream
JSON Schema V2 kind accepte solana_standard + helius_laserstream
fixture Config endpoint Helius avec interpolation d'api-key
example Config endpoint Helius mainnet explicite
fixture Config Helius mainnet + profil Helius devnet séparé, interpolation d'api-key
example Config profils Helius mainnet/devnet explicites et séparés
secret KSP_SECRET_HELIUS_API_KEY
safe projection / Debug credential Helius redacted
Config -> Transport endpoint typé HeliusLaserStream
@@ -921,7 +925,21 @@ heartbeat toujours absent
new dependency aucune
```
Le checkpoint opérateur requis avant de déclarer `pre.004` `DONE` est :
Le premier checkpoint opérateur `pre.004` reçu le 2026-08-23 donne :
```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 FAIL 109/110
cargo test -p ksp-onchain-transport-lib OK 314 unit + 38 public + 26 completeness + 4 doctests
cargo test --workspace FAIL sur le même test Config
```
L'unique échec opérateur compare `safe_value` à `********` alors que le résolveur produit correctement `wss://mainnet.helius-rpc.com/?api-key=********`. Les canaris historiques Config prouvent déjà ce contrat de redaction segmentaire pour les chaînes composées. La revue du fix a aussi identifié que `pre.004` ne matérialisait déterministiquement que mainnet alors que le contrat Helius WebSocket couvre mainnet et devnet. `pre.004-fix.001` corrige donc l'attente du test **et** ajoute un profil/fixture Devnet Helius séparé, sans modifier le résolveur, le schema, le mapping protocol ou le runtime Transport.
Le checkpoint à rejouer avant de déclarer `pre.004` + `fix.001` `DONE` est :
```bash
cargo fmt --all

86
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: 9 -->
<!-- version: 11 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **Statut : `pre.003` validé ; `pre.004` préparé.** Les six wrappers standard Helius, leurs exact-wire fixtures, canaries publiques/release-completeness et compile-fail sont verts. La tranche courante ajoute uniquement le mapping Config V2 `helius_laserstream`, une fixture/exemple Helius et les preuves de résolution/redaction du secret provider.
> **Statut : `pre.003` validé ; `pre.004` a atteint son checkpoint avec un faux négatif Config et la revue a ensuite relevé l'absence d'un cas Devnet Helius déterministe. `pre.004-fix.001` couvre les deux corrections.** `fmt`, audit, `check`, `clippy` et Transport sont verts. Le fix aligne le test Helius sur la redaction segmentaire existante et exige désormais mainnet + devnet dans des profils distincts.
## 1. Références
@@ -17,6 +17,8 @@ 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
pre.004 deltas/0.2.8/pre.004.md
pre.004 redaction test fix deltas/0.2.8/pre.004-fix.001.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
@@ -130,22 +132,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 préparé |
| 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 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é |
## 5. Contrat `transactionSubscribe` à valider
@@ -232,8 +234,8 @@ aucun payload brut dans logs/snapshots
[x] KSP-TRANSPORT-007 inchangé — tests Transport/workspace verts
[x] Config V1 HTTP-only backward readable — tests Config workspace verts
[x] Config V2 solana_standard backward readable — tests Config workspace verts
[ ] Config V2 helius_laserstream mappe vers WsProtocolKind::HeliusLaserStream — pre.004 test ajouté, pending
[ ] schema V2 accepte helius_laserstream sans relâcher les autres contraintes — pre.004 fixture pending
[x] Config V2 helius_laserstream mappe vers WsProtocolKind::HeliusLaserStream — test pre.004 atteint cette assertion avant l'échec safe_value
[x] schema V2 accepte helius_laserstream sans relâcher les autres contraintes — fixture chargée par le test pre.004
[x] no Transport -> Config/Wallet/Store/Program/tracing direct — audits/tests ownership verts
```
@@ -241,8 +243,8 @@ aucun payload brut dans logs/snapshots
```text
[x] api-key absente de Debug WsEndpointUrl — canaries héritées + pre.002 vert
[ ] KSP_SECRET_HELIUS_API_KEY redacted dans safe_value Config — pre.004 test ajouté, pending
[ ] KSP_SECRET_HELIUS_API_KEY absente de ResolvedTransportConfig Debug — pre.004 test ajouté, pending
[ ] KSP_SECRET_HELIUS_API_KEY redacted dans safe_value Config — comportement correct observé, attente du test corrigée par fix.001, checkpoint à rejouer
[ ] KSP_SECRET_HELIUS_API_KEY absente de ResolvedTransportConfig Debug — assertion située après le faux négatif, checkpoint fix.001 à rejouer
[ ] api-key absente de Debug settings/session/subscription
[ ] api-key absente des KspError safe contexts
[ ] URL complète absente des snapshots
@@ -293,16 +295,18 @@ La fixture Transport rapporte 314 tests unitaires verts, 38 tests public API ver
Surface `pre.004` préparée :
```text
[ ] schema `ws_endpoints[].kind` accepte `helius_laserstream`
[ ] adapter Config mappe `helius_laserstream` vers `WsProtocolKind::HeliusLaserStream`
[ ] fixture Config matérialise un endpoint Helius typé
[ ] exemple Transport matérialise Helius mainnet sans credential réel
[ ] `.env.example` inventorie `KSP_SECRET_HELIUS_API_KEY`
[ ] interpolation du secret produit l'URL runtime Helius attendue
[ ] safe_value redige l'URL contenant l'api-key
[ ] Debug de `ResolvedTransportConfig` n'expose pas la clé
[ ] Config produit un endpoint composable avec `HeliusLaserStreamWsSession`
[ ] `config/std.transport.json` canonique reste standard-only
[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] 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] `.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] 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.
@@ -333,7 +337,31 @@ 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.004`
## 12. Gate opérateur `pre.004` / `fix.001`
Premier passage `pre.004` reçu le 2026-08-23 :
```text
[x] cargo fmt --all
[x] python3 scripts/audit_rust_workspace_rules.py = clean
[x] cargo check --workspace
[x] cargo clippy --workspace --all-targets
[ ] cargo test -p ksp-config-lib — 109/110 ; faux négatif safe_value Helius
[x] cargo test -p ksp-onchain-transport-lib — vert
[ ] cargo test --workspace — échoue uniquement sur le même test Config
```
Observation exacte :
```text
observé = wss://mainnet.helius-rpc.com/?api-key=********
attendu = ********
```
L'observé est conforme au contrat historique du résolveur Config : dans une chaîne composée, les littéraux non sensibles restent visibles dans la projection sûre tandis que chaque placeholder secret est remplacé par `********`. Le fix ne modifie donc pas le runtime ; il corrige le canari pour attendre l'URL sûre segmentaire exacte. La revue du même checkpoint complète également la couverture Config avec un profil Helius Devnet distinct utilisant `wss://devnet.helius-rpc.com/?api-key=...`, afin que mainnet et devnet soient tous deux prouvés sans mélange de clusters.
À rejouer après `pre.004-fix.001` :
```text
[ ] cargo fmt --all
@@ -345,4 +373,4 @@ Aucun split en fichiers supplémentaires n'est retenu : les plans historiques `0
[ ] cargo test --workspace
```
Verdict courant : **`pre.003` DONE ; `pre.004` préparé, non déclaré `DONE` avant ce checkpoint.**
Verdict courant : **`pre.003` DONE ; `pre.004` fonctionnellement implémenté mais non fermé ; `pre.004-fix.001` PREPARED.**