datahaven/specs/validator-set-selection/validator-set-selection.md

Validator Set Selection Specification

Top-32 by Weighted Stake (Continuation of PR #433)

• Status: Draft
• Owners: DataHaven Team
• Last Updated: February 12, 2026
• Depends on: PR #433 (feat: automated validator set submission with era targeting)

1. Summary

PR #433 introduced era-targeted validator-set submission with a dedicated submitter role and runtime era validation. This spec is a continuation of that work.

This document adds deterministic weighted-stake selection so the outbound validator set is ranked before it is bridged:

1. Ethereum computes weighted stake per operator.
2. Ethereum deterministically sorts operators and selects top candidates.
3. DataHaven enforces a final total active authority cap of 32 after combining whitelisted and external validators.

The era-targeting model from PR #433 remains unchanged.

2. Baseline From PR #433

This spec assumes the following behavior already exists:

1. DataHavenServiceManager.sendNewValidatorSetForEra(uint64 targetEra, ...) is used for submission.
2. Submission is restricted to validatorSetSubmitter (onlyValidatorSetSubmitter).
3. external_index in the Snowbridge payload is the targetEra.
4. DataHaven runtime enforces era validity (targetEra old/too-new/duplicate checks).

3. Goals

1. Select external validators by weighted stake instead of raw member ordering.
2. Keep selection deterministic (same chain state -> same selected set).
3. Preserve PR #433 era-targeting invariants and submitter authorization flow.
4. Enforce total active authority cap = 32 (whitelisted + external).
5. Keep payload shape stable unless there is a hard requirement to version it.

4. Non-Goals

1. Replacing PR #433 submitter-role model.
2. Changing PR #433 era-target validation semantics.
3. Redesigning Snowbridge transport internals.
4. Changing reward formulas in this spec.

5. Current Behavior (Post-PR #433)

5.1 Ethereum

buildNewValidatorSetMessageForEra(targetEra) gathers all operator-set members with a mapped solochain address and forwards them in that order. There is no stake-based ranking.

5.2 Payload

Current payload carries:

1. validators
2. external_index (interpreted as targetEra)

5.3 DataHaven Runtime

set_external_validators_inner() stores incoming validators and ExternalIndex, then era application and validator composition logic consume them.

5.4 Limitation

Without stake-aware ordering, high-stake operators may be displaced by lower-stake operators when list size pressure or downstream caps apply.

6. Design Decisions

D1. Do ranking on Ethereum

EigenLayer membership/allocation context is available on Ethereum, so weighted ranking is computed there.

D2. Keep PR #433 era semantics unchanged

external_index must continue to encode targetEra. This spec does not repurpose it (no nonce/block-number substitution).

D3. Deterministic tie-break

For equal weighted stake, lower Ethereum operator address wins.

D4. Cap applies to total active authorities

Final active validator set must satisfy:

final_active = take_32(dedupe(whitelisted ++ external_sorted_limited))

D5. Strategy multipliers are explicit and default to zero if unset

Multipliers are owner-managed in strategiesAndMultipliers. If an entry is unset for a strategy, its effective multiplier is 0 (no weighted contribution).

D6. Keep strategy list and multipliers in sync

Multiplier lifecycle is tied to strategy lifecycle:

1. Add strategy -> add multiplier in the same call via IRewardsCoordinatorTypes.StrategyAndMultiplier struct.
2. Remove strategy -> delete multiplier in the same call.

7. Weighted Stake Model

For each operator o:

weightedStake(o) = sum_i( allocatedStake(o, strategy_i) * multiplier(strategy_i) )

Where:

1. allocatedStake comes from EigenLayer allocation data.
2. multiplier is a per-strategy weight (no normalization divisor is applied during ranking).

7.1 Strategy Weight Semantics

1. Every supported strategy should have an explicit multiplier entry for operational clarity.
2. Missing multiplier entry is treated as 0 multiplier.
3. Multiplier values are managed explicitly by owner/governance.

7.2 Unit Assumption

Stake inputs must be unit-consistent across strategies. If they are not, normalize before summing.

8. Ethereum Contract Changes (On Top of PR #433)

File: contracts/src/DataHavenServiceManager.sol

8.1 New State

uint32 public constant MAX_ACTIVE_VALIDATORS = 32;
mapping(IStrategy => uint96) public strategiesAndMultipliers;

8.2 New/Updated Admin APIs

function setStrategiesAndMultipliers(IRewardsCoordinatorTypes.StrategyAndMultiplier[] calldata strategyMultipliers) external onlyOwner;
function addStrategiesToValidatorsSupportedStrategies(IRewardsCoordinatorTypes.StrategyAndMultiplier[] calldata strategyMultipliers) external onlyOwner;
function removeStrategiesFromValidatorsSupportedStrategies(IStrategy[] calldata strategies) external onlyOwner;
function getStrategiesAndMultipliers() external view returns (IRewardsCoordinatorTypes.StrategyAndMultiplier[] memory);

Using EigenLayer's StrategyAndMultiplier struct pairs each strategy with its multiplier, eliminating the possibility of length mismatches between parallel arrays. Duplicate strategies in addStrategies are rejected by EigenLayer's StrategyAlreadyInOperatorSet check; duplicates in setStrategiesAndMultipliers are harmless (last-write-wins on the mapping).

8.3 Updated Selection Flow

buildNewValidatorSetMessageForEra(uint64 targetEra) should:

1. Read validator operator set members.
2. Compute weighted stake per operator.
3. Filter out operators with no solochain mapping.
4. Resolve multiplier from strategiesAndMultipliers for each strategy used.
5. If any strategy is missing a multiplier entry, treat it as 0 multiplier.
6. Filter out operators with zero weighted stake.
7. Select at most MAX_ACTIVE_VALIDATORS (32) candidates by weighted stake desc + address asc tie-break (if fewer than 32 eligible candidates exist, include all).
8. Encode using existing payload shape with externalIndex = targetEra.

For any EigenLayer call that consumes StrategyAndMultiplier[], materialize the list in ascending strategy-address order.

sendNewValidatorSetForEra(...) and onlyValidatorSetSubmitter remain unchanged from PR #433.

9. Bridge Message Format

No payload version bump in this spec.

Continue using existing ReceiveValidators message shape:

[EL_MESSAGE_ID]
[MessageVersion]
[ReceiveValidators]
[validator_count]
[validators (N * 20B)]
[external_index (u64 targetEra)]

If stake vectors are required in the future, that should be a separate versioned command proposal.

10. DataHaven Runtime Changes

File: operator/pallets/external-validators/src/lib.rs

10.1 Keep PR #433 era validation

Retain existing target-era gates and error semantics (TargetEraTooOld, TargetEraTooNew, DuplicateOrStaleTargetEra).

10.2 Enforce final total cap = 32

At validator composition time:

1. w = whitelisted.len()
2. external_budget = 32.saturating_sub(w)
3. Use at most external_budget external validators from the ranked list.
4. Build final set as take_32(dedupe(whitelisted ++ external_limited)).

10.3 Runtime constants

MaxExternalValidators can remain a defensive bound, but final active enforcement must guarantee max 32 authorities.

11. Rollout Plan

1. Merge/deploy PR #433 baseline first (submitter role + era-target checks).
2. Deploy ServiceManager upgrade with weighted ranking logic.
3. Backfill/confirm strategiesAndMultipliers for all currently supported strategies.
4. Deploy runtime changes for final total-cap enforcement.
5. Re-run submitter daemon unchanged (it still submits targetEra = ActiveEra + 1).
6. Monitor across multiple era cycles before production rollout.

12. Testing Plan

12.1 Solidity

1. Weighted stake computation across multiple strategies.
2. Deterministic tie-break behavior.
3. Top-32 selection when candidate count exceeds 32.
4. Behavior when candidate count is below 32.
5. Zero-stake filtering.
6. Missing multiplier entries are treated as zero contribution.
7. addStrategies... sets multipliers atomically via StrategyAndMultiplier struct.
8. removeStrategies... removes multiplier entries for removed strategies.
9. getStrategiesAndMultipliers() returns a list matching EigenLayer's operator set strategies.
10. Integration with buildNewValidatorSetMessageForEra(targetEra) and correct target era encoding.

12.2 Runtime

1. Existing PR #433 era-validation tests continue to pass unchanged.
2. Final active authority cap remains <= 32 with mixed whitelisted/external sets.
3. Composition logic preserves whitelisted priority while enforcing cap.

12.3 Integration / E2E

1. End-to-end submission through sendNewValidatorSetForEra with ranked validator output.
2. Delayed relay still fails with PR #433 semantics (no regressions).
3. Ranked selection outcome is deterministic across repeated runs at fixed state.

13. Security Considerations

1. Owner-managed strategy weights are governance-sensitive and should remain multisig/governance controlled.
2. Deterministic ordering prevents non-deterministic set drift.
3. Preserve PR #433 stale/duplicate/too-early rejection invariants.
4. Apply overflow checks in weighted arithmetic and any integer downcasts.

14. File Change Summary

1. contracts/src/DataHavenServiceManager.sol
   • weighted stake computation and deterministic top selection in buildNewValidatorSetMessageForEra.
2. contracts/src/interfaces/IDataHavenServiceManager.sol
   • strategiesAndMultipliers naming and add/remove strategy API signature updates with multipliers.
3. operator/pallets/external-validators/src/lib.rs
   • final authority cap enforcement at composition time (while keeping PR #433 era validation behavior).
4. contracts/test/*, operator/pallets/external-validators/src/tests.rs, test/e2e/suites/validator-set-update.test.ts
   • unit/runtime/e2e coverage for weighted selection + strategy/multiplier sync + cap behavior + non-regression on era-targeted flow.