[Storehouse] 012 - Update util checkpoint list tries to support payloadless checkpoint

[zhangchiqing]

This PR updates the checkpoint list tries util to support both v6 and v7 (payloadless) checkpoint. It also process the checkpoint in a memory efficient way without loading the entire trie into memory.

Summary by CodeRabbit

• Bug Fixes

  • checkpoint-collect-stats now stops with a clear error when the newest checkpoint is a payloadless V7 checkpoint, preventing misleading statistics.
  • Checkpoint trie listing now supports both V6 and V7 checkpoints and reports trie root hashes consistently.

• Improvements

  • Trie listing reads root hashes more efficiently without loading complete checkpoint data.

• Removed

  • Removed the checkpoint-trie-stats utility command.

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 517ecd97-9a86-4cb6-9934-e26c45ed7f5d

📥 Commits

Reviewing files that changed from the base of the PR and between f0aa72c and e3a2ec6.

📒 Files selected for processing (8)

• cmd/util/cmd/checkpoint-collect-stats/cmd.go
• cmd/util/cmd/checkpoint-collect-stats/cmd_test.go
• cmd/util/cmd/checkpoint-list-tries/cmd.go
• cmd/util/cmd/checkpoint-list-tries/cmd_test.go
• cmd/util/cmd/checkpoint-trie-stats/cmd.go
• cmd/util/cmd/root.go
• cmd/util/common/checkpoint.go
• ledger/complete/wal/checkpoint_v6_reader.go

💤 Files with no reviewable changes (2)

• cmd/util/cmd/root.go
• cmd/util/cmd/checkpoint-trie-stats/cmd.go

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The checkpoint utilities now read V6 and V7 trie root hashes through one exported WAL function. Payload statistics reject newer V7 checkpoints. The obsolete checkpoint-trie-stats command is removed.

Checkpoint utilities

Layer / File(s)	Summary
Unified checkpoint root-hash reading ledger/complete/wal/checkpoint_v6_reader.go, cmd/util/common/checkpoint.go, cmd/util/cmd/checkpoint-list-tries/*	The WAL root-hash reader is exported. Shared checkpoint lookup and checkpoint-list-tries use it for V6 and V7 checkpoints. Tests verify root-hash order for both formats.
Payload statistics checkpoint validation cmd/util/cmd/checkpoint-collect-stats/*	checkpoint-collect-stats checks the newest checkpoint before WAL replay and reports an error when a newer V7 checkpoint has no payloads. Tests cover empty, V6, equal-number V6/V7, and newer V7 cases.
Remove obsolete trie statistics command cmd/util/cmd/checkpoint-trie-stats/cmd.go, cmd/util/cmd/root.go	The checkpoint-trie-stats command, its implementation, and its root-command registration are removed.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: janezpodhostnik

Merge Risk: ⚪ Minimal · up to 50991

The updated utilities handle V6 and V7 checkpoint selection without an identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.19% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: updating the checkpoint list tries utility to support payloadless checkpoints. It is related to the primary objective, although it does not mention the me…

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch leo/payloadless-util-checkpoint-list-tries

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov-commenter]

Codecov Report

❌ Patch coverage is 53.57143% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cmd/util/cmd/checkpoint-collect-stats/cmd.go	60.00%	4 Missing and 2 partials ⚠️
cmd/util/cmd/checkpoint-list-tries/cmd.go	33.33%	6 Missing ⚠️
cmd/util/common/checkpoint.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!