proposals: mev/commit-boost driven MEV flow

[iurii-ssv]

Summary

Adds an opt-in MEV-optimized block-fetch path (selected by ProposalSoftDeadline) alongside the existing legacy path, which stays the default. Config is resolved and validated once in cli/operator; beacon/goclient consumes the pre-resolved values as pure mechanism. Also rewrites docs/MEV_CONSIDERATIONS.md around PBS-side timing games, reframing ProposerDelay as the legacy lever.

Additive — no behavior change for existing configs. Both nothing-set and the explicit legacy knobs resolve to the legacy path, bit-for-bit identical to stage.

Path selection

• nothing set → legacy (default): race BNs in parallel, take the first blinded (MEV) block, fall back to the best response within a relative ProposalSoftTimeout (default 1800ms).
• ProposerDelay / ProposalSoftTimeout set → legacy: same path, chosen explicitly.
• ProposalSoftDeadline set → MEV-optimized: a slot-relative deadline that (a) collects multi-BN bids until the deadline without early-exiting, then proposes the best-scored bid, and (b) holds the block until the deadline before starting QBFT (single- and multi-BN alike), so every operator in the cluster starts QBFT at the same slot time (aligned round timers). Mutually exclusive with the legacy knobs — combining them is rejected at startup.

New config (under eth2)

• ProposalSoftDeadline — slot-relative deadline, range [1000ms, 3600ms]. Above the safe-max of 1250ms the node refuses to start unless AllowDangerousProposalSoftDeadline is also set (then allowed up to 3600ms, with a startup WARN) — mirrors ProposerDelay / AllowDangerousProposerDelay.
• AllowDangerousProposalSoftDeadline (env ALLOW_DANGEROUS_PROPOSAL_SOFT_DEADLINE) — explicit acknowledgement of the above.

Single-BN operators that set ProposalSoftDeadline now get a slot-relative QBFT-start floor (previously single-BN ignored all block-fetch knobs and fetched directly). Worth a release note for the new knobs.

Refactor: goclient.NewOptions is removed; goclient.New applies the network-timeout defaults directly.

Docs

docs/MEV_CONSIDERATIONS.md rewritten around PBS-side timing games (mev-boost v1.11+ -config, or commit-boost); config.example.yaml updated.

Test plan

• go build ./..., go vet, go test -race ./beacon/goclient/... ./cli/operator/... green.
• Per-path behavior — MEV-optimized: wait-to-deadline (no early-exit), best-bid-wins, deadline-past fallback, single-BN floor, all-BN-fail bail; legacy: early-exit-on-blinded, soft-timeout fallback.
• Config layer: path selection, deadline range + safe-max gating, soft-timeout resolution/floor, advisory warnings.

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.7%. Comparing base (8e37cce) to head (2fc48f2).
⚠️ Report is 5 commits behind head on stage.

Files with missing lines	Patch %	Lines
beacon/goclient/proposer.go	88.1%	9 Missing and 3 partials ⚠️
beacon/goclient/goclient.go	71.4%	1 Missing and 1 partial ⚠️
cli/operator/config.go	97.4%	1 Missing and 1 partial ⚠️
cli/operator/node.go	0.0%	1 Missing ⚠️

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

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

[greptile-apps]

Greptile Summary

This PR adds an opt-in MEV-optimized block-fetch path (ProposalSoftDeadline) alongside the preserved legacy path, rewires config resolution from goclient.NewOptions into cli/operator.resolveBlockFetch, and rewrites docs/MEV_CONSIDERATIONS.md around PBS-side timing games. Existing configurations are unaffected — default and explicit-legacy-knob setups resolve bit-for-bit to the original behavior.

• New getProposalParallelByDeadline: collects proposals from all BNs until a slot-relative deadline (no early-exit on blinded), then returns the best-scored bid; single-BN operators get the same floor via waitUntilProposalSoftDeadline, aligning QBFT start across the cluster.
• resolveBlockFetch in cli/operator/config.go: validates and resolves the three timing knobs at startup, mutually-excluding the MEV-optimized path from the legacy knobs; the resolved values are written onto ConsensusClient before goclient.New is called.
• Tests: proposer_path_dispatch_test.go provides thorough behavioral coverage of both paths (deadline floor, best-bid selection, past-deadline fallback, all-fail bail, legacy early-exit); config_test.go adds path-selection and validation unit tests.

Confidence Score: 5/5

Safe to merge: the new MEV-optimized path is purely additive and opt-in, and the legacy path is preserved bit-for-bit for all existing configurations.

The change is well-structured with clear mutual exclusion between paths, comprehensive behavioral and config-layer tests, and correct context-cancellation handling throughout. The two flagged items are minor resource/observability concerns that do not affect correctness.

No files require special attention; beacon/goclient/proposer.go carries the most logic but is well-tested by the new dispatch test file.

Important Files Changed

