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]

Codecov Report

❌ Patch coverage is 1.31148% with 301 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.93%. Comparing base (267c7ef) to head (88c5d79).
⚠️ Report is 29 commits behind head on develop.

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

❌ Your project status has failed because the head coverage (72.93%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

❗ There is a different number of reports uploaded between BASE (267c7ef) and HEAD (88c5d79). Click for more details.

HEAD has 15 uploads less than BASE

Flag	BASE (267c7ef)	HEAD (88c5d79)
	78	63

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6735      +/-   ##
===========================================
- Coverage    78.40%   72.93%   -5.48%     
===========================================
  Files          585      585              
  Lines       361384   361530     +146     
===========================================
- Hits        283360   263669   -19691     
- Misses       78024    97861   +19837     

Files with missing lines	Coverage Δ
contrib/stacks-inspect/src/main.rs	0.00% <ø> (ø)
stackslib/src/chainstate/stacks/db/blocks.rs	84.89% <80.00%> (-3.24%)	⬇️
contrib/stacks-inspect/src/lib.rs	4.26% <0.00%> (-0.80%)	⬇️

... and 266 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 267c7ef...88c5d79. Read the comment docs.

🚀 New features to boost your workflow:

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

[benjamin-stacks]

Left another comment about a question I'm not sure about, but in either case this change is an improvement on the status quo, so I'm happy to approve as is.

[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 <#6735 (comment)> : > &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 <9afaaf3> . — Reply to this email directly, view it on GitHub <#6735 (comment)>, 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.

[benjamin-stacks]

One nit and one minor question, but LGTM and if it works for @wileyj, ship it!

[francesco-stacks]

lgtm, but I'll wait for @wileyj results before approving!

[wileyj]

Double-checked the recent change - lgtm!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.