v0.3.4-pre.007

2026-08-30 22:47:33 +02:00
parent fccb7d876c
commit 902b5fba99
12 changed files with 904 additions and 16 deletions
--- a/crates/ksp-store-postgres-lib/src/lib.rs
+++ b/crates/ksp-store-postgres-lib/src/lib.rs
@@ -1,5 +1,5 @@
 // file: crates/ksp-store-postgres-lib/src/lib.rs
-// version: 19
+// version: 20

 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -70,10 +70,18 @@ pub(crate) use self::health::probe_health;
 pub(crate) use self::migration::bootstrap;
 /// Current embedded migration version consumed by the private health probe.
 pub(crate) use self::migration::current_migration_version;
+/// Private RAW account cursor decoder consumed by the physical RAW account module.
+pub(crate) use self::raw_account::cursor::decode_raw_account_cursor;
+/// Private RAW account cursor encoder consumed by the physical RAW account module.
+pub(crate) use self::raw_account::cursor::encode_raw_account_cursor;
+/// Private physical account page-limit converter consumed by the physical RAW account module.
+pub(crate) use self::raw_account::cursor::raw_account_physical_page_limit;
 /// Private RAW account observation reader consumed by the physical backend runtime.
 pub(crate) use self::raw_account::get_raw_account_observation;
 /// Private RAW account state reader consumed by the physical backend runtime.
 pub(crate) use self::raw_account::get_raw_account_state;
+/// Private RAW account-state list reader consumed by the physical backend runtime.
+pub(crate) use self::raw_account::list_raw_account_states;
 /// Private atomic RAW account acquisition writer consumed by the physical backend runtime.
 pub(crate) use self::raw_account::persist_raw_account_acquisition;
 /// Private additional RAW account observation writer consumed by the physical backend runtime.
--- a/crates/ksp-store-postgres-lib/src/raw_account.rs
+++ b/crates/ksp-store-postgres-lib/src/raw_account.rs
@@ -1,15 +1,27 @@
 // file: crates/ksp-store-postgres-lib/src/raw_account.rs
-// version: 4
+// version: 5
+
+pub(crate) mod cursor;

 const GET_ACCOUNT_OBSERVATION_SQL: &str = "SELECT observation_key, account_pubkey, account_slot::text AS account_slot_text, account_state_hash, provider, protocol, acquisition_method, origin, received_at_unix_millis, capture_session_id, commitment, endpoint_id, filter_id, observed_at_unix_millis, source_payload_hash, source_payload_size_bytes, is_startup, transaction_signature, write_version::text AS write_version_text FROM ksp_raw_account_observations WHERE observation_key = $1";
 const GET_ACCOUNT_STATE_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash, lamports::text AS lamports_text, owner, executable, rent_epoch::text AS rent_epoch_text, data FROM ksp_raw_account_states WHERE pubkey = $1 AND slot = $2::TEXT::NUMERIC AND state_hash = $3";
 const INSERT_ACCOUNT_OBSERVATION_SQL: &str = "INSERT INTO ksp_raw_account_observations (observation_key, account_pubkey, account_slot, account_state_hash, provider, protocol, acquisition_method, origin, received_at_unix_millis, capture_session_id, commitment, endpoint_id, filter_id, observed_at_unix_millis, source_payload_hash, source_payload_size_bytes, is_startup, transaction_signature, write_version) VALUES ($1, $2, $3::TEXT::NUMERIC, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19::TEXT::NUMERIC) ON CONFLICT (observation_key) DO NOTHING RETURNING observation_key";
 const INSERT_ACCOUNT_STATE_SQL: &str = "INSERT INTO ksp_raw_account_states (pubkey, slot, state_hash, lamports, owner, executable, rent_epoch, data) VALUES ($1, $2::TEXT::NUMERIC, $3, $4::TEXT::NUMERIC, $5, $6, $7::TEXT::NUMERIC, $8) ON CONFLICT (pubkey, slot, state_hash) DO NOTHING RETURNING pubkey";
