Skip to content

feat(node-api): Create proof endpoint for validator balance#2840

Merged
calbera merged 20 commits intomainfrom
cursor/create-node-api-endpoint-for-validator-balance-d97e
Aug 25, 2025
Merged

feat(node-api): Create proof endpoint for validator balance#2840
calbera merged 20 commits intomainfrom
cursor/create-node-api-endpoint-for-validator-balance-d97e

Conversation

@calbera
Copy link
Copy Markdown
Contributor

@calbera calbera commented Jul 7, 2025

Add a node-api endpoint to provide Merkle proofs for a validator's balance at a specific timestamp.

@calbera calbera changed the title feat(node-api): Create proof endpoint for validator balance feat(node-api): [cursor] Create proof endpoint for validator balance Jul 7, 2025
@calbera calbera added the cursor Created/managed by cursor label Jul 7, 2025
@calbera calbera changed the title feat(node-api): [cursor] Create proof endpoint for validator balance feat(node-api): Create proof endpoint for validator balance Jul 8, 2025
@calbera calbera marked this pull request as ready for review July 8, 2025 21:37
@calbera calbera requested a review from a team as a code owner July 8, 2025 21:37
@codecov
Copy link
Copy Markdown

codecov Bot commented Jul 8, 2025

Codecov Report

❌ Patch coverage is 48.68421% with 78 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.53%. Comparing base (eb1fbf6) to head (730f58e).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
node-api/handlers/proof/validator_balance.go 0.00% 43 Missing ⚠️
...ode-api/handlers/proof/merkle/validator_balance.go 65.59% 23 Missing and 9 partials ⚠️
...e-api/handlers/proof/merkle/generalized_indexes.go 80.00% 2 Missing ⚠️
node-api/handlers/proof/validator_credentials.go 0.00% 1 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #2840      +/-   ##
==========================================
- Coverage   60.64%   60.53%   -0.11%     
==========================================
  Files         354      356       +2     
  Lines       16673    16824     +151     
==========================================
+ Hits        10111    10185      +74     
- Misses       5773     5841      +68     
- Partials      789      798       +9     
Files with missing lines Coverage Δ
node-api/handlers/proof/routes.go 100.00% <100.00%> (ø)
node-api/handlers/proof/validator_credentials.go 0.00% <0.00%> (ø)
...e-api/handlers/proof/merkle/generalized_indexes.go 82.35% <80.00%> (-0.99%) ⬇️
...ode-api/handlers/proof/merkle/validator_balance.go 65.59% <65.59%> (ø)
node-api/handlers/proof/validator_balance.go 0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@calbera calbera requested review from a team and bearmigiano July 8, 2025 22:38
Comment on lines +81 to +98
bs := mock.NewBeaconStateWith(
tc.slot, vals, 0, common.ExecutionAddress{}, tc.forkVersion,
)

bs.Balances = make([]uint64, tc.numValidators)
bs.Balances[tc.valIndex] = tc.balance

bbh := ctypes.NewBeaconBlockHeader(
tc.slot,
tc.valIndex,
tc.parentBlockRoot,
bs.HashTreeRoot(),
tc.bodyRoot,
)

proof, _, _, err := merkle.ProveBalanceInBlock(tc.valIndex, bbh, bs, bs.Balances)
require.NoError(t, err)
expectedProof := ReadProofFromFile(t, tc.expectedProofFile)
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bearmigiano you can use this code to re-create the balance proofs for specific data as needed in contracts testing


// BalanceLeaf is the leaf containing the validator's balance along with up
// to 3 other validators' balances (packed 4 per leaf).
BalanceLeaf common.Root `json:"balance_leaf"`
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bearmigiano important to note for staking pools: The leaf of the proof is not just the HashTreeRoot of the balance. Since the leaf contains multiple balances (not just the one we are proving), you must use this one while verifying the proof.

Comment thread node-api/handlers/proof/merkle/generalized_indexes.go Outdated
Comment thread node-api/handlers/proof/merkle/generalized_indexes.go Outdated
Signed-off-by: Cal Bera <calbera@berachain.com>
Signed-off-by: Cal Bera <calbera@berachain.com>
Comment on lines +40 to +43
type ValidatorBalanceRequest struct {
types.TimestampIDRequest
ValidatorIndex string `param:"validator_index" validate:"required,numeric"`
}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems identical to ValidatorCredentialsRequest. Can we use a type alias instead of duplicating the requests?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cleaned up in e541e73

…eate-node-api-endpoint-for-validator-balance-d97e
Copy link
Copy Markdown
Contributor

@abi87 abi87 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@calbera calbera enabled auto-merge (squash) August 25, 2025 18:07
@calbera calbera merged commit 76f873f into main Aug 25, 2025
21 checks passed
@calbera calbera deleted the cursor/create-node-api-endpoint-for-validator-balance-d97e branch August 25, 2025 18:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cursor Created/managed by cursor Ready for Review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants