feat: peerDAS - implement validator custody #7640

dguenther · 2025-03-31T19:10:41Z

Motivation

@hughy and I have a basic implementation of validator custody for peerDAS.

We're planning to do more testing on this, but would appreciate a review on the architecture since we're still pretty new!

This relates to #7632 - If it merges, we'll update our PR to account for it.

Description

Centralizes custody values like sampledGroups and custodyGroups into CustodyConfig. CustodyConfig is now treated as a singleton.
Creates a new advertisedGroupCount in CustodyConfig, used for the custody group count in the node's metadata/ENR.
Adds setSamplingGroupCount and setAdvertisedGroupCount to NetworkCore API. Updated by an EventEmitter on CustodyConfig.
Adds LocalValidatorRegistry to track connected validators.
Updates custody requirement in chain.onForkChoiceFinalized.

Not Included

I'll open separate issues for these if we're okay merging this PR without them.

Backfilling groups when the target custody group count increases
Handling changes in other peers' custody group counts
Race conditions around group count changing during syncing

Closes #7619

…GROUP config

- VALIDATOR_CUSTODY_REQUIREMENT - BALANCE_PER_ADDITIONAL_CUSTODY_GROUP

- define getCustodyColumnsMeta as private method

Add targetCustodyGroupCount and advertisedCustodyGroupCount

use validator effective balances instead of raw balances assuming spec changes for now do not use cached state to access effective balances. update if cached state available when triggering updates to CustodyConfig return CUSTODY_REQUIREMENT if validatorIndices is empty

- set target CGC based on latest finalized state - convert getValidatorsCustodyRequirement to use CachedBeaconStateAllForks - TODO: the chain does not currently have a means of identifying validator indices for the node

define LocalValidatorRegistry to track indices of validators that have registered with the node. read indices of local validators from LocalValidatorRegistry when updating validator custody requirements. borrow logic from ValidatorMonitor for registering and pruning validators from the map in LocalValidatorRegistry. register validators and prune validators in tandem from LocalValidatorRegistry and ValidatorMonitor. TODO: re-use validator registry in ValidatorMonitor. we need to be able to determine the indices of connected validators even if metrics are disabled.

CLAassistant · 2025-03-31T19:10:48Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
0 out of 2 committers have signed the CLA.

❌ dguenther
❌ hughy
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

packages/beacon-node/src/api/impl/validator/index.ts

use existing BeaconProposerCache to access the list of indices of connected validators add method to BeaconProposerCache to access validator indices connected validator clients call 'prepareBeaconProposer' every epoch which adds or updates an entry in the BeaconProposerCache. we can use this cache instead of introducing a duplicative data structure

matthewkeil

Great start !!!!

packages/beacon-node/src/chain/chain.ts

packages/beacon-node/src/chain/seenCache/seenGossipBlockInput.ts

packages/beacon-node/src/network/core/networkCore.ts

packages/beacon-node/src/network/metadata.ts

packages/beacon-node/src/network/peers/peerManager.ts

packages/beacon-node/src/util/dataColumns.ts

matthewkeil

I spent some time thinking about what you have here and the architecture of Lodestar. There are a couple things that I think will help long-term. I also spent some time speaking with @twoeths to make sure we go down the right path.

Here are some design considerations that we may want to incorporate

Always using the custodyConfig directly to pull values.
Keeping a custodyConfig on the main thread and one on the network thread
Maintain update of attached validators and balances happening on the chain in onFinalizedEpoch
Pass update of custody to the network (on main thread) via the ChainEventEmitter
Pass update of custody to the network (on network thread) via worker api

Using the method that Tuyen employed we can use the custodyConfig from the chain object directly on the main thread network object which will keep those two in sync.

lodestar/packages/beacon-node/src/network/network.ts

Line 123 in 3050586

this.custodyConfig = modules.chain.custodyConfig;

I'm also thinking about breaking updateCustodyRequirement into two parts. First will be calculating the custody requirement and the second will be updating the custodyConfig(s). This way we can calculate the update in onFinalizedEpoch and then event the custodyRequirement value to the network object on both main and network threads easily.

const custodyRequirement = calculateCustodyRequirement(state, validatorIndices, config);
this.custodyConfig.updateTargetCustody(custodyRequirement);
this.events.emit(ChainEvent.UpdateTargetCustody, custodyRequirement);

In the network object there would be an onUpdateTargetCustody that would be the handler for that event (kind of what you have now but will listen to the chain event bus instead of the custodyConfig object). The handler would call this.getApi().updateTargetCustody(custodyRequirement) to send the value to the network thread so that object could be updated for the PeerManager and other consumers on the network thread.

packages/beacon-node/src/metrics/validatorMonitor.ts

reverts changes leftover from an earlier approach to tracking local validators alongside the ValidatorMonitor - removes 'getLocalValidatorIndices' method from ValidatorMonitor - sleeps during onClockSlot only if metrics enabled

…r-custody

- define CustodyConfigOpts type to encapsulate options for CustodyConfig - by default, enable validator custody - add separate method for calculating target custody group count to prevent calculation if validator custody disabled - add CLI flag, 'chain.noValidatorCustody', to disable validator custody

- remove CustodyConfigOpts - remove calculateTargetCustodyGroupCount - condition all custody update logic in onForkChoiceFinalized on noValidatorCustody flag

packages/beacon-node/src/network/core/networkCore.ts

packages/cli/src/options/beaconNodeOptions/chain.ts

…r-custody

matthewkeil

Just the small nit about using the getter so it consistent with how its done for the chain config. Looks great otherwise!!

