feat: wrapped block validator token tracing for post october 2023 with saved states

[rockysingh]

Summary

• Add token balance tracing to the wrapped block validator, extending beyond HBAR-only supply checks to per-account, per-token balance verification against signed protobuf balance files from GCP
• Introduce FetchBalanceCheckpointsCommand (blocks fetchBalanceCheckpoints) to download and bundle weekly/monthly balance snapshots from the mainnet GCP bucket into length-prefixed protobuf checkpoint files
• Add BalanceCheckpointValidator and BalanceProtobufValidator to compare computed running account/token balances against checkpoint snapshots at configurable intervals (--balance-check-interval-days, default 30)
• Add BalanceFileBucket utility for downloading midnight-targeted .pb.gz balance files from GCP with signature verification support
• Add RunningAccountsState to track per-account HBAR and token balances across blocks, processing amendments (crypto transfers, token mints/burns/wipes/transfers)
• Add bundled checkpoint auto-loading (accountBalances_91019204.pb.gz) so validate-wrapped works out of the box without a separate fetch step
• Add new CLI options to validate-wrapped: --validate-balances, --balance-checkpoints, --custom-balances-dir, --balance-check-interval-days
• Add comprehensive unit tests for BalanceCheckpointValidator, BalanceCheckpointsLoader, BalanceProtobufValidator, and BalanceFileBucket
• Update documentation for fetchBalanceCheckpoints and validate-wrapped commands

Notes

The bundled accountBalances_91019204.pb.gz checkpoint was generated using the standalone [hiero-state-to-balance-file]project, which extracts account/token balances from a consensus node
saved state at block 91,019,204. This file provides a known-good starting point for balance validation. If the saved-state extraction tool or its protobuf format diverges in the future, this checkpoint may need to be regenerated. There is a potential diverge issue we need to raise. The "diverge issue" is that this is a separate standalone project — not part of the hiero-block-node repo — and the generated .pb.gz file was copied over. If that project's protobuf format, extraction logic, or Hiero dependency version changes, the bundled file could become stale or incompatible. Therefore, we will need to generate other files for any diverge.

Test plan

• Verify blocks validate-wrapped runs with default balance validation enabled (uses bundled checkpoint)
• Verify blocks fetchBalanceCheckpoints downloads and bundles balance files from GCP
• Verify --no-validate-balances disables balance checking
• Verify --balance-check-interval-days controls checkpoint frequency
• Verify --custom-balances-dir loads balance files from a local directory
• Run unit tests: BalanceCheckpointValidatorTest, BalanceCheckpointsLoaderTest, BalanceProtobufValidatorTest, BalanceFileBucketTest

Also, rebased using this pr: #2184 as it was needed to work on this issue etc.

This closes: #2173 and #2212

[jsync-swirlds]

You're pushing a large number of large binary files in this PR that appear to be cached data, not code.

1. Is that intentional
2. Can we please not do that, large binary files play havoc with git and create permanent problems for every clone of the repo (because they stay in history, even if later removed).

[rockysingh]

You're pushing a large number of large binary files in this PR that appear to be cached data, not code.

1. Is that intentional
2. Can we please not do that, large binary files play havoc with git and create permanent problems for every clone of the repo (because they stay in history, even if later removed).

That is not intentional. I had them removed. I guess I did not stage the changes correctly. I've removed them now.

[jsync-swirlds]

Just a few more large (20-50M) files to double check if we really need them.

[jsync-swirlds]

Same question.

[rockysingh]

Yes

[rockysingh]

This is created using a command but it can be very flakey to run due to GCP but gets even worse as its at a weekly granularity. This is why I've pushed them to the repo as a source of truth.

[jsync-swirlds]

Could we store it separately and load/download as needed?
It is a lot of data to store in git, and that data gets copied to every clone forever.
I understand if it's actually needed, and we can perhaps fix later if necessary, but it would be nice to not store these binaries if we can reasonably avoid it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@             Coverage Diff              @@
##               main    #2265      +/-   ##
============================================
- Coverage     80.96%   80.89%   -0.08%     
- Complexity     1445     1448       +3     
============================================
  Files           139      139              
  Lines          6730     6730              
  Branches        726      726              
============================================
- Hits           5449     5444       -5     
- Misses          962      964       +2     
- Partials        319      322       +3     

see 2 files with indirect coverage changes

🚀 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.