From 37461ec248673db6fea2373c06f47e06a234f2da Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 18 Aug 2026 21:52:00 +0200 Subject: [PATCH] v0.2.4-pre.008 --- Cargo.toml | 4 +- .../http/get_inflation_reward.duplicates.json | 1 + .../http/get_inflation_reward.empty.json | 1 + ...ion_reward.error_epoch_rewards_active.json | 1 + ...et_inflation_reward.error_min_context.json | 1 + .../http/get_inflation_reward.many_nulls.json | 1 + .../get_inflation_reward.single_null.json | 1 + .../http/get_inflation_reward.success.json | 1 + .../src/rpc_economics.rs | 74 ++- .../tests/public_api.rs | 15 +- .../tests/release_completeness.rs | 23 +- .../unit_tests/rpc_economics.rs | 185 ++++++- deltas/0.2.4/pre.008.md | 474 ++++++++++++++++++ .../011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md | 7 +- 14 files changed, 775 insertions(+), 14 deletions(-) create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.duplicates.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.empty.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_epoch_rewards_active.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_min_context.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.many_nulls.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.single_null.json create mode 100644 crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.success.json create mode 100644 deltas/0.2.4/pre.008.md diff --git a/Cargo.toml b/Cargo.toml index 349856e..f88147a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 138 +# version: 139 [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.7" +version = "0.2.4-pre.8" 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_reward.duplicates.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.duplicates.json new file mode 100644 index 0000000..e74940f --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.duplicates.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":[{"epoch":912,"effectiveSlot":431500010,"amount":777,"postBalance":1000777,"commission":5,"commissionBps":500},null,{"epoch":912,"effectiveSlot":431500010,"amount":777,"postBalance":1000777,"commission":5,"commissionBps":500}],"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.empty.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.empty.json new file mode 100644 index 0000000..8661653 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.empty.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":[],"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_epoch_rewards_active.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_epoch_rewards_active.json new file mode 100644 index 0000000..d909749 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_epoch_rewards_active.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","error":{"code":-32017,"message":"Epoch rewards period still active at slot 431500000","data":{"slot":431500000,"currentBlockHeight":400000000,"rewardsCompleteBlockHeight":400000100}},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_min_context.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_min_context.json new file mode 100644 index 0000000..8133b0f --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_min_context.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","error":{"code":-32016,"message":"Minimum context slot has not been reached","data":{"contextSlot":431000000}},"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.many_nulls.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.many_nulls.json new file mode 100644 index 0000000..e923d2a --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.many_nulls.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":[null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null],"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.single_null.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.single_null.json new file mode 100644 index 0000000..e7273e2 --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.single_null.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":[null],"id":1} diff --git a/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.success.json b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.success.json new file mode 100644 index 0000000..592d0ac --- /dev/null +++ b/crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.success.json @@ -0,0 +1 @@ +{"jsonrpc":"2.0","result":[{"epoch":912,"effectiveSlot":431500001,"amount":2500000,"postBalance":1002500000,"commission":7,"commissionBps":725},null,{"epoch":912,"effectiveSlot":431500003,"amount":1250000,"postBalance":501250000,"commission":null},{"epoch":912,"effectiveSlot":431500004,"amount":500000,"postBalance":200500000,"commission":3,"commissionBps":null}],"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 798bd9e..feb7588 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: 3 +// version: 4 /// Inflation-governor values returned by `getInflationGovernor`. #[derive(Clone, Copy, Debug, PartialEq)] @@ -142,14 +142,12 @@ impl SolanaInflationRewardConfig { } /// Returns whether this config would serialize to an empty object. - #[cfg(test)] pub(crate) const fn is_empty(&self) -> bool { return self.epoch.is_none() && self.commitment.is_none() && self.min_context_slot.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(epoch) = self.epoch { @@ -214,7 +212,6 @@ impl SolanaInflationReward { } /// Decodes one non-null inflation reward 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 { @@ -359,6 +356,40 @@ impl crate::HttpTransportPool { }; } + /// Executes typed `getInflationReward`, preserving input order, positional nulls and runtime commission extensions. + pub async fn get_inflation_reward( + &self, + role: &crate::HttpRoleName, + addresses: &[ksp_core_lib::Pubkey], + config: std::option::Option<&crate::SolanaInflationRewardConfig>, + ) -> ksp_core_lib::Result>> { + if let std::option::Option::Some(config) = config + && config.commitment() == std::option::Option::Some(crate::SolanaCommitment::Processed) + { + return std::result::Result::Err( + ksp_core_lib::Error::new( + crate::ERROR_CODE_INVALID_RPC_PARAMETERS, + "getInflationReward commitment must be confirmed or finalized when explicitly provided", + ) + .with_context("rpc_method", "getInflationReward") + .with_context("commitment", "processed"), + ); + } + let address_values = addresses.iter().map(|address| serde_json::Value::String(address.to_string())).collect::>(); + let mut params = std::vec![serde_json::Value::Array(address_values)]; + if let std::option::Option::Some(config) = config + && !config.is_empty() + { + params.push((*config).to_json_value()); + } + let value = self.execute_economics_rpc("getInflationReward", 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_inflation_rewards("getInflationReward", value, addresses.len()); + } + /// Executes typed `getStakeMinimumDelegation` and preserves the contextual runtime value in lamports. pub async fn get_stake_minimum_delegation( &self, @@ -428,6 +459,40 @@ fn push_economics_context_config(params: &mut std::vec::Vec, return; } +fn decode_inflation_rewards( + method: &str, + value: serde_json::Value, + expected_count: usize, +) -> ksp_core_lib::Result>> { + let decoded = crate::decode_wire_json::>>(method, value); + let values = match decoded { + std::result::Result::Ok(values) => values, + std::result::Result::Err(error) => return std::result::Result::Err(error), + }; + if values.len() != expected_count { + return std::result::Result::Err( + ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "getInflationReward result count does not match the requested address count") + .with_context("rpc_method", method) + .with_context("expected_count", expected_count.to_string()) + .with_context("actual_count", values.len().to_string()), + ); + } + let mut rewards = std::vec::Vec::with_capacity(values.len()); + for value in values { + match value { + std::option::Option::Some(value) => { + let reward = crate::SolanaInflationReward::decode_wire(method, value); + match reward { + std::result::Result::Ok(reward) => rewards.push(std::option::Option::Some(reward)), + std::result::Result::Err(error) => return std::result::Result::Err(error), + } + }, + std::option::Option::None => rewards.push(std::option::Option::None), + } + } + return std::result::Result::Ok(rewards); +} + 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 { @@ -499,7 +564,6 @@ struct WireInflationRate { epoch: u64, } -#[cfg(test)] #[derive(serde::Deserialize)] #[serde(rename_all = "camelCase")] struct WireInflationReward { diff --git a/crates/ksp-onchain-transport-lib/tests/public_api.rs b/crates/ksp-onchain-transport-lib/tests/public_api.rs index 9c46fc7..da05dd3 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: 21 +// version: 22 //! Integration tests for the public `ksp-onchain-transport-lib` consumer contract. @@ -450,3 +450,16 @@ fn public_v0_2_4_pre_007_simple_economics_wrappers_are_available_from_crate_root 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)); } + +#[test] +fn public_v0_2_4_pre_008_inflation_reward_wrapper_is_available_from_crate_root() { + let _get_inflation_reward = ksp_onchain_transport_lib::HttpTransportPool::get_inflation_reward; + let config = ksp_onchain_transport_lib::SolanaInflationRewardConfig::new( + std::option::Option::Some(912), + std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed), + std::option::Option::Some(431_000_000), + ); + assert_eq!(config.epoch(), std::option::Option::Some(912)); + assert_eq!(config.commitment(), std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed)); + assert_eq!(config.min_context_slot(), std::option::Option::Some(431_000_000)); +} diff --git a/crates/ksp-onchain-transport-lib/tests/release_completeness.rs b/crates/ksp-onchain-transport-lib/tests/release_completeness.rs index 66a0dc1..4561350 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: 19 +// version: 20 //! Release-level completeness canaries for the staged HTTP wrapper sequence. @@ -432,7 +432,7 @@ fn release_pre_008_ksp_transport_007_retro_audit_covers_all_typed_current_method } #[test] -fn release_v0_2_4_descriptor_set_is_exact_and_remains_read_retry_safe_during_staged_wrappers() { +fn release_v0_2_4_descriptor_set_is_exact_and_remains_read_retry_safe_through_wrapper_completion() { let mut expected_blocks = std::vec![ "getBlock", "getBlockCommitment", @@ -589,3 +589,22 @@ fn release_v0_2_4_pre_007_simple_economics_subset_is_exact_and_retry_safe() { assert_eq!(actual, expected); assert_eq!(actual.len(), 4); } + +#[test] +fn release_v0_2_4_pre_008_completes_all_five_economics_wrappers_exactly_and_retry_safe() { + let mut expected = std::vec!["getInflationGovernor", "getInflationRate", "getInflationReward", "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 + { + actual.push(descriptor.method()); + 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(), 5); +} 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 2db1c4c..4c33564 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: 2 +// version: 3 #[test] fn inflation_reward_config_preserves_epoch_commitment_and_min_context_slot() { @@ -307,3 +307,186 @@ async fn typed_get_supply_preserves_scan_rpc_error() { assert_eq!(error.code(), crate::ERROR_CODE_RPC_APPLICATION_ERROR); handle.join().expect("fixture server must join"); } + +fn inflation_reward_fixture_pubkey(value: &str) -> ksp_core_lib::Pubkey { + return value.parse::().expect("fixture inflation-reward pubkey must parse"); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_serializes_full_config_and_preserves_position_and_commission_states() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.success.json")); + let pool = pool_for_url(url.as_str()); + let addresses = std::vec![ + inflation_reward_fixture_pubkey("11111111111111111111111111111111"), + inflation_reward_fixture_pubkey("Vote111111111111111111111111111111111111111"), + inflation_reward_fixture_pubkey("SysvarRent111111111111111111111111111111111"), + inflation_reward_fixture_pubkey("Stake11111111111111111111111111111111111111"), + ]; + let config = crate::SolanaInflationRewardConfig::new( + std::option::Option::Some(912), + std::option::Option::Some(crate::SolanaCommitment::Finalized), + std::option::Option::Some(431_000_000), + ); + let rewards = pool + .get_inflation_reward(&crate::HttpRoleName::new("default"), addresses.as_slice(), std::option::Option::Some(&config)) + .await + .expect("inflation reward fixture must succeed"); + assert_eq!(rewards.len(), addresses.len()); + let first = rewards[0].as_ref().expect("first reward must be present"); + assert_eq!(first.epoch(), 912); + assert_eq!(first.effective_slot(), 431_500_001); + assert_eq!(first.amount(), 2_500_000); + assert_eq!(first.post_balance(), 1_002_500_000); + assert_eq!(first.commission(), std::option::Option::Some(7)); + assert_eq!(first.commission_bps().value(), std::option::Option::Some(&725)); + assert!(rewards[1].is_none()); + let third = rewards[2].as_ref().expect("third reward must be present"); + assert_eq!(third.commission(), std::option::Option::None); + assert!(third.commission_bps().is_omitted()); + let fourth = rewards[3].as_ref().expect("fourth reward must be present"); + assert_eq!(fourth.commission(), std::option::Option::Some(3)); + assert!(fourth.commission_bps().is_null()); + + let request = handle.join().expect("fixture server must join"); + let body = request_body(request.as_str()); + assert_eq!(body["method"], serde_json::json!("getInflationReward")); + assert_eq!( + body["params"], + serde_json::json!([ + [ + "11111111111111111111111111111111", + "Vote111111111111111111111111111111111111111", + "SysvarRent111111111111111111111111111111111", + "Stake11111111111111111111111111111111111111" + ], + {"epoch":912,"commitment":"finalized","minContextSlot":431000000} + ]) + ); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_preserves_duplicate_input_order_and_positional_nulls() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.duplicates.json")); + let pool = pool_for_url(url.as_str()); + let first = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let second = inflation_reward_fixture_pubkey("Vote111111111111111111111111111111111111111"); + let addresses = std::vec![first, second, first]; + let rewards = pool + .get_inflation_reward(&crate::HttpRoleName::new("default"), addresses.as_slice(), std::option::Option::None) + .await + .expect("duplicate inflation reward fixture must succeed"); + assert_eq!(rewards.len(), 3); + assert_eq!(rewards[0], rewards[2]); + assert!(rewards[1].is_none()); + let request = handle.join().expect("fixture server must join"); + assert_eq!( + request_body(request.as_str())["params"], + serde_json::json!([["11111111111111111111111111111111", "Vote111111111111111111111111111111111111111", "11111111111111111111111111111111"]]) + ); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_omits_absent_and_empty_config_but_keeps_address_parameter() { + let role = crate::HttpRoleName::new("default"); + let address = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let addresses = std::vec![address]; + let empty = crate::SolanaInflationRewardConfig::default(); + for config in [std::option::Option::None, std::option::Option::Some(&empty)] { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.single_null.json")); + let pool = pool_for_url(url.as_str()); + let rewards = pool.get_inflation_reward(&role, addresses.as_slice(), config).await.expect("single null inflation reward fixture must succeed"); + assert_eq!(rewards, std::vec![std::option::Option::None]); + let request = handle.join().expect("fixture server must join"); + assert_eq!(request_body(request.as_str())["params"], serde_json::json!([["11111111111111111111111111111111"]])); + } +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_accepts_empty_address_list_without_inventing_a_minimum() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.empty.json")); + let pool = pool_for_url(url.as_str()); + let rewards = pool + .get_inflation_reward(&crate::HttpRoleName::new("default"), &[], std::option::Option::None) + .await + .expect("empty inflation reward fixture must succeed"); + assert!(rewards.is_empty()); + 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_reward_does_not_invent_a_256_address_limit() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.many_nulls.json")); + let pool = pool_for_url(url.as_str()); + let address = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let addresses = std::vec![address; 300]; + let rewards = pool + .get_inflation_reward(&crate::HttpRoleName::new("default"), addresses.as_slice(), std::option::Option::None) + .await + .expect("300-address inflation reward fixture must succeed without local cardinality cap"); + assert_eq!(rewards.len(), 300); + assert!(rewards.iter().all(std::option::Option::is_none)); + let request = handle.join().expect("fixture server must join"); + let body = request_body(request.as_str()); + assert_eq!(body["params"][0].as_array().expect("address parameter must be an array").len(), 300); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_rejects_processed_commitment_before_io() { + let role = crate::HttpRoleName::new("default"); + let pool = pool_for_url("http://127.0.0.1:1"); + let address = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let config = crate::SolanaInflationRewardConfig::new( + std::option::Option::Some(912), + std::option::Option::Some(crate::SolanaCommitment::Processed), + std::option::Option::None, + ); + let result = pool.get_inflation_reward(&role, &[address], std::option::Option::Some(&config)).await; + let error = result.expect_err("processed inflation-reward commitment must fail before I/O"); + assert_eq!(error.code(), crate::ERROR_CODE_INVALID_RPC_PARAMETERS); + assert_eq!(error.context()[1].key(), "commitment"); + assert_eq!(error.context()[1].value(), "processed"); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_rejects_response_cardinality_mismatch() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.single_null.json")); + let pool = pool_for_url(url.as_str()); + let first = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let second = inflation_reward_fixture_pubkey("Vote111111111111111111111111111111111111111"); + let result = pool.get_inflation_reward(&crate::HttpRoleName::new("default"), &[first, second], std::option::Option::None).await; + let error = result.expect_err("inflation reward response count mismatch must fail typed decoding"); + assert_eq!(error.code(), crate::ERROR_CODE_INVALID_RESPONSE); + assert_eq!(error.context()[1].key(), "expected_count"); + assert_eq!(error.context()[1].value(), "2"); + assert_eq!(error.context()[2].key(), "actual_count"); + assert_eq!(error.context()[2].value(), "1"); + handle.join().expect("fixture server must join"); +} + +#[tokio::test(flavor = "current_thread")] +async fn typed_get_inflation_reward_preserves_min_context_slot_rpc_error() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.error_min_context.json")); + let pool = pool_for_url(url.as_str()); + let address = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let config = crate::SolanaInflationRewardConfig::new( + std::option::Option::Some(912), + std::option::Option::Some(crate::SolanaCommitment::Confirmed), + std::option::Option::Some(431_500_000), + ); + let result = pool.get_inflation_reward(&crate::HttpRoleName::new("default"), &[address], std::option::Option::Some(&config)).await; + let error = result.expect_err("inflation reward min-context 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_inflation_reward_preserves_epoch_rewards_period_active_rpc_error() { + let (url, handle) = serve_once(include_str!("../fixtures/http/get_inflation_reward.error_epoch_rewards_active.json")); + let pool = pool_for_url(url.as_str()); + let address = inflation_reward_fixture_pubkey("11111111111111111111111111111111"); + let result = pool.get_inflation_reward(&crate::HttpRoleName::new("default"), &[address], std::option::Option::None).await; + let error = result.expect_err("active epoch-rewards 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.008.md b/deltas/0.2.4/pre.008.md new file mode 100644 index 0000000..a752dca --- /dev/null +++ b/deltas/0.2.4/pre.008.md @@ -0,0 +1,474 @@ + + + +# Delta `0.2.4-pre.008` — `getInflationReward` complet + invariants positionnels + +## Base requise + +Livraison précédente : + +```text +0.2.4-pre.007 +workspace.package.version = "0.2.4-pre.7" +``` + +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 -> 231 unit tests OK + 25 public API tests OK + 20 release-completeness tests OK + 1 smoke Devnet ignoré comme prévu + 0 échec +``` + +## Objectif + +Achever la surface Economics `0.2.4` avec le dernier wrapper prévu : + +```text +getInflationReward +``` + +La tranche doit conserver sans perte : + +```text +ordre exact des adresses d'entrée +cardinalité exacte de la réponse +null positionnels +config epoch / commitment / minContextSlot +commission nullable +commissionBps présent / omis / null de compatibilité +absence de limite métier d'adresses inventée par KSP +erreurs RPC runtime +``` + +À l'issue de cette tranche, les `10/10` wrappers Blocks et `5/5` wrappers Economics de `V0_2_4` sont matérialisés. La compliance globale `52/52 + 14/14` reste volontairement réservée à `pre.009`. + +## Réaudit primaire du contrat Agave stable + +Baseline stable conservée : + +```text +Agave v4.2.1 +``` + +Le serveur expose : + +```text +getInflationReward( + address_strs: Vec, + config: Option, +) -> Vec> +``` + +`RpcEpochConfig` contient : + +```text +epoch: Option +commitment: Option +minContextSlot: Option +``` + +Le runtime reconstruit son résultat en itérant sur la liste d'adresses d'origine. Il restitue donc une position par entrée : + +```text +reward trouvé -> Some(RpcInflationReward) +reward absent -> None / JSON null +``` + +Cette propriété justifie le contrôle KSP explicite de cardinalité : une réponse dont la longueur diffère du nombre d'adresses demandées est un wire invalide pour le wrapper typed. + +## Correction de contrat découverte pendant `pre.008` + +Le plan `011` n'explicitait pas encore la contrainte effective de commitment de `getInflationReward`. + +Agave construit un `RpcContextConfig` depuis `RpcEpochConfig` puis appelle : + +```text +getBlocksWithLimit(first_slot_in_epoch, 1, Some(context_config)) +``` + +Cette voie applique la contrainte runtime : + +```text +commitment >= confirmed +``` + +Conséquence KSP : + +```text +commitment = processed -> rejet déterministe avant I/O +commitment = confirmed -> accepté +commitment = finalized -> accepté +commitment absent -> défaut runtime accepté +``` + +Le plan `011` passe donc de la version `4` à la version `5` avec : + +- la nouvelle contrainte locale `getInflationReward commitment >= confirmed`; +- la matrice Economics corrigée; +- le libellé de `pre.008` complété par le réaudit de commitment. + +Aucun autre changement de planning n'est effectué. + +## SIMD-0291 — Commission Rate in Basis Points + +Le document SIMD courant reste au statut : + +```text +Review +``` + +La baseline Agave stable `v4.2.1` expose néanmoins déjà : + +```text +RpcInflationReward { + epoch, + effective_slot, + amount, + post_balance, + commission: Option, + commission_bps: Option, +} +``` + +KSP conserve donc deux informations indépendantes : + +```text +commission -> Option +commissionBps -> SolanaWireField +``` + +Aucune conversion `bps -> pourcentage` n'est réalisée. Aucun champ n'est dérivé depuis l'autre. + +Le wire KSP accepte et distingue : + +```text +commissionBps présent +commissionBps omis +commissionBps explicitement null pour compatibilité provider/wire +``` + +Même si Agave stable sérialise normalement l'absence via omission, conserver `null` séparément respecte la politique générale `SolanaWireField` et évite une normalisation destructive. + +## Version Cargo + +Nouvelle prerelease technique : + +```text +0.2.4-pre.7 -> 0.2.4-pre.8 +``` + +Aucune dépendance ni feature Cargo n'est ajoutée ou modifiée. + +## Surface publique `getInflationReward` + +Nouvelle méthode : + +```text +HttpTransportPool::get_inflation_reward( + role, + &[Pubkey], + Option<&SolanaInflationRewardConfig>, +) -> Result>> +``` + +Le premier paramètre JSON-RPC est toujours la liste d'adresses, y compris lorsqu'elle est vide : + +```text +[] d'adresses -> params: [[]] +``` + +La config optionnelle est ajoutée uniquement lorsqu'elle contient au moins un champ : + +```text +None / config vide -> [addresses] +config non vide -> [addresses, config] +``` + +Exemple complet : + +```json +[ + ["address-1", "address-2"], + { + "epoch": 912, + "commitment": "finalized", + "minContextSlot": 431000000 + } +] +``` + +## Ordre, doublons et cardinalité + +Le wrapper ne trie ni ne déduplique les adresses. + +Une requête conceptuelle : + +```text +[A, B, A] +``` + +reste exactement : + +```text +[A, B, A] +``` + +et la réponse reste positionnelle : + +```text +[Some(reward A), None, Some(reward A)] +``` + +Après décodage du tableau JSON, KSP vérifie : + +```text +result.len() == addresses.len() +``` + +Sinon : + +```text +ERROR_CODE_INVALID_RESPONSE +expected_count = ... +actual_count = ... +``` + +## Absence de limite d'adresses inventée + +Aucune constante métier n'est ajoutée pour `getInflationReward`. + +En particulier, KSP ne réutilise pas artificiellement : + +```text +256 # getSignatureStatuses +1000 # getSignaturesForAddress +``` + +ou toute autre limite d'un RPC voisin. + +Une canary HTTP construit une requête de : + +```text +300 adresses +``` + +et vérifie qu'elle atteint réellement le serveur fixture puis que les `300` `null` sont restitués. + +La limite générale de taille d'une requête HTTP reste une contrainte de transport/provider, pas une cardinalité métier inventée par ce wrapper. + +## Erreurs runtime préservées + +Deux erreurs spécifiques sont couvertes par fixtures : + +```text +-32016 MinContextSlotNotReached +-32017 EpochRewardsPeriodActive +``` + +Elles restent : + +```text +ERROR_CODE_RPC_APPLICATION_ERROR +``` + +et ne sont pas converties en erreurs de décodage locales. + +Les autres erreurs runtime possibles liées à l'historique/epoch restent également transportées par le flux JSON-RPC central, notamment les familles BlockCleanedUp, BlockNotAvailable, SlotNotEpochBoundary et long-term storage lorsqu'elles surviennent réellement. + +## Discipline `#[cfg(test)]` + +La politique introduite par `pre.002-fix.001` reste appliquée. + +Deviennent runtime uniquement parce qu'ils ont maintenant un consommateur réel : + +```text +SolanaInflationRewardConfig::is_empty +SolanaInflationRewardConfig::to_json_value +SolanaInflationReward::decode_wire +WireInflationReward +``` + +Ils rejoignent les helpers Economics activés en `pre.007`. + +Aucun `#[allow(dead_code)]` n'est ajouté. + +## Chemin d'exécution + +Le wrapper suit la frontière existante : + +```text +get_inflation_reward + -> economics_descriptor("getInflationReward") + -> HttpTransportPool::execute_standard_rpc + -> decode_inflation_rewards +``` + +Le descriptor central reste : + +```text +V0_2_4 / Economics / Read / RetrySafe +``` + +Aucun chemin HTTP parallèle n'est créé. + +## Fixtures + +Nouvelles fixtures HTTP : + +```text +get_inflation_reward.success.json +get_inflation_reward.duplicates.json +get_inflation_reward.single_null.json +get_inflation_reward.empty.json +get_inflation_reward.many_nulls.json +get_inflation_reward.error_min_context.json +get_inflation_reward.error_epoch_rewards_active.json +``` + +Elles couvrent : + +- config complète; +- ordre positionnel; +- doublons d'adresses; +- `null` positionnels; +- `commission` nullable; +- `commissionBps` présent / omis / null; +- tableau d'adresses vide; +- 300 adresses sans limite métier KSP; +- erreurs RPC runtime. + +## Tests + +Neuf nouveaux tests unitaires couvrent : + +```text +config complète + positions + états commission/commissionBps +ordre des doublons + null positionnel +config absente/vide tout en conservant le paramètre addresses +liste d'adresses vide +300 adresses sans limite locale 256 +processed rejeté avant I/O +mismatch de cardinalité rejeté +MinContextSlotNotReached préservé +EpochRewardsPeriodActive préservé +``` + +Canary public API : + +```text +public_v0_2_4_pre_008_inflation_reward_wrapper_is_available_from_crate_root +``` + +Canary release : + +```text +release_v0_2_4_pre_008_completes_all_five_economics_wrappers_exactly_and_retry_safe +``` + +La canary globale : + +```text +release_v0_2_4_descriptor_set_is_exact_and_remains_read_retry_safe_during_staged_wrappers +``` + +est renommée : + +```text +release_v0_2_4_descriptor_set_is_exact_and_remains_read_retry_safe_through_wrapper_completion +``` + +car `pre.008` achève désormais les `15/15` wrappers `V0_2_4`. + +Compteurs attendus après validation locale : + +```text +240 unit tests +26 public API tests +21 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 +docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md +``` + +## Fichiers ajoutés + +```text +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.success.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.duplicates.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.single_null.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.empty.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.many_nulls.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_min_context.json +crates/ksp-onchain-transport-lib/fixtures/http/get_inflation_reward.error_epoch_rewards_active.json +deltas/0.2.4/pre.008.md +``` + +## Non-objectifs + +Cette tranche ne réalise pas encore : + +- le réaudit SIMD final `0180/0298/0301/0307/0385/0490/0550/0553`; +- le réaudit final de l'inventaire officiel HTTP; +- la preuve globale `52/52 wrappers current`; +- la preuve globale `14/14 historical Deprecated/runtime Removed`; +- les smokes de clôture; +- les graphes finaux de dépendances; +- la documentation de clôture et le prompt `0.2.5`. + +Ces points restent réservés à `pre.009`. + +## 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 +240 unit tests OK +26 public API tests OK +21 release-completeness tests OK +1 smoke Devnet ignoré +0 échec +``` + +## Commit attendu + +```text +v0.2.4-pre.008 +``` + +## Suite + +`0.2.4-pre.009` reste la tranche de clôture technique/documentaire : + +```text +réaudit SIMD HTTP final +réaudit inventaire officiel +compliance 52/52 + 14/14 +KSP-TRANSPORT-007 final +smokes +graphes +documentation +prompt 0.2.5 — Wallet foundation +``` diff --git a/docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md b/docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md index ef34c34..9f59b47 100644 --- a/docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md +++ b/docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.2.4` — HTTP Blocks + Economics + compliance HTTP finale @@ -271,7 +271,7 @@ Les champs top-level dont la présence dépend de la config (`transactions`, `si | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `getInflationGovernor` | config commitment optionnelle | `{initial,terminal,taper,foundation,foundationTerm}` en `f64` | réutiliser `SolanaCommitmentConfig`; aucun contexte de réponse | | `getInflationRate` | aucun paramètre | `{total,validator,foundation,epoch}` | requête exacte `params: []` | -| `getInflationReward` | liste ordonnée d'adresses; config optionnelle `{epoch,commitment,minContextSlot}` | `Vec>` positionnel | ordre/cardinalité identiques aux entrées; préserver `commission: u8 ou null` et `commissionBps: u16` optionnel/omis de Agave `v4.2.1` conformément à SIMD-0291; aucune limite fixe d'adresses inventée | +| `getInflationReward` | liste ordonnée d'adresses; config optionnelle `{epoch,commitment,minContextSlot}` | `Vec>` positionnel | commitment >= `confirmed`; ordre/cardinalité identiques aux entrées; préserver `commission: u8 ou null` et `commissionBps: u16` optionnel/omis de Agave `v4.2.1` conformément à SIMD-0291; aucune limite fixe d'adresses inventée | | `getStakeMinimumDelegation` | config contextuelle optionnelle `{commitment,minContextSlot}` | `SolanaRpcResponse` | réutiliser `SolanaContextConfig` / `SolanaRpcResponse`; restituer la valeur runtime en lamports sans minimum codé en dur; surveiller SIMD-0490 | | `getSupply` | config optionnelle `{commitment,excludeNonCirculatingAccountsList}` | `SolanaRpcResponse<{total,circulating,nonCirculating,nonCirculatingAccounts}>` | le booléen runtime par défaut est `false`; préserver la liste ordonnée retournée lorsqu'elle est demandée | @@ -297,6 +297,7 @@ getBlocksWithLimit commitment >= confirmed getBlocksWithLimit limit <= 500_000 getRecentPerformanceSamples limit <= 720 getBlockProduction lastSlot >= firstSlot lorsqu'ils sont tous deux présents +getInflationReward commitment >= confirmed ``` `getBlocks(end < start)` et `getBlocksWithLimit(limit = 0)` sont des cas valides qui doivent produire un tableau vide plutôt qu'une erreur locale. @@ -450,7 +451,7 @@ pre.006 réaudit SIMD-0298/0307 + getBlock moderne + bare encoding legacy + tra + wire bloc riche + SIMD-0118/0291 + canary version numérique SIMD-0385 pre.007 réaudit SIMD-0490/0550 + Economics simples : getInflationGovernor, getInflationRate, getStakeMinimumDelegation, getSupply -pre.008 getInflationReward + null positionnels + commissionBps SIMD-0291 + invariants +pre.008 réaudit commitment runtime + getInflationReward + null positionnels + commissionBps SIMD-0291 + invariants pre.009 réaudit SIMD HTTP (0180/0298/0301/0307/0385/0490/0550/0553 minimum) + réaudit inventaire officiel + compliance finale 52/52 + 14/14 + KSP-TRANSPORT-007 + docs + smokes + graphes + prompt 0.2.5 — Wallet foundation