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

v0.2.8-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 14:08:12 +02:00
parent b3363073c4
commit f2a3ec62aa
11 changed files with 335 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
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: 8 -->
<!-- version: 9 -->
# Plan `0.2.8` — Helius LaserStream WebSocket
> **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.
> **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`.
## 1. Objet, base et état courant
@@ -26,14 +26,15 @@ 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 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
pre.003 six familles standard Helius validées
pre.004 Config V2 Helius + secret/redaction préparés
workspace.package.version courant = 0.2.8-pre.3
commit attendu = v0.2.8-pre.003
workspace.package.version courant = 0.2.8-pre.4
commit attendu = v0.2.8-pre.004
aucun tag prerelease
```
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.
Le checkpoint opérateur de `pre.003` est intégralement vert : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. Les six familles standard Helius sont donc acquises sans dette de gate avant l'ouverture de Config Helius en `pre.004`.
## 2. Forecast souple courant
@@ -47,9 +48,9 @@ pre.001 DONE — audit Helius actuel + matrice + architecture + threat model +
pre.002 DONE — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
+ connexion physique partagée + guards, sans duplication de l'actor
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
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 Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport
pre.004 PREPARED — 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
@@ -241,12 +242,15 @@ profiles[].endpoints[]
profiles[].ws_endpoints[].kind
```
Le schema et l'adapter n'acceptent actuellement que :
Après `pre.004`, le schema V2 et l'adapter acceptent :
```text
solana_standard
helius_laserstream
```
Le document canonique `config/std.transport.json` reste volontairement une baseline publique Solana sans credential provider. La représentation Helius est portée par la fixture Config et `config/examples/std.transport.example.json`, afin de prouver le contrat sans introduire une fausse clé Helius dans le profil runtime par défaut.
## 5. Audit Helius officiel du 2026-08-23
### 5.1 Sources primaires utilisées
@@ -592,7 +596,7 @@ La façade standard délègue déjà les neuf familles existantes sans recopier
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.
La façade Helius a reçu les six délégations communes en `pre.003`, après que `pre.002` a volontairement limité son scope au socle protocolaire et aux guards.
### 7.7 Réalisation de `pre.003`
@@ -695,25 +699,27 @@ budget reconnect = fini, inchangé
### 7.12 Config V2
Évolution :
Contrat matérialisé par `pre.004` :
```text
profiles[].ws_endpoints[].kind:
solana_standard
helius_laserstream
helius_laserstream -> WsProtocolKind::HeliusLaserStream
```
Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config.
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.
### 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}
wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me}
```
Le nom final du secret est matérialisé avec Config. Transport ne lit jamais `std::env` et reçoit un `WsEndpointUrl` redacted.
`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`.
## 8. Threat model provider
@@ -884,12 +890,11 @@ validation finale fermée
prompt 0.2.9 prêt
```
## 13. Checkpoint `pre.003`
## 13. Checkpoint `pre.004`
Le checkpoint précédent est fermé par preuve opérateur :
Le checkpoint `pre.003` 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
@@ -898,31 +903,34 @@ cargo test -p ksp-onchain-transport-lib OK
cargo test --workspace OK
```
`pre.003` prépare maintenant :
Les preuves spécifiques `pre.003` sont acquises : fixture Helius 6/6, 38 tests public API, 26 release-completeness et 4 doctests `compile_fail`, tous verts.
`pre.004` prépare uniquement :
```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
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
secret KSP_SECRET_HELIUS_API_KEY
safe projection / Debug credential Helius redacted
Config -> Transport endpoint typé HeliusLaserStream
canonical std.transport.json inchangé, standard-only
transactionSubscribe toujours absent
heartbeat toujours absent
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 :
Le checkpoint opérateur requis avant de déclarer `pre.004` `DONE` est :
```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
```
Si ce checkpoint est vert, `pre.004` ouvre uniquement Config V2 `helius_laserstream`, schema/fixtures, mapping Config -> Transport et stratégie de secret/redaction.
Si ce checkpoint est vert, `pre.005` peut ouvrir la requête typed `transactionSubscribe` / `transactionUnsubscribe`, ses filtres/options et validations déterministes.

75
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: 8 -->
<!-- version: 9 -->
# Validation `0.2.8` — Helius LaserStream WebSocket
> **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`.
> **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.
## 1. Références
@@ -87,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` + `pre.002-fix.001` sont entièrement verts et fermés. `pre.003` est ouvert.**
Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `fix.001` et `pre.003` sont entièrement verts et fermés. `pre.004` est ouvert.**
## 3. Matrice provider normative
@@ -135,16 +135,16 @@ Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `pre.002-fix.001` sont en
| 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 | 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 implémenté, checkpoint pending |
| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 implémenté, checkpoint pending |
| 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 | 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 | 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
@@ -202,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 — implémenté en `pre.003`, fixture opérateur pending
[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 notification dispatch exact
@@ -232,6 +232,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] no Transport -> Config/Wallet/Store/Program/tracing direct — audits/tests ownership verts
```
@@ -239,6 +241,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
[ ] api-key absente de Debug settings/session/subscription
[ ] api-key absente des KspError safe contexts
[ ] URL complète absente des snapshots
@@ -255,9 +259,9 @@ 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.002` / `fix.001` et préparation `pre.003`
## 10. Preuves `pre.003` et préparation `pre.004`
Checkpoint `pre.002-fix.001` reçu :
Checkpoint `pre.003` reçu :
```text
cargo fmt --all OK
@@ -268,25 +272,40 @@ cargo test -p ksp-onchain-transport-lib OK
cargo test --workspace OK
```
Surface `pre.003` préparée :
Preuves spécifiques acquises :
```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
[x] Helius accountSubscribe/accountUnsubscribe
[x] Helius programSubscribe/programUnsubscribe
[x] Helius logsSubscribe/logsUnsubscribe
[x] Helius signatureSubscribe/signatureUnsubscribe
[x] Helius slotSubscribe/slotUnsubscribe
[x] Helius rootSubscribe/rootUnsubscribe
[x] compile-fail Helius blockSubscribe
[x] compile-fail Helius slotsUpdatesSubscribe
[x] compile-fail Helius voteSubscribe
[x] public API canary des six wrappers
[x] release completeness canary
```
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.
La fixture Transport rapporte 314 tests unitaires verts, 38 tests public API verts, 26 tests release-completeness verts et 4 doctests compile-fail verts. `pre.003` est donc `DONE`.
Aucun `transactionSubscribe`, changement Config, heartbeat ou nouvelle dépendance n'est introduit dans cette tranche.
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
```
Aucun `transactionSubscribe`, heartbeat, changement du moteur WebSocket ou nouvelle dépendance n'est introduit dans cette tranche.
## 11. Audit structurel des documents actifs
@@ -314,16 +333,16 @@ 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`
## 12. Gate opérateur `pre.004`
```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` préparé, non déclaré `DONE` avant ce checkpoint.**
Verdict courant : **`pre.003` DONE ; `pre.004` préparé, non déclaré `DONE` avant ce checkpoint.**