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

[github-actions]

This pull request has been marked as stale due to 60 days of inactivity. It will be closed in 30 days if there are no updates. Please comment if you would like to keep it open.