khadhroony-solana-project/crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs

// file: crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
// version: 1

const MAX_HELIUS_TRANSACTION_FILTER_ACCOUNTS: usize = 50_000;

/// Helius `tokenAccounts` expansion mode accepted by `transactionSubscribe`.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum HeliusTokenAccountsFilter {
    /// Disable token-account owner expansion explicitly; equivalent to omitting `tokenAccounts`.
    None,
    /// Match transactions where a token balance owned by an included account changes or its token account closes.
    BalanceChanged,
    /// Match transactions referencing any token account owned by an included account, even if the balance does not change.
    All,
}

impl HeliusTokenAccountsFilter {
    /// Returns the exact Helius WebSocket wire string.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        return match self {
            Self::None => "none",
            Self::BalanceChanged => "balanceChanged",
            Self::All => "all",
        };
    }
}

/// Transaction encoding accepted by Helius `transactionSubscribe`.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum HeliusTransactionSubscribeEncoding {
    /// Base58 encoded transaction bytes.
    Base58,
    /// Base64 encoded transaction bytes.
    Base64,
    /// Parsed JSON transaction representation.
    JsonParsed,
}

impl HeliusTransactionSubscribeEncoding {
    /// Returns the exact Helius WebSocket wire string.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        return match self {
            Self::Base58 => "base58",
            Self::Base64 => "base64",
            Self::JsonParsed => "jsonParsed",
        };
    }
}

/// Helius-specific filter object accepted as the first `transactionSubscribe` parameter.
///
/// Debug output intentionally exposes only filter presence, modes and account counts. Transaction signatures and account values are omitted so routine
/// diagnostics cannot accidentally disclose the caller's complete provider filter payload.
#[derive(Clone, Default, Eq, PartialEq)]
pub struct HeliusTransactionSubscribeFilter {
    vote: std::option::Option<bool>,
    failed: std::option::Option<bool>,
    signature: std::option::Option<std::string::String>,
    account_include: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
    account_exclude: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
    account_required: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
    token_accounts: std::option::Option<crate::HeliusTokenAccountsFilter>,
}

