Files
khadhroony-solana-project/crates/ksp-onchain-transport-lib/src/lib.rs
2026-08-22 19:56:20 +02:00

373 lines
22 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// file: crates/ksp-onchain-transport-lib/src/lib.rs
// version: 24
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]
//! KSP-owned Solana on-chain transport foundation.
//!
//! This crate owns runtime HTTP transport settings, Solana HTTP JSON-RPC envelopes and the audited standard method registry. It deliberately remains
//! independent from `ksp-config-lib`, Store and Program layers. `ksp-config-lib` now constructs these public settings through its one-way Config ->
//! Transport adapter without creating a reverse dependency. Logical endpoint clients, priority-aware pools, bounded admission limits and retry/no-resend policy
//! are available. The four typed Solana HTTP foundation canaries plus all 22 typed `0.2.2` Accounts, Tokens and Cluster wrappers execute real JSON-RPC
//! requests through the shared transport path. `0.2.3` exposes its shared Transaction wire/config primitives and all eleven Transaction wrappers through
//! `pre.007`: eight reads, two write submissions with centralized no-resend protection, and retry-safe `simulateTransaction`, including complete
//! modern/legacy `getTransaction` coverage. `0.2.4` completes the HTTP surface with all ten Blocks and five Economics wrappers, including complete
//! modern/legacy `getBlock`, positional inflation rewards, runtime-provided economics values and the final `KSP-TRANSPORT-007` compliance target.
//! The candidate surface therefore exposes typed wrappers for all 52 current audited Solana HTTP methods while retaining 14 removed historical descriptors.
//! `0.2.7-pre.002` adds the provider-neutral WebSocket settings foundation, redacted endpoint URLs, explicit protocol-family discrimination, local session/subscription
//! identities, observable lifecycle states and safe snapshots. `0.2.7-pre.004` adds the first physical WebSocket runtime: bounded handshake, one actor-owned socket,
//! bounded command/pending JSON-RPC flow, safe session snapshots and deterministic local-server fixtures. `0.2.7-pre.005` adds explicit bounded shutdown,
//! request/frame/message adversarial limits, control-frame handling and pending-request cancellation/timeout cleanup. Subscription registration remains deferred.
mod client;
mod constants;
mod error;
mod executor;
mod json_rpc;
mod pool;
mod resilience;
mod rpc_accounts;
mod rpc_blocks;
mod rpc_canary;
mod rpc_cluster;
mod rpc_common;
mod rpc_economics;
mod rpc_method;
mod rpc_tokens;
mod rpc_transactions;
mod settings;
mod ws_lifecycle;
mod ws_session;
mod ws_settings;
mod ws_subscription;
/// Passive runtime availability reported for one logical HTTP endpoint.
pub use self::client::HttpEndpointAvailability;
/// Shareable logical HTTP endpoint client owned by KSP Transport.
pub use self::client::HttpEndpointClient;
/// Safe routing snapshot for one configured endpoint role.
pub use self::client::HttpEndpointRoleSnapshot;
/// Safe metadata snapshot for one logical HTTP endpoint.
pub use self::client::HttpEndpointSnapshot;
/// Error code used when no logical endpoint can satisfy a request.
pub use self::error::ERROR_CODE_ENDPOINT_SELECTION_FAILED;
/// Error code used when an HTTP connection cannot be established.
pub use self::error::ERROR_CODE_HTTP_CONNECTION_FAILED;
/// Error code used when an HTTP request fails after connection establishment.
pub use self::error::ERROR_CODE_HTTP_REQUEST_FAILED;
/// Error code used when a decoded response cannot satisfy the expected KSP transport contract.
pub use self::error::ERROR_CODE_INVALID_RESPONSE;
/// Error code used when typed Solana RPC parameters violate a locally enforceable method contract.
pub use self::error::ERROR_CODE_INVALID_RPC_PARAMETERS;
/// Error code used when HTTP transport runtime settings are invalid.
pub use self::error::ERROR_CODE_INVALID_SETTINGS;
/// Error code used when an HTTP JSON-RPC payload cannot be decoded as JSON.
pub use self::error::ERROR_CODE_JSON_DECODE_FAILED;
/// Error code used when a JSON-RPC request cannot be encoded.
pub use self::error::ERROR_CODE_JSON_ENCODE_FAILED;
/// Error code used when a decoded JSON-RPC envelope violates protocol invariants.
pub use self::error::ERROR_CODE_JSON_RPC_PROTOCOL_INVALID;
/// Error code used when a historically documented RPC method has been removed from the targeted runtime.
pub use self::error::ERROR_CODE_METHOD_REMOVED;
/// Error code used when an endpoint or provider rate-limits a request.
pub use self::error::ERROR_CODE_RATE_LIMITED;
/// Error code used when a remote endpoint returns an application-level JSON-RPC error.
pub use self::error::ERROR_CODE_RPC_APPLICATION_ERROR;
/// Error code used when a transport deadline expires.
pub use self::error::ERROR_CODE_TIMEOUT;
/// Error code used when bounded WebSocket runtime capacity is exhausted.
pub use self::error::ERROR_CODE_WS_BACKPRESSURE_OVERFLOW;
/// Error code used when a physical WebSocket connection or handshake fails.
pub use self::error::ERROR_CODE_WS_CONNECTION_FAILED;
/// Error code used when WebSocket wire data violates protocol invariants.
pub use self::error::ERROR_CODE_WS_PROTOCOL_ERROR;
/// Error code used when a WebSocket session is no longer available.
pub use self::error::ERROR_CODE_WS_SESSION_CLOSED;
/// JSON-RPC 2.0 error payload returned by a remote Solana endpoint.
pub use self::json_rpc::JsonRpcErrorObject;
/// Validated JSON-RPC 2.0 error response.
pub use self::json_rpc::JsonRpcErrorResponse;
/// JSON-RPC 2.0 HTTP request envelope emitted by KSP.
pub use self::json_rpc::JsonRpcRequest;
/// Validated JSON-RPC 2.0 HTTP response.
pub use self::json_rpc::JsonRpcResponse;
/// Validated JSON-RPC 2.0 success response.
pub use self::json_rpc::JsonRpcSuccessResponse;
/// Parses and validates a JSON-RPC HTTP response from UTF-8 JSON text.
pub use self::json_rpc::parse_json_rpc_response_text;
/// Validates a decoded JSON value as one JSON-RPC HTTP response.
pub use self::json_rpc::parse_json_rpc_response_value;
/// Result of one logical endpoint selection.
pub use self::pool::HttpEndpointSelection;
/// Runtime admission permit for one HTTP request.
pub use self::pool::HttpRequestPermit;
/// Shareable logical HTTP endpoint pool with priority routing, admission limits and bounded deadlines.
pub use self::pool::HttpTransportPool;
/// Safe snapshot of the logical HTTP endpoint pool.
pub use self::pool::HttpTransportPoolSnapshot;
/// Dispatch knowledge used to prevent ambiguous automatic resubmission.
pub use self::resilience::HttpDispatchState;
/// Transport-level cause considered by the bounded retry policy.
pub use self::resilience::HttpRetryCause;
/// Result of evaluating one bounded transport retry opportunity.
pub use self::resilience::HttpRetryDecision;
/// Evaluates the centralized bounded HTTP retry policy for one audited RPC method.
pub use self::resilience::evaluate_transport_retry;
/// Typed transport-level Solana account without Program/SPL decoding.
pub use self::rpc_accounts::SolanaAccount;
/// Address and lamport balance returned by `getLargestAccounts`.
pub use self::rpc_accounts::SolanaAccountBalance;
/// Wire-preserving account data returned by Solana HTTP account methods.
pub use self::rpc_accounts::SolanaAccountData;
/// Account-data encoding accepted by Solana HTTP account methods.
pub use self::rpc_accounts::SolanaAccountEncoding;
/// Shared account configuration used by account-info and token-account list methods.
pub use self::rpc_accounts::SolanaAccountInfoConfig;
/// Byte range requested from account data without decoding it locally.
pub use self::rpc_accounts::SolanaDataSliceConfig;
/// One public key plus its account returned by account-list RPC methods.
pub use self::rpc_accounts::SolanaKeyedAccount;
/// Optional configuration for `getLargestAccounts`.
pub use self::rpc_accounts::SolanaLargestAccountsConfig;
/// Filter accepted by `getLargestAccounts`.
pub use self::rpc_accounts::SolanaLargestAccountsFilter;
/// Bytes used by a `memcmp` program-account filter.
pub use self::rpc_accounts::SolanaMemcmpBytes;
/// One `memcmp` filter applied to account data.
pub use self::rpc_accounts::SolanaMemcmpFilter;
/// Parsed account payload returned by the RPC node for `jsonParsed` account data.
pub use self::rpc_accounts::SolanaParsedAccountData;
/// Filter accepted by the current `getProgramAccounts` implementation.
pub use self::rpc_accounts::SolanaProgramAccountFilter;
/// Configuration for `getProgramAccounts`.
pub use self::rpc_accounts::SolanaProgramAccountsConfig;
/// Result union returned by `getProgramAccounts` with or without an RPC context.
pub use self::rpc_accounts::SolanaProgramAccountsResult;
/// Commitment distribution returned by `getBlockCommitment`.
pub use self::rpc_blocks::SolanaBlockCommitment;
/// Block-production counts returned by `getBlockProduction` before the shared RPC context wrapper is applied.
pub use self::rpc_blocks::SolanaBlockProduction;
/// Optional configuration accepted by `getBlockProduction`.
pub use self::rpc_blocks::SolanaBlockProductionConfig;
/// Slot range accepted inside `getBlockProduction` configuration.
pub use self::rpc_blocks::SolanaBlockProductionRange;
/// Effective range reported inside `getBlockProduction` results.
pub use self::rpc_blocks::SolanaBlockProductionResultRange;
/// One reward entry returned in a confirmed block.
pub use self::rpc_blocks::SolanaBlockReward;
/// One transaction entry returned inside a confirmed block.
pub use self::rpc_blocks::SolanaBlockTransaction;
/// Confirmed block wire result returned by `getBlock` when the RPC result is non-null.
pub use self::rpc_blocks::SolanaConfirmedBlock;
/// Modern configuration object accepted by `getBlock`.
pub use self::rpc_blocks::SolanaGetBlockConfig;
/// One entry returned by `getRecentPerformanceSamples`.
pub use self::rpc_blocks::SolanaPerformanceSample;
/// Transaction detail level accepted by modern `getBlock` requests.
pub use self::rpc_blocks::SolanaTransactionDetails;
/// Optional typed configuration for the `getBalance` canary.
pub use self::rpc_canary::GetBalanceConfig;
/// Typed lamport balance returned by the `getBalance` canary.
pub use self::rpc_canary::GetBalanceResult;
/// Typed genesis hash returned by the `getGenesisHash` canary.
pub use self::rpc_canary::SolanaGenesisHash;
/// Typed healthy result returned by the `getHealth` canary.
pub use self::rpc_canary::SolanaNodeHealth;
/// Typed software-version response returned by the `getVersion` canary.
pub use self::rpc_canary::SolanaNodeVersion;
/// Contact information returned for one cluster node.
pub use self::rpc_cluster::SolanaClusterNode;
/// Epoch-credit history entry returned by `getVoteAccounts`.
pub use self::rpc_cluster::SolanaEpochCredits;
/// Epoch information returned by `getEpochInfo`.
pub use self::rpc_cluster::SolanaEpochInfo;
/// Epoch schedule returned by `getEpochSchedule`.
pub use self::rpc_cluster::SolanaEpochSchedule;
/// Leader schedule mapping validator identities to relative epoch slot indices.
pub use self::rpc_cluster::SolanaLeaderSchedule;
/// Optional configuration accepted by `getLeaderSchedule`.
pub use self::rpc_cluster::SolanaLeaderScheduleConfig;
/// Typed parameter overload for `getLeaderSchedule`.
pub use self::rpc_cluster::SolanaLeaderScheduleRequest;
/// Highest full and optional incremental snapshot slots returned by `getHighestSnapshotSlot`.
pub use self::rpc_cluster::SolanaSnapshotSlotInfo;
/// One validator vote-account record returned by `getVoteAccounts`.
pub use self::rpc_cluster::SolanaVoteAccountInfo;
/// Current and delinquent validator vote-account groups returned by `getVoteAccounts`.
pub use self::rpc_cluster::SolanaVoteAccountStatus;
/// Configuration accepted by `getVoteAccounts`.
pub use self::rpc_cluster::SolanaVoteAccountsConfig;
/// Commitment level accepted by typed Solana HTTP RPC adapters.
pub use self::rpc_common::SolanaCommitment;
/// Optional commitment-only configuration shared by typed Solana HTTP RPC methods.
pub use self::rpc_common::SolanaCommitmentConfig;
/// Optional commitment and minimum-context configuration shared by typed Solana HTTP RPC methods.
pub use self::rpc_common::SolanaContextConfig;
/// Typed Solana RPC context shared by contextual HTTP responses.
pub use self::rpc_common::SolanaRpcContext;
/// Generic contextual result returned by typed Solana HTTP RPC adapters.
pub use self::rpc_common::SolanaRpcResponse;
/// Inflation-governor values returned by `getInflationGovernor`.
pub use self::rpc_economics::SolanaInflationGovernor;
/// Current inflation-rate values returned by `getInflationRate`.
pub use self::rpc_economics::SolanaInflationRate;
/// One non-null positional reward returned by `getInflationReward`.
pub use self::rpc_economics::SolanaInflationReward;
/// Optional epoch/context configuration accepted by `getInflationReward`.
pub use self::rpc_economics::SolanaInflationRewardConfig;
/// Supply totals returned inside the contextual `getSupply` response.
pub use self::rpc_economics::SolanaSupply;
/// Optional configuration accepted by `getSupply`.
pub use self::rpc_economics::SolanaSupplyConfig;
/// Functional category used by the audited Solana HTTP JSON-RPC registry.
pub use self::rpc_method::HttpRpcCategory;
/// Release that owns typed KSP coverage for one audited HTTP RPC method.
pub use self::rpc_method::HttpRpcCoverageRelease;
/// Immutable audited descriptor for one Solana HTTP JSON-RPC method.
pub use self::rpc_method::HttpRpcMethodDescriptor;
/// Documentation lifecycle status of one audited RPC method.
pub use self::rpc_method::RpcDocumentationStatus;
/// Technical operation kind used to separate reads, simulations and submissions.
pub use self::rpc_method::RpcOperationKind;
/// Request-form policy attached to a stable RPC method.
pub use self::rpc_method::RpcRequestFormStatus;
/// Runtime availability status of one audited RPC method.
pub use self::rpc_method::RpcRuntimeStatus;
/// HTTP transport retry classification attached to an RPC method descriptor.
pub use self::rpc_method::TransportRetryClass;
/// Returns all current Solana HTTP RPC method descriptors audited for the `0.2.1``0.2.4` coverage sequence.
pub use self::rpc_method::current_http_rpc_methods;
/// Finds a current or historical standard Solana HTTP RPC descriptor by exact method name.
pub use self::rpc_method::find_http_rpc_method;
/// Returns historically documented deprecated HTTP RPC descriptors retained for compliance history.
pub use self::rpc_method::historical_http_rpc_methods;
/// Token-account balance entry returned by `getTokenLargestAccounts`.
pub use self::rpc_tokens::SolanaTokenAccountBalance;
/// Exclusive selector accepted by token-account list RPC methods.
pub use self::rpc_tokens::SolanaTokenAccountSelector;
/// Token amount returned by Solana HTTP token RPC methods.
pub use self::rpc_tokens::SolanaTokenAmount;
/// Confirmed transaction result returned by `getTransaction` when the RPC result is non-null.
pub use self::rpc_transactions::SolanaConfirmedTransaction;
/// Wire-preserving transaction payload returned by `getTransaction`.
pub use self::rpc_transactions::SolanaEncodedTransaction;
/// Modern configuration object accepted by `getTransaction`.
pub use self::rpc_transactions::SolanaGetTransactionConfig;
/// Blockhash information returned by `getLatestBlockhash` and optionally by simulation.
pub use self::rpc_transactions::SolanaLatestBlockhash;
/// One recent prioritization-fee sample returned by `getRecentPrioritizationFees`.
pub use self::rpc_transactions::SolanaPrioritizationFee;
/// Configuration accepted by `requestAirdrop`.
pub use self::rpc_transactions::SolanaRequestAirdropConfig;
/// Configuration accepted by `sendTransaction` without changing KSP transport retry semantics.
pub use self::rpc_transactions::SolanaSendTransactionConfig;
/// One ordered signature record returned by `getSignaturesForAddress`.
pub use self::rpc_transactions::SolanaSignatureInfo;
/// One non-null position returned by `getSignatureStatuses`.
pub use self::rpc_transactions::SolanaSignatureStatus;
/// Optional historical-search configuration accepted by `getSignatureStatuses`.
pub use self::rpc_transactions::SolanaSignatureStatusesConfig;
/// Pagination and context configuration accepted by `getSignaturesForAddress`.
pub use self::rpc_transactions::SolanaSignaturesForAddressConfig;
/// Configuration accepted by `simulateTransaction`.
pub use self::rpc_transactions::SolanaSimulateTransactionConfig;
/// Rich result payload returned inside the contextual `simulateTransaction` response.
pub use self::rpc_transactions::SolanaSimulateTransactionResult;
/// Account-return configuration nested under `simulateTransaction`.
pub use self::rpc_transactions::SolanaSimulationAccountsConfig;
/// Binary encoding accepted for serialized transaction input payloads.
pub use self::rpc_transactions::SolanaTransactionBinaryEncoding;
/// Confirmation state reported for a signature or transaction status.
pub use self::rpc_transactions::SolanaTransactionConfirmationStatus;
/// Encoding accepted by `getTransaction`, including its retained legacy `binary` alias.
pub use self::rpc_transactions::SolanaTransactionEncoding;
/// Transaction version reported by `getTransaction` when the version field is present.
pub use self::rpc_transactions::SolanaTransactionVersion;
/// Three-state wire field used when Solana distinguishes omission from an explicit JSON `null`.
pub use self::rpc_transactions::SolanaWireField;
/// Open cluster or network descriptor used by HTTP endpoint settings.
pub use self::settings::HttpClusterName;
/// Runtime settings for one role declared by an HTTP endpoint.
pub use self::settings::HttpEndpointRoleSettings;
/// Runtime settings for one named Solana HTTP endpoint.
pub use self::settings::HttpEndpointSettings;
/// Runtime HTTP endpoint URL with redacted diagnostics.
pub use self::settings::HttpEndpointUrl;
/// Open provider descriptor used by HTTP endpoint settings.
pub use self::settings::HttpProviderName;
/// Open request-kind descriptor used by logical endpoint capabilities.
pub use self::settings::HttpRequestKind;
/// Bounded retry settings owned by the HTTP transport runtime.
pub use self::settings::HttpRetrySettings;
/// Local limits attached to one logical HTTP endpoint role.
pub use self::settings::HttpRoleLimits;
/// Open logical endpoint role descriptor.
pub use self::settings::HttpRoleName;
/// Complete runtime settings consumed by the Solana HTTP transport foundation.
pub use self::settings::HttpTransportSettings;
/// Stable local identity assigned to one physical WebSocket session.
pub use self::ws_lifecycle::WsSessionId;
/// Safe runtime snapshot for one physical WebSocket session.
pub use self::ws_lifecycle::WsSessionSnapshot;
/// Observable lifecycle state of one physical WebSocket session.
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.
pub use self::ws_lifecycle::WsSubscriptionKind;
/// Safe lifecycle projection for one logical WebSocket subscription.
pub use self::ws_lifecycle::WsSubscriptionSnapshot;
/// Observable lifecycle state of one logical WebSocket subscription.
pub use self::ws_lifecycle::WsSubscriptionState;
/// Shareable handle for one explicitly created physical WebSocket session.
pub use self::ws_session::WsSession;
/// Open cluster or network descriptor used by WebSocket endpoint settings.
pub use self::ws_settings::WsClusterName;
/// Runtime settings for one named WebSocket endpoint.
pub use self::ws_settings::WsEndpointSettings;
/// Runtime WebSocket endpoint URL with redacted diagnostics.
pub use self::ws_settings::WsEndpointUrl;
/// WebSocket protocol family understood by KSP Transport.
pub use self::ws_settings::WsProtocolKind;
/// Open provider descriptor used by WebSocket endpoint settings.
pub use self::ws_settings::WsProviderName;
/// Bounded reconnect settings owned by the WebSocket transport runtime.
pub use self::ws_settings::WsReconnectSettings;
/// Policy controlling logical resubscription after reconnect.
pub use self::ws_settings::WsResubscribePolicy;
/// Runtime limits and lifecycle settings for one physical WebSocket session.
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.
pub use self::ws_subscription::WsSubscription;
/// Owning tracing target for events emitted by the on-chain transport crate.
pub(crate) use self::constants::TRACING_TARGET;
/// Crate-internal `HttpConcurrencyPermit` state shared across the owning crate.
pub(crate) use self::resilience::HttpConcurrencyPermit;
/// Crate-internal `HttpRoleRuntime` state shared across the owning crate.
pub(crate) use self::resilience::HttpRoleRuntime;
/// Crate-internal `RoleAdmissionAttempt` variants used by the owning crate.
pub(crate) use self::resilience::RoleAdmissionAttempt;
/// Decodes one private serde wire type into the shared Transport error domain for typed RPC adapters.
pub(crate) use self::rpc_common::decode_wire_json;
/// Parses a base58 public key without echoing its wire value into diagnostics for typed RPC adapters.
pub(crate) use self::rpc_common::parse_wire_pubkey;
/// Validates endpoint settings.
pub(crate) use self::settings::validate_endpoint_settings;
/// Crate-internal command surface shared by the physical session and typed subscription handle.
pub(crate) use self::ws_session::WsSessionCommand;
/// Crate-internal notification dispatch result.
pub(crate) use self::ws_subscription::WsNotificationDispatchOutcome;
/// Crate-internal type-erased notification dispatcher.
pub(crate) use self::ws_subscription::WsNotificationDispatcher;
/// Crate-internal actor registration returned after subscribe acknowledgement.
pub(crate) use self::ws_subscription::WsSubscriptionRegistration;
/// Crate-internal actor-owned logical subscription runtime entry.
pub(crate) use self::ws_subscription::WsSubscriptionRuntime;
/// Crate-internal constructor for bounded typed notification channels.
pub(crate) use self::ws_subscription::typed_notification_channel;