From 4252a21140161834b986ffca719bcd5962593d28 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 18 Aug 2026 21:33:21 +0200 Subject: [PATCH] v0.2.4-pre.007 --- Cargo.toml | 4 +- .../http/get_inflation_governor.success.json | 1 + .../http/get_inflation_rate.success.json | 1 + ..._minimum_delegation.error_min_context.json | 1 + .../get_stake_minimum_delegation.success.json | 1 + .../fixtures/http/get_supply.error_scan.json | 1 + .../http/get_supply.excluded.success.json | 1 + .../fixtures/http/get_supply.success.json | 1 + .../src/rpc_economics.rs | 156 +++++- .../tests/public_api.rs | 17 +- .../tests/release_completeness.rs | 28 +- .../unit_tests/rpc_economics.rs | 225 ++++++++- deltas/0.2.4/pre.007.md | 475 ++++++++++++++++++ 13 files changed, 898 insertions(+), 14 deletions(-) create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_governor.success.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_rate.success.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.error_min_context.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.success.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_supply.error_scan.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_supply.excluded.success.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_supply.success.json create mode 100644 deltas/0.2.4/pre.007.md diff --git a/Cargo.toml b/Cargo.toml index e2a5fd2..349856e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 137 +# version: 138 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib"] [workspace.package] -version = "0.2.4-pre.6" +version = "0.2.4-pre.7" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_governor.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_governor.success.json new file mode 100644 index 0000000..647e1aa --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_governor.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":{"initial":0.07123456789,"terminal":0.0123456789,"taper":0.2718281828,"foundation":0.0042,"foundationTerm":6.25},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_rate.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_rate.success.json new file mode 100644 index 0000000..2583321 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_rate.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":{"total":0.0387654321,"validator":0.037654321,"foundation":0.0011111111,"epoch":913},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.error_min_context.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.error_min_context.json new file mode 100644 index 0000000..4486f1c --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.error_min_context.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","error":{"code":-32016,"message":"Minimum context slot has not been reached","data":{"contextSlot":430999999}},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.success.json new file mode 100644 index 0000000..85c638d --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":{"context":{"slot":431000123,"apiVersion":"4.2.1"},"value":42424242},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.error_scan.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.error_scan.json new file mode 100644 index 0000000..66139d9 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.error_scan.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","error":{"code":-32012,"message":"scan failed"},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.excluded.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.excluded.success.json new file mode 100644 index 0000000..36202f9 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.excluded.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":{"context":{"slot":431000125,"apiVersion":"4.2.1"},"value":{"total":610000000000000000,"circulating":510000000000000000,"nonCirculating":100000000000000000,"nonCirculatingAccounts":[]}},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.success.json new file mode 100644 index 0000000..077fdc2 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_supply.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":{"context":{"slot":431000124,"apiVersion":"4.2.1"},"value":{"total":610000000000000000,"circulating":510000000000000000,"nonCirculating":100000000000000000,"nonCirculatingAccounts":["11111111111111111111111111111111","Vote111111111111111111111111111111111111111"]}},"id":1} diff --git a/crates/ksp-onchain-transport-lib/src/rpc_economics.rs b/crates/ksp-onchain-transport-lib/src/rpc_economics.rs index 15c1642..798bd9e 100644 --- a/crates/ksp-onchain-transport-lib/src/rpc_economics.rs +++ b/crates/ksp-onchain-transport-lib/src/rpc_economics.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/src/rpc_economics.rs -// version: 2 +// version: 3 /// Inflation-governor values returned by `getInflationGovernor`. #[derive(Clone, Copy, Debug, PartialEq)] @@ -43,7 +43,6 @@ impl SolanaInflationGovernor { } /// Decodes an inflation-governor result from its Solana JSON wire shape. - #[cfg(test)] pub(crate) fn decode_wire(method: &str, value: serde_json::Value) -> ksp_core_lib::Result { let decoded = crate::decode_wire_json::(method, value); return match decoded { @@ -94,7 +93,6 @@ impl SolanaInflationRate { } /// Decodes an inflation-rate result from its Solana JSON wire shape. - #[cfg(test)] pub(crate) fn decode_wire(method: &str, value: serde_json::Value) -> ksp_core_lib::Result { let decoded = crate::decode_wire_json::(method, value); return match decoded { @@ -260,14 +258,12 @@ impl SolanaSupplyConfig { } /// Returns whether this config would serialize to an empty object. - #[cfg(test)] pub(crate) const fn is_empty(&self) -> bool { return self.commitment.is_none() && self.exclude_non_circulating_accounts_list.is_none(); } /// Serializes this config to the exact Solana JSON-RPC object. #[must_use] - #[cfg(test)] pub(crate) fn to_json_value(self) -> serde_json::Value { let mut object = serde_json::Map::new(); if let std::option::Option::Some(commitment) = self.commitment { @@ -315,7 +311,6 @@ impl SolanaSupply { } /// Decodes a supply result from its Solana JSON wire shape. - #[cfg(test)] pub(crate) fn decode_wire(method: &str, value: serde_json::Value) -> ksp_core_lib::Result { let decoded = crate::decode_wire_json::(method, value); let wire = match decoded { @@ -339,7 +334,152 @@ impl SolanaSupply { } } -#[cfg(test)] +impl crate::HttpTransportPool { + /// Executes typed `getInflationGovernor` and returns the runtime-provided schedule values unchanged. + pub async fn get_inflation_governor( + &self, + role: &crate::HttpRoleName, + config: std::option::Option<&crate::SolanaCommitmentConfig>, + ) -> ksp_core_lib::Result { + let mut params = std::vec::Vec::new(); + push_economics_commitment_config(&mut params, config); + let value = self.execute_economics_rpc("getInflationGovernor", role, params).await; + return match value { + std::result::Result::Ok(value) => crate::SolanaInflationGovernor::decode_wire("getInflationGovernor", value), + std::result::Result::Err(error) => std::result::Result::Err(error), + }; + } + + /// Executes typed `getInflationRate` without locally recalculating the inflation schedule. + pub async fn get_inflation_rate(&self, role: &crate::HttpRoleName) -> ksp_core_lib::Result { + let value = self.execute_economics_rpc("getInflationRate", role, std::vec::Vec::new()).await; + return match value { + std::result::Result::Ok(value) => crate::SolanaInflationRate::decode_wire("getInflationRate", value), + std::result::Result::Err(error) => std::result::Result::Err(error), + }; + } + + /// Executes typed `getStakeMinimumDelegation` and preserves the contextual runtime value in lamports. + pub async fn get_stake_minimum_delegation( + &self, + role: &crate::HttpRoleName, + config: std::option::Option<&crate::SolanaContextConfig>, + ) -> ksp_core_lib::Result> { + let mut params = std::vec::Vec::new(); + push_economics_context_config(&mut params, config); + let value = self.execute_economics_rpc("getStakeMinimumDelegation", role, params).await; + let value = match value { + std::result::Result::Ok(value) => value, + std::result::Result::Err(error) => return std::result::Result::Err(error), + }; + return decode_economics_u64_response("getStakeMinimumDelegation", value); + } + + /// Executes typed `getSupply`, preserving the explicit account-list exclusion flag and contextual totals. + pub async fn get_supply( + &self, + role: &crate::HttpRoleName, + config: std::option::Option<&crate::SolanaSupplyConfig>, + ) -> ksp_core_lib::Result> { + let mut params = std::vec::Vec::new(); + if let std::option::Option::Some(config) = config + && !config.is_empty() + { + params.push((*config).to_json_value()); + } + let value = self.execute_economics_rpc("getSupply", role, params).await; + let value = match value { + std::result::Result::Ok(value) => value, + std::result::Result::Err(error) => return std::result::Result::Err(error), + }; + return decode_supply_response("getSupply", value); + } + + async fn execute_economics_rpc( + &self, + method_name: &'static str, + role: &crate::HttpRoleName, + params: std::vec::Vec, + ) -> ksp_core_lib::Result { + let descriptor = economics_descriptor(method_name); + let descriptor = match descriptor { + std::result::Result::Ok(descriptor) => descriptor, + std::result::Result::Err(error) => return std::result::Result::Err(error), + }; + return self.execute_standard_rpc(role, descriptor, params).await; + } +} + +fn push_economics_commitment_config(params: &mut std::vec::Vec, config: std::option::Option<&crate::SolanaCommitmentConfig>) { + if let std::option::Option::Some(config) = config + && config.commitment().is_some() + { + params.push((*config).to_json_value()); + } + return; +} + +fn push_economics_context_config(params: &mut std::vec::Vec, 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_economics_u64_response(method: &str, value: serde_json::Value) -> ksp_core_lib::Result> { + let decoded = crate::decode_wire_json::>(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(crate::SolanaRpcResponse::new(context, wire.value)), + std::result::Result::Err(error) => std::result::Result::Err(error), + }; +} + +fn decode_supply_response(method: &str, value: serde_json::Value) -> ksp_core_lib::Result> { + let decoded = crate::decode_wire_json::>(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); + let context = match context { + std::result::Result::Ok(context) => context, + std::result::Result::Err(error) => return std::result::Result::Err(error), + }; + let supply = crate::SolanaSupply::decode_wire(method, wire.value); + return match supply { + std::result::Result::Ok(supply) => std::result::Result::Ok(crate::SolanaRpcResponse::new(context, supply)), + std::result::Result::Err(error) => std::result::Result::Err(error), + }; +} + +fn economics_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::Economics && descriptor.coverage_release() == crate::HttpRpcCoverageRelease::V0_2_4 => + { + std::result::Result::Ok(descriptor) + }, + _ => std::result::Result::Err( + ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "typed Economics descriptor is missing from the audited 0.2.4 registry") + .with_context("rpc_method", method), + ), + }; +} + +#[derive(serde::Deserialize)] +struct WireEconomicsRpcResponse { + context: serde_json::Value, + value: T, +} + #[derive(serde::Deserialize)] #[serde(rename_all = "camelCase")] struct WireInflationGovernor { @@ -350,7 +490,6 @@ struct WireInflationGovernor { foundation_term: f64, } -#[cfg(test)] #[derive(serde::Deserialize)] #[serde(rename_all = "camelCase")] struct WireInflationRate { @@ -374,7 +513,6 @@ struct WireInflationReward { commission_bps: crate::SolanaWireField, } -#[cfg(test)] #[derive(serde::Deserialize)] #[serde(rename_all = "camelCase")] struct WireSupply { diff --git a/crates/ksp-onchain-transport-lib/tests/public_api.rs b/crates/ksp-onchain-transport-lib/tests/public_api.rs index 8e3146b..9c46fc7 100644 --- a/crates/ksp-onchain-transport-lib/tests/public_api.rs +++ b/crates/ksp-onchain-transport-lib/tests/public_api.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/tests/public_api.rs -// version: 20 +// version: 21 //! Integration tests for the public `ksp-onchain-transport-lib` consumer contract. @@ -435,3 +435,18 @@ fn public_v0_2_4_pre_006_get_block_complete_request_forms_are_available_from_cra assert_eq!(config.max_supported_transaction_version(), std::option::Option::Some(1)); assert_eq!(config.rewards(), std::option::Option::Some(true)); } + +#[test] +fn public_v0_2_4_pre_007_simple_economics_wrappers_are_available_from_crate_root() { + let _get_inflation_governor = ksp_onchain_transport_lib::HttpTransportPool::get_inflation_governor; + let _get_inflation_rate = ksp_onchain_transport_lib::HttpTransportPool::get_inflation_rate; + let _get_stake_minimum_delegation = ksp_onchain_transport_lib::HttpTransportPool::get_stake_minimum_delegation; + let _get_supply = ksp_onchain_transport_lib::HttpTransportPool::get_supply; + + let supply_config = ksp_onchain_transport_lib::SolanaSupplyConfig::new( + std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Processed), + std::option::Option::Some(false), + ); + assert_eq!(supply_config.commitment(), std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Processed)); + assert_eq!(supply_config.exclude_non_circulating_accounts_list(), std::option::Option::Some(false)); +} diff --git a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs index f93b8a7..66a0dc1 100644 --- a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs +++ b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/tests/release_completeness.rs -// version: 18 +// version: 19 //! Release-level completeness canaries for the staged HTTP wrapper sequence. @@ -563,3 +563,29 @@ fn release_v0_2_4_pre_006_get_block_completes_all_ten_block_wrappers_with_legacy let get_block = ksp_onchain_transport_lib::find_http_rpc_method("getBlock").expect("getBlock descriptor must exist"); assert!(get_block.request_form_status().has_deprecated_legacy()); } + +#[test] +fn release_v0_2_4_pre_007_simple_economics_subset_is_exact_and_retry_safe() { + let mut expected = std::vec!["getInflationGovernor", "getInflationRate", "getStakeMinimumDelegation", "getSupply"]; + let mut actual = std::vec::Vec::new(); + for descriptor in ksp_onchain_transport_lib::current_http_rpc_methods() { + if descriptor.coverage_release() != ksp_onchain_transport_lib::HttpRpcCoverageRelease::V0_2_4 + || descriptor.category() != ksp_onchain_transport_lib::HttpRpcCategory::Economics + { + continue; + } + assert!(matches!( + descriptor.method(), + "getInflationGovernor" | "getInflationRate" | "getInflationReward" | "getStakeMinimumDelegation" | "getSupply" + )); + if descriptor.method() != "getInflationReward" { + assert_eq!(descriptor.operation_kind(), ksp_onchain_transport_lib::RpcOperationKind::Read); + assert_eq!(descriptor.transport_retry_class(), ksp_onchain_transport_lib::TransportRetryClass::RetrySafe); + actual.push(descriptor.method()); + } + } + actual.sort_unstable(); + expected.sort_unstable(); + assert_eq!(actual, expected); + assert_eq!(actual.len(), 4); +} diff --git a/crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs b/crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs index 1c56458..2db1c4c 100644 --- a/crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs +++ b/crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs @@ -1,5 +1,5 @@ // file: crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs -// version: 1 +// version: 2 #[test] fn inflation_reward_config_preserves_epoch_commitment_and_min_context_slot() { @@ -84,3 +84,226 @@ fn supply_rejects_invalid_non_circulating_pubkey_without_echoing_value() { assert_eq!(error.code(), crate::ERROR_CODE_INVALID_RESPONSE); assert!(!error.to_string().contains("invalid-pubkey")); } + +fn 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_once(body: &'static str) -> (std::string::String, std::thread::JoinHandle) { + 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_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_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 request_complete(bytes.as_slice()) { + break; + } + } + return std::string::String::from_utf8(bytes).expect("fixture request must be UTF-8"); +} + +fn 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::().expect("content length must parse"); + } + } + return bytes.len() >= header_end.saturating_add(4).saturating_add(content_length); +} + +fn 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_inflation_governor_serializes_processed_commitment_and_preserves_runtime_values() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_governor.success.json")); + let pool = pool_for_url(url.as_str()); + let config = crate::SolanaCommitmentConfig::new(std::option::Option::Some(crate::SolanaCommitment::Processed)); + let governor = pool + .get_inflation_governor(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config)) + .await + .expect("inflation governor fixture must succeed"); + assert_eq!(governor.initial(), 0.07123456789); + assert_eq!(governor.terminal(), 0.0123456789); + assert_eq!(governor.taper(), 0.2718281828); + assert_eq!(governor.foundation(), 0.0042); + assert_eq!(governor.foundation_term(), 6.25); + let request = handle.join().expect("fixture server must join"); + let body = request_body(request.as_str()); + assert_eq!(body["method"], serde_json::json!("getInflationGovernor")); + assert_eq!(body["params"], serde_json::json!([{"commitment":"processed"}])); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_governor_omits_absent_and_empty_config() { + let role = crate::HttpRoleName::new("default"); + let empty = crate::SolanaCommitmentConfig::default(); + for config in [std::option::Option::None, std::option::Option::Some(&empty)] { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_governor.success.json")); + let pool = pool_for_url(url.as_str()); + pool.get_inflation_governor(&role, config).await.expect("inflation governor fixture must succeed"); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([])); + } +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_rate_has_no_params_and_preserves_runtime_values() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_rate.success.json")); + let pool = pool_for_url(url.as_str()); + let rate = pool.get_inflation_rate(&crate::HttpRoleName::new("default")).await.expect("inflation rate fixture must succeed"); + assert_eq!(rate.total(), 0.0387654321); + assert_eq!(rate.validator(), 0.037654321); + assert_eq!(rate.foundation(), 0.0011111111); + assert_eq!(rate.epoch(), 913); + let request = handle.join().expect("fixture server must join"); + let body = request_body(request.as_str()); + assert_eq!(body["method"], serde_json::json!("getInflationRate")); + assert_eq!(body["params"], serde_json::json!([])); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_stake_minimum_delegation_preserves_context_and_runtime_value_without_local_minimum() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_stake_minimum_delegation.success.json")); + let pool = pool_for_url(url.as_str()); + let config = crate::SolanaContextConfig::new(std::option::Option::Some(crate::SolanaCommitment::Processed), std::option::Option::Some(431_000_000)); + let result = pool + .get_stake_minimum_delegation(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config)) + .await + .expect("stake minimum delegation fixture must succeed"); + assert_eq!(*result.value(), 42_424_242); + assert_eq!(result.context().slot(), 431_000_123); + assert_eq!(result.context().api_version(), std::option::Option::Some("4.2.1")); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([{"commitment":"processed","minContextSlot":431000000}])); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_stake_minimum_delegation_omits_absent_and_empty_config() { + let role = crate::HttpRoleName::new("default"); + let empty = crate::SolanaContextConfig::default(); + for config in [std::option::Option::None, std::option::Option::Some(&empty)] { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_stake_minimum_delegation.success.json")); + let pool = pool_for_url(url.as_str()); + pool.get_stake_minimum_delegation(&role, config).await.expect("stake minimum delegation fixture must succeed"); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([])); + } +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_supply_preserves_explicit_false_full_account_list_and_context() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_supply.success.json")); + let pool = pool_for_url(url.as_str()); + let config = crate::SolanaSupplyConfig::new(std::option::Option::Some(crate::SolanaCommitment::Processed), std::option::Option::Some(false)); + let result = pool.get_supply(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config)).await.expect("supply fixture must succeed"); + assert_eq!(result.context().slot(), 431_000_124); + assert_eq!(result.value().total(), 610_000_000_000_000_000); + assert_eq!(result.value().circulating(), 510_000_000_000_000_000); + assert_eq!(result.value().non_circulating(), 100_000_000_000_000_000); + assert_eq!(result.value().non_circulating_accounts().len(), 2); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([{"commitment":"processed","excludeNonCirculatingAccountsList":false}])); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_supply_preserves_explicit_true_as_empty_runtime_account_list() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_supply.excluded.success.json")); + let pool = pool_for_url(url.as_str()); + let config = crate::SolanaSupplyConfig::new(std::option::Option::None, std::option::Option::Some(true)); + let result = pool + .get_supply(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config)) + .await + .expect("excluded supply fixture must succeed"); + assert_eq!(result.value().non_circulating_accounts(), &[]); + assert_eq!(result.value().non_circulating(), 100_000_000_000_000_000); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([{"excludeNonCirculatingAccountsList":true}])); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_supply_omits_absent_and_empty_config() { + let role = crate::HttpRoleName::new("default"); + let empty = crate::SolanaSupplyConfig::default(); + for config in [std::option::Option::None, std::option::Option::Some(&empty)] { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_supply.success.json")); + let pool = pool_for_url(url.as_str()); + pool.get_supply(&role, config).await.expect("supply fixture must succeed"); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([])); + } +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_stake_minimum_delegation_preserves_min_context_slot_rpc_error() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_stake_minimum_delegation.error_min_context.json")); + let pool = pool_for_url(url.as_str()); + let config = crate::SolanaContextConfig::new(std::option::Option::None, std::option::Option::Some(431_000_000)); + let result = pool.get_stake_minimum_delegation(&crate::HttpRoleName::new("default"), std::option::Option::Some(&config)).await; + let error = result.expect_err("min-context-slot RPC error must propagate"); + 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_supply_preserves_scan_rpc_error() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_supply.error_scan.json")); + let pool = pool_for_url(url.as_str()); + let result = pool.get_supply(&crate::HttpRoleName::new("default"), std::option::Option::None).await; + let error = result.expect_err("supply scan RPC error must propagate"); + assert_eq!(error.code(), crate::ERROR_CODE_RPC_APPLICATION_ERROR); + handle.join().expect("fixture server must join"); +} diff --git a/deltas/0.2.4/pre.007.md b/deltas/0.2.4/pre.007.md new file mode 100644 index 0000000..8e87543 --- /dev/null +++ b/deltas/0.2.4/pre.007.md @@ -0,0 +1,475 @@ + + + +# Delta `0.2.4-pre.007` — Economics simples + réaudit SIMD-0490/0550 + +## Base requise + +Livraison précédente : + +```text +0.2.4-pre.006 +workspace.package.version = "0.2.4-pre.6" +``` + +Les validations locales fournies pour cette base sont propres : + +```text +cargo fmt --all -> terminé +cargo check --workspace -> terminé sans warning +cargo clippy --workspace --all-targets -> terminé sans warning +cargo test -p ksp-onchain-transport-lib -> 221 unit tests OK + 24 public API tests OK + 19 release-completeness tests OK + 1 smoke Devnet ignoré comme prévu + 0 échec +``` + +## Objectif + +Matérialiser les quatre wrappers Economics simples prévus par le plan `0.2.4` : + +```text +getInflationGovernor +getInflationRate +getStakeMinimumDelegation +getSupply +``` + +`getInflationReward` reste volontairement réservé à `pre.008`. + +Les cinq descriptors Economics sont déjà enregistrés sous : + +```text +V0_2_4 / Economics / Read / RetrySafe +``` + +Le registre central n'est pas modifié. + +## Réaudit primaire SIMD-0490 — Upgrade BPF Stake Program to v5.0.0 + +Le document courant reste au statut : + +```text +Review +``` + +Il prévoit notamment : + +```text +minimum delegation : 1 lamport -> 1 SOL +validator support : exposer le nouveau minimum via le RPC de minimum delegation +``` + +Ce statut ne conduit à aucune constante KSP. + +Le cross-audit Agave stable `v4.2.1` est plus important pour Transport : le runtime `getStakeMinimumDelegation` appelle déjà : + +```text +stake_utils::get_minimum_delegation( + bank.feature_set.snapshot().upgrade_bpf_stake_program_to_v5 +) +``` + +La valeur RPC est donc déjà sélectionnée par l'état runtime du feature set. + +Conséquence KSP : + +```text +aucun minimum 1 lamport codé en dur +aucun minimum 1 SOL codé en dur +aucune validation locale de la valeur +retour exact du u64 fourni par le runtime +``` + +La fixture HTTP utilise volontairement une valeur arbitraire `42_424_242` lamports pour empêcher une canary de dépendre d'une valeur économique supposée. + +## Réaudit primaire SIMD-0550 — Double Disinflation Rate + +Le document courant reste au statut : + +```text +Review +``` + +Il précise explicitement que : + +```text +getInflationRate +getInflationGovernor +``` + +reflètent la nouvelle schedule lorsqu'elle est active, mais qu'il n'y a : + +```text +aucun changement d'API +``` + +Conséquence KSP : + +- `SolanaInflationGovernor` reste un DTO de valeurs runtime `f64`; +- `SolanaInflationRate` reste un DTO de valeurs runtime `f64` + epoch; +- Transport ne réimplémente aucune formule d'inflation; +- Transport ne code en dur ni `taper = 0.15`, ni `taper = 0.30`; +- Transport ne recalcule pas `initial`; +- les fixtures utilisent des valeurs non canoniques/arbitraires afin de détecter une future normalisation locale indésirable. + +Le plan `011` décrivait déjà cette politique correctement et reste byte-identique en version 4. + +## Version Cargo + +Nouvelle prerelease technique : + +```text +0.2.4-pre.6 -> 0.2.4-pre.7 +``` + +Aucune dépendance ni feature Cargo n'est ajoutée ou modifiée. + +## `getInflationGovernor` + +Surface publique : + +```text +HttpTransportPool::get_inflation_governor( + role, + Option<&SolanaCommitmentConfig>, +) -> Result +``` + +Formes wire retenues : + +```text +None / config vide -> params: [] +config commitment -> params: [{"commitment":"..."}] +``` + +Le runtime accepte son `CommitmentConfig` général. KSP n'invente donc aucune restriction `confirmed/finalized`; une canary envoie explicitement : + +```text +commitment = processed +``` + +La réponse est décodée dans : + +```text +initial +terminal +taper +foundation +foundationTerm +``` + +sans post-traitement économique. + +## `getInflationRate` + +Surface publique : + +```text +HttpTransportPool::get_inflation_rate( + role, +) -> Result +``` + +La requête est exactement : + +```text +params: [] +``` + +La réponse conserve : + +```text +total +validator +foundation +epoch +``` + +sans recalcul local. + +## `getStakeMinimumDelegation` + +Surface publique : + +```text +HttpTransportPool::get_stake_minimum_delegation( + role, + Option<&SolanaContextConfig>, +) -> Result> +``` + +Les options stables sont réutilisées depuis le contrat commun : + +```text +commitment +minContextSlot +``` + +`None` et une config explicitement vide sont canoniquement omis. + +Une config complète avec : + +```text +commitment = processed +minContextSlot = 431000000 +``` + +est couverte et la réponse contextualisée conserve : + +```text +context.slot +context.apiVersion +value: u64 +``` + +`MinContextSlotNotReached` reste une erreur RPC applicative et n'est pas convertie en erreur de décodage KSP. + +## `getSupply` + +Surface publique : + +```text +HttpTransportPool::get_supply( + role, + Option<&SolanaSupplyConfig>, +) -> Result> +``` + +La config conserve : + +```text +commitment +excludeNonCirculatingAccountsList +``` + +Le booléen KSP reste `Option` afin de distinguer dans la requête : + +```text +omis +false +true +``` + +`None` et une config entièrement vide sont canoniquement omis car le runtime leur applique les mêmes défauts. + +Une valeur `false` explicite reste envoyée comme : + +```json +{"excludeNonCirculatingAccountsList":false} +``` + +Une valeur `true` explicite reste envoyée comme : + +```json +{"excludeNonCirculatingAccountsList":true} +``` + +Lorsque `true`, Agave retourne volontairement : + +```text +nonCirculatingAccounts = [] +``` + +sans modifier la signification des totaux retournés. KSP préserve cette liste vide telle quelle. + +Le résultat contextualisé conserve : + +```text +total +circulating +nonCirculating +nonCirculatingAccounts +``` + +Les adresses de `nonCirculatingAccounts` sont validées/typées en `Pubkey` sans fuite de la valeur fautive dans les diagnostics. + +Une `ScanError` runtime de `getSupply` reste une erreur RPC applicative. + +## Discipline `#[cfg(test)]` + +La politique introduite par `pre.002-fix.001` est maintenue. + +Deviennent runtime uniquement parce qu'ils ont maintenant un consommateur réel : + +```text +SolanaInflationGovernor::decode_wire +SolanaInflationRate::decode_wire +SolanaSupplyConfig::is_empty +SolanaSupplyConfig::to_json_value +SolanaSupply::decode_wire +WireInflationGovernor +WireInflationRate +WireSupply +WireEconomicsRpcResponse +``` + +Restent sous `#[cfg(test)]` jusqu'à `pre.008` : + +```text +SolanaInflationRewardConfig::{is_empty,to_json_value} +SolanaInflationReward::decode_wire +WireInflationReward +``` + +Aucun `#[allow(dead_code)]` n'est ajouté. + +## Chemin d'exécution + +Les quatre wrappers utilisent une seule frontière privée : + +```text +economics_descriptor + -> HttpTransportPool::execute_standard_rpc +``` + +Le helper de descriptor exige : + +```text +category = Economics +coverage_release = V0_2_4 +``` + +Transport ne crée aucun chemin HTTP parallèle et ne dépend toujours ni de Config, ni Store, ni Program, ni d'un client RPC Solana haut niveau. + +## Fixtures et tests + +Nouvelles fixtures HTTP : + +```text +get_inflation_governor.success.json +get_inflation_rate.success.json +get_stake_minimum_delegation.success.json +get_stake_minimum_delegation.error_min_context.json +get_supply.success.json +get_supply.excluded.success.json +get_supply.error_scan.json +``` + +Dix nouveaux tests unitaires couvrent : + +```text +getInflationGovernor config processed + valeurs runtime +getInflationGovernor config absente/vide +getInflationRate params vides + valeurs runtime +getStakeMinimumDelegation config contextuelle + valeur arbitraire +getStakeMinimumDelegation config absente/vide +getStakeMinimumDelegation MinContextSlotNotReached +getSupply false explicite + liste complète + contexte +getSupply true explicite + liste runtime vide +getSupply config absente/vide +getSupply ScanError +``` + +Canary public API : + +```text +public_v0_2_4_pre_007_simple_economics_wrappers_are_available_from_crate_root +``` + +Canary release : + +```text +release_v0_2_4_pre_007_simple_economics_subset_is_exact_and_retry_safe +``` + +Elle fixe exactement les quatre wrappers de cette tranche sans avancer `getInflationReward`. + +Compteurs attendus après validation locale : + +```text +231 unit tests +25 public API tests +20 release-completeness tests +1 smoke Devnet ignoré +``` + +## Fichiers modifiés + +```text +Cargo.toml +crates/ksp-onchain-transport-lib/src/rpc_economics.rs +crates/ksp-onchain-transport-lib/unit_tests/rpc_economics.rs +crates/ksp-onchain-transport-lib/tests/public_api.rs +crates/ksp-onchain-transport-lib/tests/release_completeness.rs +``` + +## Fichiers ajoutés + +```text +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_governor.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_rate.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_stake_minimum_delegation.error_min_context.json +crates/ksp-onchain-transport-lib/fixtures/http/get_supply.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_supply.excluded.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_supply.error_scan.json +deltas/0.2.4/pre.007.md +``` + +## Non-objectifs + +Cette tranche n'implémente pas : + +```text +getInflationReward +``` + +Elle ne modifie pas non plus : + +- les 10 wrappers Blocks déjà acquis; +- les 37 wrappers `0.2.1`–`0.2.3`; +- le registre des 52 current + 14 historical; +- les règles de retry; +- le smoke Devnet; +- les dépendances ou features Cargo; +- le plan `011`, déjà correct pour ce scope. + +## Validation attendue + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-onchain-transport-lib +``` + +Résultat attendu : + +```text +0 warning introduit +231 unit tests OK +25 public API tests OK +20 release-completeness tests OK +1 smoke Devnet ignoré +0 échec +``` + +## Commit attendu + +```text +v0.2.4-pre.007 +``` + +## Suite + +`0.2.4-pre.008` reste dédiée à : + +```text +getInflationReward +``` + +avec : + +```text +ordre et cardinalité des adresses +null positionnels +epoch / commitment / minContextSlot +commission nullable +commissionBps SIMD-0291 +absence de limite d'adresses inventée +invariants de réponse +``` + +Puis `pre.009` effectuera le réaudit SIMD/inventaire et la compliance HTTP finale `52/52 + 14/14`.