khadhroony-solana-project/deltas/0.2.8/pre.006.md

Delta 0.2.8-pre.006 — Helius transactionNotification + lifecycle actor

1. Base et objet

Base appliquée :

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 :

transactionSubscribe
  -> registry actor existant
  -> WsSubscription<HeliusTransactionNotification>
  -> transactionNotification
  -> reconnect/resubscribe/remap remote ID
  -> transactionUnsubscribe

2. Version technique

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 :

HeliusTransaction

avec le triplet exact :

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 :

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 :

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 :

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

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 :

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 :

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 :

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

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

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.