v0.2.3-pre.003

This commit is contained in:
2026-08-18 11:35:51 +02:00
parent 1d37f04d63
commit 2a7f3e8f40
14 changed files with 687 additions and 12 deletions

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid param: unable to decode message"},"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":{"context":{"apiVersion":"4.2.1","slot":431000002},"value":null},"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":{"context":{"apiVersion":"4.2.1","slot":431000001},"value":5000},"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":{"context":{"apiVersion":"4.2.1","slot":431000004},"value":{"blockhash":"","lastValidBlockHeight":431123456}},"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":{"context":{"apiVersion":"4.2.1","slot":431000003},"value":{"blockhash":"11111111111111111111111111111111","lastValidBlockHeight":431123456}},"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":987654321,"id":1}

View File

@@ -0,0 +1 @@
{"jsonrpc":"2.0","result":{"context":{"apiVersion":"4.2.1","slot":431000005},"value":true},"id":1}

View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/lib.rs
// version: 12
// version: 13
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]
@@ -10,8 +10,9 @@
//! 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` now exposes its shared Transaction wire/config primitives while its 11 typed wrappers remain staged;
//! the `0.2.4` family remains fully staged.
//! 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;

View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
// version: 2
// version: 3
/// Binary encoding accepted for serialized transaction input payloads.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
@@ -617,7 +617,6 @@ impl SolanaLatestBlockhash {
}
/// Decodes a latest-blockhash object from the Solana JSON wire shape.
#[cfg(test)]
pub(crate) fn decode_wire(method: &str, value: serde_json::Value) -> ksp_core_lib::Result<Self> {
let decoded = crate::decode_wire_json::<WireLatestBlockhash>(method, value);
let wire = match decoded {
@@ -1103,7 +1102,157 @@ impl SolanaSimulateTransactionResult {
}
}
#[cfg(test)]
impl crate::HttpTransportPool {
/// Executes typed `getFeeForMessage` through the common KSP HTTP transport path.
pub async fn get_fee_for_message(
&self,
role: &crate::HttpRoleName,
message_base64: &str,
config: std::option::Option<&crate::SolanaContextConfig>,
) -> ksp_core_lib::Result<crate::SolanaRpcResponse<std::option::Option<u64>>> {
let mut params = std::vec![serde_json::Value::String(message_base64.to_owned())];
push_transaction_context_config(&mut params, config);
let value = self.execute_transaction_rpc("getFeeForMessage", role, params).await;
let value = match value {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let contextual = decode_transaction_contextual_wire("getFeeForMessage", value);
let (context, value) = match contextual {
std::result::Result::Ok(contextual) => contextual,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let fee = crate::decode_wire_json::<std::option::Option<u64>>("getFeeForMessage", value);
return match fee {
std::result::Result::Ok(fee) => std::result::Result::Ok(crate::SolanaRpcResponse::new(context, fee)),
std::result::Result::Err(error) => std::result::Result::Err(error),
};
}
/// Executes typed `getLatestBlockhash` through the common KSP HTTP transport path.
pub async fn get_latest_blockhash(
&self,
role: &crate::HttpRoleName,
config: std::option::Option<&crate::SolanaContextConfig>,
) -> ksp_core_lib::Result<crate::SolanaRpcResponse<crate::SolanaLatestBlockhash>> {
let mut params = std::vec::Vec::new();
push_transaction_context_config(&mut params, config);
let value = self.execute_transaction_rpc("getLatestBlockhash", role, params).await;
let value = match value {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let contextual = decode_transaction_contextual_wire("getLatestBlockhash", value);
let (context, value) = match contextual {
std::result::Result::Ok(contextual) => contextual,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let blockhash = crate::SolanaLatestBlockhash::decode_wire("getLatestBlockhash", value);
return match blockhash {
std::result::Result::Ok(blockhash) => std::result::Result::Ok(crate::SolanaRpcResponse::new(context, blockhash)),
std::result::Result::Err(error) => std::result::Result::Err(error),
};
}
/// Executes typed `getTransactionCount` through the common KSP HTTP transport path.
pub async fn get_transaction_count(
&self,
role: &crate::HttpRoleName,
config: std::option::Option<&crate::SolanaContextConfig>,
) -> ksp_core_lib::Result<u64> {
let mut params = std::vec::Vec::new();
push_transaction_context_config(&mut params, config);
let value = self.execute_transaction_rpc("getTransactionCount", role, params).await;
return match value {
std::result::Result::Ok(value) => crate::decode_wire_json::<u64>("getTransactionCount", value),
std::result::Result::Err(error) => std::result::Result::Err(error),
};
}
/// Executes typed `isBlockhashValid` through the common KSP HTTP transport path.
pub async fn is_blockhash_valid(
&self,
role: &crate::HttpRoleName,
blockhash: &str,
config: std::option::Option<&crate::SolanaContextConfig>,
) -> ksp_core_lib::Result<crate::SolanaRpcResponse<bool>> {
let mut params = std::vec![serde_json::Value::String(blockhash.to_owned())];
push_transaction_context_config(&mut params, config);
let value = self.execute_transaction_rpc("isBlockhashValid", role, params).await;
let value = match value {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let contextual = decode_transaction_contextual_wire("isBlockhashValid", value);
let (context, value) = match contextual {
std::result::Result::Ok(contextual) => contextual,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let valid = crate::decode_wire_json::<bool>("isBlockhashValid", value);
return match valid {
std::result::Result::Ok(valid) => std::result::Result::Ok(crate::SolanaRpcResponse::new(context, valid)),
std::result::Result::Err(error) => std::result::Result::Err(error),
};
}
async fn execute_transaction_rpc(
&self,
method_name: &'static str,
role: &crate::HttpRoleName,
params: std::vec::Vec<serde_json::Value>,
) -> ksp_core_lib::Result<serde_json::Value> {
let method = transaction_descriptor(method_name);
let method = match method {
std::result::Result::Ok(method) => method,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return self.execute_standard_rpc(role, method, params).await;
}
}
fn push_transaction_context_config(params: &mut std::vec::Vec<serde_json::Value>, config: std::option::Option<&crate::SolanaContextConfig>) {
if let std::option::Option::Some(config) = config
&& (config.commitment().is_some() || config.min_context_slot().is_some())
{
params.push((*config).to_json_value());
}
return;
}
fn decode_transaction_contextual_wire(method: &str, value: serde_json::Value) -> ksp_core_lib::Result<(crate::SolanaRpcContext, serde_json::Value)> {
let decoded = crate::decode_wire_json::<WireTransactionRpcResponse>(method, value);
let wire = match decoded {
std::result::Result::Ok(wire) => wire,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let context = crate::SolanaRpcContext::decode_wire(method, wire.context);
return match context {
std::result::Result::Ok(context) => std::result::Result::Ok((context, wire.value)),
std::result::Result::Err(error) => std::result::Result::Err(error),
};
}
fn transaction_descriptor(method: &str) -> ksp_core_lib::Result<&'static crate::HttpRpcMethodDescriptor> {
let descriptor = crate::find_http_rpc_method(method);
return match descriptor {
std::option::Option::Some(descriptor)
if descriptor.category() == crate::HttpRpcCategory::Transactions && descriptor.coverage_release() == crate::HttpRpcCoverageRelease::V0_2_3 =>
{
std::result::Result::Ok(descriptor)
},
_ => std::result::Result::Err(
ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "typed Transaction descriptor is missing or misclassified in the audited registry")
.with_context("rpc_method", method),
),
};
}
#[derive(serde::Deserialize)]
struct WireTransactionRpcResponse {
context: serde_json::Value,
value: serde_json::Value,
}
fn invalid_transaction_wire(method: &str, field: &str, message: &'static str) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, message).with_context("rpc_method", method).with_context("field", field);
}
@@ -1230,7 +1379,6 @@ fn decode_replacement_blockhash_field(
};
}
#[cfg(test)]
#[derive(serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct WireLatestBlockhash {

View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/tests/public_api.rs
// version: 10
// version: 11
//! Integration tests for the public `ksp-onchain-transport-lib` consumer contract.
@@ -270,3 +270,11 @@ fn public_transaction_pre_002_shared_types_are_constructible_from_crate_root() {
assert_eq!(pagination.limit(), std::option::Option::Some(10));
assert!(ksp_onchain_transport_lib::SolanaWireField::<u64>::Omitted.is_omitted());
}
#[test]
fn public_transaction_pre_003_read_wrappers_are_available_from_crate_root() {
let _get_fee_for_message = ksp_onchain_transport_lib::HttpTransportPool::get_fee_for_message;
let _get_latest_blockhash = ksp_onchain_transport_lib::HttpTransportPool::get_latest_blockhash;
let _get_transaction_count = ksp_onchain_transport_lib::HttpTransportPool::get_transaction_count;
let _is_blockhash_valid = ksp_onchain_transport_lib::HttpTransportPool::is_blockhash_valid;
}

View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/tests/release_completeness.rs
// version: 7
// version: 8
//! Release-level completeness canaries for the `0.2.1` HTTP foundation contract.
@@ -241,3 +241,21 @@ fn release_v0_2_3_descriptor_set_and_safety_classes_are_exact_before_wrapper_com
assert_eq!(writes, 2);
assert_eq!(simulations, 1);
}
#[test]
fn release_pre_003_transaction_read_subset_is_exact_and_retry_safe() {
let mut expected = std::vec!["getFeeForMessage", "getLatestBlockhash", "getTransactionCount", "isBlockhashValid"];
let mut actual = std::vec::Vec::new();
for method_name in &expected {
let descriptor = ksp_onchain_transport_lib::find_http_rpc_method(method_name).expect("pre.003 Transaction descriptor must exist");
actual.push(descriptor.method());
assert_eq!(descriptor.category(), ksp_onchain_transport_lib::HttpRpcCategory::Transactions);
assert_eq!(descriptor.coverage_release(), ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_3);
assert_eq!(descriptor.operation_kind(), ksp_onchain_transport_lib::RpcOperationKind::Read);
assert_eq!(descriptor.transport_retry_class(), ksp_onchain_transport_lib::TransportRetryClass::RetrySafe);
}
actual.sort_unstable();
expected.sort_unstable();
assert_eq!(actual, expected);
assert_eq!(actual.len(), 4);
}

View File

@@ -1,5 +1,5 @@
// file: crates/ksp-onchain-transport-lib/unit_tests/rpc_transactions.rs
// version: 2
// version: 3
#[test]
fn transaction_encoding_strings_match_current_and_legacy_wire_labels() {
@@ -288,3 +288,185 @@ fn simulation_result_distinguishes_omitted_from_explicit_null_fields() {
assert!(result.replacement_blockhash().is_omitted());
assert!(result.loaded_addresses().is_omitted());
}
fn transaction_pool_for_url(url: &str) -> crate::HttpTransportPool {
let role = crate::HttpEndpointRoleSettings::new(
crate::HttpRoleName::new("default"),
true,
std::vec![crate::HttpRequestKind::wildcard()],
10,
crate::HttpRoleLimits::new(std::option::Option::None, std::option::Option::None, std::option::Option::None, std::option::Option::None),
);
let endpoint = crate::HttpEndpointSettings::new(
"fixture",
true,
crate::HttpProviderName::new("fixture"),
crate::HttpClusterName::new("local"),
crate::HttpEndpointUrl::parse(url).expect("fixture URL must parse"),
std::time::Duration::from_secs(1),
std::time::Duration::from_secs(1),
std::option::Option::Some(1),
std::vec![role],
);
let settings = crate::HttpTransportSettings::new(
std::vec![endpoint],
crate::HttpRetrySettings::new(0, std::time::Duration::from_millis(1), std::time::Duration::from_millis(1)),
);
return crate::HttpTransportPool::new(settings).expect("fixture pool must build");
}
fn serve_transaction_once(body: &'static str) -> (std::string::String, std::thread::JoinHandle<std::string::String>) {
let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("fixture listener must bind");
let address = listener.local_addr().expect("fixture listener address must resolve");
let handle = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("fixture server must accept one request");
let request = read_transaction_request(&mut stream);
let response = format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}", body.len(), body,);
std::io::Write::write_all(&mut stream, response.as_bytes()).expect("fixture response must write");
return request;
});
return (format!("http://{address}"), handle);
}
fn read_transaction_request(stream: &mut std::net::TcpStream) -> std::string::String {
let mut bytes = std::vec::Vec::new();
let mut buffer = [0_u8; 1024];
loop {
let count = std::io::Read::read(stream, &mut buffer).expect("fixture request must read");
if count == 0 {
break;
}
bytes.extend_from_slice(&buffer[..count]);
if transaction_request_complete(bytes.as_slice()) {
break;
}
}
return std::string::String::from_utf8(bytes).expect("fixture request must be UTF-8");
}
fn transaction_request_complete(bytes: &[u8]) -> bool {
let text = match std::str::from_utf8(bytes) {
std::result::Result::Ok(text) => text,
std::result::Result::Err(_) => return false,
};
let header_end = match text.find("\r\n\r\n") {
std::option::Option::Some(value) => value,
std::option::Option::None => return false,
};
let mut content_length = 0_usize;
for line in text[..header_end].lines() {
let (name, value) = match line.split_once(':') {
std::option::Option::Some(parts) => parts,
std::option::Option::None => continue,
};
if name.eq_ignore_ascii_case("content-length") {
content_length = value.trim().parse::<usize>().expect("content length must parse");
}
}
return bytes.len() >= header_end.saturating_add(4).saturating_add(content_length);
}
fn transaction_request_body(request: &str) -> serde_json::Value {
let body = request.split("\r\n\r\n").nth(1).expect("fixture request body must exist");
return serde_json::from_str(body).expect("fixture request body must be JSON");
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_fee_for_message_serializes_exact_params_and_decodes_contextual_fee() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_fee_for_message.success.json"));
let pool = transaction_pool_for_url(url.as_str());
let config = crate::SolanaContextConfig::new(std::option::Option::Some(crate::SolanaCommitment::Confirmed), std::option::Option::Some(431_000_000));
let response = pool
.get_fee_for_message(&crate::HttpRoleName::new("default"), "AQIDBA==", std::option::Option::Some(&config))
.await
.expect("getFeeForMessage fixture must succeed");
assert_eq!(response.context().slot(), 431_000_001);
assert_eq!(response.context().api_version(), std::option::Option::Some("4.2.1"));
assert_eq!(response.value(), &std::option::Option::Some(5_000));
let request = handle.join().expect("fixture server must join");
let body = transaction_request_body(request.as_str());
assert_eq!(body["method"], serde_json::json!("getFeeForMessage"));
assert_eq!(body["params"], serde_json::json!(["AQIDBA==", {"commitment":"confirmed","minContextSlot":431000000}]));
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_fee_for_message_preserves_null_and_omits_absent_config() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_fee_for_message.null.json"));
let pool = transaction_pool_for_url(url.as_str());
let response = pool
.get_fee_for_message(&crate::HttpRoleName::new("default"), "opaque-message", std::option::Option::None)
.await
.expect("null fee fixture must succeed");
assert_eq!(response.value(), &std::option::Option::None);
let request = handle.join().expect("fixture server must join");
assert_eq!(transaction_request_body(request.as_str())["params"], serde_json::json!(["opaque-message"]));
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_fee_for_message_preserves_rpc_application_error() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_fee_for_message.error.json"));
let pool = transaction_pool_for_url(url.as_str());
let result = pool.get_fee_for_message(&crate::HttpRoleName::new("default"), "not-decoded-locally", std::option::Option::None).await;
let error = result.expect_err("remote invalid message must remain an RPC application error");
assert_eq!(error.code(), crate::ERROR_CODE_RPC_APPLICATION_ERROR);
handle.join().expect("fixture server must join");
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_latest_blockhash_omits_empty_config_and_decodes_contextual_result() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_latest_blockhash.success.json"));
let pool = transaction_pool_for_url(url.as_str());
let config = crate::SolanaContextConfig::default();
let response = pool
.get_latest_blockhash(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config))
.await
.expect("getLatestBlockhash fixture must succeed");
assert_eq!(response.context().slot(), 431_000_003);
assert_eq!(response.value().blockhash(), "11111111111111111111111111111111");
assert_eq!(response.value().last_valid_block_height(), 431_123_456);
let request = handle.join().expect("fixture server must join");
assert_eq!(transaction_request_body(request.as_str())["params"], serde_json::json!([]));
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_latest_blockhash_rejects_empty_blockhash_from_http_response() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_latest_blockhash.invalid_empty.json"));
let pool = transaction_pool_for_url(url.as_str());
let result = pool.get_latest_blockhash(&crate::HttpRoleName::new("default"), std::option::Option::None).await;
let error = result.expect_err("empty latest blockhash must fail typed decoding");
assert_eq!(error.code(), crate::ERROR_CODE_INVALID_RESPONSE);
handle.join().expect("fixture server must join");
}
#[tokio::test(flavor = "current_thread")]
async fn typed_get_transaction_count_serializes_context_config_and_decodes_u64() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/get_transaction_count.success.json"));
let pool = transaction_pool_for_url(url.as_str());
let config = crate::SolanaContextConfig::new(std::option::Option::Some(crate::SolanaCommitment::Finalized), std::option::Option::None);
let count = pool
.get_transaction_count(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config))
.await
.expect("getTransactionCount fixture must succeed");
assert_eq!(count, 987_654_321);
let request = handle.join().expect("fixture server must join");
let body = transaction_request_body(request.as_str());
assert_eq!(body["method"], serde_json::json!("getTransactionCount"));
assert_eq!(body["params"], serde_json::json!([{"commitment":"finalized"}]));
}
#[tokio::test(flavor = "current_thread")]
async fn typed_is_blockhash_valid_preserves_opaque_blockhash_and_contextual_bool() {
let (url, handle) = serve_transaction_once(include_str!("../fixtures/http/is_blockhash_valid.success.json"));
let pool = transaction_pool_for_url(url.as_str());
let config = crate::SolanaContextConfig::new(std::option::Option::Some(crate::SolanaCommitment::Processed), std::option::Option::Some(431_000_004));
let response = pool
.is_blockhash_valid(&crate::HttpRoleName::new("default"), "opaque-blockhash", std::option::Option::Some(&config))
.await
.expect("isBlockhashValid fixture must succeed");
assert_eq!(response.context().slot(), 431_000_005);
assert_eq!(response.value(), &true);
let request = handle.join().expect("fixture server must join");
let body = transaction_request_body(request.as_str());
assert_eq!(body["method"], serde_json::json!("isBlockhashValid"));
assert_eq!(body["params"], serde_json::json!(["opaque-blockhash", {"commitment":"processed","minContextSlot":431000004}]));
}