impl HeliusTransactionSubscribeFilter {
    /// Creates a complete Helius transaction filter while preserving omitted versus explicitly empty account arrays.
    #[must_use]
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        vote: std::option::Option<bool>,
        failed: std::option::Option<bool>,
        signature: std::option::Option<std::string::String>,
        account_include: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
        account_exclude: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
        account_required: std::option::Option<std::vec::Vec<ksp_core_lib::Pubkey>>,
        token_accounts: std::option::Option<crate::HeliusTokenAccountsFilter>,
    ) -> Self {
        return Self { vote, failed, signature, account_include, account_exclude, account_required, token_accounts };
    }

    /// Returns the optional vote-transaction filter flag.
    #[must_use]
    pub const fn vote(&self) -> std::option::Option<bool> {
        return self.vote;
    }

    /// Returns the optional failed-transaction filter flag.
    #[must_use]
    pub const fn failed(&self) -> std::option::Option<bool> {
        return self.failed;
    }

    /// Returns the optional exact transaction signature filter.
    #[must_use]
    pub fn signature(&self) -> std::option::Option<&str> {
        return match self.signature.as_ref() {
            std::option::Option::Some(signature) => std::option::Option::Some(signature.as_str()),
            std::option::Option::None => std::option::Option::None,
        };
    }

    /// Returns the optional OR-style account inclusion list.
    #[must_use]
    pub fn account_include(&self) -> std::option::Option<&[ksp_core_lib::Pubkey]> {
        return match self.account_include.as_ref() {
            std::option::Option::Some(accounts) => std::option::Option::Some(accounts.as_slice()),
            std::option::Option::None => std::option::Option::None,
        };
    }

    /// Returns the optional account exclusion list.
    #[must_use]
    pub fn account_exclude(&self) -> std::option::Option<&[ksp_core_lib::Pubkey]> {
        return match self.account_exclude.as_ref() {
            std::option::Option::Some(accounts) => std::option::Option::Some(accounts.as_slice()),
            std::option::Option::None => std::option::Option::None,
        };
    }

    /// Returns the optional AND-style required-account list.
    #[must_use]
    pub fn account_required(&self) -> std::option::Option<&[ksp_core_lib::Pubkey]> {
        return match self.account_required.as_ref() {
            std::option::Option::Some(accounts) => std::option::Option::Some(accounts.as_slice()),
            std::option::Option::None => std::option::Option::None,
        };
    }

    /// Returns the optional Helius token-account owner-expansion mode.
    #[must_use]
    pub const fn token_accounts(&self) -> std::option::Option<crate::HeliusTokenAccountsFilter> {
        return self.token_accounts;
    }

    fn validate(&self) -> ksp_core_lib::Result<()> {
        let include = validate_account_list("accountInclude", self.account_include.as_deref());
        if let std::result::Result::Err(error) = include {
            return std::result::Result::Err(error);
        }
        let exclude = validate_account_list("accountExclude", self.account_exclude.as_deref());
        if let std::result::Result::Err(error) = exclude {
            return std::result::Result::Err(error);
        }
        let required = validate_account_list("accountRequired", self.account_required.as_deref());
        if let std::result::Result::Err(error) = required {
            return std::result::Result::Err(error);
        }
        return std::result::Result::Ok(());
    }

    fn to_json_value(&self) -> serde_json::Value {
        let mut object = serde_json::Map::new();
        if let std::option::Option::Some(vote) = self.vote {
            object.insert("vote".to_owned(), serde_json::Value::Bool(vote));
        }
        if let std::option::Option::Some(failed) = self.failed {
            object.insert("failed".to_owned(), serde_json::Value::Bool(failed));
        }
        if let std::option::Option::Some(signature) = self.signature.as_ref() {
            object.insert("signature".to_owned(), serde_json::Value::String(signature.clone()));
        }
        insert_account_list(&mut object, "accountInclude", self.account_include.as_deref());
        insert_account_list(&mut object, "accountExclude", self.account_exclude.as_deref());
        insert_account_list(&mut object, "accountRequired", self.account_required.as_deref());
        if let std::option::Option::Some(token_accounts) = self.token_accounts {
            object.insert("tokenAccounts".to_owned(), serde_json::Value::String(token_accounts.as_str().to_owned()));
        }
        return serde_json::Value::Object(object);
    }
}

impl std::fmt::Debug for HeliusTransactionSubscribeFilter {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter
            .debug_struct("HeliusTransactionSubscribeFilter")
            .field("vote", &self.vote)
            .field("failed", &self.failed)
            .field("signature_present", &self.signature.is_some())
            .field("account_include_count", &self.account_include.as_ref().map(std::vec::Vec::len))
            .field("account_exclude_count", &self.account_exclude.as_ref().map(std::vec::Vec::len))
            .field("account_required_count", &self.account_required.as_ref().map(std::vec::Vec::len))
            .field("token_accounts", &self.token_accounts)
            .finish();
    }
}

/// Optional Helius `transactionSubscribe` result-shaping configuration.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct HeliusTransactionSubscribeOptions {
    commitment: std::option::Option<crate::SolanaCommitment>,
    encoding: std::option::Option<crate::HeliusTransactionSubscribeEncoding>,
    transaction_details: std::option::Option<crate::SolanaTransactionDetails>,
    show_rewards: std::option::Option<bool>,
    max_supported_transaction_version: std::option::Option<u8>,
}

impl HeliusTransactionSubscribeOptions {
    /// Creates a complete optional Helius transaction-subscription configuration.
    #[must_use]
    pub const fn new(
        commitment: std::option::Option<crate::SolanaCommitment>,
        encoding: std::option::Option<crate::HeliusTransactionSubscribeEncoding>,
        transaction_details: std::option::Option<crate::SolanaTransactionDetails>,
        show_rewards: std::option::Option<bool>,
        max_supported_transaction_version: std::option::Option<u8>,
    ) -> Self {
        return Self { commitment, encoding, transaction_details, show_rewards, max_supported_transaction_version };
    }

