v0.3.10-pre.004

crates/ksp-job-backfill-lib/tests/http_block_material.rs

@@ -0,0 +1,141 @@
+// file: crates/ksp-job-backfill-lib/tests/http_block_material.rs
+// version: 1
+
+//! Cross-layer canary for the future Worker-owned HTTP block adapter without changing production ownership.
+
+fn pool_for_url(url: &str) -> ksp_onchain_transport_lib::HttpTransportPool {
+    let role = ksp_onchain_transport_lib::HttpEndpointRoleSettings::new(
+        ksp_onchain_transport_lib::HttpRoleName::new("default"),
+        true,
+        std::vec![ksp_onchain_transport_lib::HttpRequestKind::wildcard()],
+        10,
+        ksp_onchain_transport_lib::HttpRoleLimits::new(
+            std::option::Option::None,
+            std::option::Option::None,
+            std::option::Option::None,
+            std::option::Option::None,
+        ),
+    );
+    let endpoint = ksp_onchain_transport_lib::HttpEndpointSettings::new(
+        "http-block-fixture",
+        true,
+        ksp_onchain_transport_lib::HttpProviderName::new("fixture-provider"),
+        ksp_onchain_transport_lib::HttpClusterName::new("devnet"),
+        ksp_onchain_transport_lib::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],
+    );
+    return ksp_onchain_transport_lib::HttpTransportPool::new(ksp_onchain_transport_lib::HttpTransportSettings::new(
+        std::vec![endpoint],
+        ksp_onchain_transport_lib::HttpRetrySettings::new(0, std::time::Duration::from_millis(1), std::time::Duration::from_millis(1)),
+    ))
+    .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 mut bytes = std::vec::Vec::new();
+        let mut buffer = [0_u8; 1024];
+        loop {
+            let count = std::io::Read::read(&mut stream, &mut buffer).expect("fixture request must read");
+            if count == 0 {
+                break;
+            }
+            bytes.extend_from_slice(&buffer[..count]);
+            if bytes.windows(4).any(|window| return window == b"\r\n\r\n") {
+                break;
+            }
+        }
+        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;
+    });
+    return (format!("http://{address}"), handle);
+}
+
+fn map_meta(field: &ksp_onchain_transport_lib::SolanaWireField<serde_json::Value>) -> ksp_raw_transaction_lib::RawTransactionWireField<serde_json::Value> {
+    return match field {
+        ksp_onchain_transport_lib::SolanaWireField::Omitted => ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+        ksp_onchain_transport_lib::SolanaWireField::Null => ksp_raw_transaction_lib::RawTransactionWireField::Null,
+        ksp_onchain_transport_lib::SolanaWireField::Value(value) => ksp_raw_transaction_lib::RawTransactionWireField::Value(value.clone()),
+    };
+}
+
+fn map_version(
+    field: &ksp_onchain_transport_lib::SolanaWireField<ksp_onchain_transport_lib::SolanaTransactionVersion>,
+) -> ksp_raw_transaction_lib::RawTransactionWireField<ksp_raw_transaction_lib::RawTransactionVersion> {
+    return match field {
+        ksp_onchain_transport_lib::SolanaWireField::Omitted => ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+        ksp_onchain_transport_lib::SolanaWireField::Null => ksp_raw_transaction_lib::RawTransactionWireField::Null,
+        ksp_onchain_transport_lib::SolanaWireField::Value(ksp_onchain_transport_lib::SolanaTransactionVersion::Legacy) => {
+            ksp_raw_transaction_lib::RawTransactionWireField::Value(ksp_raw_transaction_lib::RawTransactionVersion::Legacy)
+        },
+        ksp_onchain_transport_lib::SolanaWireField::Value(ksp_onchain_transport_lib::SolanaTransactionVersion::Number(number)) => {
+            ksp_raw_transaction_lib::RawTransactionWireField::Value(ksp_raw_transaction_lib::RawTransactionVersion::Number(*number))
+        },
+    };
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn pre_004_http_observed_block_projects_each_base64_transaction_to_common_material_without_new_production_edge() {
+    const BODY: &str = concat!(
+        "{\"jsonrpc\":\"2.0\",\"result\":{\"previousBlockhash\":\"previous\",\"blockhash\":\"block\",\"parentSlot\":430000122,",
+        "\"rewards\":[],\"numRewardPartitions\":0,\"blockTime\":1787072400,\"blockHeight\":410000000,",
+        "\"transactions\":[{\"transaction\":[\"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        "AAAAAA\",\"base64\"],\"meta\":{\"err\":null,\"fee\":5000},\"version\":\"legacy\"},",
+        "{\"transaction\":[\"AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEA\",",
+        "\"base64\"],\"meta\":{\"err\":null,\"fee\":6000},\"version\":0}]},\"id\":1}",
+    );
+    let (url, handle) = serve_once(BODY);
+    let pool = pool_for_url(url.as_str());
+    let config = ksp_onchain_transport_lib::SolanaGetBlockConfig::new(
+        std::option::Option::Some(ksp_onchain_transport_lib::SolanaCommitment::Confirmed),
+        std::option::Option::Some(ksp_onchain_transport_lib::SolanaTransactionEncoding::Base64),
+        std::option::Option::Some(ksp_onchain_transport_lib::SolanaTransactionDetails::Full),
+        std::option::Option::Some(0),
+        std::option::Option::Some(false),
+    );
+    let observed = pool
+        .get_block_observed(&ksp_onchain_transport_lib::HttpRoleName::new("default"), 430_000_123, std::option::Option::Some(&config))
+        .await
+        .expect("observed block fixture must succeed");
+    assert_eq!(observed.endpoint_name(), "http-block-fixture");
+    assert_eq!(observed.provider().as_str(), "fixture-provider");
+    let block = observed.value().as_ref().expect("fixture block must be present");
+    let transactions = block.transactions().value().expect("fixture transactions must be present");
+    assert_eq!(transactions.len(), 2);
+    let network = ksp_store_lib::RawNetworkId::new("devnet").expect("fixture network must be valid");
+    let expected_signatures = [[0_u8; 64], [1_u8; 64]];
+    for (index, transaction) in transactions.iter().enumerate() {
+        let (data, meta, version) = match transaction.transaction() {
+            ksp_onchain_transport_lib::SolanaEncodedTransaction::Binary {
+                data,
+                encoding: ksp_onchain_transport_lib::SolanaTransactionBinaryEncoding::Base64,
+            } => (data.as_str(), map_meta(transaction.meta()), map_version(transaction.version())),
+            _ => panic!("fixture must remain full Base64 transaction material"),
+        };
+        let transaction_index = u32::try_from(index).expect("fixture transaction index must fit u32");
+        let material = ksp_raw_transaction_lib::RawTransactionMaterial::binary_base64_with_embedded_signature(
+            network.clone(),
+            430_000_123,
+            block.block_time(),
+            data,
+            meta,
+            version,
+            ksp_raw_transaction_lib::RawTransactionWireField::Value(transaction_index),
+        )
+        .expect("HTTP block material must map to common RAW material");
+        let raw = ksp_raw_transaction_lib::canonicalize_raw_transaction(material).expect("mapped HTTP block material must canonicalize");
+        assert_eq!(raw.reference().signature().as_bytes(), &expected_signatures[index]);
+        assert_eq!(raw.slot(), 430_000_123);
+        assert_eq!(raw.block_time().map(|value| return value.unix_millis()), std::option::Option::Some(1_787_072_400_000));
+        assert!(raw.payload().bytes().ends_with(format!("\"transactionIndex\":{transaction_index}}}").as_bytes()));
+    }
+    handle.join().expect("fixture server must join");
+    return;
+}

crates/ksp-onchain-transport-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-onchain-transport-lib/USAGE.md -->
-<!-- version: 24 -->
+<!-- version: 25 -->
 
 # Utilisation de `ksp-onchain-transport-lib`
 
@@ -449,7 +449,9 @@ let inflation_rate = pool.get_inflation_rate(&role).await;
 let stake_minimum = pool.get_stake_minimum_delegation(&role, Some(&context)).await;
 ```
 
-`getBlock` possède également une forme bare-encoding legacy séparée et deprecated. Les valeurs Economics restent celles du runtime : le consumer ne doit pas supposer localement un taux d'inflation ou un minimum de délégation constant.
+`getBlock` possède également une forme bare-encoding legacy séparée et deprecated. Pour les consumers qui doivent conserver la provenance exacte d’un pool multi-endpoint, `get_block_observed(...)` exécute la même forme moderne et retourne la valeur typée avec le nom sûr de l’endpoint et le provider réellement gagnants après sélection/retry/reroute. Cette projection n’expose ni URL, ni headers, ni body HTTP brut. Une réponse RPC `null` reste `None` dans la valeur observée.
+
+Lorsque `transactionDetails = full` et `encoding = base64`, chaque `SolanaBlockTransaction` conserve le transaction wire Base64, `meta` et `version`. Le consumer peut alors projeter ces DTOs vers sa couche métier sans faire dépendre Transport d’une canonicalisation RAW particulière. Les valeurs Economics restent celles du runtime : le consumer ne doit pas supposer localement un taux d'inflation ou un minimum de délégation constant.
 
 ## 6. Exécution JSON-RPC standard générique
 

crates/ksp-onchain-transport-lib/fixtures/http/get_block.observed_material.success.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","result":{"previousBlockhash":"previous-blockhash-fixture","blockhash":"blockhash-fixture","parentSlot":430000122,"rewards":[],"numRewardPartitions":0,"blockTime":1787072400,"blockHeight":410000000,"transactions":[{"transaction":["AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","base64"],"meta":{"err":null,"fee":5000},"version":"legacy"}]},"id":1}

crates/ksp-onchain-transport-lib/src/rpc_blocks.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
-// version: 7
+// version: 8
 
 const MAX_GET_BLOCKS_RANGE: u64 = 500_000;
 const MAX_GET_RECENT_PERFORMANCE_SAMPLES: u64 = 720;
@@ -591,25 +591,42 @@ impl crate::HttpTransportPool {
         slot: u64,
         config: std::option::Option<&crate::SolanaGetBlockConfig>,
     ) -> ksp_core_lib::Result<std::option::Option<crate::SolanaConfirmedBlock>> {
-        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,
-                    "getBlock commitment must be confirmed or finalized when explicitly provided",
-                )
-                .with_context("rpc_method", "getBlock")
-                .with_context("commitment", "processed"),
-            );
-        }
-        let mut params = std::vec![serde_json::json!(slot)];
-        if let std::option::Option::Some(config) = config {
-            params.push((*config).to_json_value());
-        }
+        let params = get_block_params(slot, config);
+        let params = match params {
+            std::result::Result::Ok(params) => params,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
         return self.execute_get_block(role, params).await;
     }
 
+    /// Executes the current object-form `getBlock` request and reports the safe identity of the endpoint that produced the successful response.
+    ///
+    /// Routing, admission, timeout and retry behavior are identical to [`Self::get_block`]. The returned observation never contains an endpoint URL,
+    /// HTTP headers or a raw HTTP body.
+    pub async fn get_block_observed(
+        &self,
+        role: &crate::HttpRoleName,
+        slot: u64,
+        config: std::option::Option<&crate::SolanaGetBlockConfig>,
+    ) -> ksp_core_lib::Result<crate::HttpObservedValue<std::option::Option<crate::SolanaConfirmedBlock>>> {
+        let params = get_block_params(slot, config);
+        let params = match params {
+            std::result::Result::Ok(params) => params,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let observed = self.execute_blocks_rpc_observed("getBlock", role, params).await;
+        let observed = match observed {
+            std::result::Result::Ok(observed) => observed,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let (value, endpoint_name, provider) = observed.into_parts();
+        let block = decode_get_block(value);
+        return match block {
+            std::result::Result::Ok(block) => std::result::Result::Ok(crate::HttpObservedValue::new(block, endpoint_name, provider)),
+            std::result::Result::Err(error) => std::result::Result::Err(error),
+        };
+    }
+
     /// Executes the deprecated bare-encoding `getBlock` request form retained by Solana RPC for backwards compatibility.
     #[deprecated(note = "use HttpTransportPool::get_block with SolanaGetBlockConfig; the bare encoding request form is deprecated")]
     pub async fn get_block_legacy(
@@ -635,16 +652,8 @@ impl crate::HttpTransportPool {
         params: std::vec::Vec<serde_json::Value>,
     ) -> ksp_core_lib::Result<std::option::Option<crate::SolanaConfirmedBlock>> {
         let value = self.execute_blocks_rpc("getBlock", role, params).await;
-        let value = match value {
-            std::result::Result::Ok(value) => value,
-            std::result::Result::Err(error) => return std::result::Result::Err(error),
-        };
-        if value.is_null() {
-            return std::result::Result::Ok(std::option::Option::None);
-        }
-        let block = crate::SolanaConfirmedBlock::decode_wire("getBlock", value);
-        return match block {
-            std::result::Result::Ok(block) => std::result::Result::Ok(std::option::Option::Some(block)),
+        return match value {
+            std::result::Result::Ok(value) => decode_get_block(value),
             std::result::Result::Err(error) => std::result::Result::Err(error),
         };
     }
@@ -829,6 +838,48 @@ impl crate::HttpTransportPool {
         };
         return self.execute_standard_rpc(role, method, params).await;
     }
+
+    async fn execute_blocks_rpc_observed(
+        &self,
+        method_name: &'static str,
+        role: &crate::HttpRoleName,
+        params: std::vec::Vec<serde_json::Value>,
+    ) -> ksp_core_lib::Result<crate::HttpObservedValue<serde_json::Value>> {
+        let method = blocks_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_observed(role, method, params).await;
+    }
+}
+
+fn decode_get_block(value: serde_json::Value) -> ksp_core_lib::Result<std::option::Option<crate::SolanaConfirmedBlock>> {
+    if value.is_null() {
+        return std::result::Result::Ok(std::option::Option::None);
+    }
+    let block = crate::SolanaConfirmedBlock::decode_wire("getBlock", value);
+    return match block {
+        std::result::Result::Ok(block) => std::result::Result::Ok(std::option::Option::Some(block)),
+        std::result::Result::Err(error) => std::result::Result::Err(error),
+    };
+}
+
+fn get_block_params(slot: u64, config: std::option::Option<&crate::SolanaGetBlockConfig>) -> ksp_core_lib::Result<std::vec::Vec<serde_json::Value>> {
+    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, "getBlock commitment must be confirmed or finalized when explicitly provided")
+                .with_context("rpc_method", "getBlock")
+                .with_context("commitment", "processed"),
+        );
+    }
+    let mut params = std::vec![serde_json::json!(slot)];
+    if let std::option::Option::Some(config) = config {
+        params.push((*config).to_json_value());
+    }
+    return std::result::Result::Ok(params);
 }
 
 #[derive(serde::Deserialize)]

crates/ksp-onchain-transport-lib/tests/public_api.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/tests/public_api.rs
-// version: 49
+// version: 50
 
 //! Integration tests for the public `ksp-onchain-transport-lib` consumer contract.
 
@@ -1021,3 +1021,10 @@ fn public_v0_2_9_pre_010_yellowstone_reconnect_snapshot_is_available_from_crate_
     let _observed = ksp_onchain_transport_lib::YellowstoneGrpcSubscribeSnapshot::last_observed_slot;
     let _terminal = ksp_onchain_transport_lib::YellowstoneGrpcSubscribeSnapshot::terminal_error_code;
 }
+
+#[test]
+fn public_v0_3_10_pre_004_observed_get_block_surface_is_available_from_crate_root() {
+    let method = ksp_onchain_transport_lib::HttpTransportPool::get_block_observed;
+    let _ = method;
+    return;
+}

crates/ksp-onchain-transport-lib/unit_tests/rpc_blocks.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/unit_tests/rpc_blocks.rs
-// version: 6
+// version: 7
 
 #[test]
 fn transaction_details_and_get_block_config_preserve_all_modern_options() {
@@ -188,6 +188,35 @@ fn serve_once(body: &'static str) -> (std::string::String, std::thread::JoinHand
     return (format!("http://{address}"), handle);
 }
 
+fn serve_status_and_count(status_line: &'static str) -> (std::string::String, std::thread::JoinHandle<(usize, 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 first request");
+        let first_request = read_request(&mut stream);
+        let response = format!("HTTP/1.1 {status_line}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
+        std::io::Write::write_all(&mut stream, response.as_bytes()).expect("fixture response must write");
+        let mut count = 1_usize;
+        listener.set_nonblocking(true).expect("fixture listener must become nonblocking");
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(120);
+        while std::time::Instant::now() < deadline {
+            match listener.accept() {
+                std::result::Result::Ok((mut retry_stream, _)) => {
+                    let _ = read_request(&mut retry_stream);
+                    std::io::Write::write_all(&mut retry_stream, response.as_bytes()).expect("fixture retry response must write");
+                    count = count.saturating_add(1);
+                },
+                std::result::Result::Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                    std::thread::sleep(std::time::Duration::from_millis(5));
+                },
+                std::result::Result::Err(error) => panic!("fixture listener failed while counting retries: {error}"),
+            }
+        }
+        return (count, first_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];
@@ -784,3 +813,92 @@ async fn typed_get_block_rejects_processed_commitment_before_io() {
     assert_eq!(error.context()[1].key(), "commitment");
     assert_eq!(error.context()[1].value(), "processed");
 }
+
+#[tokio::test(flavor = "current_thread")]
+async fn pre_004_get_block_observed_reports_actual_winner_after_retry_reroute() {
+    let (first_url, first_handle) = serve_status_and_count("429 Too Many Requests");
+    let (winner_url, winner_handle) = serve_once(include_str!("../fixtures/http/get_block.observed_material.success.json"));
+    let urls = [(first_url.as_str(), "first-endpoint", "first-provider"), (winner_url.as_str(), "winner-endpoint", "winner-provider")];
+    let mut endpoints = std::vec::Vec::with_capacity(urls.len());
+    for (url, endpoint_name, provider) in urls {
+        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),
+        );
+        endpoints.push(crate::HttpEndpointSettings::new(
+            endpoint_name,
+            true,
+            crate::HttpProviderName::new(provider),
+            crate::HttpClusterName::new("local"),
+            crate::HttpEndpointUrl::parse(url).expect("fixture URL must parse"),
+            std::time::Duration::from_millis(100),
+            std::time::Duration::from_secs(1),
+            std::option::Option::Some(1),
+            std::vec![role],
+        ));
+    }
+    let pool = crate::HttpTransportPool::new(crate::HttpTransportSettings::new(
+        endpoints,
+        crate::HttpRetrySettings::new(1, std::time::Duration::from_millis(1), std::time::Duration::from_millis(2)),
+    ))
+    .expect("observed fixture pool must build");
+    let config = crate::SolanaGetBlockConfig::new(
+        std::option::Option::Some(crate::SolanaCommitment::Confirmed),
+        std::option::Option::Some(crate::SolanaTransactionEncoding::Base64),
+        std::option::Option::Some(crate::SolanaTransactionDetails::Full),
+        std::option::Option::Some(0),
+        std::option::Option::Some(false),
+    );
+    let observed = pool
+        .get_block_observed(&crate::HttpRoleName::new("default"), 430_000_123, std::option::Option::Some(&config))
+        .await
+        .expect("retry-safe observed getBlock must succeed on the second endpoint");
+    assert_eq!(observed.endpoint_name(), "winner-endpoint");
+    assert_eq!(observed.provider().as_str(), "winner-provider");
+    let block = observed.value().as_ref().expect("winning response must contain a block");
+    let transactions = block.transactions().value().expect("winning block must contain transactions");
+    assert_eq!(transactions.len(), 1);
+    assert!(matches!(
+        transactions[0].transaction(),
+        crate::SolanaEncodedTransaction::Binary { encoding: crate::SolanaTransactionBinaryEncoding::Base64, .. }
+    ));
+    let rendered = format!("{observed:?}");
+    assert!(rendered.contains("winner-endpoint"));
+    assert!(rendered.contains("winner-provider"));
+    assert!(rendered.contains("<available>"));
+    assert!(!rendered.contains("AQAAAAAAAA"));
+    let (first_count, first_request) = first_handle.join().expect("first fixture server must join");
+    assert_eq!(first_count, 1);
+    assert_eq!(request_body(first_request.as_str())["method"], serde_json::json!("getBlock"));
+    let winner_request = winner_handle.join().expect("winner fixture server must join");
+    assert_eq!(request_body(winner_request.as_str())["method"], serde_json::json!("getBlock"));
+    return;
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn pre_004_get_block_observed_preserves_null_and_reuses_get_block_validation() {
+    let (url, handle) = serve_once(include_str!("../fixtures/http/get_block.null.json"));
+    let pool = pool_for_url(url.as_str());
+    let observed = pool
+        .get_block_observed(&crate::HttpRoleName::new("default"), 430_000_123, std::option::Option::None)
+        .await
+        .expect("observed null getBlock must succeed");
+    assert!(observed.value().is_none());
+    assert_eq!(observed.endpoint_name(), "fixture");
+    assert_eq!(observed.provider().as_str(), "fixture");
+    handle.join().expect("fixture server must join");
+    let processed = crate::SolanaGetBlockConfig::new(
+        std::option::Option::Some(crate::SolanaCommitment::Processed),
+        std::option::Option::Some(crate::SolanaTransactionEncoding::Base64),
+        std::option::Option::Some(crate::SolanaTransactionDetails::Full),
+        std::option::Option::Some(0),
+        std::option::Option::Some(false),
+    );
+    let result = pool.get_block_observed(&crate::HttpRoleName::new("default"), 1, std::option::Option::Some(&processed)).await;
+    let error = result.expect_err("processed observed getBlock commitment must reject before I/O");
+    assert_eq!(error.code(), crate::ERROR_CODE_INVALID_RPC_PARAMETERS);
+    return;
+}

crates/ksp-raw-transaction-lib/Cargo.toml

@@ -1,5 +1,5 @@
 # file: crates/ksp-raw-transaction-lib/Cargo.toml
-# version: 1
+# version: 2
 
 [package]
 name = "ksp-raw-transaction-lib"
@@ -8,6 +8,7 @@ edition.workspace = true
 repository.workspace = true
 
 [dependencies]
+base64.workspace = true
 ksp-core-lib = { path = "../ksp-core-lib" }
 ksp-store-api = { path = "../ksp-store-api" }
 serde_json = { workspace = true }

crates/ksp-raw-transaction-lib/src/canonical.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/src/canonical.rs
-// version: 1
+// version: 2
 
 use sha2::Digest; // rust-rules: trait-import
 
@@ -75,6 +75,26 @@ impl crate::RawTransactionMaterial {
             version,
         };
     }
+
+    /// Creates complete source-neutral RAW v1 material from a Base64 transaction wire that embeds its own canonical signature array.
+    pub fn binary_base64_with_embedded_signature(
+        network: ksp_store_api::RawNetworkId,
+        slot: u64,
+        block_time: std::option::Option<i64>,
+        transaction_data: impl std::convert::Into<std::string::String>,
+        meta: crate::RawTransactionWireField<serde_json::Value>,
+        version: crate::RawTransactionWireField<crate::RawTransactionVersion>,
+        transaction_index: crate::RawTransactionWireField<u32>,
+    ) -> ksp_core_lib::Result<Self> {
+        let transaction_data = transaction_data.into();
+        let signature = crate::extract_raw_transaction_signature_from_binary_base64(transaction_data.as_str());
+        return match signature {
+            std::result::Result::Ok(signature) => {
+                std::result::Result::Ok(Self { block_time, meta, network, signature, slot, transaction_data, transaction_index, version })
+            },
+            std::result::Result::Err(error) => std::result::Result::Err(error),
+        };
+    }
 }
 
 impl std::fmt::Debug for crate::RawTransactionMaterial {

crates/ksp-raw-transaction-lib/src/error.rs

@@ -1,12 +1,12 @@
 // file: crates/ksp-raw-transaction-lib/src/error.rs
-// version: 1
+// version: 2
 
 /// Error code used when RAW v1 canonical payload construction cannot preserve the frozen format contract.
 pub const ERROR_CODE_RAW_TRANSACTION_CANONICALIZATION_INVALID: ksp_core_lib::ErrorCode =
     ksp_core_lib::ErrorCode::new("raw_transaction", "canonicalization_invalid");
 /// Error code used when source-neutral RAW transaction material violates a bounded semantic invariant.
 pub const ERROR_CODE_RAW_TRANSACTION_MATERIAL_INVALID: ksp_core_lib::ErrorCode = ksp_core_lib::ErrorCode::new("raw_transaction", "material_invalid");
-/// Error code used when textual Solana transaction signature material cannot decode to exactly 64 canonical bytes.
+/// Error code used when Solana transaction signature material cannot resolve to exactly 64 canonical bytes.
 pub const ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID: ksp_core_lib::ErrorCode = ksp_core_lib::ErrorCode::new("raw_transaction", "signature_invalid");
 
 /// Creates a safe canonicalization error without copying source payload material.
@@ -21,7 +21,7 @@ pub(crate) fn material_error(field: &'static str) -> ksp_core_lib::Error {
         .with_context("field", field);
 }
 
-/// Creates a safe signature error without copying textual signature material.
+/// Creates a safe signature error without copying source signature or transaction material.
 pub(crate) fn signature_error() -> ksp_core_lib::Error {
     return ksp_core_lib::Error::new(crate::ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID, "invalid canonical Solana transaction signature");
 }

crates/ksp-raw-transaction-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/src/lib.rs
-// version: 1
+// version: 2
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -37,12 +37,14 @@ pub use self::canonical::canonicalize_raw_transaction;
 pub use self::error::ERROR_CODE_RAW_TRANSACTION_CANONICALIZATION_INVALID;
 /// Error code used when source-neutral RAW transaction material violates a bounded semantic invariant.
 pub use self::error::ERROR_CODE_RAW_TRANSACTION_MATERIAL_INVALID;
-/// Error code used when textual Solana transaction signature material cannot decode to exactly 64 canonical bytes.
+/// Error code used when Solana transaction signature material cannot resolve to exactly 64 canonical bytes.
 pub use self::error::ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID;
 /// Maximum UTF-8 byte length admitted for one textual Base58 Solana transaction signature.
 pub use self::signature::MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES;
 /// Minimum UTF-8 byte length admitted for one textual Base58 Solana transaction signature.
 pub use self::signature::MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES;
+/// Extracts the first canonical 64-byte Solana signature from one complete Base64 transaction wire.
+pub use self::signature::extract_raw_transaction_signature_from_binary_base64;
 /// Parses one bounded Base58 Solana transaction signature to exactly 64 canonical bytes.
 pub use self::signature::parse_raw_transaction_signature;
 

crates/ksp-raw-transaction-lib/src/signature.rs

@@ -1,5 +1,7 @@
 // file: crates/ksp-raw-transaction-lib/src/signature.rs
-// version: 1
+// version: 2
+
+use base64::Engine; // rust-rules: trait-import
 
 /// Maximum UTF-8 byte length admitted for one textual Base58 Solana transaction signature.
 pub const MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES: usize = 88;
@@ -50,6 +52,80 @@ pub fn parse_raw_transaction_signature(value: &str) -> ksp_core_lib::Result<ksp_
     return std::result::Result::Ok(ksp_store_api::RawTransactionSignature::new(decoded));
 }
 
+/// Extracts the first canonical 64-byte Solana signature from one complete Base64-encoded transaction wire.
+///
+/// The compact signature-count prefix must use its canonical short-vector representation, contain at least one signature,
+/// and the decoded transaction must retain message bytes after the declared signature array.
+pub fn extract_raw_transaction_signature_from_binary_base64(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
+    if value.is_empty() || value.len() > ksp_store_api::MAX_RAW_PAYLOAD_BYTES {
+        return std::result::Result::Err(crate::signature_error());
+    }
+    let decoded = base64::engine::general_purpose::STANDARD.decode(value);
+    let decoded = match decoded {
+        std::result::Result::Ok(decoded) => decoded,
+        std::result::Result::Err(_) => return std::result::Result::Err(crate::signature_error()),
+    };
+    if base64::engine::general_purpose::STANDARD.encode(decoded.as_slice()) != value {
+        return std::result::Result::Err(crate::signature_error());
+    }
+    let prefix = decode_signature_count(decoded.as_slice());
+    let (signature_count, prefix_len) = match prefix {
+        std::result::Result::Ok(prefix) => prefix,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    if signature_count == 0 {
+        return std::result::Result::Err(crate::signature_error());
+    }
+    let signatures_len = match signature_count.checked_mul(64) {
+        std::option::Option::Some(length) => length,
+        std::option::Option::None => return std::result::Result::Err(crate::signature_error()),
+    };
+    let message_offset = match prefix_len.checked_add(signatures_len) {
+        std::option::Option::Some(offset) => offset,
+        std::option::Option::None => return std::result::Result::Err(crate::signature_error()),
+    };
+    if message_offset >= decoded.len() {
+        return std::result::Result::Err(crate::signature_error());
+    }
+    let first_end = match prefix_len.checked_add(64) {
+        std::option::Option::Some(end) => end,
+        std::option::Option::None => return std::result::Result::Err(crate::signature_error()),
+    };
+    let first = match decoded.get(prefix_len..first_end) {
+        std::option::Option::Some(first) => first,
+        std::option::Option::None => return std::result::Result::Err(crate::signature_error()),
+    };
+    let mut signature = [0_u8; 64];
+    signature.copy_from_slice(first);
+    return std::result::Result::Ok(ksp_store_api::RawTransactionSignature::new(signature));
+}
+
+fn decode_signature_count(bytes: &[u8]) -> ksp_core_lib::Result<(usize, usize)> {
+    let mut value = 0_usize;
+    for index in 0..3_usize {
+        let byte = match bytes.get(index) {
+            std::option::Option::Some(byte) => *byte,
+            std::option::Option::None => return std::result::Result::Err(crate::signature_error()),
+        };
+        let payload = usize::from(byte & 0x7f);
+        let shift = index * 7;
+        value |= payload << shift;
+        if byte & 0x80 == 0 {
+            if index != 0 {
+                let minimum = 1_usize << shift;
+                if value < minimum {
+                    return std::result::Result::Err(crate::signature_error());
+                }
+            }
+            if value > usize::from(u16::MAX) {
+                return std::result::Result::Err(crate::signature_error());
+            }
+            return std::result::Result::Ok((value, index + 1));
+        }
+    }
+    return std::result::Result::Err(crate::signature_error());
+}
+
 fn base58_digit(byte: u8) -> std::option::Option<u8> {
     return match byte {
         b'1'..=b'9' => std::option::Option::Some(byte - b'1'),

crates/ksp-raw-transaction-lib/tests/dependency_boundary.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/tests/dependency_boundary.rs
-// version: 2
+// version: 3
 
 //! Dependency-boundary canaries for the common RAW Transaction foundation.
 
@@ -18,8 +18,9 @@ fn production_sources() -> std::string::String {
 }
 
 #[test]
-fn pre_002_manifest_uses_api_models_and_exact_common_dependencies() {
+fn pre_004_manifest_adds_only_base64_to_the_exact_common_dependency_surface() {
     let manifest = manifest();
+    assert!(manifest.contains("base64.workspace = true"));
     assert!(manifest.contains("ksp-core-lib = { path = \"../ksp-core-lib\" }"));
     assert!(manifest.contains("ksp-store-api = { path = \"../ksp-store-api\" }"));
     assert!(manifest.contains("serde_json = { workspace = true }"));

crates/ksp-raw-transaction-lib/tests/public_api.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/tests/public_api.rs
-// version: 2
+// version: 3
 
 //! Integration canaries for the public common RAW Transaction crate-root surface.
 
@@ -77,3 +77,25 @@ fn pre_002_acquisition_assembly_accepts_store_api_producer_owned_metadata() {
     assert_eq!(acquisition.transaction().reference(), acquisition.observation().transaction());
     return;
 }
+
+#[test]
+fn pre_004_embedded_signature_and_block_material_contract_are_available_from_crate_root() {
+    let encoded = "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+    let signature = ksp_raw_transaction_lib::extract_raw_transaction_signature_from_binary_base64(encoded);
+    assert!(signature.is_ok());
+    let network = ksp_store_api::RawNetworkId::new("devnet");
+    assert!(network.is_ok());
+    if let std::result::Result::Ok(network) = network {
+        let material = ksp_raw_transaction_lib::RawTransactionMaterial::binary_base64_with_embedded_signature(
+            network,
+            1,
+            std::option::Option::None,
+            encoded,
+            ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+            ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+            ksp_raw_transaction_lib::RawTransactionWireField::Value(0),
+        );
+        assert!(material.is_ok());
+    }
+    return;
+}

crates/ksp-raw-transaction-lib/unit_tests/canonical.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/unit_tests/canonical.rs
-// version: 1
+// version: 2
 
 fn network() -> std::option::Option<ksp_store_api::RawNetworkId> {
     return match ksp_store_api::RawNetworkId::new("devnet") {
@@ -217,3 +217,31 @@ fn pre_002_material_and_wire_debug_do_not_render_transaction_or_meta_material()
     assert_eq!(std::format!("{:?}", crate::RawTransactionWireField::Value(secret_meta)), "Value(..)");
     return;
 }
+
+#[test]
+fn pre_004_embedded_signature_material_preserves_block_fields_and_canonicalizes() {
+    let network = match ksp_store_api::RawNetworkId::new("devnet") {
+        std::result::Result::Ok(network) => network,
+        std::result::Result::Err(_) => return,
+    };
+    let material = crate::RawTransactionMaterial::binary_base64_with_embedded_signature(
+        network,
+        430_000_123,
+        std::option::Option::Some(1_787_072_400),
+        "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        crate::RawTransactionWireField::Value(serde_json::json!({"err":null,"fee":5000})),
+        crate::RawTransactionWireField::Value(crate::RawTransactionVersion::Legacy),
+        crate::RawTransactionWireField::Value(0_u32),
+    );
+    assert!(material.is_ok());
+    let transaction = match material.and_then(crate::canonicalize_raw_transaction) {
+        std::result::Result::Ok(transaction) => transaction,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(transaction.reference().signature().as_bytes(), &[0_u8; 64]);
+    assert_eq!(transaction.slot(), 430_000_123);
+    assert_eq!(transaction.block_time().map(|value| return value.unix_millis()), std::option::Option::Some(1_787_072_400_000));
+    assert!(transaction.payload().bytes().starts_with(b"{\"transaction\":[\"AQAAAA"));
+    assert!(transaction.payload().bytes().ends_with(b"\"version\":\"legacy\",\"transactionIndex\":0}"));
+    return;
+}

crates/ksp-raw-transaction-lib/unit_tests/signature.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/unit_tests/signature.rs
-// version: 1
+// version: 2
 
 #[test]
 fn pre_002_signature_parser_accepts_exact_sixty_four_zero_bytes() {
@@ -31,3 +31,32 @@ fn pre_002_signature_parser_rejects_text_bounds_invalid_base58_and_noncanonical_
     }
     return;
 }
+
+#[test]
+fn pre_004_embedded_signature_extracts_first_signature_from_canonical_transaction_base64() {
+    let encoded = "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+    let signature = crate::extract_raw_transaction_signature_from_binary_base64(encoded);
+    assert!(signature.is_ok());
+    if let std::result::Result::Ok(signature) = signature {
+        assert_eq!(signature.as_bytes(), &[0_u8; 64]);
+    }
+    return;
+}
+
+#[test]
+fn pre_004_embedded_signature_rejects_invalid_base64_noncanonical_short_vec_and_truncation() {
+    for encoded in [
+        "not-base64",
+        "gQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+    ] {
+        let result = crate::extract_raw_transaction_signature_from_binary_base64(encoded);
+        assert!(result.is_err());
+        if let std::result::Result::Err(error) = result {
+            assert_eq!(error.code(), crate::ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID);
+            assert!(!error.to_string().contains(encoded));
+        }
+    }
+    return;
+}