v0.2.8-pre.008

2026-08-23 17:19:44 +02:00
parent 7eb6dec809
commit 7c12ec886b
8 changed files with 672 additions and 27 deletions
--- a/deltas/0.2.8/pre.008.md
+++ b/deltas/0.2.8/pre.008.md
@@ -0,0 +1,238 @@
+<!-- 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.