+const LIST_ACCOUNT_STATES_ASC_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash FROM ksp_raw_account_states WHERE ($1::TEXT IS NULL OR slot >= $1::TEXT::NUMERIC) AND ($2::TEXT IS NULL OR slot <= $2::TEXT::NUMERIC) AND ($3::TEXT IS NULL OR (slot, pubkey, state_hash) > ($3::TEXT::NUMERIC, $4::BYTEA, $5::BYTEA)) ORDER BY slot ASC, pubkey ASC, state_hash ASC LIMIT $6";
+const LIST_ACCOUNT_STATES_BY_PUBKEY_ASC_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash FROM ksp_raw_account_states WHERE pubkey = $1 AND ($2::TEXT IS NULL OR slot >= $2::TEXT::NUMERIC) AND ($3::TEXT IS NULL OR slot <= $3::TEXT::NUMERIC) AND ($4::TEXT IS NULL OR (slot, pubkey, state_hash) > ($4::TEXT::NUMERIC, $5::BYTEA, $6::BYTEA)) ORDER BY slot ASC, pubkey ASC, state_hash ASC LIMIT $7";
+const LIST_ACCOUNT_STATES_BY_PUBKEY_DESC_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash FROM ksp_raw_account_states WHERE pubkey = $1 AND ($2::TEXT IS NULL OR slot >= $2::TEXT::NUMERIC) AND ($3::TEXT IS NULL OR slot <= $3::TEXT::NUMERIC) AND ($4::TEXT IS NULL OR (slot, pubkey, state_hash) < ($4::TEXT::NUMERIC, $5::BYTEA, $6::BYTEA)) ORDER BY slot DESC, pubkey DESC, state_hash DESC LIMIT $7";
+const LIST_ACCOUNT_STATES_DESC_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash FROM ksp_raw_account_states WHERE ($1::TEXT IS NULL OR slot >= $1::TEXT::NUMERIC) AND ($2::TEXT IS NULL OR slot <= $2::TEXT::NUMERIC) AND ($3::TEXT IS NULL OR (slot, pubkey, state_hash) < ($3::TEXT::NUMERIC, $4::BYTEA, $5::BYTEA)) ORDER BY slot DESC, pubkey DESC, state_hash DESC LIMIT $6";
 const LOCK_ACCOUNT_OBSERVATION_SQL: &str = "SELECT observation_key, account_pubkey, account_slot::text AS account_slot_text, account_state_hash, provider, protocol, acquisition_method, origin, received_at_unix_millis, capture_session_id, commitment, endpoint_id, filter_id, observed_at_unix_millis, source_payload_hash, source_payload_size_bytes, is_startup, transaction_signature, write_version::text AS write_version_text FROM ksp_raw_account_observations WHERE observation_key = $1 FOR UPDATE";
 const LOCK_ACCOUNT_REFERENCE_SQL: &str =
    "SELECT 1 FROM ksp_raw_account_states WHERE pubkey = $1 AND slot = $2::TEXT::NUMERIC AND state_hash = $3 FOR KEY SHARE";
 const LOCK_ACCOUNT_STATE_SQL: &str = "SELECT pubkey, slot::text AS slot_text, state_hash, lamports::text AS lamports_text, owner, executable, rent_epoch::text AS rent_epoch_text, data FROM ksp_raw_account_states WHERE pubkey = $1 AND slot = $2::TEXT::NUMERIC AND state_hash = $3 FOR UPDATE";

