Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.8-pre.006

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-23 15:41:54 +02:00
parent 8e739b9e55
commit 1c8d69778b
13 changed files with 862 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
crates/ksp-onchain-transport-lib/src/lib.rs
View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/lib.rs
// version: 32
// version: 33
#![warn(missing_docs)]
#![deny(unreachable_pub)]
@@ -27,8 +27,8 @@
//! provider-extension subscription API. `0.2.8-pre.002` adds a Helius LaserStream WebSocket protocol discriminator and two typed protocol facades while
//! keeping the `WsSession` actor/socket implementation unique and the historical generic constructor standard-only.
//! `0.2.8-pre.003` exposes the six standard families Helius supports through the provider facade, while `0.2.8-pre.005` adds the typed Helius
//! `transactionSubscribe` request contract, provider filter/options validation and exact subscribe/unsubscribe control-wire helpers without exposing a live
//! transaction subscription handle before actor integration.
//! `transactionSubscribe` request contract and provider filter/options validation. `0.2.8-pre.006` integrates the live transaction handle and typed
//! `transactionNotification` union into the same actor-owned registry, remote-ID remap, unsubscribe-race handling and per-subscription backpressure path.
mod client;
mod constants;
@@ -342,8 +342,14 @@ pub use self::ws_cluster::SolanaSlotUpdate;
pub use self::ws_cluster::SolanaSlotUpdateStats;
/// Typed unstable gossip-vote notification delivered by standard Solana `voteSubscribe`.
pub use self::ws_cluster::SolanaVoteNotification;
/// Full/accounts-mode notification delivered by Helius `transactionSubscribe`.
pub use self::ws_helius_transactions::HeliusFullTransactionNotification;
/// Helius `tokenAccounts` expansion mode accepted by `transactionSubscribe`.
pub use self::ws_helius_transactions::HeliusTokenAccountsFilter;
/// Typed Helius `transactionNotification` payload union.
pub use self::ws_helius_transactions::HeliusTransactionNotification;
/// Signatures-mode notification delivered by Helius `transactionSubscribe`.
pub use self::ws_helius_transactions::HeliusTransactionSignatureNotification;
/// Transaction encoding accepted by Helius `transactionSubscribe`.
pub use self::ws_helius_transactions::HeliusTransactionSubscribeEncoding;
/// Helius-specific filter object accepted as the first `transactionSubscribe` parameter.
@@ -360,7 +366,7 @@ pub use self::ws_lifecycle::WsSessionSnapshot;
pub use self::ws_lifecycle::WsSessionState;
/// Stable local identity assigned to one logical WebSocket subscription.
pub use self::ws_lifecycle::WsSubscriptionId;
/// Standard Solana subscription family represented by one logical WebSocket subscription.
/// WebSocket subscription family represented by one logical subscription.
pub use self::ws_lifecycle::WsSubscriptionKind;
/// Safe lifecycle projection for one logical WebSocket subscription.
pub use self::ws_lifecycle::WsSubscriptionSnapshot;
@@ -390,7 +396,7 @@ pub use self::ws_settings::WsResubscribePolicy;
pub use self::ws_settings::WsSessionSettings;
/// Complete runtime settings consumed by the KSP WebSocket transport foundation.
pub use self::ws_settings::WsTransportSettings;
/// Typed handle for one logical Solana WebSocket subscription.
/// Typed handle for one logical WebSocket subscription.
pub use self::ws_subscription::WsSubscription;
/// Typed value carried by a contextual Solana `logsNotification`.
pub use self::ws_transactions::SolanaLogsNotification;

