239 lines
7.4 KiB
Markdown
239 lines
7.4 KiB
Markdown
<!-- file: deltas/0.2.8/pre.008.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.8-pre.008` — adversarial Helius provider + limites + diagnostics sûrs
|
|
|
|
## 1. Base et objet
|
|
|
|
Base appliquée :
|
|
|
|
```text
|
|
0.2.8-pre.7.fix.4
|
|
```
|
|
|
|
Le checkpoint opérateur final de `pre.007` est intégralement vert :
|
|
|
|
```text
|
|
cargo fmt --all OK
|
|
python3 scripts/audit_rust_workspace_rules.py clean
|
|
cargo check --workspace OK
|
|
cargo clippy --workspace --all-targets OK
|
|
Transport unit 331/331
|
|
Transport public API 40/40
|
|
Transport release completeness 29/29
|
|
Transport doctests compile-fail 4/4
|
|
cargo test --workspace OK
|
|
```
|
|
|
|
`pre.008` durcit la surface Helius WebSocket contre des comportements provider adversariaux sans créer de nouveau runtime. La tranche réutilise l'actor physique, les limites frame/message, le reconnect, le registry et la backpressure existants.
|
|
|
|
## 2. Version technique
|
|
|
|
```text
|
|
workspace.package.version = 0.2.8-pre.8
|
|
commit attendu = v0.2.8-pre.008
|
|
Git tag = aucun tag prerelease
|
|
```
|
|
|
|
Le header root `Cargo.toml` passe en version `232`.
|
|
|
|
## 3. Ré-audit Helius courant
|
|
|
|
La documentation Helius réauditée le 2026-08-23 confirme :
|
|
|
|
```text
|
|
transactionSubscribe supporté
|
|
transactionUnsubscribe supporté
|
|
accountInclude/accountExclude/accountRequired 50 000 adresses max par liste
|
|
blockSubscribe non supporté Helius
|
|
slotsUpdatesSubscribe non supporté Helius
|
|
voteSubscribe non supporté Helius
|
|
endpoints WSS unifiés mainnet/devnet
|
|
```
|
|
|
|
La tranche n'introduit donc aucune nouvelle famille provider.
|
|
|
|
## 4. `Debug` sûr pour les notifications Helius
|
|
|
|
Le prompt `0.2.8` interdit les payloads arbitraires/massifs dans les diagnostics génériques. Avant cette tranche, les types de notification Helius dérivaient `Debug`, ce qui pouvait rendre :
|
|
|
|
```text
|
|
transaction JSON brut
|
|
signature complète
|
|
memo/error provider
|
|
fallback Unknown(serde_json::Value) brut
|
|
```
|
|
|
|
`pre.008` remplace ces dérivations par des implémentations explicites :
|
|
|
|
```text
|
|
HeliusFullTransactionNotification
|
|
transaction <omitted>
|
|
signature <omitted>
|
|
slot visible
|
|
transaction_index visible
|
|
|
|
HeliusTransactionSignatureNotification
|
|
signature <omitted>
|
|
slot/index visibles
|
|
err omitted/null/value seulement
|
|
memo omitted/null/value seulement
|
|
block_time omitted/null/value seulement
|
|
confirmation_status omitted/null/value seulement
|
|
|
|
HeliusTransactionNotification::Unknown
|
|
payload Value conservé fonctionnellement
|
|
Debug = Unknown("<omitted>")
|
|
```
|
|
|
|
Aucun accessor fonctionnel n'est supprimé. La donnée reste accessible explicitement au consommateur qui la demande ; seul le chemin diagnostic implicite est redacted.
|
|
|
|
## 5. Capability guard inverse
|
|
|
|
La façade Helius avait déjà quatre doctests compile-fail :
|
|
|
|
```text
|
|
Helius -X-> blockSubscribe
|
|
Helius -X-> slotsUpdatesSubscribe
|
|
Helius -X-> voteSubscribe
|
|
Helius -X-> into_inner
|
|
```
|
|
|
|
`pre.008` ajoute le canari inverse :
|
|
|
|
```text
|
|
SolanaStandardWsSession -X-> transactionSubscribe
|
|
```
|
|
|
|
La séparation standard/provider est donc prouvée dans les deux sens sans exposer le `WsSession` générique.
|
|
|
|
## 6. Provider RPC application error
|
|
|
|
Un serveur local adversarial retourne une erreur JSON-RPC `transactionSubscribe` avec :
|
|
|
|
```text
|
|
code provider
|
|
message canary sensible
|
|
payload data arbitraire de plusieurs KiB
|
|
```
|
|
|
|
Le canari exige :
|
|
|
|
```text
|
|
ERROR_CODE_RPC_APPLICATION_ERROR
|
|
context sûr = rpc_code + method
|
|
message/data provider non copiés dans KspError
|
|
api-key URL non rendue
|
|
filter signature non rendue
|
|
session physique reste Active
|
|
subscription_count revient à 0
|
|
rootSubscribe fonctionne ensuite normalement
|
|
```
|
|
|
|
Une erreur d'application provider ne doit donc pas être promue en panne de transport.
|
|
|
|
## 7. Notification method mismatch
|
|
|
|
Un remote ID enregistré comme `HeliusTransaction` reçoit volontairement un `rootNotification`.
|
|
|
|
Résultat attendu :
|
|
|
|
```text
|
|
logical transaction subscription -> Failed / WS_PROTOCOL_ERROR
|
|
remote binding transaction -> cleanup transactionUnsubscribe
|
|
session physique -> Active
|
|
subscription root saine -> Active et notification reçue
|
|
```
|
|
|
|
Le mismatch de famille ne doit pas contaminer les autres logical subscriptions.
|
|
|
|
## 8. Payload entrant oversized
|
|
|
|
Un endpoint Helius local envoie une frame texte supérieure aux limites configurées :
|
|
|
|
```text
|
|
max_message_size_bytes = 256
|
|
max_frame_size_bytes = 128
|
|
```
|
|
|
|
Le canari prouve que la limite tungstenite/actor s'applique avant tout décodage JSON provider, déclenche le reconnect borné existant et laisse la connexion Helius de remplacement utilisable pour un `rootSubscribe`/unsubscribe normal.
|
|
|
|
Aucun nouveau compteur ou chemin de reconnect n'est ajouté.
|
|
|
|
## 9. Backpressure et lifecycle conservés
|
|
|
|
La preuve provider-specific de `pre.006` reste autoritaire pour :
|
|
|
|
```text
|
|
queue capacity = 1
|
|
transaction notification overflow
|
|
échec de la seule transaction subscription
|
|
cleanup transactionUnsubscribe
|
|
root subscription saine non affectée
|
|
session physique Active
|
|
```
|
|
|
|
`pre.008` ne duplique pas ce scénario. Les canaris partagés hérités continuent aussi de couvrir unsubscribe pendant reconnect, decode failure isolé, pending bounds et shutdown pendant backoff.
|
|
|
|
## 10. Canaris ajoutés
|
|
|
|
Quatre unit tests Helius sont ajoutés :
|
|
|
|
```text
|
|
notification Debug redaction Full/Signature/Unknown
|
|
provider RPC application error sûre + session réutilisable
|
|
notification method mismatch isolé + cleanup transactionUnsubscribe
|
|
oversized inbound provider payload + reconnect + session réutilisable
|
|
```
|
|
|
|
Un release-completeness canary supplémentaire vérifie les guards, les `Debug` explicites et la réutilisation des mécanismes de bornage de l'actor.
|
|
|
|
Un doctest compile-fail supplémentaire interdit `transactionSubscribe` sur `SolanaStandardWsSession`.
|
|
|
|
Comptages attendus :
|
|
|
|
```text
|
|
Transport unit 335
|
|
Transport public API 40
|
|
release completeness 30
|
|
doctests compile-fail 5
|
|
```
|
|
|
|
## 11. Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
|
|
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
|
|
deltas/0.2.8/pre.008.md
|
|
```
|
|
|
|
## 12. Hors scope
|
|
|
|
Restent hors de `pre.008` :
|
|
|
|
```text
|
|
compliance finale Helius + standard/HTTP pre.009
|
|
smoke Helius live + cargo tree final pre.010
|
|
fermeture docs/indexes + prompt 0.2.9 pre.011
|
|
LaserStream gRPC futur backend séparé
|
|
Gatekeeper/preconf WebSocket hors scope 0.2.8
|
|
```
|
|
|
|
## 13. Gate opérateur
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo test --workspace
|
|
```
|
|
|
|
Critère de fermeture : zéro warning, audit clean, **335 unit / 40 public API / 30 completeness / 5 doctests** et workspace vert.
|