261 lines
15 KiB
Rust
261 lines
15 KiB
Rust
// file: crates/ksp-onchain-transport-lib/src/lib.rs
|
||
// version: 13
|
||
#![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 its first four read wrappers:
|
||
//! `getFeeForMessage`, `getLatestBlockhash`, `getTransactionCount` and `isBlockhashValid`. The remaining seven Transaction wrappers and the `0.2.4` family
|
||
//! remain staged.
|
||
|
||
mod client;
|
||
mod constants;
|
||
mod error;
|
||
mod executor;
|
||
mod json_rpc;
|
||
mod pool;
|
||
mod resilience;
|
||
mod rpc_accounts;
|
||
mod rpc_canary;
|
||
mod rpc_cluster;
|
||
mod rpc_common;
|
||
mod rpc_method;
|
||
mod rpc_tokens;
|
||
mod rpc_transactions;
|
||
mod settings;
|
||
|
||
pub(crate) use self::constants::TRACING_TARGET;
|
||
|
||
/// 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;
|
||
/// 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;
|
||
/// 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;
|
||
/// 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;
|
||
/// 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;
|