From ec02ef6f7872cdf3ac470ea7aee2e62f511c4f14 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 20:45:32 +0000 Subject: [PATCH 001/102] doc: remove stale NotInPreparePhase claim on get_nakamoto_reward_cycle_info Commit 480c59a (2024-05-30) removed the `if !burnchain.is_in_prepare_phase(burn_height) { return Err(Error::NotInPreparePhase); }` branch from get_nakamoto_reward_cycle_info, but left the doc comment claiming `Returns Err(Error::NotInPreparePhase) if `burn_height` is not in the prepare phase`. The function never constructs that variant; the caller passes a reward cycle (not a burn height) and the burn height is derived internally as the first block of the cycle. --- stackslib/src/chainstate/nakamoto/coordinator/mod.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs index 0e17267361f..d2e9e175c86 100644 --- a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs +++ b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs @@ -293,7 +293,6 @@ fn find_prepare_phase_sortitions( /// /// Returns Ok(Some(reward-cycle-info)) if we found the first sortition in the prepare phase. /// Returns Ok(None) if we're still waiting for the PoX anchor block sortition -/// Returns Err(Error::NotInPreparePhase) if `burn_height` is not in the prepare phase pub fn get_nakamoto_reward_cycle_info( sortition_tip: &SortitionId, reward_cycle: u64, From 32a0a42939e53cb8927903f73f7ff6eb228b296c Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 20:51:33 +0000 Subject: [PATCH 002/102] doc: remove stale 'invalid slot' error claim on get_miner_slot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit 7c7f9b3 (2024-07-26, 'feat: support multi-miner integration test') replaced the fallible `u32::try_from(i).map_err(...)` slot-id conversion in get_miner_slot with `signer_ranges.swap_remove(signer_ix)` on a precomputed `Vec>`. After that refactor the function returns Ok(None) for every internal failure mode; the only Err path is upstream propagation from `make_miners_stackerdb_config(...)?`, which has nothing to do with the slot number being invalid. The doc-comment's fourth bullet — 'Returns an error if the miner is in the StackerDB config but the slot number is invalid' — no longer corresponds to any branch in the body. --- stackslib/src/chainstate/nakamoto/mod.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index a0112f49feb..947c0641448 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -5234,7 +5234,6 @@ impl NakamotoChainState { /// Returns Some(Range) if the miner is in the StackerDB config, where the range of slots for the miner is [start, end). /// i.e., inclusive of `start`, exclusive of `end`. /// Returns None if the miner is not in the StackerDB config. - /// Returns an error if the miner is in the StackerDB config but the slot number is invalid. pub fn get_miner_slot( sortdb: &SortitionDB, tip: &BlockSnapshot, From bccd1e31876c24862aa90aa01c8dc92eddc8b162 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 20:58:44 +0000 Subject: [PATCH 003/102] doc: correct bind() comment to reflect panic-on-failure behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit 16f8973 (2023-09-13, 'use tiny http instead of hand rolled') replaced the fallible `TcpListener::bind(listener)?` setup with `HttpServer::http(listener).expect("failed to start HttpServer")`. After that change the bind() implementation never constructs an Err: it always returns Ok(listener), and a failure inside HttpServer::http panics. The doc-comment still claims 'Errors out if bind(2) fails', which is false — bind(2) failure panics the thread instead of being returned to the caller. This may also warrant a code-level fix: callers (e.g. libsigner's runloop.rs:224) propagate the result with `?`, suggesting they expect to handle a bind failure rather than crash. Documenting the current behavior accurately is the conservative comment-only change; restoring fallibility is a separate design decision. --- libsigner/src/events.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/events.rs b/libsigner/src/events.rs index 44775497249..71e4c593421 100644 --- a/libsigner/src/events.rs +++ b/libsigner/src/events.rs @@ -400,7 +400,7 @@ impl EventReceiver for SignerEventReceiver { /// Start listening on the given socket address. /// Returns the address that was bound. - /// Errors out if bind(2) fails + /// Panics if `HttpServer::http()` fails to bind to the listener address. fn bind(&mut self, listener: SocketAddr) -> Result { self.http_server = Some(HttpServer::http(listener).expect("failed to start HttpServer")); self.local_addr = Some(listener); From 1bee65f2516230796ddb23b31afdd0c897d9d23f Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:01:40 +0000 Subject: [PATCH 004/102] doc: correct LeaderBlockCommitOp::check return claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The comment 'Returns Ok() and a vector of PoxAddresses which were punished by this op' was added in commit e721bd5 (2024-06-03) when the punishment-via-bitvec feature was added. It misdescribes the function: the signature is Result<(), op_error> (returns the unit type, not a vector); the vector that the comment refers to is stored as a side effect in self.treatment (renamed from self.punished in commit 3fcd23f, 2024-06-10), and its element type is Vec, not Vec — Treatment is an enum {Reward, Punish}, so the vector contains both reward AND punishment addresses, not only 'punished' ones. Replace with an accurate one-liner that describes the side-effect-on-self path. --- .../src/chainstate/burn/operations/leader_block_commit.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/burn/operations/leader_block_commit.rs b/stackslib/src/chainstate/burn/operations/leader_block_commit.rs index 26641d5c11b..d229ad1acb6 100644 --- a/stackslib/src/chainstate/burn/operations/leader_block_commit.rs +++ b/stackslib/src/chainstate/burn/operations/leader_block_commit.rs @@ -1042,7 +1042,9 @@ impl LeaderBlockCommitOp { Ok(()) } - /// Returns Ok() and a vector of PoxAddresses which were punished by this op + /// Validates this block-commit. On success, records how each PoX address in the reward set + /// was treated by this op (reward or punishment) in `self.treatment` — but only when + /// `reward_set_info.allow_nakamoto_punishment` is true. pub fn check( &mut self, burnchain: &Burnchain, From c70db22948991c8852dafbb5d7d723067ffe49e1 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:07:48 +0000 Subject: [PATCH 005/102] doc: correct increase_lock_v{2,3,4} panic/version claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three doc-comments on STXBalanceSnapshot::increase_lock_v* misdescribe the function behavior: * increase_lock_v2 (line 547): comment claims 'Panics if self was not locked by V2 PoX'. Commit 139ed665 (2024-01-17, mislabeled as 'chore: cargo fmt') replaced the panic! with return Err(InterpreterError::Expect(...)). The function returns an error; it no longer panics. * increase_lock_v3 (line 766): same pattern. Body returns Err(VmInternalError::Expect(...)) on the !is_v3_locked() branch; the doc still claims a panic. * increase_lock_v4 (line 892): the function body does panic on !is_v4_locked(), but the doc-comment says 'V3 PoX'. Off-by-one PoX version in the doc — fix the version, keep the 'Panics' claim (which is accurate for this function). Three minimum-touch doc edits, no behavior change. --- clarity/src/vm/database/structures.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs index 9741f3fb4ff..783df493de1 100644 --- a/clarity/src/vm/database/structures.rs +++ b/clarity/src/vm/database/structures.rs @@ -544,7 +544,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> { } /// Increase the account's current lock to `new_total_locked`. - /// Panics if `self` was not locked by V2 PoX. + /// Returns Err(VmInternalError::Expect) if `self` was not locked by V2 PoX. pub fn increase_lock_v2(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> { let unlocked = self.unlock_available_tokens_if_any()?; if unlocked > 0 { @@ -763,7 +763,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> { } /// Increase the account's current lock to `new_total_locked`. - /// Panics if `self` was not locked by V3 PoX. + /// Returns Err(VmInternalError::Expect) if `self` was not locked by V3 PoX. pub fn increase_lock_v3(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> { let unlocked = self.unlock_available_tokens_if_any()?; if unlocked > 0 { @@ -889,7 +889,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> { } /// Increase the account's current lock to `new_total_locked`. - /// Panics if `self` was not locked by V3 PoX. + /// Panics if `self` was not locked by V4 PoX. pub fn increase_lock_v4(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> { let unlocked = self.unlock_available_tokens_if_any()?; if unlocked > 0 { From db4a2ffbdeaabfac6a3c02196dda45e5a0dd913b Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:14:32 +0000 Subject: [PATCH 006/102] doc: correct main_loop comment about run_one_pass return value SignerRunLoop trait's run_one_pass method returns Option, but main_loop's doc-comment claims the loop continues until `run_one_pass()` returns 'false'. The loop body actually checks 'if let Some(final_state) = self.run_one_pass(...)' and exits on the Some(R) variant. The comment has been wrong since the libsigner crate was introduced in commit 4e306ce (2023-08-28); the function was declared as returning Option from the start, so the 'false' in the doc was always inconsistent with the type signature. --- libsigner/src/runloop.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/runloop.rs b/libsigner/src/runloop.rs index f66ec9bdbf9..67b2875e929 100644 --- a/libsigner/src/runloop.rs +++ b/libsigner/src/runloop.rs @@ -52,7 +52,7 @@ pub trait SignerRunLoop { /// This is the main loop body for the signer. It continuously receives events from /// `event_recv`, polling for up to `self.get_event_timeout()` units of time. Once it has /// polled for events, they are fed into `run_one_pass()`. This continues until either - /// `run_one_pass()` returns `false`, or the event receiver hangs up. At this point, this + /// `run_one_pass()` returns `Some(R)`, or the event receiver hangs up. At this point, this /// method calls the `event_stop_signaler.send()` to terminate the receiver. /// /// This would run in a separate thread from the event receiver. From 5480ee70d50a542a5b11f7c47dfd60ad3c634af3 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:17:32 +0000 Subject: [PATCH 007/102] doc: correct make_block_commit return-on-failure claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit make_block_commit's doc-comment says 'Returns None if we fail somehow' but the function signature is Result: failure paths in the body all construct Err(NakamotoNodeError::...), never Ok(None). The 'on success' line also described the return as a tuple of three values when the actual return type is a 7-field struct (LastCommit) — replace with an accurate description of LastCommit's relevant fields. --- stacks-node/src/nakamoto_node/relayer.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stacks-node/src/nakamoto_node/relayer.rs b/stacks-node/src/nakamoto_node/relayer.rs index 6b0bdea184e..6d966224f7d 100644 --- a/stacks-node/src/nakamoto_node/relayer.rs +++ b/stacks-node/src/nakamoto_node/relayer.rs @@ -1062,8 +1062,9 @@ impl RelayerThread { /// /// Takes the Nakamoto chain tip (consensus hash, block header hash). /// - /// Returns the (the most recent burn snapshot, the most recent stakcs tip, the commit-op) on success - /// Returns None if we fail somehow. + /// Returns Ok(LastCommit) on success — its block_commit/burn_tip/stacks_tip + /// fields are the most recent commit-op, burn snapshot, and stacks tip. + /// Returns Err(NakamotoNodeError) if we fail somehow. /// /// TODO: unit test pub(crate) fn make_block_commit( From 7225f7ad6e6fc4c984ceacb5cb1e520eb24a9aec Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:19:47 +0000 Subject: [PATCH 008/102] doc: correct canonical_repr_at_block to reflect enum STXBalance The doc-comment claimed the canonicalized return is a struct with amount_unlocked = 0 and unlock_height = 0. STXBalance was a struct with those fields until commit 44cbd41 (2022-12-22, 'import clarity again'), which converted it into an enum with variants {Unlocked, LockedPoxOne, LockedPoxTwo, ...}. The body of canonical_repr_at_block now returns STXBalance::Unlocked { amount }, which has no amount_unlocked / unlock_height fields. Replace the comment's description with the actual return shape. --- clarity/src/vm/database/structures.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs index 783df493de1..2651b59872b 100644 --- a/clarity/src/vm/database/structures.rs +++ b/clarity/src/vm/database/structures.rs @@ -1159,9 +1159,9 @@ impl STXBalance { } /// Returns a canonicalized STXBalance at a given burn_block_height - /// (i.e., if burn_block_height >= unlock_height, then return struct where - /// amount_unlocked = 0, unlock_height = 0), and the amount of tokens which - /// are "unlocked" by the canonicalization + /// (i.e., if burn_block_height >= unlock_height, then return + /// STXBalance::Unlocked { amount: total_balance }), and the amount of + /// tokens which are "unlocked" by the canonicalization. pub fn canonical_repr_at_block( &self, burn_block_height: u64, From 4ade2f63d6b017d917dec705938e705d80236e75 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:25:18 +0000 Subject: [PATCH 009/102] doc: get_block_processed_and_signed_weight does not filter on orphaned MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc-comment claimed the function returns the non-orphaned block, but the SQL query 'SELECT index_block_hash,processed,orphaned,signing_weight FROM nakamoto_staging_blocks WHERE consensus_hash = ?1 AND block_hash = ?2 ORDER BY signing_weight DESC, index_block_hash LIMIT 1' has no orphaned filter. The function returns the orphan flag in its tuple, and the caller in store_block_if_better (line 629) destructures and checks the flag — proving the function does return orphaned matches. Reword the doc to describe the actual behavior. --- stackslib/src/chainstate/nakamoto/staging_blocks.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/staging_blocks.rs b/stackslib/src/chainstate/nakamoto/staging_blocks.rs index 1a08778d14b..889227287cc 100644 --- a/stackslib/src/chainstate/nakamoto/staging_blocks.rs +++ b/stackslib/src/chainstate/nakamoto/staging_blocks.rs @@ -279,9 +279,10 @@ impl<'a> NakamotoStagingBlocksConnRef<'a> { Ok(res.is_some()) } - /// Get the block ID, processed-status, orphan-status, and signing weight of the non-orphaned + /// Get the block ID, processed-status, orphan-status, and signing weight of the /// block with the given consensus hash and sighash with the most amount of signatures. - /// There will be at most one such block. + /// There will be at most one such block. The returned `orphaned` flag lets the caller + /// decide how to handle an orphaned match — the query does not filter on it. /// /// NOTE: for Nakamoto blocks, the sighash is the same as the block hash. pub fn get_block_processed_and_signed_weight( From 296011bd710e16fe11191cb12e2f8e914ef5d34c Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:30:38 +0000 Subject: [PATCH 010/102] doc: process_new_anchored_block returns BlockAcceptResponse not bool Doc claimed Ok(true)/Ok(false) but the function returns Result, with variants Accepted, AlreadyStored, and Rejected(String). The bool->enum refactor in commit 3a0bc7ae6e (2024-09-11, 'chore: have block acceptance return a BlockAcceptResult instead of a bool') changed the return type but left the doc-comment unchanged. Rewrite the doc to describe the actual variants returned. --- stackslib/src/net/relay.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/stackslib/src/net/relay.rs b/stackslib/src/net/relay.rs index 9ba52461138..5a929554c4f 100644 --- a/stackslib/src/net/relay.rs +++ b/stackslib/src/net/relay.rs @@ -778,7 +778,10 @@ impl Relayer { /// Insert a staging block that got relayed to us somehow -- e.g. uploaded via http, downloaded /// by us, or pushed via p2p. - /// Return Ok(true) if we stored it, Ok(false) if we didn't + /// Returns `Ok(BlockAcceptResponse::Accepted)` if the block was newly stored, + /// `Ok(BlockAcceptResponse::AlreadyStored)` if we already had it, + /// `Ok(BlockAcceptResponse::Rejected(reason))` if it was rejected, and + /// `Err(..)` on DB or chainstate errors. pub fn process_new_anchored_block( sort_ic: &SortitionDBConn, chainstate: &mut StacksChainState, From cf9a580460d8511c0be6adac8036d34a7de92d85 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:31:57 +0000 Subject: [PATCH 011/102] doc: process_new_nakamoto_block_ext returns BlockAcceptResponse not bool Doc claimed Ok(true)/Ok(false) but the function returns Result. When force_broadcast is true and the block is already known, the function returns BlockAcceptResponse::Accepted; when force_broadcast is false and the block is already known, it returns BlockAcceptResponse::AlreadyStored. The bool->enum refactor in commit 3a0bc7ae6e (2024-09-11) changed both return paths but the doc-comment still describes the old bool contract. Rewrite the success/no-broadcast lines to describe the actual variants returned. Preserve the Err: list verbatim. --- stackslib/src/net/relay.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/stackslib/src/net/relay.rs b/stackslib/src/net/relay.rs index 5a929554c4f..57bc7ca868a 100644 --- a/stackslib/src/net/relay.rs +++ b/stackslib/src/net/relay.rs @@ -880,10 +880,12 @@ impl Relayer { /// Insert a staging Nakamoto block that got relayed to us somehow -- e.g. uploaded via http, /// downloaded by us, or pushed via p2p. - /// Return Ok(true) if we should broadcast the block. If force_broadcast is true, then this - /// function will return Ok(true) even if we already have the block. - /// Return Ok(false) if we should not broadcast it (e.g. we already have it, it was invalid, - /// etc.) + /// Returns `Ok(BlockAcceptResponse::Accepted)` if the block was newly stored (or if + /// `force_broadcast` is true and we already have it). + /// Returns `Ok(BlockAcceptResponse::AlreadyStored)` if we already have the block (and + /// `force_broadcast` is false), or if `accept_block` returned `false`. + /// Returns `Ok(BlockAcceptResponse::Rejected(reason))` if the block was rejected + /// (fault-injected, problematic AST, etc.). /// Return Err(..) in the following cases, beyond DB errors: /// * If the block is from a tenure we don't recognize /// * If we're not in the Nakamoto epoch From 1d280f3a674bb81f882ae4281d93b384f326d54c Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:36:33 +0000 Subject: [PATCH 012/102] doc: preprocess_anchored_block refers to non-existent SortitionDB::expects_stacks_block Doc-comment said 'Caller must have called SortitionDB::expects_stacks_block()'. SortitionDB::expects_stacks_block exists nowhere in the repo. The function with the equivalent semantic (does the chain expect a block with this hash on this fork?) is SortitionHandleTx::expects_stacks_block_in_fork (sortdb.rs:1361). At commit c3212fb639 (2018-vintage) both 'expects_stacks_block' and 'expects_stacks_block_in_fork' existed on BurnDB; the non-fork variant was removed in subsequent refactors but the comment never followed. Rename in the doc to point readers at the real function. --- stackslib/src/chainstate/stacks/db/blocks.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index 8f15deb9289..aadd203ded1 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -3265,9 +3265,9 @@ impl StacksChainState { /// Pre-process and store an anchored block to staging, queuing it up for /// subsequent processing once all of its ancestors have been processed. /// - /// Caller must have called SortitionDB::expects_stacks_block() to determine if this block belongs - /// to the blockchain. The consensus_hash is the hash of the burnchain block whose sortition - /// elected the given Stacks block. + /// Caller must have called SortitionHandleTx::expects_stacks_block_in_fork() to determine if + /// this block belongs to the blockchain. The consensus_hash is the hash of the burnchain block + /// whose sortition elected the given Stacks block. /// /// If we find the same Stacks block in two or more burnchain forks, insert it there too. /// From 2fd61cb291848bc7bf0a67c221f7ecac62c8c789 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:44:46 +0000 Subject: [PATCH 013/102] doc: as_block_rejection doc says 'block accept' but extracts rejection The doc-comment on as_block_rejection() said 'Get the block accept data from the block response' (identical to the doc on the preceding as_block_accepted()). The function actually extracts the rejection case: matches BlockResponse::Rejected(rejection) and returns Option<&BlockRejection>. The comment was wrong from introduction in commit 7519cdb197 (2024-12-18) - clear copy-paste from the sibling. Rename 'accept' to 'rejection' in the doc. --- libsigner/src/v0/messages.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/v0/messages.rs b/libsigner/src/v0/messages.rs index 8220a3e99f4..bf6dbb6a975 100644 --- a/libsigner/src/v0/messages.rs +++ b/libsigner/src/v0/messages.rs @@ -1412,7 +1412,7 @@ impl BlockResponse { } } - /// Get the block accept data from the block response + /// Get the block rejection data from the block response pub fn as_block_rejection(&self) -> Option<&BlockRejection> { match self { BlockResponse::Rejected(rejection) => Some(rejection), From 367685fe8621556e5d522a18a12c47cf025630f7 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:47:41 +0000 Subject: [PATCH 014/102] doc: rotate_vrf_and_register doc claims bool return but function returns () MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc-comment said 'Returns true if we succeed in doing so; false if not.' The function signature has no return type — it returns (). Both the early no-op path (line 1029, 'return;') and the success path (line 1058) return implicitly with no value. Callers cannot observe success or failure from this method. The doc has been wrong since the function was authored in cfd1a123a9c (2023-12-04). Rewrite to describe the actual behavior: silent no-op on either already-in-flight or submission failure. --- stacks-node/src/nakamoto_node/relayer.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stacks-node/src/nakamoto_node/relayer.rs b/stacks-node/src/nakamoto_node/relayer.rs index 6d966224f7d..4d54fe26d64 100644 --- a/stacks-node/src/nakamoto_node/relayer.rs +++ b/stacks-node/src/nakamoto_node/relayer.rs @@ -1022,7 +1022,8 @@ impl RelayerThread { } /// Create and broadcast a VRF public key registration transaction. - /// Returns true if we succeed in doing so; false if not. + /// No-ops (without indicating failure) if a registration is already in-flight or if the + /// underlying bitcoin submission fails — callers cannot observe success from this method. pub fn rotate_vrf_and_register(&mut self, burn_block: &BlockSnapshot) { if self.last_vrf_key_burn_height.is_some() { // already in-flight From 56ae04de4a7dd6b8603bfb9ea3fc5ca95532b6b2 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:48:43 +0000 Subject: [PATCH 015/102] doc: process_new_nakamoto_block refers to non-existent inner_process_new_nakamoto_block Doc said 'Wrapper around inner_process_new_nakamoto_block' but inner_process_new_nakamoto_block has never existed in the repo (grep returns only the doc reference). The wrapper actually calls process_new_nakamoto_block_ext with force_broadcast=false. The doc has been wrong since the wrapper was introduced in commit 21fc76d4d9 (2024-08-14, 'feat: allow forced block broadcast'). Replace with the actual callee name. --- stackslib/src/net/relay.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/net/relay.rs b/stackslib/src/net/relay.rs index 57bc7ca868a..edaabba46e7 100644 --- a/stackslib/src/net/relay.rs +++ b/stackslib/src/net/relay.rs @@ -854,7 +854,7 @@ impl Relayer { } } - /// Wrapper around inner_process_new_nakamoto_block + /// Wrapper around `process_new_nakamoto_block_ext` that pins `force_broadcast` to `false`. pub fn process_new_nakamoto_block( burnchain: &Burnchain, sortdb: &SortitionDB, From 6a3354e7e3b140716476d8efb2dec28ceaf68d5b Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:54:56 +0000 Subject: [PATCH 016/102] doc: total_signing_weight returns Result not ChainstateError The doc-comment said 'a ChainstateError is returned' but the function signature is Result. The Err arm at line 324 returns Err('Unable to calculate total weight - No signers in reward set'.to_string()). ChainstateError is not in the return type and is not constructed in the body. Author may have intended ChainstateError originally but the function shipped with String in commit f963b354ed0 (2024-05-30). Update the doc to describe the actual error type. --- stackslib/src/chainstate/stacks/boot/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/boot/mod.rs b/stackslib/src/chainstate/stacks/boot/mod.rs index 9aa20c9220f..ee784d6cc64 100644 --- a/stackslib/src/chainstate/stacks/boot/mod.rs +++ b/stackslib/src/chainstate/stacks/boot/mod.rs @@ -318,7 +318,7 @@ impl RewardSet { } /// Return the total `weight` of all signers in the reward set. - /// If there are no reward set signers, a ChainstateError is returned. + /// If there are no reward set signers, returns `Err(String)` describing the failure. pub fn total_signing_weight(&self) -> Result { let Some(ref reward_set_signers) = self.signers else { return Err("Unable to calculate total weight - No signers in reward set".to_string()); From 3daae56f294c0f09e59d7a7954372d943948d4e1 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:58:31 +0000 Subject: [PATCH 017/102] doc: MARF::seal returns Err on already-sealed, does not panic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc-comment said 'Runtime-panics if the MARF was already sealed.' The function signature is Result and the body explicitly returns Err(Error::ReadOnlyError) when self.storage.readonly() is true — i.e. exactly the already-sealed precondition the doc names. Doc has been wrong since the function was introduced in 4e1a88add6 (2022-02-10). Replace the panic claim with the actual Err variant. --- stackslib/src/chainstate/stacks/index/marf.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/index/marf.rs b/stackslib/src/chainstate/stacks/index/marf.rs index 4d9b71325ff..93f6a3b0505 100644 --- a/stackslib/src/chainstate/stacks/index/marf.rs +++ b/stackslib/src/chainstate/stacks/index/marf.rs @@ -690,7 +690,7 @@ impl<'a, T: MarfTrieId> MarfTransaction<'a, T> { /// Seal the in-RAM MARF state so that no subsequent writes will be permitted. /// Returns the new root hash of the MARF. - /// Runtime-panics if the MARF was already sealed. + /// Returns `Err(Error::ReadOnlyError)` if the MARF was already sealed (i.e. readonly). pub fn seal(&mut self) -> Result { if self.storage.readonly() { return Err(Error::ReadOnlyError); From 78e26b93713d99a9875b161692d6cd16234d3adc Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 21:59:42 +0000 Subject: [PATCH 018/102] doc: extend_trie returns Result<(), Error> not bool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Doc said 'Returns true/false, based on whether or not the trie will be created (this can return false if we're resuming work on an unconfirmed trie)'. The signature is Result<(), Error> — no bool is returned. Every Ok arm yields Ok(()): the unconfirmed-resume case at line 888 returns Ok(()), the brand-new case at line 882 returns Ok(()), the extend case at line 899 returns Ok(()). There is no path that returns a bool. Doc was wrong since the function returned bool in commit 561499acfe5 (2020-07-05) and was changed to () in commit e1195b57156 (2020-09-01) without updating the doc. Also rename 's' to 'storage' to match the parameter name. --- stackslib/src/chainstate/stacks/index/marf.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/stackslib/src/chainstate/stacks/index/marf.rs b/stackslib/src/chainstate/stacks/index/marf.rs index 93f6a3b0505..ea665bd2aac 100644 --- a/stackslib/src/chainstate/stacks/index/marf.rs +++ b/stackslib/src/chainstate/stacks/index/marf.rs @@ -862,9 +862,7 @@ impl MARF { /// create or open a particular Trie. /// If the trie doesn't exist, then extend it from the current Trie and create a root node that /// has back pointers to its immediate children in the current trie. - /// On Ok, s will point to new_bhh and will be open for reading. - /// Returns true/false, based on whether or not the trie will be created (this can return false - /// if we're resuming work on an unconfirmed trie) + /// On Ok(()), `storage` will point to `new_bhh` and will be open for reading. pub fn extend_trie(storage: &mut TrieStorageTransaction, new_bhh: &T) -> Result<(), Error> { if storage.readonly() { unreachable!("CORRUPTION: constructed read-only TrieStorageTransaction instance"); From ace0cc82f5d05096ce8636cb041be7c10be99aa2 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 22:04:15 +0000 Subject: [PATCH 019/102] doc: from_parent_unsigned returns Option, not an error type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc-comment said 'Return an error on overflow' but the function signature is Option and the overflow path at line 823 returns None. There is no Result, no Error enum variant — the failure mode is plain None. Doc has been wrong since the function was introduced in 71c62059858 (2019-09-16). Replace 'error' with the actual None return shape. --- stackslib/src/chainstate/stacks/block.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/stacks/block.rs b/stackslib/src/chainstate/stacks/block.rs index d8093e155df..5a12d40053a 100644 --- a/stackslib/src/chainstate/stacks/block.rs +++ b/stackslib/src/chainstate/stacks/block.rs @@ -811,8 +811,8 @@ impl StacksMicroblockHeader { StacksMicroblockHeader::first_unsigned(parent_block_hash, &Sha512Trunc256Sum([0u8; 32])) } - /// Create an unsigned microblock header from its parent - /// Return an error on overflow + /// Create an unsigned microblock header from its parent. + /// Returns `None` if `parent_header.sequence + 1` overflows. pub fn from_parent_unsigned( parent_header: &StacksMicroblockHeader, tx_merkle_root: &Sha512Trunc256Sum, From bcbd91245ac0c4d52f1b444a0dcba798853be081 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 22:12:56 +0000 Subject: [PATCH 020/102] doc: process_block_ops returns tuple, doc claimed only BlockSnapshot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc-comment said 'Returns the BlockSnapshot created from this block.' The function signature returns Result<(BlockSnapshot, BurnchainStateTransition), BurnchainError> — a 2-tuple. The doc omits the BurnchainStateTransition. Update the description to name both members of the tuple. --- stackslib/src/chainstate/burn/db/processing.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/burn/db/processing.rs b/stackslib/src/chainstate/burn/db/processing.rs index 58fea322125..4d94263ab90 100644 --- a/stackslib/src/chainstate/burn/db/processing.rs +++ b/stackslib/src/chainstate/burn/db/processing.rs @@ -228,7 +228,8 @@ impl SortitionHandleTx<'_> { /// * do a cryptographic sortition to select the next Stacks block /// * commit all valid transactions /// * commit the results of the sortition - /// Returns the BlockSnapshot created from this block. + /// Returns `(BlockSnapshot created from this block, BurnchainStateTransition for the + /// committed ops)` on success. pub fn process_block_ops( &mut self, mainnet: bool, From f42ae3d73019238239b857bd2b53e4463bbf6068 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 22:16:45 +0000 Subject: [PATCH 021/102] doc: net/api new_get* helpers were copy-pasted from getinfo.rs Five net/api request constructors carried the doc-comment 'Make a new getinfo request to this endpoint' even though each builds a different endpoint: - getpoxinfo.rs new_getpoxinfo (/v2/pox) - getsigner.rs new_getsigner - getstackers.rs new_getstackers - gettenureinfo.rs new_get_nakamoto_tenure_info (/v3/tenures/info) - gettenuretip.rs new_get_tenure_tip (/v3/tenures/tip/...) Doc was copy-pasted from getinfo.rs (where it is correct) and never adjusted. Rename the noun in each per-file comment to match the endpoint the function actually builds. --- stackslib/src/net/api/getpoxinfo.rs | 2 +- stackslib/src/net/api/getsigner.rs | 2 +- stackslib/src/net/api/getstackers.rs | 2 +- stackslib/src/net/api/gettenureinfo.rs | 2 +- stackslib/src/net/api/gettenuretip.rs | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/stackslib/src/net/api/getpoxinfo.rs b/stackslib/src/net/api/getpoxinfo.rs index 7dac63c2ea0..696aae83a32 100644 --- a/stackslib/src/net/api/getpoxinfo.rs +++ b/stackslib/src/net/api/getpoxinfo.rs @@ -634,7 +634,7 @@ impl HttpResponse for RPCPoxInfoRequestHandler { } impl StacksHttpRequest { - /// Make a new getinfo request to this endpoint + /// Make a new getpoxinfo request to this endpoint pub fn new_getpoxinfo(host: PeerHost, tip_req: TipRequest) -> StacksHttpRequest { StacksHttpRequest::new_for_peer( host, diff --git a/stackslib/src/net/api/getsigner.rs b/stackslib/src/net/api/getsigner.rs index e80923ba363..ae2e6ee7d40 100644 --- a/stackslib/src/net/api/getsigner.rs +++ b/stackslib/src/net/api/getsigner.rs @@ -164,7 +164,7 @@ impl HttpResponse for GetSignerRequestHandler { } impl StacksHttpRequest { - /// Make a new getinfo request to this endpoint + /// Make a new getsigner request to this endpoint pub fn new_getsigner( host: PeerHost, signer_pubkey: &Secp256k1PublicKey, diff --git a/stackslib/src/net/api/getstackers.rs b/stackslib/src/net/api/getstackers.rs index 31bafa2734f..3c37833148d 100644 --- a/stackslib/src/net/api/getstackers.rs +++ b/stackslib/src/net/api/getstackers.rs @@ -218,7 +218,7 @@ impl HttpResponse for GetStackersRequestHandler { } impl StacksHttpRequest { - /// Make a new getinfo request to this endpoint + /// Make a new getstackers request to this endpoint pub fn new_getstackers( host: PeerHost, cycle_num: u64, diff --git a/stackslib/src/net/api/gettenureinfo.rs b/stackslib/src/net/api/gettenureinfo.rs index 307c7cc6cbb..1e848b78025 100644 --- a/stackslib/src/net/api/gettenureinfo.rs +++ b/stackslib/src/net/api/gettenureinfo.rs @@ -139,7 +139,7 @@ impl HttpResponse for RPCNakamotoTenureInfoRequestHandler { } impl StacksHttpRequest { - /// Make a new getinfo request to this endpoint + /// Make a new get-tenure-info request to this endpoint pub fn new_get_nakamoto_tenure_info(host: PeerHost) -> StacksHttpRequest { StacksHttpRequest::new_for_peer( host, diff --git a/stackslib/src/net/api/gettenuretip.rs b/stackslib/src/net/api/gettenuretip.rs index 595491c40fe..202de83dde6 100644 --- a/stackslib/src/net/api/gettenuretip.rs +++ b/stackslib/src/net/api/gettenuretip.rs @@ -150,7 +150,7 @@ impl HttpResponse for RPCNakamotoTenureTipRequestHandler { } impl StacksHttpRequest { - /// Make a new getinfo request to this endpoint + /// Make a new get-tenure-tip request to this endpoint pub fn new_get_tenure_tip(host: PeerHost, consensus_hash: &ConsensusHash) -> StacksHttpRequest { StacksHttpRequest::new_for_peer( host, From 8bdc67c69b13f6992a8493181abdf81c2deb27e2 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:24:36 +0000 Subject: [PATCH 022/102] tmp: pox v4 doc fix --- clarity/src/vm/database/structures.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs index 2651b59872b..526a8c3e1cd 100644 --- a/clarity/src/vm/database/structures.rs +++ b/clarity/src/vm/database/structures.rs @@ -863,7 +863,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> { /// Extend this account's current lock to `unlock_burn_height`. /// After calling, this method will set the balance to a "LockedPoxFour" balance, - /// because this method is only invoked as a result of PoX3 interactions + /// because this method is only invoked as a result of PoX4 interactions pub fn extend_lock_v4(&mut self, unlock_burn_height: u64) -> Result<(), VmExecutionError> { let unlocked = self.unlock_available_tokens_if_any()?; if unlocked > 0 { @@ -929,7 +929,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> { } /// Return true iff `self` represents a snapshot that has a lock - /// created by PoX v3. + /// created by PoX v4. pub fn is_v4_locked(&mut self) -> Result { match self.canonical_balance_repr()? { STXBalance::LockedPoxFour { .. } => Ok(true), From 00f931358d018eb8f5df3a5dda2d8455bc113d6a Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:26:19 +0000 Subject: [PATCH 023/102] tmp: set_block_processed/orphaned attachable doc --- stackslib/src/chainstate/nakamoto/staging_blocks.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/staging_blocks.rs b/stackslib/src/chainstate/nakamoto/staging_blocks.rs index 889227287cc..46eaa46f617 100644 --- a/stackslib/src/chainstate/nakamoto/staging_blocks.rs +++ b/stackslib/src/chainstate/nakamoto/staging_blocks.rs @@ -544,8 +544,7 @@ impl<'a> NakamotoStagingBlocksConnRef<'a> { impl NakamotoStagingBlocksTx<'_> { /// Notify the staging database that a given stacks block has been processed. - /// This will update the attachable status for children blocks, as well as marking the stacks - /// block itself as processed. + /// This marks the staging row for `block` as processed. pub fn set_block_processed(&self, block: &StacksBlockId) -> Result<(), ChainstateError> { let clear_staged_block = "UPDATE nakamoto_staging_blocks SET processed = 1, processed_time = ?2 @@ -559,8 +558,8 @@ impl NakamotoStagingBlocksTx<'_> { } /// Modify the staging database that a given stacks block can never be processed. - /// This will update the attachable status for children blocks, as well as marking the stacks - /// block itself as orphaned. + /// This marks any staging row whose `parent_block_id` is `block` as orphaned, and marks + /// the staging row for `block` itself as both processed and orphaned. pub fn set_block_orphaned(&self, block: &StacksBlockId) -> Result<(), ChainstateError> { let update_dependents = "UPDATE nakamoto_staging_blocks SET orphaned = 1 WHERE parent_block_id = ?"; From ac0b013a7fdf527902a5dc5158652f005e6f7409 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:27:18 +0000 Subject: [PATCH 024/102] tmp: get_nakamoto_blocks_in_tenure doc --- stackslib/src/chainstate/nakamoto/staging_blocks.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/staging_blocks.rs b/stackslib/src/chainstate/nakamoto/staging_blocks.rs index 46eaa46f617..4cd689ca079 100644 --- a/stackslib/src/chainstate/nakamoto/staging_blocks.rs +++ b/stackslib/src/chainstate/nakamoto/staging_blocks.rs @@ -435,7 +435,7 @@ impl<'a> NakamotoStagingBlocksConnRef<'a> { .collect()) } - /// Get all nakamoto blocks in a tenure + /// Get all processed nakamoto blocks in a tenure. pub fn get_nakamoto_blocks_in_tenure( &self, consensus_hash: &ConsensusHash, From 98030d8ddb51f564709ee25ce0bcc8f3e2fe21ad Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:28:10 +0000 Subject: [PATCH 025/102] tmp: check_first_nakamoto_tenure_change --- stackslib/src/chainstate/nakamoto/tenure.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/tenure.rs b/stackslib/src/chainstate/nakamoto/tenure.rs index 99c85bf366e..4bd139fef65 100644 --- a/stackslib/src/chainstate/nakamoto/tenure.rs +++ b/stackslib/src/chainstate/nakamoto/tenure.rs @@ -548,8 +548,9 @@ impl NakamotoChainState { /// Verify that a tenure change tx is a valid first-ever tenure change. It must connect to an /// epoch2 block, and it must be sortition-induced. /// - /// Returns Some(mocked-epoch2-tenure) on success - /// Returns None on error + /// Returns Ok(Some(mocked-epoch2-tenure)) on success + /// Returns Ok(None) if the tenure change is invalid + /// Returns Err(..) on DB error pub(crate) fn check_first_nakamoto_tenure_change( headers_conn: &Connection, tenure_payload: &TenureChangePayload, From 14a34bf3e4dc6bbf62a5a04c6967bebd6f17294b Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:31:28 +0000 Subject: [PATCH 026/102] tmp: clarity special_get info doc fix --- clarity/src/vm/functions/database.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/clarity/src/vm/functions/database.rs b/clarity/src/vm/functions/database.rs index 7167c6d5358..4c97d361ca6 100644 --- a/clarity/src/vm/functions/database.rs +++ b/clarity/src/vm/functions/database.rs @@ -934,7 +934,7 @@ pub fn special_delete_entry_v205( /// # Errors: /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`]. /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments. -/// - [`RuntimeCheckErrorKind::GetBlockInfoExpectPropertyName`] if `args[0]` isn't a ClarityName or isn't a valid [`BlockInfoProperty`]. +/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName or isn't a valid [`BlockInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::GetBlockInfoExpectPropertyName`] before reaching runtime). /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`. /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`. /// - [`VmInternalError`] from database operations when retrieving block information. @@ -1098,8 +1098,8 @@ pub fn special_get_block_info( /// /// # Errors: /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments. -/// - [`RuntimeCheckErrorKind::GetBlockInfoExpectPropertyName`] if `args[0]` isn't a ClarityName. -/// - [`RuntimeCheckErrorKind::NoSuchBurnBlockInfoProperty`] if `args[0]` isn't a [`BurnBlockInfoProperty`]. +/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName (the static analyzer normally rejects this). +/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a [`BurnBlockInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::NoSuchBurnBlockInfoProperty`]). /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`. /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`]. /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`. @@ -1302,7 +1302,7 @@ pub fn special_get_stacks_block_info( /// /// # Errors: /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments. -/// - [`RuntimeCheckErrorKind::GetTenureInfoExpectPropertyName`] if `args[0]` isn't a ClarityName or isn't a valid [`TenureInfoProperty`]. +/// - [`RuntimeCheckErrorKind::Unreachable`] if `args[0]` isn't a ClarityName or isn't a valid [`TenureInfoProperty`] (the static analyzer normally rejects this with [`StaticCheckErrorKind::GetTenureInfoExpectPropertyName`] before reaching runtime). /// - [`RuntimeCheckErrorKind::TypeValueError`] if `args[1]` doesn't evaluate to a `uint`. /// - [`RuntimeCheckErrorKind`] cost errors (e.g., `CostOverflow`, `CostBalanceExceeded`) from [`runtime_cost`]. /// - [`VmExecutionError`] propagated from [`eval`] when evaluating `args[1]`. From ccb370ab856a8b8573166a642d3cd667d31d652b Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:41:42 +0000 Subject: [PATCH 027/102] tmp: BlockAccepted struct doc --- libsigner/src/v0/messages.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/v0/messages.rs b/libsigner/src/v0/messages.rs index bf6dbb6a975..28af57999a9 100644 --- a/libsigner/src/v0/messages.rs +++ b/libsigner/src/v0/messages.rs @@ -1625,7 +1625,7 @@ impl StacksMessageCodec for BlockResponseData { } } -/// A rejection response from a signer for a proposed block +/// An acceptance response from a signer for a proposed block #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct BlockAccepted { /// The signer signature hash of the block that was accepted From 1fe56c0c3f57b0ee360b9ebe70031281c5fffc4a Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:42:23 +0000 Subject: [PATCH 028/102] tmp: MockProposal::new doc --- libsigner/src/v0/messages.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/v0/messages.rs b/libsigner/src/v0/messages.rs index 28af57999a9..f35ac2b1413 100644 --- a/libsigner/src/v0/messages.rs +++ b/libsigner/src/v0/messages.rs @@ -354,7 +354,7 @@ pub struct MockProposal { } impl MockProposal { - /// Create a new mock proposal data struct from the provided peer info, chain id, and private key. + /// Create a new mock proposal data struct from the provided peer info and private key. pub fn new(peer_info: PeerInfo, stacks_private_key: &StacksPrivateKey) -> Self { let mut sig = Self { signature: MessageSignature::empty(), From 0dfcdfd576d34fa082c27555fe641645f9e06519 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:43:08 +0000 Subject: [PATCH 029/102] tmp: BlockResponseData::new doc --- libsigner/src/v0/messages.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/libsigner/src/v0/messages.rs b/libsigner/src/v0/messages.rs index f35ac2b1413..2256a8d82de 100644 --- a/libsigner/src/v0/messages.rs +++ b/libsigner/src/v0/messages.rs @@ -1530,7 +1530,8 @@ pub struct BlockResponseData { } impl BlockResponseData { - /// Create a new BlockResponseData for the provided tenure extend timestamp and unknown bytes + /// Create a new BlockResponseData from the provided tenure-extend timestamp, reject reason, + /// tenure-extend read-count timestamp, and failed-tx id. `unknown_bytes` is initialised empty. pub fn new( tenure_extend_timestamp: u64, reject_reason: RejectReason, From 13eba1b0871692e19542464757d4d41365b1bc0e Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:44:19 +0000 Subject: [PATCH 030/102] tmp: pre_epoch_begin doc --- stackslib/src/chainstate/stacks/miner.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stackslib/src/chainstate/stacks/miner.rs b/stackslib/src/chainstate/stacks/miner.rs index 5b8a9fe5670..7db6ff51674 100644 --- a/stackslib/src/chainstate/stacks/miner.rs +++ b/stackslib/src/chainstate/stacks/miner.rs @@ -1856,9 +1856,9 @@ impl StacksBlockBuilder { /// This function should be called before `epoch_begin`. /// It loads the parent microblock stream, sets the parent microblock, and returns /// data necessary for `epoch_begin`. - /// Returns chainstate transaction, clarity instance, burnchain header hash - /// of the burn tip, burn tip height + 1, the parent microblock stream, - /// the parent consensus hash, the parent header hash, and a bool + /// Returns a `MinerEpochInfo` with chainstate transaction, clarity instance, + /// burnchain header hash of the burn tip, burn tip height + 1, the parent + /// microblock stream, and a bool /// representing whether the network is mainnet or not. pub fn pre_epoch_begin<'a>( &mut self, From 00ba74db2c8611cb99c2c442c775eb197d77e73d Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:45:03 +0000 Subject: [PATCH 031/102] tmp: build_anchored_block doc --- stackslib/src/chainstate/stacks/miner.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/miner.rs b/stackslib/src/chainstate/stacks/miner.rs index 7db6ff51674..6107cc7cd12 100644 --- a/stackslib/src/chainstate/stacks/miner.rs +++ b/stackslib/src/chainstate/stacks/miner.rs @@ -2285,7 +2285,7 @@ impl StacksBlockBuilder { // Or keep the skip and remove the comment #[cfg_attr(test, mutants::skip)] /// Given access to the mempool, mine an anchored block with no more than the given execution cost. - /// returns the assembled block, and the consumed execution budget. + /// returns the assembled block, the consumed execution budget, and the block size in bytes. pub fn build_anchored_block( chainstate_handle: &StacksChainState, // not directly used; used as a handle to open other chainstates burn_dbconn: &SortitionHandleConn, From dc64b3a7e40791f3793dcd696e72a036e67bd098 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:46:38 +0000 Subject: [PATCH 032/102] tmp: sign_next* docs --- stackslib/src/chainstate/stacks/transaction.rs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/stackslib/src/chainstate/stacks/transaction.rs b/stackslib/src/chainstate/stacks/transaction.rs index 93c59c1124f..fa48e840a69 100644 --- a/stackslib/src/chainstate/stacks/transaction.rs +++ b/stackslib/src/chainstate/stacks/transaction.rs @@ -838,7 +838,10 @@ impl StacksTransaction { } /// Sign a sighash and append the signature and public key to the given spending condition. - /// Returns the next sighash + /// Returns the sighash that the *next* signer should use. + /// For `Singlesig` and `Multisig`, this is the advanced sighash after this signature. + /// For `OrderIndependentMultisig`, this is `cur_sighash` unchanged, since every signer in an + /// order-independent multisig signs the same sighash. fn sign_and_append( condition: &mut TransactionSpendingCondition, cur_sighash: &Txid, @@ -916,7 +919,9 @@ impl StacksTransaction { } /// Append the next signature from the origin account authorization. - /// Return the next sighash. + /// Return the sighash that the next origin signer should use. + /// For Singlesig / Multisig this is the advanced sighash; for OrderIndependentMultisig + /// it is `cur_sighash` unchanged. pub fn sign_next_origin( &mut self, cur_sighash: &Txid, @@ -949,7 +954,9 @@ impl StacksTransaction { } /// Append the next signature from the sponsoring account. - /// Return the next sighash + /// Return the sighash that the next sponsor signer should use. + /// For Singlesig / Multisig this is the advanced sighash; for OrderIndependentMultisig + /// it is `cur_sighash` unchanged. pub fn sign_next_sponsor( &mut self, cur_sighash: &Txid, From 3152cfb520f3f727c015a786b1329370e8bb2765 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:51:45 +0000 Subject: [PATCH 033/102] tmp: get_consensus_at doc --- stackslib/src/chainstate/burn/db/sortdb.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/burn/db/sortdb.rs b/stackslib/src/chainstate/burn/db/sortdb.rs index 3125db5630b..a9055a787ce 100644 --- a/stackslib/src/chainstate/burn/db/sortdb.rs +++ b/stackslib/src/chainstate/burn/db/sortdb.rs @@ -2169,8 +2169,7 @@ impl<'a> SortitionHandleConn<'a> { } /// Get consensus hash from a particular chain tip's history - /// Returns None if the block height or block hash does not correspond to a - /// known snapshot. + /// Returns None if the block height does not correspond to a known snapshot. pub fn get_consensus_at(&self, block_height: u64) -> Result, db_error> { if block_height >= BLOCK_HEIGHT_MAX { return Err(db_error::BlockHeightOutOfRange); From 4f82321e0a3fecaf6d1265a6d51c5190ebf89630 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:52:23 +0000 Subject: [PATCH 034/102] tmp: get_coinbase_tx doc --- stackslib/src/chainstate/stacks/block.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/block.rs b/stackslib/src/chainstate/stacks/block.rs index 5a12d40053a..67d97ac631f 100644 --- a/stackslib/src/chainstate/stacks/block.rs +++ b/stackslib/src/chainstate/stacks/block.rs @@ -423,7 +423,7 @@ impl StacksBlock { } /// Find and return the coinbase transaction. It's always the first transaction. - /// If there are 0 coinbase txs, or more than 1, then return None + /// If the first transaction is not a coinbase (including the empty-block case), return None. pub fn get_coinbase_tx(&self) -> Option { let tx = self.txs.first()?; match tx.payload { From 84a1c1f5728e750c7b2e35771ecdbd8186755228 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:52:59 +0000 Subject: [PATCH 035/102] tmp: find_mature_miner_rewards doc --- stackslib/src/chainstate/stacks/db/accounts.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/stacks/db/accounts.rs b/stackslib/src/chainstate/stacks/db/accounts.rs index d09063fdb66..413d414acc8 100644 --- a/stackslib/src/chainstate/stacks/db/accounts.rs +++ b/stackslib/src/chainstate/stacks/db/accounts.rs @@ -981,8 +981,9 @@ impl StacksChainState { } /// Find the latest miner reward to mature, assuming that there are mature rewards. - /// Returns a list of payments to make to each address -- miners and user-support burners -- as - /// well as an info struct about where the rewards took place on the chain. + /// Returns `Some((miner_reward, user_support_payments, parent_miner_reward, info))` where + /// `user_support_payments` is the list of user-support-burner payments and `info` describes + /// where the rewards took place on the chain. Returns `None` if no mature rewards exist. pub fn find_mature_miner_rewards( clarity_tx: &mut ClarityTx, sortdb_conn: &Connection, From eb83c5ac4861ff38ae93c924f3d8e3b0a3d33650 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:53:39 +0000 Subject: [PATCH 036/102] tmp: get_nakamoto_block_status doc --- stackslib/src/chainstate/nakamoto/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index 947c0641448..fad0c584586 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -3116,7 +3116,7 @@ impl NakamotoChainState { } /// Get the status of a Nakamoto block. - /// Returns Some(accepted?, orphaned?) on success + /// Returns Some(processed?, orphaned?) on success /// Returns None if there's no such block /// Returns Err on DBError pub fn get_nakamoto_block_status( From f3018b4441e93132a0c45037a8d19db2da251005 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 22:57:45 +0000 Subject: [PATCH 037/102] tmp: pox-locking pox4 docs --- pox-locking/src/lib.rs | 2 +- pox-locking/src/pox_2.rs | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pox-locking/src/lib.rs b/pox-locking/src/lib.rs index ee67990caab..6e65c73d8e7 100644 --- a/pox-locking/src/lib.rs +++ b/pox-locking/src/lib.rs @@ -20,7 +20,7 @@ //! This library provides a contract-call special case handler //! `crate::handle_contract_call_special_cases()` which matches a //! contract-call result against zero-address published contracts -//! `pox`, `pox-2`, and `pox-3`. For each of those contracts, it +//! `pox`, `pox-2`, `pox-3`, and `pox-4`. For each of those contracts, it //! checks if the function called requires applying or updating the //! `STXBalance` struct's locks, and if the function was successfully //! invoked. If so, it updates the PoX lock. diff --git a/pox-locking/src/pox_2.rs b/pox-locking/src/pox_2.rs index e2b605786eb..112ade18af3 100644 --- a/pox-locking/src/pox_2.rs +++ b/pox-locking/src/pox_2.rs @@ -56,7 +56,7 @@ pub fn is_read_only(func_name: &str) -> bool { } /// Parse the returned value from PoX `stack-stx` and `delegate-stack-stx` functions -/// from pox-2.clar or pox-3.clar into a format more readily digestible in rust. +/// from pox-2.clar, pox-3.clar, or pox-4.clar into a format more readily digestible in rust. /// Panics if the supplied value doesn't match the expected tuple structure pub fn parse_pox_stacking_result( result: &Value, @@ -98,7 +98,7 @@ pub fn parse_pox_stacking_result( } } -/// Parse the returned value from PoX2 or PoX3 `stack-extend` and `delegate-stack-extend` functions +/// Parse the returned value from PoX2, PoX3, or PoX4 `stack-extend` and `delegate-stack-extend` functions /// into a format more readily digestible in rust. /// Panics if the supplied value doesn't match the expected tuple structure pub fn parse_pox_extend_result(result: &Value) -> std::result::Result<(PrincipalData, u64), i128> { @@ -133,7 +133,7 @@ pub fn parse_pox_extend_result(result: &Value) -> std::result::Result<(Principal } } -/// Parse the returned value from PoX2 or PoX3 `stack-increase` function +/// Parse the returned value from PoX2, PoX3, or PoX4 `stack-increase` function /// into a format more readily digestible in rust. /// Panics if the supplied value doesn't match the expected tuple structure pub fn parse_pox_increase(result: &Value) -> std::result::Result<(PrincipalData, u128), i128> { From 8ed4c8cf95f8dbe72f40b6b446cf75e6c97b5e95 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 23:01:05 +0000 Subject: [PATCH 038/102] tmp: send_next_download_request doc --- stackslib/src/net/download/nakamoto/tenure_downloader.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/net/download/nakamoto/tenure_downloader.rs b/stackslib/src/net/download/nakamoto/tenure_downloader.rs index 5637424795d..d03a7e92d93 100644 --- a/stackslib/src/net/download/nakamoto/tenure_downloader.rs +++ b/stackslib/src/net/download/nakamoto/tenure_downloader.rs @@ -697,7 +697,7 @@ impl NakamotoTenureDownloader { /// data URL corresponding to self.naddr. /// Returns Ok(true) if we sent the request, or there's already an in-flight request. The /// caller should try this again until it gets one of the other possible return values. - /// Returns Ok(false) if not (e.g. neighbor is known to be dead or broken) + /// Returns Ok(false) if `make_next_download_request` failed to build a request. /// Returns Err(..) if self.naddr is known to be a dead or broken peer, or if we were unable to /// resolve its data URL to a socket address. pub fn send_next_download_request( From a39bf4bada3a93800b970d029d208b767630b7f3 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:10:27 +0000 Subject: [PATCH 039/102] tmp: ReplayScopeOpt doc --- stacks-signer/src/v0/signer_state.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-signer/src/v0/signer_state.rs b/stacks-signer/src/v0/signer_state.rs index 6a17bbef38b..3b08e3f5241 100644 --- a/stacks-signer/src/v0/signer_state.rs +++ b/stacks-signer/src/v0/signer_state.rs @@ -98,7 +98,7 @@ pub struct ReplayScope { pub past_tip: NewBurnBlock, } -/// Optional `TxReplayScope`, representing the potential absence of a replay scope. +/// Optional `ReplayScope`, representing the potential absence of a replay scope. pub type ReplayScopeOpt = Option; /// Represents the Tx Replay state From c7b8dd30f31726cfc5fa4bf9a04a5da005708703 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:11:48 +0000 Subject: [PATCH 040/102] tmp: make_min_median_distribution doc user-burns --- stackslib/src/chainstate/burn/distribution.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/stackslib/src/chainstate/burn/distribution.rs b/stackslib/src/chainstate/burn/distribution.rs index f3abb66a06e..a14d59d242d 100644 --- a/stackslib/src/chainstate/burn/distribution.rs +++ b/stackslib/src/chainstate/burn/distribution.rs @@ -131,7 +131,7 @@ impl BurnSamplePoint { } /// Make a burn distribution -- a list of (burn total, block candidate) pairs -- from a block's - /// block commits and user support burns. + /// block commits. /// /// All operations need to be supplied in an ordered Vec of Vecs containing /// the ops at each block height in a mining commit window. Normally, this window @@ -140,9 +140,6 @@ impl BurnSamplePoint { /// consider which window is active; it merely deduces it by inspecting the length of the /// given `block_commits` argument. /// - /// If a burn refers to more than one commitment, its burn amount is *split* between those - /// commitments - /// /// Burns are evaluated over the mining commitment window, where the effective burn for /// a commitment is := min(last_burn_amount, median over the window) /// From 0fd89f58ffb3884396d544b83018b63427bee34f Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:12:41 +0000 Subject: [PATCH 041/102] tmp: capitulate_miner_view doc local_address --- stacks-signer/src/v0/signer_state.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-signer/src/v0/signer_state.rs b/stacks-signer/src/v0/signer_state.rs index 3b08e3f5241..14981da4881 100644 --- a/stacks-signer/src/v0/signer_state.rs +++ b/stacks-signer/src/v0/signer_state.rs @@ -963,7 +963,7 @@ impl LocalStateMachine { } } - /// Determines whether a signer with the `local_address` and `local_update` should capitulate + /// Determines whether a signer with the given `local_update` should capitulate /// its current miner view to a new state. This is not necessarily the same as the current global /// view of the miner as it is up to signers to capitulate before this becomes the finalized view. pub fn capitulate_miner_view( From b2af0615d2db6925557506c937ef1b086d0380b4 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:13:36 +0000 Subject: [PATCH 042/102] tmp: ATC_LOOKUP doc above->below --- stackslib/src/chainstate/burn/atc.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/burn/atc.rs b/stackslib/src/chainstate/burn/atc.rs index 4d44adf6672..ffa3f0e782f 100644 --- a/stackslib/src/chainstate/burn/atc.rs +++ b/stackslib/src/chainstate/burn/atc.rs @@ -145,7 +145,7 @@ impl AtcRational { /// that the miner underpaid relative to their past performance, and the closer to 0.0 this ratio /// is, the more likely the null miner wins and this miner loses. /// -/// This table is generated with `make_null_miner_lookup_table()` above. +/// This table is generated with the `make_null_miner_lookup_table()` test below. pub(crate) const ATC_LOOKUP: [AtcRational; 1024] = [ AtcRational(Uint256([14665006693661589504, 0, 0, 0])), AtcRational(Uint256([14663943061084833792, 0, 0, 0])), From 30fdb70cd6d37ab473e5eee3caa3f0087561fb3b Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:23:41 +0000 Subject: [PATCH 043/102] tmp: put_data_with_size doc --- clarity/src/vm/database/clarity_db.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clarity/src/vm/database/clarity_db.rs b/clarity/src/vm/database/clarity_db.rs index 30728694fad..e666c76f4f5 100644 --- a/clarity/src/vm/database/clarity_db.rs +++ b/clarity/src/vm/database/clarity_db.rs @@ -501,7 +501,7 @@ impl<'a> ClarityDatabase<'a> { self.store.put_data(key, &value.serialize()) } - /// Like `put()`, but returns the serialized byte size of the stored value + /// Like `put_data()`, but returns the serialized byte size of the stored value pub fn put_data_with_size( &mut self, key: &str, From 0c58133aca5e9af07c13541561f1fc68f2628de7 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:24:31 +0000 Subject: [PATCH 044/102] tmp: NakamotoBlockBuilder::new doc params --- stackslib/src/chainstate/nakamoto/miner.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/miner.rs b/stackslib/src/chainstate/nakamoto/miner.rs index 497c967f4a2..f7754f16ed3 100644 --- a/stackslib/src/chainstate/nakamoto/miner.rs +++ b/stackslib/src/chainstate/nakamoto/miner.rs @@ -274,7 +274,7 @@ impl NakamotoBlockBuilder { /// Make a Nakamoto block builder appropriate for building atop the given block header /// - /// * `parent_stacker_header` - the stacks header this builder's block will build off + /// * `parent_stacks_header` - the stacks header this builder's block will build off /// /// * `tenure_id_consensus_hash` - consensus hash of this tenure's burnchain block. /// This is the consensus hash that goes into the block header. @@ -290,6 +290,13 @@ impl NakamotoBlockBuilder { /// /// * `soft_limit` - an optional soft limit for the block's clarity cost for this block /// + /// * `contract_limit_percentage` - an optional cap (as a percentage of the block budget) for + /// contract-call cost in this block + /// + /// * `timestamp` - an optional override for the block-header timestamp + /// + /// * `max_tenure_bytes` - the maximum total byte budget for the tenure + /// pub fn new( parent_stacks_header: &StacksHeaderInfo, tenure_id_consensus_hash: &ConsensusHash, From df7466825439273282873f7d2e4fd0b206ef1b59 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:25:15 +0000 Subject: [PATCH 045/102] tmp: check_shadow_coinbase_tx doc --- stackslib/src/chainstate/nakamoto/shadow.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/shadow.rs b/stackslib/src/chainstate/nakamoto/shadow.rs index 58133588a29..2d233b81c59 100644 --- a/stackslib/src/chainstate/nakamoto/shadow.rs +++ b/stackslib/src/chainstate/nakamoto/shadow.rs @@ -114,8 +114,9 @@ impl NakamotoBlock { self.header.is_shadow_block() } - /// Verify that if this shadow block has a coinbase, that its VRF proof is consistent with the leader - /// public key's VRF key. If there is no coinbase tx, then this is a no-op. + /// Verify that if this shadow block has a coinbase, then it carries a VRF proof and pays to the + /// burn address for the configured network. The VRF proof itself is not checked against any key + /// (shadow blocks are not produced by a miner). If there is no coinbase tx, then this is a no-op. pub(crate) fn check_shadow_coinbase_tx(&self, mainnet: bool) -> Result<(), ChainstateError> { if !self.is_shadow_block() { error!( From 91908ac9f76ad35a0fa4fd1f307cec6717ad0ffd Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:26:06 +0000 Subject: [PATCH 046/102] tmp: shadow_load_tenure_info doc --- stackslib/src/chainstate/nakamoto/shadow.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/shadow.rs b/stackslib/src/chainstate/nakamoto/shadow.rs index 2d233b81c59..f8f52e8c83d 100644 --- a/stackslib/src/chainstate/nakamoto/shadow.rs +++ b/stackslib/src/chainstate/nakamoto/shadow.rs @@ -422,7 +422,7 @@ impl NakamotoChainState { } impl NakamotoBlockBuilder { - /// This function should be called before `tenure_begin`. + /// This function should be called before `shadow_tenure_begin`. /// It creates a MinerTenureInfo struct which owns connections to the chainstate and sortition /// DBs, so that block-processing is guaranteed to terminate before the lives of these handles /// expire. From 2249d6874cf8cea5260835fef1f35e425e83b580 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:26:46 +0000 Subject: [PATCH 047/102] tmp: validate_shadow_against_burnchain doc burn_tip --- stackslib/src/chainstate/nakamoto/shadow.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/shadow.rs b/stackslib/src/chainstate/nakamoto/shadow.rs index f8f52e8c83d..0850e0a7bb5 100644 --- a/stackslib/src/chainstate/nakamoto/shadow.rs +++ b/stackslib/src/chainstate/nakamoto/shadow.rs @@ -171,7 +171,7 @@ impl NakamotoBlock { /// /// Verifies the following: /// -- (self.header.consensus_hash) that this block falls into this block-commit's tenure - /// -- (self.header.burn_spent) that this block's burn total matches `burn_tip`'s total burn + /// -- (self.header.burn_spent) that this block's burn total matches `tenure_burn_chain_tip`'s total burn /// -- if this block has a tenure change, then it's consistent with the miner's public key and /// self.header.consensus_hash /// From f6229e78268b55183991a85f987bb2550ce0c829 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:27:33 +0000 Subject: [PATCH 048/102] tmp: get_shadow_vrf_proof doc --- stackslib/src/chainstate/nakamoto/shadow.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/shadow.rs b/stackslib/src/chainstate/nakamoto/shadow.rs index 0850e0a7bb5..e46209a2c43 100644 --- a/stackslib/src/chainstate/nakamoto/shadow.rs +++ b/stackslib/src/chainstate/nakamoto/shadow.rs @@ -314,7 +314,7 @@ impl NakamotoChainState { /// Load the stored VRF proof for the given shadow block's tenure. /// /// Returns Ok(Some(vrf proof)) on success - /// Returns Ok(None) if the parent tenure isn't a shadow tenure + /// Returns Ok(None) if `tip_block_id` is not present or is not a shadow block pub(crate) fn get_shadow_vrf_proof( chainstate_conn: &mut SDBI, tip_block_id: &StacksBlockId, From ec796f09abbffa234b8fb578b2d1d5cedd1c26f8 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:28:21 +0000 Subject: [PATCH 049/102] tmp: get_matured_miner_reward_schedules doc --- stackslib/src/chainstate/nakamoto/tenure.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/tenure.rs b/stackslib/src/chainstate/nakamoto/tenure.rs index 4bd139fef65..e79902872f7 100644 --- a/stackslib/src/chainstate/nakamoto/tenure.rs +++ b/stackslib/src/chainstate/nakamoto/tenure.rs @@ -333,7 +333,8 @@ impl NakamotoChainState { } /// Get scheduled miner rewards that have matured when this tenure starts. - /// Returns (list of miners to pay, any residual payments to the parent miner) on success. + /// Returns `Ok(Some(MaturedMinerPaymentSchedules { latest_miners, parent_miner }))` on success. + /// Returns `Err(ChainstateError)` if a required header/reward lookup fails. pub(crate) fn get_matured_miner_reward_schedules( chainstate_tx: &mut ChainstateTx, tip_index_hash: &StacksBlockId, From e93e96e0076c5020aeb8ab6f9625c1b06a17939d Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:29:21 +0000 Subject: [PATCH 050/102] tmp: PREAMBLE_ENCODED_SIZE doc fields above --- stacks-codec/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-codec/src/lib.rs b/stacks-codec/src/lib.rs index dbdf88400da..d8cf9c37d79 100644 --- a/stacks-codec/src/lib.rs +++ b/stacks-codec/src/lib.rs @@ -242,7 +242,7 @@ pub const MAX_PAYLOAD_LEN: u32 = 1 + 16 * 1024 * 1024; pub const MAX_MESSAGE_LEN: u32 = MAX_PAYLOAD_LEN + (PREAMBLE_ENCODED_SIZE + MAX_RELAYERS_LEN * RELAY_DATA_ENCODED_SIZE); -/// P2P preamble length (addands correspond to fields above) +/// P2P preamble length (addends correspond to the fields of `blockstack_lib::net::Preamble`, in order). pub const PREAMBLE_ENCODED_SIZE: u32 = 4 + 4 + 4 From 35a1832e1d4de04c5fac54b326871ea5f1396760 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:30:16 +0000 Subject: [PATCH 051/102] tmp: BlockMetadata.tenure_size doc --- stackslib/src/chainstate/nakamoto/miner.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/miner.rs b/stackslib/src/chainstate/nakamoto/miner.rs index f7754f16ed3..11bf8b6d493 100644 --- a/stackslib/src/chainstate/nakamoto/miner.rs +++ b/stackslib/src/chainstate/nakamoto/miner.rs @@ -245,7 +245,8 @@ pub struct BlockMetadata { pub tenure_consumed: ExecutionCost, /// The cost budget for the current tenure pub tenure_budget: ExecutionCost, - /// The size of the blocks in the current tenure in bytes + /// The size, in bytes, of the single block just built (i.e. `builder.bytes_so_far`). + /// Tenure-wide accumulation lives on `StacksHeaderInfo::total_tenure_size`. pub tenure_size: u64, /// The events emitted by the transactions included in this block pub tx_events: Vec, From 7c4fc08c4da184a9b1e1323ace268673ea3fccf9 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:31:25 +0000 Subject: [PATCH 052/102] tmp: MerkleTree::path empty-tree doc --- stacks-common/src/util/hash.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stacks-common/src/util/hash.rs b/stacks-common/src/util/hash.rs index e33483d18ca..29248c804c8 100644 --- a/stacks-common/src/util/hash.rs +++ b/stacks-common/src/util/hash.rs @@ -519,7 +519,9 @@ where } /// Get the path from the given data's leaf up to the root. - /// will be None if the data isn't a leaf. + /// Will be `None` if the data isn't a leaf and the tree is non-empty. + /// **Panics** if `self` is empty (built via `MerkleTree::empty()` or + /// `MerkleTree::new(&[])`) — there is no row to index into. pub fn path(&self, data: &[u8]) -> Option> { let leaf_hash = MerkleTree::get_leaf_hash(data); let mut hash_index = self.find_hash_index(&leaf_hash, 0)?; From c6aa36c62b94907451fd4be5c992f9bce303ba6e Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:32:25 +0000 Subject: [PATCH 053/102] tmp: check_valid_consensus_hash doc --- stackslib/src/chainstate/nakamoto/tenure.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/tenure.rs b/stackslib/src/chainstate/nakamoto/tenure.rs index e79902872f7..82e7f1f4b08 100644 --- a/stackslib/src/chainstate/nakamoto/tenure.rs +++ b/stackslib/src/chainstate/nakamoto/tenure.rs @@ -614,8 +614,9 @@ impl NakamotoChainState { } /// Check that a consensus hash is on the canonical burnchain fork - /// Returns Some(corresponding snapshot) if so - /// Returns None if it's not on the canonical fork + /// Returns Ok(Some(corresponding snapshot)) if so + /// Returns Ok(None) if the consensus hash has no snapshot, or its snapshot is not on the canonical fork + /// Returns Err(..) on DB error pub(crate) fn check_valid_consensus_hash( sort_handle: &mut SH, ch: &ConsensusHash, From 908515b3b74d42e9240ed5f849b8a0d3d76deceb Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:37:39 +0000 Subject: [PATCH 054/102] tmp: handle_insert_block_error doc --- stacks-signer/src/v0/signer.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stacks-signer/src/v0/signer.rs b/stacks-signer/src/v0/signer.rs index 53f0806c48d..375d545f602 100644 --- a/stacks-signer/src/v0/signer.rs +++ b/stacks-signer/src/v0/signer.rs @@ -2265,7 +2265,9 @@ impl Signer { } } - /// Helper for logging insert_block error + /// Helper for logging an `insert_block` error and then aborting the signer process. + /// This function does not return — it `panic!`s after logging. Callers wired up via + /// `.unwrap_or_else(|e| self.handle_insert_block_error(e))` are signalling intent to halt. pub fn handle_insert_block_error(&self, e: DBError) { error!("{self}: Failed to insert block into signer-db: {e:?}"); panic!("{self} Failed to write block to signerdb: {e}"); From f4c57a10a973abc8f439f246ea2ae235c4e5564e Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:43:00 +0000 Subject: [PATCH 055/102] tmp: SignerDb::new doc --- stacks-signer/src/signerdb.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-signer/src/signerdb.rs b/stacks-signer/src/signerdb.rs index d811510f9a4..249e645572c 100644 --- a/stacks-signer/src/signerdb.rs +++ b/stacks-signer/src/signerdb.rs @@ -1219,7 +1219,7 @@ impl SignerDb { /// The current schema version used in this build of the signer binary. pub const SCHEMA_VERSION: u32 = SchemaVersion::V19.as_u32(); - /// Create a new `SignerState` instance. + /// Create a new `SignerDb` instance. /// This will create a new SQLite database at the given path /// or an in-memory database if the path is ":memory:" pub fn new(db_path: impl AsRef) -> Result { From 671be3f90da50e070f0dc2afc4df82aeef21a1d4 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:43:42 +0000 Subject: [PATCH 056/102] tmp: is_preamble_valid doc --- stackslib/src/net/chat.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stackslib/src/net/chat.rs b/stackslib/src/net/chat.rs index a5d1d673306..a2084a37a8b 100644 --- a/stackslib/src/net/chat.rs +++ b/stackslib/src/net/chat.rs @@ -799,9 +799,9 @@ impl ConversationP2P { } /// Validate an inbound message's preamble against our knowledge of the burn chain. - /// Return Ok(true) if we can proceed - /// Return Ok(false) if we can't proceed, but the remote peer is not in violation of the protocol - /// Return Err(net_error::InvalidMessage) if the remote peer returns an invalid message in + /// Returns Ok(true) if we can proceed. A `debug!` log is emitted (but `Ok(true)` is still + /// returned) when the peer is too far ahead for neighbor walks. + /// Returns Err(net_error::InvalidMessage) if the remote peer returns an invalid message in /// violation of the protocol pub fn is_preamble_valid( &self, From 1aa04ccf4cc32ecbb3f795a1ddc772079316b5d2 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:44:34 +0000 Subject: [PATCH 057/102] tmp: highest_reward_cycle doc --- stackslib/src/net/inv/nakamoto.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/net/inv/nakamoto.rs b/stackslib/src/net/inv/nakamoto.rs index fae6eea8a7c..505c7d706e0 100644 --- a/stackslib/src/net/inv/nakamoto.rs +++ b/stackslib/src/net/inv/nakamoto.rs @@ -524,7 +524,7 @@ impl NakamotoTenureInv { rc_tenures.get(rc_height).unwrap_or(false) } - /// How many reward cycles of data do we have for this peer? + /// Highest reward cycle for which we have any inv data from this peer (zero if none). pub fn highest_reward_cycle(&self) -> u64 { self.tenures_inv .last_key_value() From 613369b5aa529bd9d29023903565aa1100f97d8f Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:45:43 +0000 Subject: [PATCH 058/102] tmp: make_chunk_request_schedule doc --- stackslib/src/net/stackerdb/sync.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/stackslib/src/net/stackerdb/sync.rs b/stackslib/src/net/stackerdb/sync.rs index e7a5bb9571c..0923beb440a 100644 --- a/stackslib/src/net/stackerdb/sync.rs +++ b/stackslib/src/net/stackerdb/sync.rs @@ -298,9 +298,11 @@ impl StackerDBSync { /// Given the downloaded set of chunk inventories, identify: /// * which chunks we need to fetch, because they're newer than ours. - /// * what order to fetch chunks in, in rarest-first order - /// Returns a list of (chunk requests, list of neighbors that can service them), which is - /// ordered from rarest chunk to most-common chunk. + /// * what order to fetch chunks in. + /// Returns a list of (chunk requests, list of neighbors that can service them), currently + /// ordered from most-common chunk (highest neighbor count) to rarest. NOTE: this is opposite + /// to the inline comment's stated intent and to `make_chunk_push_schedule` — see the + /// `schedule.reverse()` call below. May represent a stale doc or an intentional inversion. pub fn make_chunk_request_schedule( &self, network: &PeerNetwork, From 1a30db12c07753d732cbd8f07ae92a805665ef14 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:46:44 +0000 Subject: [PATCH 059/102] tmp: update_from_handshake_data doc --- stackslib/src/net/chat.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stackslib/src/net/chat.rs b/stackslib/src/net/chat.rs index a2084a37a8b..c3c4a277e56 100644 --- a/stackslib/src/net/chat.rs +++ b/stackslib/src/net/chat.rs @@ -1125,7 +1125,9 @@ impl ConversationP2P { } /// Update connection state from handshake data. - /// Returns true if we learned a new public key; false if not + /// Returns Ok(true) if the peer's public key was *replaced* (a prior key existed and differs + /// from the new one). Returns Ok(false) when the peer is supplying its public key for the + /// first time, or when the new key matches the prior one. pub fn update_from_handshake_data( &mut self, preamble: &Preamble, From 5442f0e79768d7c8508db18210719c9279fa81a6 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:47:34 +0000 Subject: [PATCH 060/102] tmp: process_getnakamotoinv_finishes doc --- stackslib/src/net/inv/nakamoto.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stackslib/src/net/inv/nakamoto.rs b/stackslib/src/net/inv/nakamoto.rs index 505c7d706e0..ef0e82c1743 100644 --- a/stackslib/src/net/inv/nakamoto.rs +++ b/stackslib/src/net/inv/nakamoto.rs @@ -963,8 +963,8 @@ impl NakamotoInvStateMachine { /// Finish asking for inventories, and update inventory state. /// Returns Ok(num-messages, true) if an inv state machine learned something. - /// Returns Ok(num-messages, false) if not - /// Returns Err(..) on I/O errors + /// Returns Ok(num-messages, false) if not. Per-peer I/O errors are logged and the + /// corresponding neighbor is marked broken via `add_broken`; they are not propagated. pub fn process_getnakamotoinv_finishes( &mut self, network: &mut PeerNetwork, From 63cf74aba26d2f200a57d43d222acecf86c7e6b5 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:48:17 +0000 Subject: [PATCH 061/102] tmp: insert_block doc broadcast column --- stacks-signer/src/signerdb.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-signer/src/signerdb.rs b/stacks-signer/src/signerdb.rs index 249e645572c..5cdc9705052 100644 --- a/stacks-signer/src/signerdb.rs +++ b/stacks-signer/src/signerdb.rs @@ -1624,7 +1624,7 @@ impl SignerDb { } /// Insert or replace a block into the database. - /// Preserves the `broadcast` column if replacing an existing block. + /// Preserves the `broadcasted` column if replacing an existing block. pub fn insert_block(&mut self, block_info: &BlockInfo) -> Result<(), DBError> { let block_json = serde_json::to_string(&block_info).expect("Unable to serialize block info"); From 0f65f1c37dcca9eef5cede7fd85a730db997eec4 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:53:16 +0000 Subject: [PATCH 062/102] tmp: commit_metadata_for_trie doc drop sibling fn name --- stackslib/src/clarity_vm/clarity.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/clarity_vm/clarity.rs b/stackslib/src/clarity_vm/clarity.rs index 21d0e07a44b..e1c267e014e 100644 --- a/stackslib/src/clarity_vm/clarity.rs +++ b/stackslib/src/clarity_vm/clarity.rs @@ -191,7 +191,7 @@ pub trait WritableMarfStore: /// These needs are each captured in distinct methods for committing this transaction. pub trait ClarityMarfStoreTransaction { /// Commit all inserted metadata and associate it with the block trie identified by `target`. - /// It can later be deleted via `drop_metadata_for()` if given the same taret. + /// It can later be deleted via `drop_metadata_for_trie()` if given the same target. /// Returns Ok(()) on success /// Returns Err(..) on error fn commit_metadata_for_trie(&mut self, target: &StacksBlockId) -> Result<(), VmExecutionError>; From c4b0d186dd9b075fe88ab80e3afe1d9715f1eb06 Mon Sep 17 00:00:00 2001 From: stale-comment-agent Date: Thu, 14 May 2026 23:54:06 +0000 Subject: [PATCH 063/102] tmp: handle_signer_stackerdb_update doc reward_cycle --- stackslib/src/chainstate/nakamoto/signer_set.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/signer_set.rs b/stackslib/src/chainstate/nakamoto/signer_set.rs index 737ae834b4b..e28b7a77a34 100644 --- a/stackslib/src/chainstate/nakamoto/signer_set.rs +++ b/stackslib/src/chainstate/nakamoto/signer_set.rs @@ -197,7 +197,8 @@ impl NakamotoSigners { } /// Compute the reward set for the next reward cycle, store it, and write it to the .signers - /// contract. `reward_cycle` is the _current_ reward cycle. + /// contract. `reward_cycle` is the upcoming cycle the reward set is being computed *for* + /// (i.e. the cycle the prepare phase is preparing). pub fn handle_signer_stackerdb_update( clarity: &mut ClarityTransactionConnection, pox_constants: &PoxConstants, From 11515b605a8e2974e295ee529d1a75a725dee198 Mon Sep 17 00:00:00 2001 From: swarm Date: Thu, 14 May 2026 23:57:47 +0000 Subject: [PATCH 064/102] stale-comment: address_testnet doc says mainnet --- stackslib/src/chainstate/stacks/auth.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/auth.rs b/stackslib/src/chainstate/stacks/auth.rs index 9bac5dfaf89..aec3d85fe15 100644 --- a/stackslib/src/chainstate/stacks/auth.rs +++ b/stackslib/src/chainstate/stacks/auth.rs @@ -930,7 +930,7 @@ impl TransactionSpendingCondition { } } - /// Get the mainnet account address of the spending condition + /// Get the testnet account address of the spending condition pub fn address_testnet(&self) -> StacksAddress { match *self { TransactionSpendingCondition::Singlesig(ref data) => data.address_testnet(), From e153163ce6b2d3d8e5be76b05f39930d997bc0b9 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:00:28 +0000 Subject: [PATCH 065/102] stale-comment: try_replace_chunk doc lists only StaleChunk --- stackslib/src/net/stackerdb/db.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/stackslib/src/net/stackerdb/db.rs b/stackslib/src/net/stackerdb/db.rs index da5129da371..50f20fc6267 100644 --- a/stackslib/src/net/stackerdb/db.rs +++ b/stackslib/src/net/stackerdb/db.rs @@ -395,8 +395,15 @@ impl StackerDBTx<'_> { Ok(()) } - /// Add or replace a chunk for a given reward cycle, if it is valid - /// Otherwise, this errors out with Error::StaleChunk + /// Add or replace a chunk for a given reward cycle, if it is valid. + /// Otherwise, returns one of: + /// * `net_error::StackerDBChunkTooBig` if `chunk` exceeds the configured maximum size, + /// * `net_error::NoSuchSlot` if the slot does not exist for this DB, + /// * `net_error::BadSlotSigner` if `slot_desc`'s signature does not verify under the slot's + /// configured signer, + /// * `net_error::StaleChunk` if `slot_desc.slot_version` is not strictly greater than the + /// stored slot's version, or + /// * `net_error::TooManySlotWrites` if `slot_desc.slot_version` exceeds `config.max_writes`. pub fn try_replace_chunk( &self, smart_contract: &QualifiedContractIdentifier, From 507a0ec302048a127231c6ddeb4616b9e24372e7 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:04:46 +0000 Subject: [PATCH 066/102] stale-comment: finished_tenure_consensus_hash maps to bool not block ID --- stackslib/src/chainstate/nakamoto/keys.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/keys.rs b/stackslib/src/chainstate/nakamoto/keys.rs index 5883917ec55..e3e0d0263eb 100644 --- a/stackslib/src/chainstate/nakamoto/keys.rs +++ b/stackslib/src/chainstate/nakamoto/keys.rs @@ -57,7 +57,9 @@ pub fn tenure_start_block_id(ch: &ConsensusHash) -> String { format!("nakamoto::headers::tenure_start_block_id::{}", ch) } -/// MARF key to map a tenure to its final block's block ID +/// MARF key marking a tenure as finished. The stored value is the boolean +/// `true` (see `make_bool_value`); presence of this key indicates the tenure +/// has ended, absence indicates it is still in progress. pub fn finished_tenure_consensus_hash(ch: &ConsensusHash) -> String { format!("nakamoto::tenures::finished_tenure_consensus_hash::{}", ch) } From 40aaed666b28e814e4a2f86a04c6bc28098dd1e6 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:06:51 +0000 Subject: [PATCH 067/102] stale-comment: get_nakamoto_tenure_length doc misrepresents return value --- stackslib/src/chainstate/nakamoto/tenure.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/tenure.rs b/stackslib/src/chainstate/nakamoto/tenure.rs index 82e7f1f4b08..1469da99789 100644 --- a/stackslib/src/chainstate/nakamoto/tenure.rs +++ b/stackslib/src/chainstate/nakamoto/tenure.rs @@ -484,9 +484,11 @@ impl NakamotoChainState { Ok(chainstate_conn.get_parent_tenure_consensus_hash(tip_block_id, consensus_hash)?) } - /// Get the number of blocks in a tenure, given a block ID. + /// Get `height_in_tenure` for the Nakamoto block identified by `block_id` + /// (i.e. its 1-indexed position within its tenure). When called with the + /// last block of a tenure, this equals the number of blocks in that tenure. /// Only works for Nakamoto blocks, not Stacks epoch2 blocks. - /// Returns 0 if there are no blocks in this tenure + /// Returns 0 if no row exists for `block_id`. pub fn get_nakamoto_tenure_length( chainstate_conn: &Connection, block_id: &StacksBlockId, From 4440f8332ffbb285402f853c424a00aeeb383727 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:10:18 +0000 Subject: [PATCH 068/102] stale-comment: decode_http_request doc says tuple, returns struct --- libsigner/src/http.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/http.rs b/libsigner/src/http.rs index ba135b69f63..b76cf879222 100644 --- a/libsigner/src/http.rs +++ b/libsigner/src/http.rs @@ -58,7 +58,7 @@ impl SignerHttpRequest { } /// Decode the HTTP request payload into its headers and body. -/// Returns (verb, path, table of headers, body_offset) on success +/// Returns a `SignerHttpRequest` (verb, path, table of headers, body_offset) on success. pub fn decode_http_request(payload: &[u8]) -> Result { // realistically, there won't be more than 32 headers let mut headers_buf = [httparse::EMPTY_HEADER; MAX_HTTP_HEADERS]; From dde9968afbed6325612823277d6666bf515ae15f Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:12:20 +0000 Subject: [PATCH 069/102] stale-comment: make_next_download_request doc lists nonexistent Ok(None) --- stackslib/src/net/download/nakamoto/tenure_downloader.rs | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/stackslib/src/net/download/nakamoto/tenure_downloader.rs b/stackslib/src/net/download/nakamoto/tenure_downloader.rs index d03a7e92d93..80ae17c4662 100644 --- a/stackslib/src/net/download/nakamoto/tenure_downloader.rs +++ b/stackslib/src/net/download/nakamoto/tenure_downloader.rs @@ -479,12 +479,9 @@ impl NakamotoTenureDownloader { /// Produce the next HTTP request that, when successfully executed, will fetch the data needed /// to advance this state machine. - /// Not all states require an HTTP request for advanceement. /// - /// Returns Ok(Some(request)) if a request is needed - /// Returns Ok(None) if a request is not needed (i.e. we're waiting for some other machine's - /// state) - /// Returns Err(()) if we're done. + /// Returns Ok(Some(request)) if a request is needed (any non-`Done` state). + /// Returns Err(()) if we're done (the `Done` state). pub fn make_next_download_request( &self, peerhost: PeerHost, From 189911a10ecc21058a4eb4740c1e2c57dd69814c Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:16:48 +0000 Subject: [PATCH 070/102] stale-comment: get_current_burnchain_block_height doc only describes pre-3.0 path --- clarity/src/vm/database/clarity_db.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/clarity/src/vm/database/clarity_db.rs b/clarity/src/vm/database/clarity_db.rs index e666c76f4f5..6aa27b5326c 100644 --- a/clarity/src/vm/database/clarity_db.rs +++ b/clarity/src/vm/database/clarity_db.rs @@ -1102,10 +1102,14 @@ impl ClarityDatabase<'_> { } /// Get the last-known burnchain block height. - /// Note that this is _not_ the burnchain height in which this block was mined! - /// This is the burnchain block height of the parent of the Stacks block at the current Stacks - /// block height (i.e. that returned by `get_index_block_header_hash` for - /// `get_current_block_height`). + /// + /// Behavior depends on the active Clarity epoch: + /// * Before epoch 3.0, this is the burnchain block height of the parent of the Stacks block + /// at the current Stacks block height (i.e. that returned by `get_index_block_header_hash` + /// for `get_current_block_height`) — note this is _not_ the burnchain height in which this + /// block was mined. + /// * In epoch 3.0+, this is the current burnchain tip height (queried directly via + /// `BurnStateDB::get_tip_burn_block_height`). pub fn get_current_burnchain_block_height(&mut self) -> Result { let cur_stacks_height = self.store.get_current_block_height(); From 0fa6a452dbbb059c7791f57ee1f6fcff12b7dbe7 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:19:07 +0000 Subject: [PATCH 071/102] stale-comment: walk_peer_graph doc reverses tuple order --- stackslib/src/net/neighbors/mod.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/stackslib/src/net/neighbors/mod.rs b/stackslib/src/net/neighbors/mod.rs index 2a49bad96f2..2347a48419b 100644 --- a/stackslib/src/net/neighbors/mod.rs +++ b/stackslib/src/net/neighbors/mod.rs @@ -392,8 +392,11 @@ impl PeerNetwork { /// Update the state of our peer graph walk. /// If we complete a walk, give back a walk result. /// Mask errors by restarting the graph walk. - /// Returns the walk result, and a true/false flag to indicate whether or not the work for the - /// walk was finished (i.e. we either completed the walk, or we reset the walk) + /// Returns a tuple `(done, walk_result_opt)`: + /// * `done` — `true` if the work for the walk was finished (i.e. we either completed the walk, + /// or we reset the walk), `false` if there is more progress still to make. + /// * `walk_result_opt` — `Some(result)` if the walk ran to completion this call, `None` + /// otherwise. pub fn walk_peer_graph(&mut self, ibd: bool) -> (bool, Option) { if !self.setup_walk(ibd) { // nothing to do From 332717f63754fd831045a265935ff6062b5715ea Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:29:46 +0000 Subject: [PATCH 072/102] stale-comment: get_db_version_from_path doc says string; returns u32 --- stackslib/src/chainstate/burn/db/sortdb.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/burn/db/sortdb.rs b/stackslib/src/chainstate/burn/db/sortdb.rs index a9055a787ce..394014c8b6e 100644 --- a/stackslib/src/chainstate/burn/db/sortdb.rs +++ b/stackslib/src/chainstate/burn/db/sortdb.rs @@ -3125,7 +3125,7 @@ impl SortitionDB { } /// Get the schema version of a sortition DB, given the path to it. - /// Returns the version string, if it exists. + /// Returns the version number as a `u32`, if it exists. /// /// Does **not** migrate the database (like `open()` or `connect()` would) pub fn get_db_version_from_path(path: &str) -> Result, db_error> { From 606fd06a038fdb10f57ab9a3d8d4d2e2126cbfc8 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:36:42 +0000 Subject: [PATCH 073/102] stale-comment: SignerEntries::parse doc names nonexistent type NakamotoSignEntry --- libsigner/src/signer_set.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/signer_set.rs b/libsigner/src/signer_set.rs index 75c25bacbfd..ab337dfd7fe 100644 --- a/libsigner/src/signer_set.rs +++ b/libsigner/src/signer_set.rs @@ -48,7 +48,7 @@ pub enum Error { } impl SignerEntries { - /// Try to parse the reward set defined by `NakamotoSignEntry` into the SignerEntries struct + /// Try to parse the reward set defined by `NakamotoSignerEntry` into the SignerEntries struct pub fn parse(is_mainnet: bool, reward_set: &[NakamotoSignerEntry]) -> Result { let mut signer_pk_to_id = HashMap::with_capacity(reward_set.len()); let mut signer_id_to_pk = HashMap::with_capacity(reward_set.len()); From 986db08a9effc8ca95191e7b7bdf8afb67615d32 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 00:40:24 +0000 Subject: [PATCH 074/102] stale-comment: store_burnchain_db_entry doc claims row ID; returns () --- stackslib/src/burnchains/db.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/burnchains/db.rs b/stackslib/src/burnchains/db.rs index 99e835855ce..68b6d22b046 100644 --- a/stackslib/src/burnchains/db.rs +++ b/stackslib/src/burnchains/db.rs @@ -341,7 +341,7 @@ pub static SCHEMA_3: &[&str] = &[ impl BurnchainDBTransaction<'_> { /// Store a burnchain block header into the burnchain database. - /// Returns the row ID on success. + /// Uses `INSERT OR IGNORE`, so a duplicate header is silently dropped. pub(crate) fn store_burnchain_db_entry( &self, header: &BurnchainBlockHeader, From 6cf8bd778854d7861564f201106794b1a74fd6b4 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 01:47:19 +0000 Subject: [PATCH 075/102] stale-comment: SortitionHash::initial doc describes mix_burn_header --- stackslib/src/chainstate/burn/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/burn/mod.rs b/stackslib/src/chainstate/burn/mod.rs index 6a12d68dd9a..437a6ff8173 100644 --- a/stackslib/src/chainstate/burn/mod.rs +++ b/stackslib/src/chainstate/burn/mod.rs @@ -113,7 +113,7 @@ pub struct BlockSnapshot { } impl SortitionHash { - /// Calculate a new sortition hash from the given burn header hash + /// Initial sortition hash, used before any burn header is mixed in. It's all 0's. pub fn initial() -> SortitionHash { SortitionHash([0u8; 32]) } From a787bffaa291a8881b89a600a68bc5d74d742412 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 02:00:08 +0000 Subject: [PATCH 076/102] stale-comment: finish_block doc omits SIP-031 event from FinishBlockEvents --- stackslib/src/chainstate/nakamoto/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index fad0c584586..299a34f3692 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -4397,7 +4397,7 @@ impl NakamotoChainState { /// `mine_anchored_block` in miner.rs. /// Processes matured miner rewards, alters liquid supply of ustx, processes /// stx lock events, and marks the microblock public key as used - /// Returns stx lockup events. + /// Returns the stx lockup events and (on a new tenure) the SIP-031 mint/transfer event. pub fn finish_block( clarity_tx: &mut ClarityTx, miner_payouts: Option<&MaturedMinerRewards>, From 2d8cd76e96d5831c74dcdcd2501292a5f59f0b2e Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 02:03:55 +0000 Subject: [PATCH 077/102] stale-comment: get_block_cost doc says 'of block' but queries total_tenure_cost --- stackslib/src/chainstate/nakamoto/mod.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index 299a34f3692..d25de971e89 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -2544,7 +2544,9 @@ impl NakamotoChainState { .map_err(ChainstateError::from) } - /// Return the ExecutionCost of `block` + /// Return the total tenure ExecutionCost up to and including `block`. + /// This queries the `total_tenure_cost` column (cumulative); use the `cost` column for the + /// per-block ExecutionCost. pub fn get_block_cost( chainstate_conn: &Connection, block: &StacksBlockId, From f2c8dd8f5c5d0aff94156d035262ea06a52c50c8 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 02:06:46 +0000 Subject: [PATCH 078/102] stale-comment: get_tx_info_from_txid doc lists 2 of 3 returned values --- stackslib/src/chainstate/nakamoto/mod.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index d25de971e89..700d00c6d5d 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -3720,7 +3720,8 @@ impl NakamotoChainState { } } - /// Get index_block_hash and transaction payload hex by txid from the transactions table + /// Get the index_block_hash, transaction payload hex, and execution result string for a txid + /// from the transactions table. pub fn get_tx_info_from_txid( conn: &Connection, txid: &Txid, From c398e58216b6f848d2e1bab3a0edf9cf8323779e Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 02:28:05 +0000 Subject: [PATCH 079/102] stale-comment: decode_http_response doc has tuple order reversed --- libsigner/src/http.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/http.rs b/libsigner/src/http.rs index b76cf879222..304360ffa87 100644 --- a/libsigner/src/http.rs +++ b/libsigner/src/http.rs @@ -123,7 +123,7 @@ pub fn decode_http_request(payload: &[u8]) -> Result Date: Fri, 15 May 2026 02:40:23 +0000 Subject: [PATCH 080/102] stale-comment: add_block_rejection_signer_addr doc says signature --- stacks-signer/src/signerdb.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stacks-signer/src/signerdb.rs b/stacks-signer/src/signerdb.rs index 5cdc9705052..7b276ecc062 100644 --- a/stacks-signer/src/signerdb.rs +++ b/stacks-signer/src/signerdb.rs @@ -1738,7 +1738,9 @@ impl SignerDb { .collect() } - /// Record an observed block rejection_signature + /// Record an observed block rejection from a signer, identified by the signer's address and + /// the `RejectReasonPrefix` reject code. Does not record a signature; signatures are recorded + /// by `add_block_signature`. pub fn add_block_rejection_signer_addr( &self, block_sighash: &Sha512Trunc256Sum, From a16d8f7f44690f7ffd0093429ed26ee194f8ba37 Mon Sep 17 00:00:00 2001 From: swarm Date: Fri, 15 May 2026 02:55:03 +0000 Subject: [PATCH 081/102] stale-comment: append_block doc omits Option --- stackslib/src/chainstate/stacks/db/blocks.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index aadd203ded1..0bbfd584e5e 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -5328,7 +5328,8 @@ impl StacksChainState { /// processed yet. /// /// Returns a `StacksEpochReceipt` containing receipts and events from the transactions executed - /// in the block, and a `PreCommitClarityBlock` struct. + /// in the block, a `PreCommitClarityBlock` struct, and an `Option` describing + /// the reward set just computed at this block (if any). /// /// The `StacksEpochReceipts` contains the list of transaction /// receipts for the preceeding microblock stream that the From 2b469ad73d1e1eb090a647079c2410cdf769ad16 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 03:35:19 +0000 Subject: [PATCH 082/102] doc: BlockProposalData::new mentions miner_diagnostic_data, not unknown_bytes --- libsigner/src/events.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsigner/src/events.rs b/libsigner/src/events.rs index 71e4c593421..d2d47f581c9 100644 --- a/libsigner/src/events.rs +++ b/libsigner/src/events.rs @@ -111,7 +111,7 @@ pub struct BlockProposalData { } impl BlockProposalData { - /// Create a new BlockProposalData for the provided server version and unknown bytes + /// Create a new BlockProposalData for the provided server version and miner diagnostic data. pub fn new(server_version: String, miner_diagnostic_data: MinerDiagnosticData) -> Self { Self { version: BLOCK_PROPOSAL_DATA_VERSION, From e3e60040826481ed976a8e86b264b60152d5d9a4 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 03:44:09 +0000 Subject: [PATCH 083/102] doc: handle_comms_epoch2 takes bits, not comms --- stackslib/src/chainstate/coordinator/mod.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/coordinator/mod.rs b/stackslib/src/chainstate/coordinator/mod.rs index e78303dbc6a..c0d7ce7b470 100644 --- a/stackslib/src/chainstate/coordinator/mod.rs +++ b/stackslib/src/chainstate/coordinator/mod.rs @@ -558,8 +558,7 @@ impl< } /// This is the Stacks 2.x coordinator loop body, which handles communications - /// from the given `comms`. It returns `true` if the coordinator is still running, and `false` - /// if not. + /// dispatched by the given event `bits`. Returns `true` if the coordinator is still running, and `false` otherwise. pub fn handle_comms_epoch2(&mut self, bits: u8, miner_status: Arc>) -> bool { // timeout so that we handle Ctrl-C a little gracefully if (bits & (CoordinatorEvents::NEW_STACKS_BLOCK as u8)) != 0 { From b96f3e944ae9da2770e59439f022a523ad9a7b19 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 03:47:49 +0000 Subject: [PATCH 084/102] doc: handle_new_nakamoto_stacks_block always returns Ok(None) on success --- stackslib/src/chainstate/nakamoto/coordinator/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs index d2e9e175c86..f19a471a4f9 100644 --- a/stackslib/src/chainstate/nakamoto/coordinator/mod.rs +++ b/stackslib/src/chainstate/nakamoto/coordinator/mod.rs @@ -765,10 +765,10 @@ impl< fn fault_injection_pause_nakamoto_block_processing() {} /// Handle one or more new Nakamoto Stacks blocks. - /// If we process a PoX anchor block, then return its block hash. This unblocks processing the - /// next reward cycle's burnchain blocks. Subsequent calls to this function will terminate - /// with Some(pox-anchor-block-hash) until the reward cycle info is processed in the sortition - /// DB. + /// When this function reaches the first Stacks block in the prepare phase for the next reward + /// cycle, it pauses to process burnchain sortitions for that cycle (via an inline call to + /// `handle_new_nakamoto_burnchain_block`) before continuing. The successful return is always + /// `Ok(None)`; the `Option` in the return type is reserved for future use. pub fn handle_new_nakamoto_stacks_block(&mut self) -> Result, Error> { debug!("Handle new Nakamoto block"); let canonical_sortition_tip = self.canonical_sortition_tip.clone().ok_or_else(|| { From ea61e064fd304c1992b55ff04c7fc8f1929e095a Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 03:50:13 +0000 Subject: [PATCH 085/102] doc: handle_pox_cycle_start_pox_4 is a no-op --- stackslib/src/chainstate/stacks/boot/mod.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/stackslib/src/chainstate/stacks/boot/mod.rs b/stackslib/src/chainstate/stacks/boot/mod.rs index ee784d6cc64..3e6749ce95d 100644 --- a/stackslib/src/chainstate/stacks/boot/mod.rs +++ b/stackslib/src/chainstate/stacks/boot/mod.rs @@ -507,10 +507,9 @@ impl StacksChainState { // TODO: add tests from mutation testing results #4854 #[cfg_attr(test, mutants::skip)] - /// Do all the necessary Clarity operations at the start of a PoX reward cycle. - /// Currently, this just means applying any auto-unlocks to Stackers who qualified. - /// - /// This should only be called for PoX v4 cycles. + /// No-op start-of-cycle hook for PoX v4. PoX v4 has no Rust-side start-of-cycle + /// operations (unlike v2/v3, which apply missed auto-unlocks here); kept for symmetry + /// with the v2 and v3 helpers. Returns an empty event vector. pub fn handle_pox_cycle_start_pox_4( _clarity: &mut ClarityTransactionConnection, _cycle_number: u64, From 5da221d12120e0d1dee30b4cfff743fa92189057 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 04:04:59 +0000 Subject: [PATCH 086/102] doc: relay_epoch3_blocks uses recently_sent map, not force_send param --- stackslib/src/net/relay.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/stackslib/src/net/relay.rs b/stackslib/src/net/relay.rs index edaabba46e7..78e50180138 100644 --- a/stackslib/src/net/relay.rs +++ b/stackslib/src/net/relay.rs @@ -2645,8 +2645,10 @@ impl Relayer { #[cfg_attr(test, mutants::skip)] /// Relay Nakamoto blocks. - /// By default, only sends them if we don't have them yet. - /// This can be overridden by setting `force_send` to true. + /// Each block is skipped if it was already relayed within + /// `connection_opts.nakamoto_push_interval_ms` (tracked via + /// `self.recently_sent_nakamoto_blocks`), or if its tenure is not in the + /// last `connection_opts.max_nakamoto_block_relay_age` sortitions. pub fn relay_epoch3_blocks( &mut self, _local_peer: &LocalPeer, From a9513c276d31af9cba9ed350cc9028b848744f2c Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 04:24:16 +0000 Subject: [PATCH 087/102] doc: effective_unlock_height mentions PoX 4 early unlock for PoX 3 --- clarity/src/vm/database/structures.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/clarity/src/vm/database/structures.rs b/clarity/src/vm/database/structures.rs index 526a8c3e1cd..ef833f75d07 100644 --- a/clarity/src/vm/database/structures.rs +++ b/clarity/src/vm/database/structures.rs @@ -1036,7 +1036,8 @@ impl STXBalance { } /// This method returns the datastructure's lazy view of the unlock_height - /// *while* factoring in the PoX 2 early unlock for PoX 1 and PoX 3 early unlock for PoX 2. + /// *while* factoring in the PoX 2 early unlock for PoX 1, the PoX 3 early + /// unlock for PoX 2, and the PoX 4 early unlock for PoX 3. /// This value is still lazy: this unlock height may be less than the current /// burn block height, if so it will be updated in a canonicalized view. pub fn effective_unlock_height( From 938e0f9017226fb9207fcde9bb2b7daf02444245 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 04:32:19 +0000 Subject: [PATCH 088/102] doc: tx_busy_handler never panics; describes actual behaviour --- stacks-common/src/util/db.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/stacks-common/src/util/db.rs b/stacks-common/src/util/db.rs index da629dfde25..e5ae3a75b69 100644 --- a/stacks-common/src/util/db.rs +++ b/stacks-common/src/util/db.rs @@ -48,8 +48,10 @@ pub fn update_lock_table(conn: &Connection) { LOCK_TABLE.lock().unwrap().insert(k, v); } -/// Called by `rusqlite` if we are waiting too long on a database lock -/// If called too many times, will assume a deadlock and panic +/// Called by `rusqlite` if we are waiting too long on a database lock. +/// Logs an error with a backtrace and the current `LOCK_TABLE` every +/// ~5 minutes of accumulated waiting, then keeps sleeping and returning +/// `true` so `rusqlite` retries the lock indefinitely. pub fn tx_busy_handler(run_count: i32) -> bool { const AVG_SLEEP_TIME_MS: u64 = 100; From 309977880ada1d0b8f2a0363774f6a7dae680f42 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 04:56:48 +0000 Subject: [PATCH 089/102] doc: inner_execute_contract refers to ExecutionState, not Environment The Environment struct was split into ExecutionState/InvocationContext/ GlobalContext in commit f9f5e5c47c; the inline reference in the doc- comment on inner_execute_contract still pointed at the old type name. --- clarity/src/vm/contexts.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clarity/src/vm/contexts.rs b/clarity/src/vm/contexts.rs index 784edf564dc..6569131921c 100644 --- a/clarity/src/vm/contexts.rs +++ b/clarity/src/vm/contexts.rs @@ -1257,7 +1257,7 @@ impl<'a, 'b, 'hooks> ExecutionState<'a, 'b, 'hooks> { /// `allow_private` should always be set to `false` for user transactions: /// this ensures that only `define-public` and `define-read-only` methods can /// be invoked. The `allow_private` mode should only be used by - /// `Environment::execute_contract_allow_private`. + /// `ExecutionState::execute_contract_allow_private`. fn inner_execute_contract( &mut self, invoke_ctx: &InvocationContext, From d7c92788ceb1a7a26b6f65a8caea526fb665d9bf Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 05:35:07 +0000 Subject: [PATCH 090/102] quality: 018 process-stx-unlocks-tuple-doc --- stackslib/src/chainstate/stacks/db/blocks.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index 0bbfd584e5e..f0cb57fa09f 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -4593,7 +4593,9 @@ impl StacksChainState { } /// Process all STX that unlock at this block height. - /// Return the total number of uSTX unlocked in this block + /// Returns `(total_unlocked_ustx, lockup_events)`, where `total_unlocked_ustx` is the total + /// number of uSTX unlocked in this block and `lockup_events` is the list of `STXMintEvent`s + /// emitted for each unlocked recipient. pub fn process_stx_unlocks( clarity_tx: &mut ClarityTx<'_, '_>, ) -> Result<(u128, Vec), Error> { From 4f9fbd7382ac6d35e6fc8b5b25caa380358d9545 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 05:37:00 +0000 Subject: [PATCH 091/102] quality: 019 setup-block-doc-omits-six-fields --- stackslib/src/chainstate/stacks/db/blocks.rs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index f0cb57fa09f..bd14ea10f26 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -4985,10 +4985,13 @@ impl StacksChainState { /// Called in both follower and miner block assembly paths. /// - /// Returns clarity_tx, list of receipts, microblock execution cost, - /// microblock fees, microblock burns, list of microblock tx receipts, - /// miner rewards tuples, the stacks epoch id, and a boolean that - /// represents whether the epoch transition has been applied. + /// Returns a `SetupBlockResult`, which contains: clarity_tx, list of receipts, + /// microblock execution cost, microblock fees, microblock burns, list of + /// microblock tx receipts, miner rewards tuples, the stacks epoch id, a boolean + /// that represents whether the epoch transition has been applied, the + /// burnchain-originated stack-stx / transfer-stx / delegate-stx / vote-for-agg-key + /// operations applied in this block, the auto-unlock events emitted by reward-cycle + /// processing, and an optional signer-set calculation result. /// /// The `burn_dbconn`, `sortition_dbconn`, and `conn` arguments /// all reference the same sortition database through different From 1eacc6e0ed3cdc933739f3396539f6070908b159 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 05:45:51 +0000 Subject: [PATCH 092/102] quality: 020 process-microblocks-transactions-doc-omits-receipts --- stackslib/src/chainstate/stacks/db/blocks.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index bd14ea10f26..bdf9ee8916b 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -3918,8 +3918,8 @@ impl StacksChainState { Ok(None) } - /// Process a stream of microblocks - /// Return the fees and burns. + /// Process a stream of microblocks. + /// Returns `(fees, burns, receipts)` on success. pub fn process_microblocks_transactions( clarity_tx: &mut ClarityTx, microblocks: &[StacksMicroblock], From d37b6ab1498a0edfbc50f27cab67afd3b66b9769 Mon Sep 17 00:00:00 2001 From: quality-swarm Date: Fri, 15 May 2026 05:47:16 +0000 Subject: [PATCH 093/102] quality: 021 process-block-transactions-doc-omits-receipts --- stackslib/src/chainstate/stacks/db/blocks.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/stacks/db/blocks.rs b/stackslib/src/chainstate/stacks/db/blocks.rs index bdf9ee8916b..e2df77445bf 100644 --- a/stackslib/src/chainstate/stacks/db/blocks.rs +++ b/stackslib/src/chainstate/stacks/db/blocks.rs @@ -4491,7 +4491,7 @@ impl StacksChainState { } /// Process a single anchored block. - /// Return the fees and burns. + /// Returns `(fees, burns, receipts)` on success. pub fn process_block_transactions( clarity_tx: &mut ClarityTx, block_txs: &[StacksTransaction], From 844c4ffd12e7f152d7b3b86b892fdfd0fe0858be Mon Sep 17 00:00:00 2001 From: quality-agent Date: Fri, 15 May 2026 06:31:12 +0000 Subject: [PATCH 094/102] doc: fix burn-block-info property identifiers in special_get_burn_block_info --- clarity/src/vm/functions/database.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/clarity/src/vm/functions/database.rs b/clarity/src/vm/functions/database.rs index 4c97d361ca6..2390703c705 100644 --- a/clarity/src/vm/functions/database.rs +++ b/clarity/src/vm/functions/database.rs @@ -1091,10 +1091,10 @@ pub fn special_get_block_info( } /// Handles the `get-burn-block-info?` special function. -/// Interprets `args` as variables `[property_name, burn_block_height]`, and returns -/// a property value determined by `property_name`: -/// - `header_hash` returns the burn block header hash at `burn_block_height` -/// - `pox_addrs` returns the list of PoX addresses paid out at `burn_block_height` +/// Interprets `args` as variables `[property-name, burn-block-height]`, and returns +/// a property value determined by `property-name`: +/// - `header-hash` returns the burn block header hash at `burn-block-height` +/// - `pox-addrs` returns the list of PoX addresses paid out at `burn-block-height` /// /// # Errors: /// - [`RuntimeCheckErrorKind::IncorrectArgumentCount`] if there aren't 2 arguments. From 954d7bd2389ce55fe409dece22ccfbf43f95932a Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 06:38:50 +0000 Subject: [PATCH 095/102] fix doc comment for EarlyReturnError::UnwrapFailed --- clarity/src/vm/errors.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/clarity/src/vm/errors.rs b/clarity/src/vm/errors.rs index 8f6fa863494..00a486a1475 100644 --- a/clarity/src/vm/errors.rs +++ b/clarity/src/vm/errors.rs @@ -173,8 +173,8 @@ pub enum RuntimeError { /// These errors halt evaluation and fail the transaction. pub enum EarlyReturnError { /// Failed to unwrap an `Optional` (`none`) or `Response` (`err` or `ok`) Clarity value. - /// The `Box` holds the original or thrown value. Triggered by `try!`, `unwrap-or`, or - /// `unwrap-err-or`. + /// The `Box` holds the original or thrown value. Triggered by `try!`, `unwrap!`, or + /// `unwrap-err!`. UnwrapFailed(Box), /// An 'asserts!' expression evaluated to false. /// The `Box` holds the value provided as the second argument to `asserts!`. From e48e2eb4d7b375261fd9f0f7176ef5742775419a Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 06:48:18 +0000 Subject: [PATCH 096/102] fix LruCache::flush doc to match flattened Result type --- stacks-common/src/util/lru_cache.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/stacks-common/src/util/lru_cache.rs b/stacks-common/src/util/lru_cache.rs index 91233d9ec4e..83005a88bcb 100644 --- a/stacks-common/src/util/lru_cache.rs +++ b/stacks-common/src/util/lru_cache.rs @@ -204,8 +204,7 @@ impl LruCache { /// Flush all dirty values in the cache, calling the given function, `f`, /// for each dirty value. - /// Outer result is an error iff the cache is corrupted and should be discarded. - /// Inner result is an error iff the function, `f`, returns an error. + /// Returns an error iff the function, `f`, returns an error. pub fn flush( &mut self, mut f: impl FnMut(&K, V) -> Result<(), E>, From 21d6bf010d792028bad527768f6d462d9c90344c Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 06:59:35 +0000 Subject: [PATCH 097/102] fix get_reward_set doc to match return type --- stacks-signer/src/client/stacks_client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-signer/src/client/stacks_client.rs b/stacks-signer/src/client/stacks_client.rs index 0739fd72bab..4cf7ecc696d 100644 --- a/stacks-signer/src/client/stacks_client.rs +++ b/stacks-signer/src/client/stacks_client.rs @@ -476,7 +476,7 @@ impl StacksClient { Ok(self.get_reward_set(reward_cycle)?.stacker_set.signers) } - /// Get the reward set signers from the stacks node for the given reward cycle + /// Get the reward set from the stacks node for the given reward cycle pub fn get_reward_set(&self, reward_cycle: u64) -> Result { debug!("StacksClient: Getting reward set signers"; "reward_cycle" => reward_cycle, From 3bffda1c575e0d1c526a5bd6673f38cefdd0758f Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 07:20:23 +0000 Subject: [PATCH 098/102] fix verify_signer_signatures doc to include NoRegisteredSigners --- stackslib/src/chainstate/nakamoto/mod.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stackslib/src/chainstate/nakamoto/mod.rs b/stackslib/src/chainstate/nakamoto/mod.rs index 700d00c6d5d..c39366d4652 100644 --- a/stackslib/src/chainstate/nakamoto/mod.rs +++ b/stackslib/src/chainstate/nakamoto/mod.rs @@ -841,7 +841,8 @@ impl NakamotoBlockHeader { /// - Order of signatures is maintained vs signer set /// /// Returns the signing weight on success. - /// Returns ChainstateError::InvalidStacksBlock on error + /// Returns ChainstateError::InvalidStacksBlock when the signatures fail validation, + /// or ChainstateError::NoRegisteredSigners if the reward set has no signers. #[cfg_attr(test, mutants::skip)] pub fn verify_signer_signatures(&self, reward_set: &RewardSet) -> Result { let message = self.signer_signature_hash(); From 520c3942e15a5a7cfcb8cbd119f415b37cc201ab Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 07:47:11 +0000 Subject: [PATCH 099/102] fix get_read_count_extend_timestamp doc: copy-paste from tenure-extend --- stacks-node/src/nakamoto_node/stackerdb_listener.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stacks-node/src/nakamoto_node/stackerdb_listener.rs b/stacks-node/src/nakamoto_node/stackerdb_listener.rs index 6045a5e3bd6..5d4bdf3d6b4 100644 --- a/stacks-node/src/nakamoto_node/stackerdb_listener.rs +++ b/stacks-node/src/nakamoto_node/stackerdb_listener.rs @@ -749,7 +749,7 @@ impl StackerDBListenerComms { } /// Get the timestamp at which at least 70% of the signing power should be - /// willing to accept a time-based tenure extension. + /// willing to accept a time-based read-count extension. pub fn get_read_count_extend_timestamp(&self, weight_threshold: u32) -> u64 { let signer_read_count_timestamps = self .signer_read_count_timestamps From 39b45c6b21e2143c6a5d633ac9ec686f57fc5cf3 Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 07:49:41 +0000 Subject: [PATCH 100/102] fix check_burnchain_config_changed doc: actual return tuple, unconditional updates --- stacks-node/src/nakamoto_node/relayer.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/stacks-node/src/nakamoto_node/relayer.rs b/stacks-node/src/nakamoto_node/relayer.rs index 4d54fe26d64..ebfc6e89021 100644 --- a/stacks-node/src/nakamoto_node/relayer.rs +++ b/stacks-node/src/nakamoto_node/relayer.rs @@ -2284,8 +2284,10 @@ impl RelayerThread { continue_running } - /// Reload config.burnchain to see if burn_fee_cap has changed. - /// If it has, update the miner spend amount and return true. + /// Reload `config.burnchain` and check whether it has changed from the last observed value. + /// Unconditionally update the miner's recorded spend amount and last-seen burnchain config. + /// Returns `(changed, current_burnchain_config)` where `changed` is true iff the burnchain + /// config differs from the last one observed (false on the first call). pub fn check_burnchain_config_changed(&self) -> (bool, BurnchainConfig) { let burnchain_config = self.config.get_burnchain_config(); let last_burnchain_config_opt = self.globals.get_last_burnchain_config(); From 5789dd39dc1a26fc927a08a5bbf503fc4a56e961 Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 08:18:14 +0000 Subject: [PATCH 101/102] docs: pox-locking pox_lock_extend/increase docs use LockingError, not Error --- pox-locking/src/pox_2.rs | 4 ++-- pox-locking/src/pox_3.rs | 4 ++-- pox-locking/src/pox_4.rs | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pox-locking/src/pox_2.rs b/pox-locking/src/pox_2.rs index 112ade18af3..0e488a60ed0 100644 --- a/pox-locking/src/pox_2.rs +++ b/pox-locking/src/pox_2.rs @@ -172,7 +172,7 @@ pub fn parse_pox_increase(result: &Value) -> std::result::Result<(PrincipalData, /// Returns Ok( account snapshot ) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v2 contract, /// so this should surface in a panic. pub fn pox_lock_increase_v2( @@ -225,7 +225,7 @@ pub fn pox_lock_increase_v2( /// Returns Ok(lock_amount) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v2 contract, /// so this should surface in a panic. pub fn pox_lock_extend_v2( diff --git a/pox-locking/src/pox_3.rs b/pox-locking/src/pox_3.rs index 1aefe8ec05d..58108ef92ee 100644 --- a/pox-locking/src/pox_3.rs +++ b/pox-locking/src/pox_3.rs @@ -95,7 +95,7 @@ pub fn pox_lock_v3( /// Returns Ok(lock_amount) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v3 contract, /// so this should surface in a panic. pub fn pox_lock_extend_v3( @@ -131,7 +131,7 @@ pub fn pox_lock_extend_v3( /// Returns Ok( account snapshot ) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v3 contract, /// so this should surface in a panic. pub fn pox_lock_increase_v3( diff --git a/pox-locking/src/pox_4.rs b/pox-locking/src/pox_4.rs index de8eeea38bc..413c00e4efa 100644 --- a/pox-locking/src/pox_4.rs +++ b/pox-locking/src/pox_4.rs @@ -68,7 +68,7 @@ pub fn pox_lock_v4( /// Returns Ok(lock_amount) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v4 contract, /// so this should surface in a panic. pub fn pox_lock_extend_v4( @@ -104,7 +104,7 @@ pub fn pox_lock_extend_v4( /// Returns Ok( account snapshot ) when successful /// /// # Errors -/// - Returns Error::PoxExtendNotLocked if this function was called on an account +/// - Returns LockingError::PoxExtendNotLocked if this function was called on an account /// which isn't locked. This *should* have been checked by the PoX v4 contract, /// so this should surface in a panic. pub fn pox_lock_increase_v4( From fe029dd7004fbb0c701010656dd2384a44818d22 Mon Sep 17 00:00:00 2001 From: quality-bot Date: Fri, 15 May 2026 08:32:59 +0000 Subject: [PATCH 102/102] docs: static_check_problematic_relayed_tx returns Result<(), Error>, not bool --- stackslib/src/net/relay.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stackslib/src/net/relay.rs b/stackslib/src/net/relay.rs index 78e50180138..913f0e3d7da 100644 --- a/stackslib/src/net/relay.rs +++ b/stackslib/src/net/relay.rs @@ -1766,8 +1766,8 @@ impl Relayer { /// Verify that a relayed transaction is not problematic. This is a static check -- we only /// look at the tx contents. /// - /// Return true if the check passes -- i.e. it's not problematic - /// Return false if the check fails -- i.e. it is problematic + /// Return `Ok(())` if the check passes -- i.e. it's not problematic + /// Return `Err(..)` if the check fails -- i.e. it is problematic pub fn static_check_problematic_relayed_tx( mainnet: bool, epoch_id: StacksEpochId,