+struct RawAccountListDbRow {
+    pubkey: std::vec::Vec<u8>,
+    slot_text: std::string::String,
+    state_hash: std::vec::Vec<u8>,
+}
+
 struct RawAccountObservationDbRow {
    account_pubkey: std::vec::Vec<u8>,
    account_slot_text: std::string::String,
@@ -93,6 +105,104 @@ pub(crate) async fn get_raw_account_state(
    return std::result::Result::Ok(std::option::Option::Some(decoded));
 }

+/// Lists deterministic canonical RAW account-state references using PostgreSQL keyset pagination.
+pub(crate) async fn list_raw_account_states(
+    pool: &deadpool_postgres::Pool,
+    network: &ksp_store_api::RawNetworkId,
+    query: &ksp_store_api::RawAccountStateQuery,
+) -> std::result::Result<ksp_store_api::RawPage<ksp_store_api::RawAccountStateReference>, crate::PostgresBackendError> {
+    if query.network() != network {
+        return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::WrongNetwork, "raw_account_list_network"));
+    }
+    let (requested_usize, sql_limit) = match crate::raw_account_physical_page_limit(query.page().limit().get()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let decoded_cursor = match query.page().cursor() {
+        std::option::Option::Some(value) => match crate::decode_raw_account_cursor(query, value) {
+            std::result::Result::Ok(decoded) => std::option::Option::Some(decoded),
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        },
+        std::option::Option::None => std::option::Option::None,
+    };
+    let client_result = pool.get().await;
+    let client = match client_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(crate::map_pool_error(error)),
+    };
+    let slots = query.slots();
+    let start_text = slots.start_inclusive().map(|value| return value.to_string());
+    let end_text = slots.end_inclusive().map(|value| return value.to_string());
+    let cursor_slot_text = decoded_cursor.as_ref().map(|value| return value.last_slot.to_string());
+    let cursor_pubkey = decoded_cursor.as_ref().map(|value| return value.last_pubkey.to_vec());
+    let cursor_state_hash = decoded_cursor.as_ref().map(|value| return value.last_state_hash.to_vec());
+    let rows_result = match query.pubkey() {
+        std::option::Option::Some(pubkey) => {
+            let pubkey_bytes: &[u8] = pubkey.as_ref();
+            let sql = match query.direction() {
+                ksp_store_api::RawSortDirection::Ascending => LIST_ACCOUNT_STATES_BY_PUBKEY_ASC_SQL,
+                ksp_store_api::RawSortDirection::Descending => LIST_ACCOUNT_STATES_BY_PUBKEY_DESC_SQL,
+                _ => {
+                    return std::result::Result::Err(crate::PostgresBackendError::new(
+                        crate::PostgresBackendErrorKind::QueryInvalid,
+                        "raw_account_list_direction",
+                    ));
+                },
+            };
+            client.query(sql, &[&pubkey_bytes, &start_text, &end_text, &cursor_slot_text, &cursor_pubkey, &cursor_state_hash, &sql_limit]).await
+        },
+        std::option::Option::None => {
+            let sql = match query.direction() {
+                ksp_store_api::RawSortDirection::Ascending => LIST_ACCOUNT_STATES_ASC_SQL,
+                ksp_store_api::RawSortDirection::Descending => LIST_ACCOUNT_STATES_DESC_SQL,
+                _ => {
+                    return std::result::Result::Err(crate::PostgresBackendError::new(
+                        crate::PostgresBackendErrorKind::QueryInvalid,
+                        "raw_account_list_direction",
+                    ));
+                },
+            };
+            client.query(sql, &[&start_text, &end_text, &cursor_slot_text, &cursor_pubkey, &cursor_state_hash, &sql_limit]).await
+        },
+    };
+    let rows = match rows_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => {
+            return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::ReadFailed, "raw_account_list_query"));
+        },
+    };
+    let mut decoded = std::vec::Vec::with_capacity(rows.len());
+    for row in rows {
+        let physical = match raw_account_list_db_row(&row) {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let item = match decode_raw_account_list_row(network, physical) {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        decoded.push(item);
+    }
+    let has_more = decoded.len() > requested_usize;
+    if has_more {
+        decoded.truncate(requested_usize);
+    }
+    let next_cursor = if has_more {
+        let last = match decoded.last() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => return std::result::Result::Err(data_invalid("raw_account_list_page")),
+        };
+        match crate::encode_raw_account_cursor(query, last.0, last.1.pubkey(), &last.1.state_hash()) {
+            std::result::Result::Ok(value) => std::option::Option::Some(value),
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        }
+    } else {
+        std::option::Option::None
+    };
+    let items = decoded.into_iter().map(|value| return value.1).collect();
+    return std::result::Result::Ok(ksp_store_api::RawPage::new(items, next_cursor));
+}
+
 /// Reads one persisted RAW account observation by producer-owned idempotence key.
 pub(crate) async fn get_raw_account_observation(
    pool: &deadpool_postgres::Pool,
@@ -235,6 +345,42 @@ pub(crate) async fn record_raw_account_observation(
    return std::result::Result::Ok(outcome);
 }

+fn raw_account_list_db_row(row: &tokio_postgres::Row) -> std::result::Result<RawAccountListDbRow, crate::PostgresBackendError> {
+    let pubkey = match row.try_get::<_, std::vec::Vec<u8>>("pubkey") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(data_invalid("raw_account_list_decode")),
+    };
+    let slot_text = match row.try_get::<_, std::string::String>("slot_text") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(data_invalid("raw_account_list_decode")),
+    };
+    let state_hash = match row.try_get::<_, std::vec::Vec<u8>>("state_hash") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(data_invalid("raw_account_list_decode")),
+    };
+    return std::result::Result::Ok(RawAccountListDbRow { pubkey, slot_text, state_hash });
+}
+
+fn decode_raw_account_list_row(
+    network: &ksp_store_api::RawNetworkId,
+    row: RawAccountListDbRow,
+) -> std::result::Result<(u64, ksp_store_api::RawAccountStateReference), crate::PostgresBackendError> {
+    let pubkey = match fixed_bytes::<32>(row.pubkey, "raw_account_list_pubkey") {
+        std::result::Result::Ok(value) => ksp_store_api::Pubkey::new_from_array(value),
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let slot = match decode_u64_decimal(row.slot_text.as_str(), "raw_account_list_slot") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let state_hash = match fixed_bytes::<32>(row.state_hash, "raw_account_list_state_hash") {
+        std::result::Result::Ok(value) => ksp_store_api::RawContentHash::new(value),
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let reference = ksp_store_api::RawAccountStateReference::new(network.clone(), pubkey, slot, state_hash);
+    return std::result::Result::Ok((slot, reference));
+}
+
 fn raw_account_observation_db_row(row: &tokio_postgres::Row) -> std::result::Result<RawAccountObservationDbRow, crate::PostgresBackendError> {
    let account_pubkey: std::vec::Vec<u8> = match row.try_get("account_pubkey") {
        std::result::Result::Ok(value) => value,
--- a/crates/ksp-store-postgres-lib/src/raw_account/cursor.rs
+++ b/crates/ksp-store-postgres-lib/src/raw_account/cursor.rs
@@ -0,0 +1,230 @@
+// file: crates/ksp-store-postgres-lib/src/raw_account/cursor.rs
+// version: 1
+
+use sha2::Digest; // rust-rules: trait-import
+
+const CURSOR_BYTES: usize = 109;
+const CURSOR_DIGEST_OFFSET: usize = 77;
+const CURSOR_DOMAIN: &[u8] = b"KSP/raw-account-state-cursor/v1";
+const CURSOR_MAGIC: &[u8; 4] = b"KSPA";
+const CURSOR_VERSION: u8 = 1;
+const MAX_POSTGRES_PAGE_LIMIT: u64 = 9_223_372_036_854_775_806;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+/// Decoded backend-private continuation key extracted from one validated RAW account cursor.
+pub(crate) struct RawAccountDecodedCursor {
+    /// Last canonical account pubkey returned by the previous page.
+    pub(crate) last_pubkey: [u8; 32],
+    /// Last canonical account-state hash returned by the previous page.
+    pub(crate) last_state_hash: [u8; 32],
+    /// Last canonical account slot returned by the previous page.
+    pub(crate) last_slot: u64,
+}
+
+/// Decodes and validates one backend-private RAW account cursor against its query binding.
+pub(crate) fn decode_raw_account_cursor(
+    query: &ksp_store_api::RawAccountStateQuery,
+    cursor: &ksp_store_api::RawPageCursor,
+) -> std::result::Result<RawAccountDecodedCursor, crate::PostgresBackendError> {
+    let bytes = cursor.as_bytes();
+    if bytes.len() != CURSOR_BYTES {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_size"));
+    }
+    if bytes.get(0..4) != std::option::Option::Some(CURSOR_MAGIC.as_ref()) {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_magic"));
+    }
+    if bytes.get(4).copied() != std::option::Option::Some(CURSOR_VERSION) {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_version"));
+    }
+    let slot_bytes = match bytes.get(5..13) {
+        std::option::Option::Some(value) => match <[u8; 8]>::try_from(value) {
+            std::result::Result::Ok(decoded) => decoded,
+            std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_slot")),
+        },
+        std::option::Option::None => return std::result::Result::Err(query_invalid("raw_account_cursor_slot")),
+    };
+    let last_slot = u64::from_be_bytes(slot_bytes);
+    let last_pubkey = match bytes.get(13..45) {
+        std::option::Option::Some(value) => match <[u8; 32]>::try_from(value) {
+            std::result::Result::Ok(decoded) => decoded,
+            std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_pubkey")),
+        },
+        std::option::Option::None => return std::result::Result::Err(query_invalid("raw_account_cursor_pubkey")),
+    };
+    let last_state_hash = match bytes.get(45..CURSOR_DIGEST_OFFSET) {
+        std::option::Option::Some(value) => match <[u8; 32]>::try_from(value) {
+            std::result::Result::Ok(decoded) => decoded,
+            std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_state_hash")),
+        },
+        std::option::Option::None => return std::result::Result::Err(query_invalid("raw_account_cursor_state_hash")),
+    };
+    let range_result = validate_slot_in_range(query.slots(), last_slot);
+    if let std::result::Result::Err(error) = range_result {
+        return std::result::Result::Err(error);
+    }
+    let pubkey_result = validate_pubkey_filter(query.pubkey(), &last_pubkey);
+    if let std::result::Result::Err(error) = pubkey_result {
+        return std::result::Result::Err(error);
+    }
+    let expected_digest = match binding_digest(query, last_slot, &last_pubkey, &last_state_hash) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let stored_digest = match bytes.get(CURSOR_DIGEST_OFFSET..CURSOR_BYTES) {
+        std::option::Option::Some(value) => match <[u8; 32]>::try_from(value) {
+            std::result::Result::Ok(decoded) => decoded,
+            std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_digest")),
+        },
+        std::option::Option::None => return std::result::Result::Err(query_invalid("raw_account_cursor_digest")),
+    };
+    if stored_digest != expected_digest {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_binding"));
+    }
+    return std::result::Result::Ok(RawAccountDecodedCursor { last_pubkey, last_state_hash, last_slot });
+}
+
+/// Encodes one backend-private RAW account cursor bound to the supplied query context.
+pub(crate) fn encode_raw_account_cursor(
+    query: &ksp_store_api::RawAccountStateQuery,
+    last_slot: u64,
+    last_pubkey: &ksp_store_api::Pubkey,
+    last_state_hash: &ksp_store_api::RawContentHash,
+) -> std::result::Result<ksp_store_api::RawPageCursor, crate::PostgresBackendError> {
+    let range_result = validate_slot_in_range(query.slots(), last_slot);
+    if let std::result::Result::Err(error) = range_result {
+        return std::result::Result::Err(error);
+    }
+    let pubkey_bytes = match <[u8; 32]>::try_from(last_pubkey.as_ref()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_pubkey")),
+    };
+    let pubkey_result = validate_pubkey_filter(query.pubkey(), &pubkey_bytes);
+    if let std::result::Result::Err(error) = pubkey_result {
+        return std::result::Result::Err(error);
+    }
+    let digest = match binding_digest(query, last_slot, &pubkey_bytes, last_state_hash.as_bytes()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let mut bytes = std::vec::Vec::with_capacity(CURSOR_BYTES);
+    bytes.extend_from_slice(CURSOR_MAGIC);
+    bytes.push(CURSOR_VERSION);
+    bytes.extend_from_slice(&last_slot.to_be_bytes());
+    bytes.extend_from_slice(&pubkey_bytes);
+    bytes.extend_from_slice(last_state_hash.as_bytes());
+    bytes.extend_from_slice(&digest);
+    if bytes.len() != CURSOR_BYTES {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_encode_size"));
+    }
+    return match ksp_store_api::RawPageCursor::try_new(bytes.into_boxed_slice()) {
+        std::result::Result::Ok(value) => std::result::Result::Ok(value),
+        std::result::Result::Err(_) => std::result::Result::Err(query_invalid("raw_account_cursor_encode")),
+    };
+}
+
+/// Converts one caller page size into the exact PostgreSQL LIMIT+1 representation.
+pub(crate) fn raw_account_physical_page_limit(requested: u64) -> std::result::Result<(usize, i64), crate::PostgresBackendError> {
+    if requested > MAX_POSTGRES_PAGE_LIMIT {
+        return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::PageLimitUnsupported, "raw_account_page_limit"));
+    }
+    let requested_usize = match usize::try_from(requested) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => {
+            return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::PageLimitUnsupported, "raw_account_page_limit"));
+        },
+    };
+    let requested_plus_one = match requested.checked_add(1) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => {
+            return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::PageLimitUnsupported, "raw_account_page_limit"));
+        },
+    };
+    let sql_limit = match i64::try_from(requested_plus_one) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => {
+            return std::result::Result::Err(crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::PageLimitUnsupported, "raw_account_page_limit"));
+        },
+    };
+    return std::result::Result::Ok((requested_usize, sql_limit));
+}
+
+fn binding_digest(
+    query: &ksp_store_api::RawAccountStateQuery,
+    last_slot: u64,
+    last_pubkey: &[u8; 32],
+    last_state_hash: &[u8; 32],
+) -> std::result::Result<[u8; 32], crate::PostgresBackendError> {
+    let direction = match query.direction() {
+        ksp_store_api::RawSortDirection::Ascending => 0_u8,
+        ksp_store_api::RawSortDirection::Descending => 1_u8,
+        _ => return std::result::Result::Err(query_invalid("raw_account_cursor_direction")),
+    };
+    let network_len = match u64::try_from(query.network().as_str().len()) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(query_invalid("raw_account_cursor_network")),
+    };
+    let mut hasher = sha2::Sha256::new();
+    hasher.update(CURSOR_DOMAIN);
+    hasher.update(network_len.to_be_bytes());
+    hasher.update(query.network().as_str().as_bytes());
+    hash_optional_pubkey(&mut hasher, query.pubkey());
+    hasher.update([direction]);
+    hash_optional_slot(&mut hasher, query.slots().start_inclusive());
+    hash_optional_slot(&mut hasher, query.slots().end_inclusive());
+    hasher.update(last_slot.to_be_bytes());
+    hasher.update(last_pubkey);
+    hasher.update(last_state_hash);
+    let finalized = hasher.finalize();
+    let mut digest = [0_u8; 32];
+    digest.copy_from_slice(finalized.as_ref());
+    return std::result::Result::Ok(digest);
+}
+
+fn hash_optional_pubkey(hasher: &mut sha2::Sha256, value: std::option::Option<&ksp_store_api::Pubkey>) {
+    match value {
+        std::option::Option::Some(pubkey) => {
+            hasher.update([1_u8]);
+            hasher.update(pubkey.as_ref());
+        },
+        std::option::Option::None => hasher.update([0_u8]),
+    }
+    return;
+}
+
+fn hash_optional_slot(hasher: &mut sha2::Sha256, value: std::option::Option<u64>) {
+    match value {
+        std::option::Option::Some(slot) => {
+            hasher.update([1_u8]);
+            hasher.update(slot.to_be_bytes());
+        },
+        std::option::Option::None => hasher.update([0_u8]),
+    }
+    return;
+}
+
+fn query_invalid(phase: &'static str) -> crate::PostgresBackendError {
+    return crate::PostgresBackendError::new(crate::PostgresBackendErrorKind::QueryInvalid, phase);
+}
+
+fn validate_pubkey_filter(filter: std::option::Option<&ksp_store_api::Pubkey>, last_pubkey: &[u8; 32]) -> std::result::Result<(), crate::PostgresBackendError> {
+    if let std::option::Option::Some(pubkey) = filter
+        && pubkey.as_ref() != last_pubkey.as_slice()
+    {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_pubkey_filter"));
+    }
+    return std::result::Result::Ok(());
+}
+
+fn validate_slot_in_range(range: ksp_store_api::RawSlotRange, slot: u64) -> std::result::Result<(), crate::PostgresBackendError> {
+    if let std::option::Option::Some(start) = range.start_inclusive()
+        && slot < start
+    {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_slot_range"));
+    }
+    if let std::option::Option::Some(end) = range.end_inclusive()
+        && slot > end
+    {
+        return std::result::Result::Err(query_invalid("raw_account_cursor_slot_range"));
+    }
+    return std::result::Result::Ok(());
+}
--- a/crates/ksp-store-postgres-lib/src/runtime.rs
+++ b/crates/ksp-store-postgres-lib/src/runtime.rs
@@ -1,5 +1,5 @@
 // file: crates/ksp-store-postgres-lib/src/runtime.rs
-// version: 13
+// version: 14

 const APPLICATION_NAME: &str = "ksp-store";
 const MAX_CONNECTION_URI_BYTES: usize = 4_096;
@@ -340,6 +340,14 @@ impl PostgresBackend {
        return crate::get_raw_account_state(&self.pool, &self.network, reference).await;
    }

+    /// Lists deterministic canonical RAW account-state references with a backend-owned opaque continuation cursor.
+    pub async fn list_raw_account_states(
+        &self,
+        query: &ksp_store_api::RawAccountStateQuery,
+    ) -> std::result::Result<ksp_store_api::RawPage<ksp_store_api::RawAccountStateReference>, crate::PostgresBackendError> {
+        return crate::list_raw_account_states(&self.pool, &self.network, query).await;
+    }
+
    /// Reads one persisted RAW account observation by producer-owned idempotence key.
    pub async fn get_raw_account_observation(
        &self,