215
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
// version: 3
// version: 4
const MAX_HELIUS_TRANSACTION_FILTER_ACCOUNTS: usize = 50_000;
@@ -150,7 +150,6 @@ impl HeliusTransactionSubscribeFilter {
return std::result::Result::Ok(());
}
#[cfg(test)]
fn to_json_value(&self) -> serde_json::Value {
let mut object = serde_json::Map::new();
if let std::option::Option::Some(vote) = self.vote {
@@ -261,7 +260,6 @@ impl HeliusTransactionSubscribeOptions {
return std::result::Result::Ok(());
}
#[cfg(test)]
fn to_json_value(self) -> serde_json::Value {
let mut object = serde_json::Map::new();
if let std::option::Option::Some(commitment) = self.commitment {
@@ -283,11 +281,10 @@ impl HeliusTransactionSubscribeOptions {
}
}
/// Complete typed request contract for Helius `transactionSubscribe` before actor registration.
/// Complete typed request contract for Helius `transactionSubscribe`.
///
/// The request owns the exact provider filter and optional result-shaping object. `pre.005` deliberately does not expose a public live subscription method:
/// actor-owned registration, notification delivery, reconnect and unsubscribe races are added atomically in `pre.006` so callers never receive an incomplete
/// provider subscription handle.
/// The request owns the exact provider filter and optional result-shaping object. Validation and serialization occur before actor registration so deterministic
/// provider constraints fail without WebSocket I/O.
#[derive(Clone, Eq, PartialEq)]
pub struct HeliusTransactionSubscribeRequest {
filter: crate::HeliusTransactionSubscribeFilter,
@@ -335,7 +332,6 @@ impl std::fmt::Debug for HeliusTransactionSubscribeRequest {
}
}
#[cfg(test)]
fn helius_transaction_subscribe_params(request: &crate::HeliusTransactionSubscribeRequest) -> ksp_core_lib::Result<std::vec::Vec<serde_json::Value>> {
let validation = request.validate();
if let std::result::Result::Err(error) = validation {
@@ -348,41 +344,189 @@ fn helius_transaction_subscribe_params(request: &crate::HeliusTransactionSubscri
return std::result::Result::Ok(params);
}
#[cfg(test)]
const fn helius_transaction_subscribe_method() -> &'static str {
return "transactionSubscribe";
/// Full/accounts-mode notification delivered by Helius `transactionSubscribe`.
///
/// The nested transaction payload is deliberately retained as JSON because its exact Solana wire representation depends on the requested encoding and detail
/// mode. KSP types the stable provider envelope while preserving the full nested payload without Program-specific decoding.
#[derive(Clone, Debug, PartialEq)]
pub struct HeliusFullTransactionNotification {
transaction: serde_json::Value,
signature: std::string::String,
slot: u64,
transaction_index: u64,
}
#[cfg(test)]
const fn helius_transaction_unsubscribe_method() -> &'static str {
return "transactionUnsubscribe";
impl HeliusFullTransactionNotification {
/// Returns the provider transaction/status payload without interpreting Program-specific contents.
#[must_use]
pub const fn transaction(&self) -> &serde_json::Value {
return &self.transaction;
}
/// Returns the base58 transaction signature reported by Helius.
#[must_use]
pub fn signature(&self) -> &str {
return self.signature.as_str();
}
/// Returns the slot in which the transaction was processed.
#[must_use]
pub const fn slot(&self) -> u64 {
return self.slot;
}
/// Returns the zero-based transaction position within the block.
#[must_use]
pub const fn transaction_index(&self) -> u64 {
return self.transaction_index;
}
}
#[cfg(test)]
fn decode_helius_transaction_subscribe_result(value: serde_json::Value) -> ksp_core_lib::Result<u64> {
return match value.as_u64() {
std::option::Option::Some(remote_id) => std::result::Result::Ok(remote_id),
std::option::Option::None => std::result::Result::Err(
ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "Helius transactionSubscribe acknowledgement must contain a numeric subscription id")
.with_context("rpc_method", "transactionSubscribe"),
),
};
/// Signatures-mode notification delivered by Helius `transactionSubscribe`.
#[derive(Clone, Debug, PartialEq)]
pub struct HeliusTransactionSignatureNotification {
signature: std::string::String,
slot: u64,
transaction_index: u64,
err: crate::SolanaWireField<serde_json::Value>,
memo: crate::SolanaWireField<std::string::String>,
block_time: crate::SolanaWireField<i64>,
confirmation_status: crate::SolanaWireField<std::string::String>,
}
#[cfg(test)]
fn helius_transaction_unsubscribe_params(remote_id: u64) -> std::vec::Vec<serde_json::Value> {
return std::vec![serde_json::Value::Number(remote_id.into())];
impl HeliusTransactionSignatureNotification {
/// Returns the base58 transaction signature reported by Helius.
#[must_use]
pub fn signature(&self) -> &str {
return self.signature.as_str();
}
/// Returns the slot in which the transaction was processed.
#[must_use]
pub const fn slot(&self) -> u64 {
return self.slot;
}
/// Returns the zero-based transaction position within the block.
#[must_use]
pub const fn transaction_index(&self) -> u64 {
return self.transaction_index;
}
/// Returns the optional transaction error while preserving omitted/null/value wire states.
#[must_use]
pub const fn err(&self) -> &crate::SolanaWireField<serde_json::Value> {
return &self.err;
}
/// Returns the optional memo while preserving omitted/null/value wire states.
#[must_use]
pub const fn memo(&self) -> &crate::SolanaWireField<std::string::String> {
return &self.memo;
}
/// Returns the optional block time while preserving omitted/null/value wire states.
#[must_use]
pub const fn block_time(&self) -> &crate::SolanaWireField<i64> {
return &self.block_time;
}
/// Returns the optional confirmation-status label while preserving omitted/null/value wire states.
#[must_use]
pub const fn confirmation_status(&self) -> &crate::SolanaWireField<std::string::String> {
return &self.confirmation_status;
}
}
#[cfg(test)]
fn decode_helius_transaction_unsubscribe_result(value: serde_json::Value) -> ksp_core_lib::Result<bool> {
return match value.as_bool() {
std::option::Option::Some(unsubscribed) => std::result::Result::Ok(unsubscribed),
std::option::Option::None => std::result::Result::Err(
ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "Helius transactionUnsubscribe acknowledgement must contain a boolean result")
.with_context("rpc_method", "transactionUnsubscribe"),
),
};
/// Typed Helius `transactionNotification` payload union.
///
/// `Full` also covers the provider `accounts` detail mode because both contain the nested `transaction` member. `Signature` covers the lightweight
/// signatures mode. `Unknown` preserves `none` mode and forward-compatible provider shapes instead of failing the logical subscription.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum HeliusTransactionNotification {
/// Full/accounts notification carrying the nested transaction payload.
Full(crate::HeliusFullTransactionNotification),
/// Lightweight signatures notification.
Signature(crate::HeliusTransactionSignatureNotification),
/// Provider shape not currently typed by KSP, preserved losslessly.
Unknown(serde_json::Value),
}
impl crate::HeliusLaserStreamWsSession {
/// Opens one Helius `transactionSubscribe` logical subscription through the shared physical actor.
///
/// The returned handle keeps a stable local identity across physical reconnects. Helius remote subscription IDs stay actor-private and are remapped after
/// resubscribe. Calling [`crate::WsSubscription::unsubscribe`] removes the remote mapping before sending `transactionUnsubscribe`, so provider messages
/// already in flight after cancellation are ignored without reactivating the logical subscription.
pub async fn transaction_subscribe(
&self,
request: &crate::HeliusTransactionSubscribeRequest,
) -> ksp_core_lib::Result<crate::WsSubscription<crate::HeliusTransactionNotification>> {
let params = helius_transaction_subscribe_params(request);
let params = match params {
std::result::Result::Ok(params) => params,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return self
.physical_session()
.subscribe_typed(crate::WsSubscriptionKind::HeliusTransaction, params, |value| return decode_helius_transaction_notification(value))
.await;
}
}
#[derive(serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct WireHeliusFullTransactionNotification {
transaction: serde_json::Value,
signature: std::string::String,
slot: u64,
transaction_index: u64,
}
#[derive(serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct WireHeliusTransactionSignatureNotification {
signature: std::string::String,
slot: u64,
transaction_index: u64,
#[serde(default)]
err: crate::SolanaWireField<serde_json::Value>,
#[serde(default)]
memo: crate::SolanaWireField<std::string::String>,
#[serde(default)]
block_time: crate::SolanaWireField<i64>,
#[serde(default)]
confirmation_status: crate::SolanaWireField<std::string::String>,
}
fn decode_helius_transaction_notification(value: serde_json::Value) -> ksp_core_lib::Result<crate::HeliusTransactionNotification> {
if value.get("transaction").is_some() {
let decoded = crate::decode_wire_json::<WireHeliusFullTransactionNotification>("transactionNotification", value.clone());
if let std::result::Result::Ok(decoded) = decoded {
return std::result::Result::Ok(crate::HeliusTransactionNotification::Full(crate::HeliusFullTransactionNotification {
transaction: decoded.transaction,
signature: decoded.signature,
slot: decoded.slot,
transaction_index: decoded.transaction_index,
}));
}
}
if value.get("signature").is_some() && value.get("slot").is_some() && value.get("transactionIndex").is_some() {
let decoded = crate::decode_wire_json::<WireHeliusTransactionSignatureNotification>("transactionNotification", value.clone());
if let std::result::Result::Ok(decoded) = decoded {
return std::result::Result::Ok(crate::HeliusTransactionNotification::Signature(crate::HeliusTransactionSignatureNotification {
signature: decoded.signature,
slot: decoded.slot,
transaction_index: decoded.transaction_index,
err: decoded.err,
memo: decoded.memo,
block_time: decoded.block_time,
confirmation_status: decoded.confirmation_status,
}));
}
}
return std::result::Result::Ok(crate::HeliusTransactionNotification::Unknown(value));
}
fn validate_account_list(field: &'static str, accounts: std::option::Option<&[ksp_core_lib::Pubkey]>) -> ksp_core_lib::Result<()> {
@@ -400,7 +544,6 @@ fn validate_account_list(field: &'static str, accounts: std::option::Option<&[ks
return std::result::Result::Ok(());
}
#[cfg(test)]
fn insert_account_list(
object: &mut serde_json::Map<std::string::String, serde_json::Value>,
field: &'static str,

22
crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
// version: 6
// version: 7
/// Stable local identity assigned to one physical WebSocket session.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
@@ -76,7 +76,7 @@ pub enum WsSubscriptionState {
Failed,
}
/// Standard Solana subscription family represented by one logical WebSocket subscription.
/// WebSocket subscription family represented by one logical subscription.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum WsSubscriptionKind {
@@ -98,10 +98,12 @@ pub enum WsSubscriptionKind {
SlotsUpdates,
/// `voteSubscribe` family.
Vote,
/// Helius LaserStream WebSocket `transactionSubscribe` extension family.
HeliusTransaction,
}
impl WsSubscriptionKind {
/// Returns the stable KSP descriptor for this standard subscription family.
/// Returns the stable KSP descriptor for this WebSocket subscription family.
#[must_use]
pub const fn as_str(self) -> &'static str {
return match self {
@@ -114,10 +116,11 @@ impl WsSubscriptionKind {
Self::Slot => "slot",
Self::SlotsUpdates => "slots_updates",
Self::Vote => "vote",
Self::HeliusTransaction => "helius_transaction",
};
}
/// Returns the exact standard Solana subscribe JSON-RPC method for this family.
/// Returns the exact subscribe JSON-RPC method for this family.
pub(crate) const fn subscribe_method(self) -> &'static str {
return match self {
Self::Account => "accountSubscribe",
@@ -129,10 +132,11 @@ impl WsSubscriptionKind {
Self::Slot => "slotSubscribe",
Self::SlotsUpdates => "slotsUpdatesSubscribe",
Self::Vote => "voteSubscribe",
Self::HeliusTransaction => "transactionSubscribe",
};
}
/// Returns the exact standard Solana unsubscribe JSON-RPC method for this family.
/// Returns the exact unsubscribe JSON-RPC method for this family.
pub(crate) const fn unsubscribe_method(self) -> &'static str {
return match self {
Self::Account => "accountUnsubscribe",
@@ -144,10 +148,11 @@ impl WsSubscriptionKind {
Self::Slot => "slotUnsubscribe",
Self::SlotsUpdates => "slotsUpdatesUnsubscribe",
Self::Vote => "voteUnsubscribe",
Self::HeliusTransaction => "transactionUnsubscribe",
};
}
/// Returns the exact standard Solana notification method emitted for this family.
/// Returns the exact notification method emitted for this family.
pub(crate) const fn notification_method(self) -> &'static str {
return match self {
Self::Account => "accountNotification",
@@ -159,10 +164,13 @@ impl WsSubscriptionKind {
Self::Slot => "slotNotification",
Self::SlotsUpdates => "slotsUpdatesNotification",
Self::Vote => "voteNotification",
Self::HeliusTransaction => "transactionNotification",
};
}
/// Returns whether Solana documents this standard subscription family as unstable.
///
/// Provider extensions are stable here unless explicitly classified otherwise.
pub(crate) const fn is_unstable(self) -> bool {
return matches!(self, Self::Block | Self::SlotsUpdates | Self::Vote);
}
@@ -211,7 +219,7 @@ impl WsSubscriptionSnapshot {
return self.id;
}
/// Returns the standard subscription family.
/// Returns the logical WebSocket subscription family.
#[must_use]
pub const fn kind(&self) -> crate::WsSubscriptionKind {
return self.kind;

8
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
// version: 3
// version: 4
/// Typed facade for one standard Solana WebSocket physical session.
///
@@ -58,9 +58,9 @@ impl std::fmt::Debug for SolanaStandardWsSession {
/// Typed facade for one Helius LaserStream WebSocket physical session.
///
/// The facade exposes the six standard Solana subscription families that Helius documents as supported. `0.2.8-pre.005` also publishes the typed Helius
/// transaction request/filter/options contract, but the live transaction-subscription method remains intentionally absent until `pre.006` integrates
/// `transactionNotification`, reconnect and unsubscribe races into the shared actor. No public inner handle is exposed, so callers cannot bypass the
/// The facade exposes the six standard Solana subscription families that Helius documents as supported plus the Helius-specific typed
/// `transactionSubscribe` lifecycle. Transaction notifications, reconnect/resubscribe, unsubscribe races and bounded backpressure all delegate to the same
/// shared [`crate::WsSession`] actor; the facade owns no second socket, registry or queue. No public inner handle is exposed, so callers cannot bypass the
/// provider-specific surface by recovering a generic [`crate::WsSession`].
///
/// ```compile_fail

12
crates/ksp-onchain-transport-lib/src/ws_subscription.rs
View File

@@ -1,7 +1,7 @@
// file: crates/ksp-onchain-transport-lib/src/ws_subscription.rs
// version: 5
// version: 6
/// Typed handle for one logical Solana WebSocket subscription.
/// Typed handle for one logical WebSocket subscription.
///
/// The handle owns the bounded typed notification receiver while the physical session actor owns the remote subscription identity and socket. The remote
/// numeric subscription identifier is intentionally never exposed because it is transient and is remapped by the session actor after reconnect.
@@ -43,7 +43,7 @@ impl<T> WsSubscription<T> {
return self.id;
}
/// Returns the standard Solana subscription family.
/// Returns the logical WebSocket subscription family.
#[must_use]
pub const fn kind(&self) -> crate::WsSubscriptionKind {
return self.kind;
@@ -71,7 +71,7 @@ impl<T> WsSubscription<T> {
return self.notification_rx.recv().await;
}
/// Cancels this logical subscription and sends the matching Solana unsubscribe request when a remote binding still exists.
/// Cancels this logical subscription and sends the matching protocol unsubscribe request when a remote binding still exists.
///
/// The returned boolean preserves the standard Solana unsubscribe result when the current remote binding is reachable. Local cancellation is terminal
/// for this handle; during reconnect it wins before resubscribe selection, and a late remote acknowledgement is cleaned up best-effort without
@@ -198,11 +198,11 @@ impl WsSubscriptionRegistration {
pub(crate) struct WsSubscriptionRuntime {
/// Stable local identity.
pub(crate) id: crate::WsSubscriptionId,
/// Standard Solana subscription family.
/// WebSocket subscription family.
pub(crate) kind: crate::WsSubscriptionKind,
/// Current logical lifecycle state.
pub(crate) state: crate::WsSubscriptionState,
/// Original standard subscribe parameters retained internally for deterministic resubscribe.
/// Original subscribe parameters retained internally for deterministic resubscribe.
pub(crate) params: std::vec::Vec<serde_json::Value>,
/// Current transient remote subscription identity when bound.
pub(crate) remote_id: std::option::Option<u64>,