miden_node_utils/
limiter.rs

1//! Limits for RPC and store parameters and payload sizes.
2//!
3//! # Rationale
4//! - Parameter limits are kept across all multi-value RPC parameters. This caps worst-case SQL `IN`
5//!   clauses and keeps responses comfortably under the 4 MiB payload budget enforced in the store.
6//! - Limits are enforced both at the RPC boundary and inside the store to prevent bypasses and to
7//!   avoid expensive queries even if validation is skipped earlier in the stack.
8//! - `MAX_PAGINATED_PAYLOAD_BYTES` is set to 4 MiB (e.g. 1000 nullifier rows at ~36 B each, 1000
9//!   transactions summaries streamed in chunks).
10//!
11//! Add new limits here so callers share the same values and rationale.
12
13/// Basic request limit.
14pub const GENERAL_REQUEST_LIMIT: usize = 1000;
15
16#[expect(missing_docs)]
17#[derive(Debug, thiserror::Error)]
18#[error("parameter {which} exceeded limit {limit}: {size}")]
19pub struct QueryLimitError {
20    which: &'static str,
21    size: usize,
22    limit: usize,
23}
24
25/// Checks limits against the desired query parameters, per query parameter and
26/// bails if they exceed a defined value.
27pub trait QueryParamLimiter {
28    /// Name of the parameter to mention in the error.
29    const PARAM_NAME: &'static str;
30    /// Limit that causes a bail if exceeded.
31    const LIMIT: usize;
32    /// Do the actual check.
33    fn check(size: usize) -> Result<(), QueryLimitError> {
34        if size > Self::LIMIT {
35            Err(QueryLimitError {
36                which: Self::PARAM_NAME,
37                size,
38                limit: Self::LIMIT,
39            })?;
40        }
41        Ok(())
42    }
43}
44
45/// Maximum payload size (in bytes) for paginated responses returned by the
46/// store.
47pub const MAX_RESPONSE_PAYLOAD_BYTES: usize = 4 * 1024 * 1024;
48
49/// Used for the following RPC endpoints:
50/// * `sync_transactions`
51///
52/// Capped at 1000 account IDs to keep SQL `IN` clauses bounded and response payloads under the
53/// 4 MB budget.
54pub struct QueryParamAccountIdLimit;
55impl QueryParamLimiter for QueryParamAccountIdLimit {
56    const PARAM_NAME: &str = "account_id";
57    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
58}
59
60/// Used for the following RPC endpoints:
61/// * `select_nullifiers_by_prefix`
62///
63/// Capped at 1000 prefixes to keep queries and responses comfortably within the 4 MB payload
64/// budget and to avoid unbounded prefix scans.
65pub struct QueryParamNullifierPrefixLimit;
66impl QueryParamLimiter for QueryParamNullifierPrefixLimit {
67    const PARAM_NAME: &str = "nullifier_prefix";
68    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
69}
70
71/// Used for the following RPC endpoints:
72/// * `select_nullifiers_by_prefix`
73/// * `sync_nullifiers`
74///
75/// Capped at 1000 nullifiers to bound `IN` clauses and keep response sizes under the 4 MB budget.
76pub struct QueryParamNullifierLimit;
77impl QueryParamLimiter for QueryParamNullifierLimit {
78    const PARAM_NAME: &str = "nullifier";
79    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
80}
81
82/// Used for the following RPC endpoints
83/// * `get_note_sync`
84///
85/// Capped at 1000 tags so note sync responses remain within the 4 MB payload budget.
86pub struct QueryParamNoteTagLimit;
87impl QueryParamLimiter for QueryParamNoteTagLimit {
88    const PARAM_NAME: &str = "note_tag";
89    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
90}
91
92/// Used for the following RPC endpoints
93/// `select_notes_by_id`
94///
95/// The limit is set to 100 notes to keep responses within the 4 MiB payload cap because individual
96/// notes are bounded to roughly 32 KiB.
97pub struct QueryParamNoteIdLimit;
98impl QueryParamLimiter for QueryParamNoteIdLimit {
99    const PARAM_NAME: &str = "note_id";
100    const LIMIT: usize = 100;
101}
102
103/// Used for internal queries retrieving note inclusion proofs by commitment.
104///
105/// Capped at 1000 commitments to keep internal proof lookups bounded and responses under the 4 MB
106/// payload cap.
107pub struct QueryParamNoteCommitmentLimit;
108impl QueryParamLimiter for QueryParamNoteCommitmentLimit {
109    const PARAM_NAME: &str = "note_commitment";
110    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
111}
112
113/// Only used internally, not exposed via public RPC.
114///
115/// Capped at 1000 block headers to bound internal batch operations and keep payloads below the
116/// 4 MB limit.
117pub struct QueryParamBlockLimit;
118impl QueryParamLimiter for QueryParamBlockLimit {
119    const PARAM_NAME: &str = "block_header";
120    const LIMIT: usize = GENERAL_REQUEST_LIMIT;
121}
122
123/// Used for the following RPC endpoints
124/// * `get_account`
125///
126/// Capped at 64 total storage map keys across all slots to limit the number of SMT proofs
127/// returned.
128pub struct QueryParamStorageMapKeyTotalLimit;
129impl QueryParamLimiter for QueryParamStorageMapKeyTotalLimit {
130    const PARAM_NAME: &str = "storage_map_key";
131    const LIMIT: usize = 64;
132}
miden_node_utils/limiter.rs

miden_node_utils/
limiter.rs