Filename	Overview
beacon/goclient/proposer.go	Core new dispatch logic: single-BN MEV-optimized floor, getProposalParallelByDeadline (slot-relative collect), waitForFirstValidProposal fallback, waitUntilProposalSoftDeadline. Uses time.After which leaks a timer if ctx cancels before deadline fires.
beacon/goclient/goclient.go	Adds proposalSoftDeadline field; moves network-timeout defaulting from removed NewOptions into New; adds defensive multi-BN legacy guard. Well-structured.
beacon/goclient/options.go	Removes NewOptions (logic absorbed into resolveBlockFetch + New); adds ProposalSoftDeadline field with clear doc comment. Clean removal.
cli/operator/config.go	Adds resolveBlockFetch with determineBlockFetchPath/validateProposalSoftDeadline. Block-fetch path selection is clean and mutually exclusive; legacy defaulting is preserved bit-for-bit.
cli/operator/node.go	Removes NewOptions call; passes pre-resolved cfg.ConsensusClient directly to goclient.New. Simplified correctly.
beacon/goclient/proposer_path_dispatch_test.go	New test file with comprehensive per-path behavioral coverage: deadline floor, best-bid selection, past-deadline fallback, all-fail bail, single-BN floor/no-floor, legacy early-exit and soft-timeout fallback.
cli/operator/config_test.go	Expands config-layer tests: path determination, blockFetchPath.String(), validateProposalSoftDeadline range, resolveBlockFetch defaults and warning scenarios. Good coverage.
beacon/goclient/proposer_test.go	Introduces spectestingMu to serialize ssv-spec fixture mutations (fixing a race in concurrent multi-BN tests); refactors createClientForProposerTest and existing multi-client test to use dynamic-slot responses.
protocol/v2/ssv/runner/proposer.go	Comment-only change: updates ProposerDelay docs to mark it as a legacy lever and recommend PBS-side timing games instead.
docs/MEV_CONSIDERATIONS.md	Full rewrite around PBS-side timing games; documents both mev-boost and commit-boost configs, path selection logic, and the new ProposalSoftDeadline knob. Appendix preserves legacy ProposerDelay guidance.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[GetBeaconBlock called] --> B{len clients == 1?}
    B -- yes --> C[fetchProposal direct]
    C --> D{useSlotRelativeFetch?}
    D -- yes --> E[waitUntilProposalSoftDeadline\nblock until slot_start + deadline]
    D -- no --> F[return block immediately]
    E --> F
    B -- no --> G{useSlotRelativeFetch?}
    G -- no --> H[getProposalParallelLegacy\nrace BNs, early-exit on blinded\nrelative proposalSoftTimeout]
    G -- yes --> I[getProposalParallelByDeadline\nspawn per-BN fetchers]
    I --> J{collect loop\nuntil softCtx deadline}
    J -- res received --> K{all failed AND\nbestProposal==nil?}
    K -- yes --> L[bail early\nwaitForFirstValidProposal]
    K -- no --> M[update bestProposal\nif higher score]
    M --> J
    J -- softCtx.Done --> N{bestProposal != nil?}
    N -- yes --> O[return bestProposal]
    N -- no --> L
    L --> P{ctx.Done?}
    P -- yes --> Q[return ctx.Err]
    P -- no --> R{first valid\nproposal received?}
    R -- yes --> O
    R -- no, all failed --> S[return all-clients-failed error]

Loading

_{Reviews (3): Last reviewed commit: "adjustmets" | Re-trigger Greptile}

[iurii-ssv]

@greptile pls re-review

[momosh-ssv]

Seems that this assertion expects safe_max_ms, but resolveBlockFetch logs the field as safe_max_proposal_soft_deadline_ms (config.go:230), so ContextMap() returns nil here and this subtest fails:

go test -run Test_resolveBlockFetch ./cli/operator/
--- FAIL: .../mev-optimized_above_safe-max_with_flag_-_warns_with_ms_fields
    expected: int64(1450)  actual: <nil>

Maybe align the two — updating the assertion to safe_max_proposal_soft_deadline_ms would match the legacy branch's max_safe_proposer_delay_ms style?

[iurii-ssv]

Recording a decision made during the ePBS work (#2901) that affects this PR, so it doesn't live only in ephemeral planning notes:

Decision: hold this PR — merge ePBS (#2901) first, then reconsider its role.

Rationale: ePBS removes the out-of-protocol apparatus this PR's flow configures (mev-boost/commit-boost relay polling is gone post-Gloas), but not the underlying "select the bid as late as the deadline allows" dynamic. Post-Gloas that lever relocates: for a non-self-building proposer it moves into SSV (the timing of the Gloas block-produce call) and/or the BN's own bid selection, while the larger late-MEV lever moves to the builder — or to SSV's §6 envelope timing when self-building.

Consequences for this PR when re-evaluated:

• ProposalSoftDeadline likely carries over with re-derived bounds for the tighter 25%-of-slot proposal deadline (vs 33%) — a reduced job, not a removed one.
• Note the pre-Gloas proposalSoftTimeout does not apply on the Gloas produce path (it uses the first-client fetch and bypasses it), so there is no soft-timeout↔delay coupling to tune there.
• Related knobs already landing in ePBS (EIP-7732 / Gloas) — SIP-94 #2901: ProposerDelay stays (now applies to pre-Gloas slots only) and a new ProposerDelayEPBS (default 0, hard-capped at 1s, no dangerous override) takes over from the Gloas fork on. The docs/MEV_CONSIDERATIONS.md ePBS rewrite is deferred and can land together with this PR's re-evaluation.