[kingpinXD]

Summary

• Stage 1, export (contrib/snapshot/export_snapshot.py + make snapshot-export): produces a zetacored export genesis JSON for testnet or mainnet. Reuses download_snapshot.py for the fetch and skips the node sync a devnet fork needs, since export reads committed state straight from the data dir. Strips the logger preamble so the output is valid JSON.
• Stage 2, compute (zetatool snapshot): a pure, deterministic function over that export. Attributes liquid + staked + unbonding per address (slashing-aware via TokensFromShares), routes module accounts, the zero address and pinned contracts to a single remainder, and emits Postgres-ready CSV + schema.sql. remainder = supply - attributed, so nothing is dropped and the books balance by construction.
• Contract pinning: contracts hold native ZETA no keypair can claim, so they are pinned out of attribution. --pin-file reads them from a file, and contrib/snapshot/pins_mainnet.txt carries the 16 mainnet contracts found by an eth_getCode scan of the top-500 holders (9,351,261 ZETA). A pin that matches no holder now fails the run, which is what catches a typo or a wrong-network pin file.
• Verified against a real testnet export at height 22052574: sum of 2,411,443 balances equals recorded bank supply equals live supply, to the wei. Mainnet export at height 17619782 also produced and reconciled.
• Offline tooling only. No changes to consensus, modules, or runtime behavior.

contrib/snapshot/README.md has the exact commands for both stages, the flags, and a Verification status section listing what is and is not proven yet.

Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8edf120. Configure here.}

[github-actions]

!!!WARNING!!!
nosec detected in the following files: cmd/zetatool/cli/snapshot.go

Be very careful about using #nosec in code. It can be a quick way to suppress security warnings and move forward with development, it should be employed with caution. Suppressing warnings with #nosec can hide potentially serious vulnerabilities. Only use #nosec when you're absolutely certain that the security issue is either a false positive or has been mitigated in another way.

Only suppress a single rule (or a specific set of rules) within a section of code, while continuing to scan for other problems. To do this, you can list the rule(s) to be suppressed within the #nosec annotation, e.g: /* #nosec G401 */ or //#nosec G201 G202 G203
Broad #nosec annotations should be avoided, as they can hide other vulnerabilities. The CI will block you from merging this PR until you remove #nosec annotations that do not target specific rules.

Pay extra attention to the way #nosec is being used in the files listed above.

[ws4charlie]

can you pls check the cursor + greptile comments? the stale-cache one especially — download_snapshot.py exits 0 when a cache already exists, so a rerun without --force silently exports the old height.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[usmaneth]

core compute is solid - tried to double-count a validator's self-delegation via the valoper form and the pinned-delegator path, both hold, and the module list matches maccPerms exactly. the real gap is that nothing enforces a zero-height export, so a plain one ships every pending reward to the multisig with all checks green - inline. the open threads on the stale snapshot cache, mainnet-without-pin-file, and the rm -rf on --home are the other things i'd want answered before this produces a real migration snapshot.

[usmaneth]

the distribution check closes the zero-height gap properly - a plain export now fails before anything is written, and the pool/share reconciliation in validateStaking means stake can't quietly leak into the remainder either. good to go from my side.

[kingpinXD]

@ws4charlie the cursor and greptile comments are all addressed: stale cache and path quoting in c9a1fc0, zero-height in b9b0ea5 (#4647, zetatool now refuses a non-zero-height export). On the #nosec warning, the four G304 suppressions in cmd/zetatool/cli/snapshot.go are operator-supplied file paths (export input, pin file, output dir, and the CSV we just wrote), so there's no untrusted input reaching them.