From 4fd4ab4bf8822b79f0f221747868d957cbafa141 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:55:04 +0800 Subject: [PATCH] RPC-201: rand_getScanLeaves is refused by default from v0.9.0, by the node's own version RPC only; no consensus change and no change on a v0.8.x node. The default now follows the release: served before v0.9.0 unless --disable-scan-leaves, refused from v0.9.0 unless the new --enable-scan-leaves (the two together are refused). So the flip the owner decided on 2026-11-05 happens with the version bump. While it serves the method a node logs a warning at its 1st, 2nd, 4th, ... served call since start, the count only, so the journal shows whether wallets before v0.8.3 still scan through it. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01YGaYNQ4cvFtg2UmokVgrAN --- crates/randprotocol-node/src/main.rs | 59 ++++++++++++++++++++++++++-- crates/randprotocol-node/src/rpc.rs | 20 ++++++++++ docs/cli.md | 3 +- docs/rpc.md | 15 ++++--- 4 files changed, 87 insertions(+), 10 deletions(-) diff --git a/crates/randprotocol-node/src/main.rs b/crates/randprotocol-node/src/main.rs index 2ae362e0..97b71f87 100644 --- a/crates/randprotocol-node/src/main.rs +++ b/crates/randprotocol-node/src/main.rs @@ -1019,10 +1019,15 @@ enum Cmd { admission_budget_mb: Option, /// Refuse `rand_getScanLeaves` on both listeners (audit v12, RPC-201). A wallet before /// v0.8.3 scans with it and then fetches only its own leaves, which tells this node which - /// leaves it owns; `rand` v0.8.3+ never calls it. Served by default until the next minor, - /// which flips the default. - #[arg(long)] + /// leaves it owns; `rand` v0.8.3+ never calls it. Served by default before v0.9.0 and + /// refused by default from v0.9.0 on (`--enable-scan-leaves` serves it there). + #[arg(long, conflicts_with = "enable_scan_leaves")] disable_scan_leaves: bool, + /// Serve `rand_getScanLeaves` on a release that refuses it by default (v0.9.0 on), for an + /// operator who still has wallets before v0.8.3 to serve and accepts that the node learns + /// which leaves they own (RPC-201). No effect before v0.9.0, where it is served anyway. + #[arg(long)] + enable_scan_leaves: bool, /// Apply incoming proposals on the consensus loop, as before v0.8.0, instead of on a /// blocking worker (spec 2026-10-11 off-loop apply §4.5): the kill switch. The by-hash /// fetch answer binding is a separate fix and stays on. @@ -3311,6 +3316,7 @@ async fn main() -> Result<()> { max_multisig_accounts, admission_budget_mb, disable_scan_leaves, + enable_scan_leaves, apply_proposals_inline, prover_skip_memory_check, prover_allow_origin, @@ -3364,6 +3370,7 @@ async fn main() -> Result<()> { let admission_budget = admission_budget_mb .map(|mb| usize::try_from(mb).ok().and_then(|mb| mb.checked_mul(1 << 20)).ok_or_else(|| anyhow::anyhow!("--admission-budget-mb {mb} is too large"))) .transpose()?; + let disable_scan_leaves = scan_leaves_refused(disable_scan_leaves, enable_scan_leaves, env!("CARGO_PKG_VERSION")); let rpc_options = node::RpcOptions { public_addr: public_rpc, viewing_token, admission_budget, disable_scan_leaves }; let handle = node::start_with(NodeConfig { viewing_open: rpc_viewing_open, @@ -4665,6 +4672,26 @@ pub fn parse_fluff_prob(s: &str) -> Result { } } +/// RPC-201: whether this node refuses `rand_getScanLeaves`, from its two flags and the release +/// it is (`version`, the crate's `major.minor.patch[-pre]`). `--disable-scan-leaves` refuses and +/// `--enable-scan-leaves` serves, on any release; with neither, a release before v0.9.0 serves +/// (wallets before v0.8.3 still scan with it) and v0.9.0 or later refuses — the owner's decision +/// of 2026-11-05 (monorepo#39), taken by the version so the flip needs no edit at the bump. A +/// version that does not parse refuses. +fn scan_leaves_refused(disable: bool, enable: bool, version: &str) -> bool { + if disable { + return true; + } + if enable { + return false; + } + let mut parts = version.split(['.', '-']).map(|p| p.parse::().ok()); + match (parts.next().flatten(), parts.next().flatten()) { + (Some(major), Some(minor)) => (major, minor) >= (0, 9), + _ => true, + } +} + /// CON-601: `--max-state-proof-tier`, a perps proof tier (`ledger::perps::TIERS`). pub fn parse_state_proof_tier(s: &str) -> Result { let tiers = randprotocol_core::ledger::perps::TIERS; @@ -7441,6 +7468,32 @@ mod prune_flag_tests { assert_eq!(randprotocol_core::gas::GasPolicy::from_prices(gas_price, byte_price), None); } + /// RPC-201, the owner's decision of 2026-11-05: `rand_getScanLeaves` is served by default + /// until v0.9.0 and refused by default from it. The default follows the release's own + /// version, so the flip needs no code change at the bump; either flag overrides it, and the + /// two together are refused at the command line. + #[test] + fn rpc201_scan_leaves_is_refused_by_default_from_v0_9_0() { + use clap::Parser; + for v in ["0.8.6", "0.8.99", "0.8.7-rc1"] { + assert!(!scan_leaves_refused(false, false, v), "{v}: served by default"); + assert!(scan_leaves_refused(true, false, v), "{v}: --disable-scan-leaves"); + assert!(!scan_leaves_refused(false, true, v), "{v}: --enable-scan-leaves changes nothing"); + } + for v in ["0.9.0", "0.9.0-rc1", "0.10.2", "1.0.0"] { + assert!(scan_leaves_refused(false, false, v), "{v}: refused by default"); + assert!(scan_leaves_refused(true, false, v), "{v}"); + assert!(!scan_leaves_refused(false, true, v), "{v}: --enable-scan-leaves serves it"); + } + assert!(scan_leaves_refused(false, false, "not a version"), "unreadable: the private default"); + // This build: before v0.9.0 the method is served unless disabled. + assert_eq!(scan_leaves_refused(false, false, env!("CARGO_PKG_VERSION")), !env!("CARGO_PKG_VERSION").starts_with("0.8.")); + let run = |extra: &[&str]| Cli::try_parse_from(["rand-node", "run", "--datadir", "/tmp/x", "--key", "/tmp/k"].into_iter().chain(extra.iter().copied())); + let Cmd::Run { enable_scan_leaves, .. } = run(&["--enable-scan-leaves"]).unwrap().cmd else { panic!("run") }; + assert!(enable_scan_leaves); + assert!(run(&["--enable-scan-leaves", "--disable-scan-leaves"]).is_err(), "one or the other"); + } + /// RPC-201: `--disable-scan-leaves` parses, and its absence serves the method (the default /// until the next minor). #[test] diff --git a/crates/randprotocol-node/src/rpc.rs b/crates/randprotocol-node/src/rpc.rs index 1f9e5b54..174b8fa8 100644 --- a/crates/randprotocol-node/src/rpc.rs +++ b/crates/randprotocol-node/src/rpc.rs @@ -1802,6 +1802,11 @@ fn parse_limit(params: &Value, idx: usize) -> Result { } } +/// RPC-201: `rand_getScanLeaves` calls this process has served (not the refused ones). Logged at +/// powers of two, so an operator can tell from the journal whether any wallet before v0.8.3 +/// still scans through the node before turning the method off. +pub(crate) static SCAN_LEAVES_SERVED: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + /// An envelope's scan head as `rand_getScanLeaves` serves it: `kem_ct ‖ to_receiver ‖ to_sender`, /// standard base64 with padding. Whatever lengths the parts have — a wallet reads a head of any /// other length than 1 208 bytes in full rather than guessing at its split. @@ -3007,6 +3012,16 @@ async fn dispatch(st: &RpcState, req: &Request) -> Result { data: None, }); } + // RPC-201: who still calls it decides when it can go. No caller is recorded, only + // the count, at 1, 2, 4, 8, … served calls since the node started. + let served = SCAN_LEAVES_SERVED.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1; + if served.is_power_of_two() { + tracing::warn!( + served, + "rand_getScanLeaves served {served} time(s) since start: a wallet before v0.8.3 is scanning through this node, \ + which shows it the leaves that wallet owns (RPC-201; --disable-scan-leaves refuses the method)" + ); + } let from: u64 = param(p, 0, "from_index")?; let limit = parse_limit(p, 1)?; let rows = st.storage.notes_from(from, limit).map_err(RpcError::internal)?; @@ -5465,6 +5480,11 @@ pub(crate) mod tests { let (_d, st, _gs) = chain(); assert!(st.scan_leaves, "served by default for now (wallets before v0.8.3 use it)"); let off = RpcState { scan_leaves: false, ..st.clone() }; + // Only served calls are counted (the counter is the process's, so other tests move it + // too: it never goes down, and a refusal alone does not move it past a served call). + let before = SCAN_LEAVES_SERVED.load(std::sync::atomic::Ordering::Relaxed); + ok(&st, "rand_getScanLeaves", json!([0, 1])).await; + assert!(SCAN_LEAVES_SERVED.load(std::sync::atomic::Ordering::Relaxed) > before, "a served call is counted"); for state in [off.clone(), off.for_public_listener()] { let e = call(&state, "rand_getScanLeaves", json!([0, 100])).await.unwrap_err(); assert_eq!(e.code, -32601, "{}", e.message); diff --git a/docs/cli.md b/docs/cli.md index a303ca6e..55a74fc9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -449,7 +449,8 @@ one the cut announced; a mismatch on one node is almost always an old binary. | `--max-state-proof-tier ` | the highest tier whose key build fits in three quarters of the memory left: the host's RAM, or its cgroup's `memory.high`/`memory.max` if lower, less the node's resident size, re-measured every minute and held at 16 or lower for the first minute after a start (CON-701; 16 from ~1.43 GB left, 18 from ~5.73 GB, 20 from ~22.9 GB — so 14 or 12 on a 2 GB host under `MemoryHigh=85%`, CON-751; on macOS the host's RAM alone) | CON-601: a perps state proof above this tier whose shape the node holds no verifier key for is refused at the pool's pre-screen, before any verification or key build (`StateProofAboveNodeTier`); node policy only, a block carrying one still applies. One of 10, 12, 14, 16, 18, 20 (`docs/perps.md`) | | `--max-multisig-accounts ` | none | MSA-4: once the chain's multisig register holds this many accounts (the genesis-seeded ones included), a `CreateMultisig` is refused at the pool's pre-screen (`MultisigAtNodeCap`: not cached, no peer penalised) and is not verified, pooled, relayed or proposed by this node. Node policy only, for a chain whose genesis sets no `multisig.max_accounts` (chain 21); a block carrying a create still applies (`docs/multisig.md`) | | `--admission-budget-mb ` | 1/16 of the host's RAM, within 64–256 MiB, never under one largest transaction | the admission byte budget (issue #157): RPC request bodies plus transactions waiting for verification. Past it `rand_sendTransaction` answers `-32005` (busy, retry) and gossiped transactions are shed with `Ignore`; a body is charged three times its length, the heap it is measured to hold (OPS-602); a value under one largest transaction (three times the body cap, plus the block cap: 129 MiB on chain 21) is refused at startup (`docs/rpc.md`) | -| `--disable-scan-leaves` | off (the method is served) | refuse `rand_getScanLeaves` on both listeners with `-32601` naming the flag (audit v12, RPC-201). A wallet before v0.8.3 scans with it and then reads only its own leaves, which tells the node which leaves it owns; `rand` v0.8.3+ never calls it. The default flips to off at the next minor (`docs/rpc.md`, `rand_getScanLeaves`) | +| `--disable-scan-leaves` | off (the method is served) | refuse `rand_getScanLeaves` on both listeners with `-32601` naming the flag (audit v12, RPC-201). A wallet before v0.8.3 scans with it and then reads only its own leaves, which tells the node which leaves it owns; `rand` v0.8.3+ never calls it. From v0.9.0 the method is refused without the flag (`docs/rpc.md`, `rand_getScanLeaves`) | +| `--enable-scan-leaves` | off | serve `rand_getScanLeaves` on a release that refuses it by default (v0.9.0 on), for an operator who still serves wallets before v0.8.3 and accepts that the node learns their leaves (RPC-201). No effect before v0.9.0; refused together with `--disable-scan-leaves` | | `--apply-proposals-inline` | off | restore the inline apply: incoming proposals are applied on the consensus loop, as before v0.8.0's off-loop apply; by default the apply runs on a blocking thread (at most 4 at once, up to 8 waiting behind a parent, at most 2 per proposer), with the prechecks, `on_proposal`'s checks and the insert still on the loop (`docs/compute-optimization.md` §3.3). The by-hash fetch answer binding (an answer that is not the block asked for is dropped) is a separate fix and stays on with this flag | | `--prover-skip-memory-check` | off | skip the free-memory gate | | `--prover-fee ` | none | the fee every job sent to the hosted prover must pay, in RAND (display units, up to 9 decimals): one RAND output to `--prover-fee-address` inside the bundle proved; needs `--prover-fee-address`, and only a v3 (split-authorisation) witness can carry it (`docs/prover.md` §3.5) | diff --git a/docs/rpc.md b/docs/rpc.md index 4d361bc7..90366f61 100644 --- a/docs/rpc.md +++ b/docs/rpc.md @@ -313,12 +313,15 @@ its own choice. **Turning it off (audit v12, RPC-201).** Wallets before v0.8.3 still scan with this method, so every node that serves it still learns those wallets' leaves. `rand-node run --disable-scan-leaves` refuses it on both listeners (`-32601`, the message names the flag and asks for rand v0.8.3+); -`rand_getCommitments` is unaffected. **The plan:** served by default in v0.8.x so a wallet -before v0.8.3 keeps scanning; at the next minor (v0.9.0) the default flips to off, with -`--enable-scan-leaves` for an operator who wants it, once the wallet download page has carried -v0.8.3+ for a release cycle. The public RPC deploy template (`deploy/enable-public-rpc.sh`) does -not pass the flag yet: nothing in these docs says the public RPC should break old wallets before -the flip, so that is the operator's call per host until v0.9.0. +`rand_getCommitments` is unaffected. **The default follows the release** (owner's decision of +2026-11-05): a v0.8.x node serves the method unless `--disable-scan-leaves` is passed, so a wallet +before v0.8.3 keeps scanning; a node of v0.9.0 or later refuses it unless `--enable-scan-leaves` +is passed. The node reads its own version for this, so the flip happens with the version bump and +needs no other change. The two flags together are refused. While it serves the method a node +logs a warning at its 1st, 2nd, 4th, 8th, … served call since start (the count only, no caller), +so an operator can see in the journal whether any wallet before v0.8.3 still scans through it +before turning it off. The public RPC deploy template (`deploy/enable-public-rpc.sh`) does not +pass `--disable-scan-leaves`: that is the operator's call per host until v0.9.0. ### `rand_getNullifiers` Params: `[from_height]` or `[from_height, limit]`. Result: every nullifier published from that