feat: improve block selection in `stacks-inspect`

[brice-stacks]

Improves the UX by merging validate-naka-block and validate-block, improves the lookup time by optimizing the queries, and improves the output for a better experience. Adds --early-exit flag to exit on first error instead of completing all blocks.

[codecov[bot]]

Codecov Report

:x: Patch coverage is 1.30293% with 303 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 77.23%. Comparing base (e156f8d) to head (9487007).

Files with missing lines	Patch %	Lines
contrib/stacks-inspect/src/lib.rs	0.00%	302 Missing :warning:
stackslib/src/chainstate/stacks/db/blocks.rs	80.00%	1 Missing :warning:

:x: Your project check has failed because the head coverage (77.23%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6735      +/-   ##
===========================================
+ Coverage    68.57%   77.23%   +8.65%     
===========================================
  Files          582      582              
  Lines       361458   361607     +149     
===========================================
+ Hits        247879   279293   +31414     
+ Misses      113579    82314   -31265     

Files with missing lines	Coverage Δ
contrib/stacks-inspect/src/main.rs	0.00% <ø> (ø)
stackslib/src/chainstate/stacks/db/blocks.rs	88.16% <80.00%> (+9.33%)	:arrow_up:
contrib/stacks-inspect/src/lib.rs	4.24% <0.00%> (-0.82%)	:arrow_down:

... and 342 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update e156f8d...9487007. Read the comment docs.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jcnelson]

I think @wileyj should try this patch out on a block-replay before merging, because the corresponding block validation script will need to be updated to use this new CLI.

That said, I'm kinda iffy on whether or not it was a good idea to put stacks-inspect into contrib if it's going to serve such a vital purpose in the release process. Is there a level of support we could have for stacks-inspect that's above what's in contrib, but without adding it to the bug bounty program? Maybe a question for @dhaney-stacks

[wileyj]

it's a block validation party today - will start once #6754 is complete. regarding keeping this in contrib, as long as we can easily exclude stacks-inspect code from any big bounty program it could be moved back to the repo root or something.

[wileyj]

updated the validation script, and a few things are odd so far (not sure if it's bad or not, but it is behaving differently than stacks-inspect in 3.3.0.0.3 for example). when validating pre-nakamoto blocks, the speed of earlier blocks finishes much faster, and it seems to be progressively slower for each process. ex: if i partition the total number of blocks and validation those blocks - the first blocks finish much faster. 100_000 blocks 10 partitions 10_000 blocks per partition partition0 finishes quite fast (these would be the first blocks in the chain, probably smaller blocks without much activity - finishes in a few minutes) partition9 will take much longer (larger blocks, more txs etc and takes a few hours)

for comparison, in 3.3.0.0.3 - each partition took roughly the same amount of time when using the (deprecated in this PR) function index-range, roughly 12_700s for each partition.

==> slice0.log <==
Command: /home/wileyj/stacks-inspect/target/release/stacks-inspect --config /home/wileyj/stacks-inspect/stackslib/conf/mainnet-follower-conf.toml validate-block  /home/wileyj/scratch/slice0 range 0 15469 2>/dev/null
Validating indexed blocks: 0-15469 (out of 185630)
Validating: 100% (16602/16602)

Finished validating 16602 blocks in 439s
0
==> slice1.log <==
Command: /home/wileyj/stacks-inspect/target/release/stacks-inspect --config /home/wileyj/stacks-inspect/stackslib/conf/mainnet-follower-conf.toml validate-block  /home/wileyj/scratch/slice1 range 15469 30938 2>/dev/null
Validating indexed blocks: 15469-30938 (out of 185630)
Validating:  53% (9004/16719)
==> slice2.log <==
... 
==> slice9.log <==
Command: /home/wileyj/stacks-inspect/target/release/stacks-inspect --config /home/wileyj/stacks-inspect/stackslib/conf/mainnet-follower-conf.toml validate-block  /home/wileyj/scratch/slice9 range 139221 154690 2>/dev/null
Validating indexed blocks: 139221-154690 (out of 185630)
Validating:   1% (300/17143)

i'm running a complete validation now, will share more details once it's complete and the logs are full.

[wileyj]

attaching output from validating all blocks using range across 12 partitions. logs.zip

as noted on the call, since hte blocks are processed serially - it makes more sense why the earlier blocks are validated much faster than the later blocks, and why some partitions take substantially longer than with version of stacks-inspect in develop branch (which doesn't process the blocks serially).

overall, a full run with from this branch took roughly 13 hours whereas from develop it was around 11 hours.

i will also introduce a block failure and re-run to see how the binary change logs validation failures

[wileyj]

@brice-stacks for readability - this is a little awkward. would be it possible to put the failure on a separate line?

note that this is a synthetic failure i introduced for epoch 2.5 to see what the output looks like

$ /home/wileyj/stacks-inspect/target/release/stacks-inspect --config /home/wileyj/stacks-inspect/stackslib/conf/mainnet-follower-conf.toml validate-block  /home/wileyj/scratch/slice0 range 107054 107056 2>/dev/null
Validating:  66% (2/3)Failed processing block! block = e60964eb18499310d30fe140725aa7f2d67d9aa6339ffd891cc06a36b6585ae0, error = InvalidStacksBlock("Block d442968758f7cf09927223bfcc86585adea0bd847f9438972ee2e8f33aa07d7f state root mismatch: expected ae1b7b0a25589259e13408e7e056e8d64e657da4305909bb34a3120396b49ddf, got b7795364840ba230f6bcd99d672760f17ce9b3a1208b7b09cb6eb32259e74b5a")

since the use case here is to not stop once a failure is discovered, it's helpful to have each one printed on their own line - that may be tricky with the change to a % based output though 🤔

[brice-stacks]

I'm going to put the index-range option back in place and make sure that it works.

[brice-stacks]

Ok, I've added index-range back in. I couldn't come up with any way that made any sense to combine pre-Nakamoto and post-Nakamoto blocks with this option, so instead, we now have

stacks-inspect validate-block <path-to-chainstate> index-range <start> <end>

and

stacks-inspect validate-block <path-to-chainstate> naka-index-range <start> <end>

Also, for convenience, I added a feature so that if you don't pass <start> <end>, it will let you know how many blocks there are, so you can use that information to decide what to pass in.

[wileyj]

neat! I'll give it a try tonight

On Thu, Dec 18, 2025 at 14:20 Brice @.***> wrote:

@.**** commented on this pull request.

In contrib/stacks-inspect/src/lib.rs https://github.com/stacks-network/stacks-core/pull/6735#discussion_r2632827318 :

     &block,

     block_size,
     &next_staging_block.consensus_hash,
     &next_staging_block.anchored_block_hash,
     next_staging_block.commit_burn,
     next_staging_block.sortition_burn,
 );

• Ok(())

I made this change in 9afaaf3 https://github.com/stacks-network/stacks-core/commit/9afaaf3e87351d4525cde10392e395544f561163 .

— Reply to this email directly, view it on GitHub https://github.com/stacks-network/stacks-core/pull/6735#discussion_r2632827318, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAVXIHF5XBK772UQH7BL6WL4CMSDBAVCNFSM6AAAAACNZ7AIJSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTKOJVGM3TAMJVHE . You are receiving this because you were mentioned.Message ID: @.***>

[brice-stacks]

neat! I'll give it a try tonight

Sorry, I haven't updated the script yet. I'll get to that today.