236 lines
7.8 KiB
Markdown
236 lines
7.8 KiB
Markdown
<!-- file: deltas/0.2.8/pre.006.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.8-pre.006` — Helius transactionNotification + lifecycle actor
|
|
|
|
## 1. Base et objet
|
|
|
|
Base appliquée :
|
|
|
|
```text
|
|
0.2.8-pre.5.fix.2
|
|
```
|
|
|
|
Le checkpoint opérateur de cette base est intégralement vert et sans warning : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace` passent. Transport compte alors `322` tests unitaires, `39` tests public API, `27` tests release-completeness et `4` doctests compile-fail.
|
|
|
|
Cette tranche transforme le contrat de requête Helius préparé en `pre.005` en une souscription live complète, sans créer de second moteur WebSocket :
|
|
|
|
```text
|
|
transactionSubscribe
|
|
-> registry actor existant
|
|
-> WsSubscription<HeliusTransactionNotification>
|
|
-> transactionNotification
|
|
-> reconnect/resubscribe/remap remote ID
|
|
-> transactionUnsubscribe
|
|
```
|
|
|
|
## 2. Version technique
|
|
|
|
```text
|
|
workspace.package.version = 0.2.8-pre.6
|
|
commit attendu = v0.2.8-pre.006
|
|
Git tag = aucun tag prerelease
|
|
```
|
|
|
|
Le header root `Cargo.toml` passe en version `226`.
|
|
|
|
## 3. Subscription kind provider
|
|
|
|
`WsSubscriptionKind` gagne :
|
|
|
|
```text
|
|
HeliusTransaction
|
|
```
|
|
|
|
avec le triplet exact :
|
|
|
|
```text
|
|
as_str helius_transaction
|
|
subscribe_method transactionSubscribe
|
|
unsubscribe_method transactionUnsubscribe
|
|
notification_method transactionNotification
|
|
```
|
|
|
|
Cette extension ne modifie pas la partition standard Solana de neuf familles et reste hors des trois familles standard classées unstable (`Block`, `SlotsUpdates`, `Vote`).
|
|
|
|
Le generic actor existant reste l'unique propriétaire :
|
|
|
|
- du socket physique ;
|
|
- du pending map JSON-RPC ;
|
|
- des local IDs ;
|
|
- des remote IDs ;
|
|
- du registry de subscriptions ;
|
|
- du reconnect/resubscribe ;
|
|
- des queues de notifications ;
|
|
- du cleanup unsubscribe ;
|
|
- du shutdown.
|
|
|
|
## 4. Handle live Helius
|
|
|
|
`HeliusLaserStreamWsSession` expose maintenant :
|
|
|
|
```rust
|
|
transaction_subscribe(
|
|
&self,
|
|
request: &HeliusTransactionSubscribeRequest,
|
|
) -> Result<WsSubscription<HeliusTransactionNotification>>
|
|
```
|
|
|
|
La validation déterministe et la sérialisation de `pre.005` restent exécutées avant l'enregistrement actor. Le helper de sérialisation et ses sous-helpers redeviennent du code de production uniquement parce qu'ils ont désormais un consommateur réel ; ils restent strictement privés au module.
|
|
|
|
Aucune visibilité n'est élargie pour les tests. Les canaris du sous-module accèdent aux helpers privés avec `super::Item`; les contrats publics sont consommés via `crate::Item`.
|
|
|
|
## 5. Notification typed
|
|
|
|
Trois formes publiques sont exposées au crate-root.
|
|
|
|
### 5.1 Full/accounts
|
|
|
|
`HeliusFullTransactionNotification` conserve :
|
|
|
|
```text
|
|
transaction serde_json::Value
|
|
signature String
|
|
slot u64
|
|
transactionIndex u64
|
|
```
|
|
|
|
Le nested `transaction` reste lossless en JSON, car sa forme dépend de `encoding` et `transactionDetails`; Transport ne décode pas les Programs.
|
|
|
|
### 5.2 Signatures
|
|
|
|
`HeliusTransactionSignatureNotification` conserve :
|
|
|
|
```text
|
|
signature String
|
|
slot u64
|
|
transactionIndex u64
|
|
err Omitted | Null | Value(JSON)
|
|
memo Omitted | Null | Value(String)
|
|
blockTime Omitted | Null | Value(i64)
|
|
confirmationStatus Omitted | Null | Value(String)
|
|
```
|
|
|
|
Les champs optionnels réutilisent `SolanaWireField` afin de ne pas confondre omission et `null`.
|
|
|
|
### 5.3 Union publique
|
|
|
|
```text
|
|
HeliusTransactionNotification::Full(...)
|
|
HeliusTransactionNotification::Signature(...)
|
|
HeliusTransactionNotification::Unknown(JSON)
|
|
```
|
|
|
|
`Unknown` conserve uniquement le `params.result` provider. L'enveloppe JSON-RPC complète et `params.subscription` ne franchissent pas le boundary public. Cette forme couvre notamment un `transactionDetails=none` ou une évolution provider non encore typée sans tuer arbitrairement la logical subscription.
|
|
|
|
## 6. Reconnect, unsubscribe tardif et backpressure
|
|
|
|
Le support Helius s'appuie directement sur les garanties du moteur `0.2.7` :
|
|
|
|
- les params `transactionSubscribe` originaux sont conservés par le registry ;
|
|
- après reconnect, un nouvel ID remote remplace l'ancien ;
|
|
- le `WsSubscriptionId` local reste stable ;
|
|
- le remote ID n'est jamais public ;
|
|
- au début d'un unsubscribe, le mapping remote -> local est retiré avant l'émission de `transactionUnsubscribe` ;
|
|
- une notification provider déjà en vol après cancellation est donc ignorée ;
|
|
- un overflow de queue échoue seulement la logical subscription lente ;
|
|
- le cleanup best-effort utilise automatiquement `transactionUnsubscribe` grâce au nouveau `WsSubscriptionKind`.
|
|
|
|
Cette sémantique correspond au contrat Helius actuel qui précise que quelques messages en vol peuvent encore arriver brièvement après `transactionUnsubscribe`.
|
|
|
|
## 7. Canaris ajoutés/actualisés
|
|
|
|
Les tests Helius transaction couvrent maintenant :
|
|
|
|
```text
|
|
notification Full / Signature / Unknown
|
|
live transactionSubscribe exact via façade publique
|
|
transactionNotification routée vers WsSubscription
|
|
transactionUnsubscribe exact via handle public
|
|
reconnect : remote ID 41 -> 99
|
|
resubscribe : params identiques
|
|
stable local WsSubscriptionId
|
|
late transactionNotification après demande unsubscribe ignorée
|
|
overflow transaction : handle lent Failed + ERROR_CODE_WS_BACKPRESSURE_OVERFLOW
|
|
cleanup overflow : transactionUnsubscribe [remote_id]
|
|
Helius root sain reste Active et reçoit encore sa notification
|
|
```
|
|
|
|
Un canari lifecycle verrouille aussi le triplet exact du nouveau `WsSubscriptionKind::HeliusTransaction`.
|
|
|
|
Les public/release canaries gagnent :
|
|
|
|
- le symbole public `HeliusLaserStreamWsSession::transaction_subscribe` ;
|
|
- les trois types publics de notification ;
|
|
- la présence du kind provider ;
|
|
- l'absence de second `connect_async`/actor dans le module Helius ;
|
|
- la conservation des compile-fail Helius block/slotsUpdates/vote/escape-hatch.
|
|
|
|
Comptages attendus :
|
|
|
|
```text
|
|
Transport unit 325
|
|
Transport public API 40
|
|
release completeness 28
|
|
doctests compile-fail 4
|
|
```
|
|
|
|
## 8. Documentation
|
|
|
|
Le plan `015` :
|
|
|
|
- ferme `pre.005`, `fix.001` et `fix.002` après preuve opérateur sans warning ;
|
|
- marque `pre.006` PREPARED ;
|
|
- documente l'union notification, le remap remote/local et les nouveaux canaris lifecycle.
|
|
|
|
La validation `011` :
|
|
|
|
- enregistre le checkpoint final `pre.005` ;
|
|
- ouvre la gate `pre.006` ;
|
|
- conserve heartbeat, adversarial élargi et smoke live dans leurs tranches prévues.
|
|
|
|
## 9. Hors scope
|
|
|
|
Restent explicitement hors de `pre.006` :
|
|
|
|
```text
|
|
heartbeat / idle timer pre.007
|
|
provider adversarial/security élargi pre.008
|
|
compliance finale pre.009
|
|
smoke Helius live opt-in pre.010
|
|
LaserStream gRPC future transport séparé
|
|
```
|
|
|
|
Aucune nouvelle dépendance n'est ajoutée.
|
|
|
|
## 10. Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/src/lib.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_subscription.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/ws_lifecycle.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.006.md
|
|
```
|
|
|
|
## 11. 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 : aucune erreur, aucun warning nouveau, audit Rust clean et tous les nouveaux canaris lifecycle Helius verts.
|