packages/beacon-node/src/network/core/networkCore.ts

packages/beacon-node/src/network/metadata.ts

packages/beacon-node/src/network/networkConfig.ts

packages/beacon-node/src/network/peers/discover.ts

packages/beacon-node/src/network/peers/peerManager.ts

packages/cli/src/options/beaconNodeOptions/chain.ts

matthewkeil

LGTM!! 🚀

wemeetagain · 2025-09-10T16:00:53Z

🎉 This PR is included in v1.34.0 🎉

dguenther and others added 19 commits March 25, 2025 12:36

Add VALIDATOR_CUSTODY_REQUIREMENT and BALANCE_PER_ADDITIONAL_CUSTODY_…

f40da81

…GROUP config

add missing config fields to getSpecCriticalParams

308f33f

- VALIDATOR_CUSTODY_REQUIREMENT - BALANCE_PER_ADDITIONAL_CUSTODY_GROUP

convert CustodyConfig from type to class

51e147c

- define getCustodyColumnsMeta as private method

Add targetCustodyGroupCount and advertisedCustodyGroupCount

7062510

Merge pull request #2 from dguenther/vc-add-cgcs

04879c0

Add targetCustodyGroupCount and advertisedCustodyGroupCount

Fetch sampleSubnets and samplingGroups from CustodyConfig

d5b74a1

Use CustodyConfig in PeerDiscovery

9bc3975

add CustodyConfig to init for NetworkCore in networkCoreWorker

46345da

update CustodyConfig on forkChoiceFinalized events

7c1ce33

- set target CGC based on latest finalized state - convert getValidatorsCustodyRequirement to use CachedBeaconStateAllForks - TODO: the chain does not currently have a means of identifying validator indices for the node

Pass sampling groups into network worker as well

fe23ffa

Update metadata and ENR with advertised group count

a6771ab

Replace sampledColumns with getSampledColumns

ed58676

Remove custodyGroups from custodyConfig

d2647ad

Clean up uses of data column groups

2a018b4

Fix from code review

bf78076

Fix dataColumn tests

aa664e3

Fix skipped test

332f08f

dguenther added 2 commits March 31, 2025 15:13

Remove unused CustodyConfig from BaseNetworkInit

1fa193c

Simplify diff

727ea9d

nflaig reviewed Mar 31, 2025

View reviewed changes

packages/beacon-node/src/api/impl/validator/index.ts Outdated Show resolved Hide resolved

dguenther and others added 7 commits March 31, 2025 15:36

Update comment

6c60c45

Fix Network

b6c5963

Simplify diff

f89b721

Simplify discover

0c733b7

Remove exports

d5d9352

Add tests for updateCustodyRequirement

6e513f7

Remove unused getSampledGroups

6c58566

matthewkeil requested changes Apr 1, 2025

View reviewed changes

matthewkeil reviewed Apr 2, 2025

View reviewed changes

packages/beacon-node/src/metrics/validatorMonitor.ts Outdated Show resolved Hide resolved

hughy and others added 11 commits April 3, 2025 10:42

reverts changes adjacent to ValidatorMonitor

bb64459

reverts changes leftover from an earlier approach to tracking local validators alongside the ValidatorMonitor - removes 'getLocalValidatorIndices' method from ValidatorMonitor - sleeps during onClockSlot only if metrics enabled

Revert optional operator

5a93092

Revert peerManager changes to samplingGroups

736b3a6

Cache values instead of using getters

e45f9e6

Use ChainEventEmitter instead of CustodyEvent

43773a9

Merge remote-tracking branch 'upstream/peerDAS' into peerDAS-validato…

b07d7e6

…r-custody

update CustodyConfig separately from computing custody requirement

be88817

Use CustodyConfig in NetworkConfig

516f84a

Use updateTargetCustodyGroupCount in NetworkConfig

5bd3044

do not emit custody events if validator custody disabled

25d568b

- remove CustodyConfigOpts - remove calculateTargetCustodyGroupCount - condition all custody update logic in onForkChoiceFinalized on noValidatorCustody flag

dguenther commented Apr 8, 2025

View reviewed changes

packages/beacon-node/src/network/core/networkCore.ts Show resolved Hide resolved

dguenther commented Apr 8, 2025

View reviewed changes

packages/cli/src/options/beaconNodeOptions/chain.ts Show resolved Hide resolved

Cleanup code

f0343fe

dguenther marked this pull request as ready for review April 8, 2025 04:15

dguenther requested a review from a team as a code owner April 8, 2025 04:16

Merge remote-tracking branch 'upstream/peerDAS' into peerDAS-validato…

e0426e7

…r-custody

matthewkeil requested changes Apr 14, 2025

View reviewed changes

Access custodyConfig via getter

9dae088

matthewkeil approved these changes Apr 14, 2025

View reviewed changes

matthewkeil merged commit 08ddb0b into ChainSafe:peerDAS Apr 14, 2025
2 checks passed

dguenther deleted the peerDAS-validator-custody branch April 17, 2025 15:09

dguenther mentioned this pull request Apr 30, 2025

peerDAS - Implement validator custody #7619

Closed

Uh oh!

feat: peerDAS - implement validator custody #7640

feat: peerDAS - implement validator custody #7640

Uh oh!

Conversation

dguenther commented Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

matthewkeil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthewkeil left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthewkeil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthewkeil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wemeetagain commented Sep 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dguenther commented Mar 31, 2025 •

edited

Loading

CLAassistant commented Mar 31, 2025 •

edited

Loading

matthewkeil left a comment •

edited

Loading