    /// Returns the optional commitment level.
    #[must_use]
    pub const fn commitment(&self) -> std::option::Option<crate::SolanaCommitment> {
        return self.commitment;
    }

    /// Returns the optional Helius transaction encoding.
    #[must_use]
    pub const fn encoding(&self) -> std::option::Option<crate::HeliusTransactionSubscribeEncoding> {
        return self.encoding;
    }

    /// Returns the optional transaction detail level.
    #[must_use]
    pub const fn transaction_details(&self) -> std::option::Option<crate::SolanaTransactionDetails> {
        return self.transaction_details;
    }

    /// Returns whether rewards were explicitly requested.
    #[must_use]
    pub const fn show_rewards(&self) -> std::option::Option<bool> {
        return self.show_rewards;
    }

    /// Returns the highest transaction version the caller declares it can consume.
    #[must_use]
    pub const fn max_supported_transaction_version(&self) -> std::option::Option<u8> {
        return self.max_supported_transaction_version;
    }

    fn validate(&self) -> ksp_core_lib::Result<()> {
        let requires_version =
            matches!(self.transaction_details, std::option::Option::Some(crate::SolanaTransactionDetails::Full | crate::SolanaTransactionDetails::Accounts));
        if requires_version && self.max_supported_transaction_version.is_none() {
            let detail = match self.transaction_details {
                std::option::Option::Some(detail) => detail.as_str(),
                std::option::Option::None => "omitted",
            };
            return std::result::Result::Err(
                ksp_core_lib::Error::new(
                    crate::ERROR_CODE_INVALID_RPC_PARAMETERS,
                    "Helius transactionSubscribe requires maxSupportedTransactionVersion for full or accounts transaction details",
                )
                .with_context("rpc_method", "transactionSubscribe")
                .with_context("field", "maxSupportedTransactionVersion")
                .with_context("transaction_details", detail),
            );
        }
        return std::result::Result::Ok(());
    }

    fn to_json_value(self) -> serde_json::Value {
        let mut object = serde_json::Map::new();
        if let std::option::Option::Some(commitment) = self.commitment {
            object.insert("commitment".to_owned(), serde_json::Value::String(commitment.as_str().to_owned()));
        }
        if let std::option::Option::Some(encoding) = self.encoding {
            object.insert("encoding".to_owned(), serde_json::Value::String(encoding.as_str().to_owned()));
        }
        if let std::option::Option::Some(transaction_details) = self.transaction_details {
            object.insert("transactionDetails".to_owned(), serde_json::Value::String(transaction_details.as_str().to_owned()));
        }
        if let std::option::Option::Some(show_rewards) = self.show_rewards {
            object.insert("showRewards".to_owned(), serde_json::Value::Bool(show_rewards));
        }
        if let std::option::Option::Some(version) = self.max_supported_transaction_version {
            object.insert("maxSupportedTransactionVersion".to_owned(), serde_json::Value::Number(version.into()));
        }
        return serde_json::Value::Object(object);
    }
}

/// Complete typed request contract for Helius `transactionSubscribe` before actor registration.
///
/// 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.
#[derive(Clone, Eq, PartialEq)]
pub struct HeliusTransactionSubscribeRequest {
    filter: crate::HeliusTransactionSubscribeFilter,
    options: std::option::Option<crate::HeliusTransactionSubscribeOptions>,
}

impl HeliusTransactionSubscribeRequest {
    /// Creates one typed Helius transaction-subscription request.
    #[must_use]
    pub fn new(filter: crate::HeliusTransactionSubscribeFilter, options: std::option::Option<crate::HeliusTransactionSubscribeOptions>) -> Self {
        return Self { filter, options };
    }

    /// Returns the provider transaction filter.
    #[must_use]
    pub const fn filter(&self) -> &crate::HeliusTransactionSubscribeFilter {
        return &self.filter;
    }

    /// Returns the optional provider result-shaping configuration.
    #[must_use]
    pub const fn options(&self) -> std::option::Option<&crate::HeliusTransactionSubscribeOptions> {
        return self.options.as_ref();
    }

