v0.2.8-pre.006
This commit is contained in:
235
deltas/0.2.8/pre.006.md
Normal file
235
deltas/0.2.8/pre.006.md
Normal file
@@ -0,0 +1,235 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user