    /// Validates deterministic Helius request constraints before any WebSocket I/O.
    pub fn validate(&self) -> ksp_core_lib::Result<()> {
        let filter = self.filter.validate();
        if let std::result::Result::Err(error) = filter {
            return std::result::Result::Err(error);
        }
        if let std::option::Option::Some(options) = self.options {
            let options = options.validate();
            if let std::result::Result::Err(error) = options {
                return std::result::Result::Err(error);
            }
        }
        return std::result::Result::Ok(());
    }

    /// Builds the exact JSON-RPC params array after deterministic validation.
    #[allow(dead_code)] // Consumed by actor-owned transaction subscription registration in pre.006.
    pub(crate) fn to_params(&self) -> ksp_core_lib::Result<std::vec::Vec<serde_json::Value>> {
        let validation = self.validate();
        if let std::result::Result::Err(error) = validation {
            return std::result::Result::Err(error);
        }
        let mut params = std::vec![self.filter.to_json_value()];
        if let std::option::Option::Some(options) = self.options {
            params.push(options.to_json_value());
        }
        return std::result::Result::Ok(params);
    }
}

impl std::fmt::Debug for HeliusTransactionSubscribeRequest {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter.debug_struct("HeliusTransactionSubscribeRequest").field("filter", &self.filter).field("options", &self.options).finish();
    }
}

/// Returns the exact Helius transaction-subscribe JSON-RPC method name.
#[allow(dead_code)] // Consumed by actor-owned transaction subscription registration in pre.006.
pub(crate) const fn helius_transaction_subscribe_method() -> &'static str {
    return "transactionSubscribe";
}

/// Returns the exact Helius transaction-unsubscribe JSON-RPC method name.
#[allow(dead_code)] // Consumed by actor-owned transaction subscription cleanup in pre.006.
pub(crate) const fn helius_transaction_unsubscribe_method() -> &'static str {
    return "transactionUnsubscribe";
}

/// Decodes a successful Helius transaction-subscribe acknowledgement without exposing the remote ID publicly.
#[allow(dead_code)] // Consumed by actor-owned transaction subscription registration in pre.006.
pub(crate) 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"),
        ),
    };
}

/// Builds the exact Helius transaction-unsubscribe params array for one actor-owned remote subscription ID.
#[allow(dead_code)] // Consumed by actor-owned transaction subscription cleanup in pre.006.
pub(crate) fn helius_transaction_unsubscribe_params(remote_id: u64) -> std::vec::Vec<serde_json::Value> {
    return std::vec![serde_json::Value::Number(remote_id.into())];
}

/// Decodes the boolean Helius transaction-unsubscribe result.
#[allow(dead_code)] // Consumed by actor-owned transaction subscription cleanup in pre.006.
pub(crate) 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"),
        ),
    };
}

fn validate_account_list(field: &'static str, accounts: std::option::Option<&[ksp_core_lib::Pubkey]>) -> ksp_core_lib::Result<()> {
    if let std::option::Option::Some(accounts) = accounts
        && accounts.len() > MAX_HELIUS_TRANSACTION_FILTER_ACCOUNTS
    {
        return std::result::Result::Err(
            ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RPC_PARAMETERS, "Helius transactionSubscribe account filter exceeds the provider limit")
                .with_context("rpc_method", "transactionSubscribe")
                .with_context("field", field)
                .with_context("actual_count", accounts.len().to_string())
                .with_context("max_count", MAX_HELIUS_TRANSACTION_FILTER_ACCOUNTS.to_string()),
        );
    }
    return std::result::Result::Ok(());
}

fn insert_account_list(
    object: &mut serde_json::Map<std::string::String, serde_json::Value>,
    field: &'static str,
    accounts: std::option::Option<&[ksp_core_lib::Pubkey]>,
) {
    if let std::option::Option::Some(accounts) = accounts {
        let values = accounts.iter().map(|account| return serde_json::Value::String(account.to_string())).collect::<std::vec::Vec<_>>();
        object.insert(field.to_owned(), serde_json::Value::Array(values));
    }
    return;
}

#[cfg(test)]
#[path = "../unit_tests/ws_helius_transactions.rs"]
mod tests;