Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
b244fd1
feat(validator): decode a blinded block from produceBlockV3
MegaRedHand Oct 26, 2026
a95ebe8
feat(validator): ask for and publish blinded blocks over the Beacon API
MegaRedHand Oct 26, 2026
a413a2d
feat(validator): publish a blinded block only on the node that produc…
MegaRedHand Oct 26, 2026
7ad2c9e
feat(validator): sign and send builder registrations
MegaRedHand Oct 26, 2026
4d72075
feat(validator): propose builder blocks behind --builder-proposals
MegaRedHand Oct 26, 2026
b60e645
test(rpc): drive the builder flow end to end with the validator client
MegaRedHand Oct 26, 2026
da6c4e9
docs: describe the validator client's builder proposals
MegaRedHand Oct 26, 2026
ff2149e
fix(validator): keep a slow relay from counting as a missed proposal
MegaRedHand Oct 26, 2026
7911c6f
fix(validator): report a late blinded refusal and delay from the publ…
MegaRedHand Oct 26, 2026
e07123f
docs: say what the keymanager's gas limit and fee recipient now reach
MegaRedHand Oct 29, 2026
7d766f0
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 4, 2026
b04a1ac
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 5, 2026
ee5fed8
fix(validator): address the builder proposals review
MegaRedHand Nov 5, 2026
e919655
docs(validator): say a zero --suggested-fee-recipient is reported
MegaRedHand Nov 5, 2026
7eced44
fix(validator): write out every control character in a node's error text
MegaRedHand Nov 5, 2026
25f3ca5
fix(validator): keep a running send's flag set when another is refused
MegaRedHand Nov 5, 2026
9823ed7
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 5, 2026
52c9030
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 5, 2026
23faacd
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 6, 2026
c09478b
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 11, 2026
ad59936
fix(validator): address the second builder proposals review
MegaRedHand Nov 12, 2026
2e4ec29
refactor(validator): carry the producer with the block and the deadli…
MegaRedHand Nov 12, 2026
dffbfaa
Merge feat/beacon-builder-blocks into feat/beacon-builder-vc
MegaRedHand Nov 13, 2026
285f3ac
fix(validator): mark a cut error text; give a delayed registration a …
MegaRedHand Nov 13, 2026
99f899e
fix(validator): follow-ups from the bots' third review
MegaRedHand Nov 13, 2026
6fd0fa5
fix(validator): re-send a refused per-slot registration every slot
MegaRedHand Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -862,11 +862,14 @@ transitions are in `ethlambda-types`, per the section above. Nothing above
and a block at slot N packs only `(N-1, parent_root)`, replaced by the empty
aggregate when `verified_sync_aggregate` fails (see `docs/spec_deviations.md`).
`SlotClock` picks the
offsets by each slot's own fork, and `/eth/v1/config/spec` supplies them. It
offsets by each slot's own fork, and `/eth/v1/config/spec` supplies them. With
`--builder-proposals`, pre-gloas slots register validators with the node's builder
and may sign a blinded block, published to the producing node only. It
keeps EIP-3076 minimal-watermark slashing protection in
`--validators-dir/slashing_protection.json` (`crate::slashing_protection`),
durable before every block and attestation signature; PTC votes have an
in-memory `(validator, slot)` dedup only, and envelopes are unguarded.
durable before every block (blinded ones included) and attestation signature;
PTC votes have an in-memory `(validator, slot)` dedup only, and envelopes are
unguarded.
`get_head_node` is one bottom-up walk for every fork, with
the current slot's fork selecting the payload rules and the boost gate, so a
follower on any network that schedules gloas (Sepolia does) pays work
Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,7 @@ the standard Beacon API, so it works against `ethlambda beacon` (run with the
| `--secrets-dir` | One password file per keystore, named after the validator's public key |
| `--suggested-fee-recipient` | Execution address for block rewards, `0x`-prefixed. Optional, but without it the beacon node picks an address that is not yours |
| `--graffiti` | Text for proposed blocks, at most 32 bytes |
| `--builder-proposals` | Propose builder blocks before gloas: register each validator with the beacon node's builder (`--builder` on an ethlambda node) and sign a blinded block when the builder's bid wins. Off by default |
| `--enable-keymanager` | Serve the keymanager API on `--keymanager-port` (default `5062`). Off by default, since it mutates key material |

Metrics are served on `--metrics-port` (default `5064`). See
Expand Down
125 changes: 124 additions & 1 deletion bin/ethlambda/src/validator.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
use std::path::PathBuf;

use ethlambda_types::beacon::primitives::{Bytes32, ExecutionAddress, H160};
use ethlambda_validator::ValidatorConfig;
use ethlambda_validator::proposer_settings::{GRAFFITI_BYTES, graffiti_from_text};
use ethlambda_validator::{BuilderProposals, ValidatorConfig};

/// An execution address is exactly this wide.
const ADDRESS_BYTES: usize = 20;
Expand Down Expand Up @@ -79,6 +79,32 @@ pub(crate) struct ValidatorOptions {
#[arg(long, default_value = "false")]
pub(crate) enable_keymanager: bool,

/// Propose builder blocks: register each validator with the beacon node's
/// builder and accept a blinded block when the builder's bid wins. Requires
/// a beacon node started with a builder (ethlambda: `--builder`). Fulu and
/// earlier only; from gloas the builder market works through proposer
/// preferences instead.
#[arg(long, default_value = "false")]
pub(crate) builder_proposals: bool,

/// How a builder's bid is weighed against the local payload: the local
/// payload wins iff `local >= factor * bid / 100`. 100 compares them as
/// they are; 0 prefers the local payload unless it cannot be built.
#[arg(
long,
default_value = "100",
requires = "builder_proposals",
conflicts_with = "prefer_builder_proposals"
)]
pub(crate) builder_boost_factor: u64,

/// Take the builder's block whenever there is a valid bid: this client
/// sends `builder_boost_factor = u64::MAX`. The beacon node still keeps
/// its local payload when its execution client sets
/// `shouldOverrideBuilder`.
#[arg(long, default_value = "false", requires = "builder_proposals")]
pub(crate) prefer_builder_proposals: bool,

/// Register every loaded key that has no slashing-protection record,
/// instead of refusing to start.
///
Expand Down Expand Up @@ -134,6 +160,21 @@ impl ValidatorOptions {
Ok(Some(H160(bytes)))
}

/// The builder configuration these flags describe, or `None` when builder
/// proposals are off.
///
/// `--prefer-builder-proposals` wins over the factor by construction:
/// clap refuses the two together, so at most one is ever set.
pub(crate) fn builder(&self) -> Option<BuilderProposals> {
self.builder_proposals.then_some(BuilderProposals {
boost_factor: if self.prefer_builder_proposals {
u64::MAX
} else {
self.builder_boost_factor
},
})
}

/// Reject a port clash before anything binds, the way the node's own
/// options do.
pub(crate) fn validate_ports(&self) -> eyre::Result<()> {
Expand All @@ -157,6 +198,7 @@ pub(crate) async fn run(options: ValidatorOptions) -> eyre::Result<()> {
options.validate_ports()?;
let graffiti = options.graffiti()?;
let suggested_fee_recipient = options.suggested_fee_recipient()?;
let builder = options.builder();
ethlambda_validator::run(ValidatorConfig {
beacon_nodes: options.beacon_nodes,
graffiti,
Expand All @@ -167,6 +209,7 @@ pub(crate) async fn run(options: ValidatorOptions) -> eyre::Result<()> {
keymanager: options
.enable_keymanager
.then(|| std::net::SocketAddr::new(options.http_address, options.keymanager_port)),
builder,
init_slashing_protection: options.init_slashing_protection,
})
.await
Expand All @@ -188,10 +231,90 @@ mod tests {
graffiti: graffiti.to_string(),
suggested_fee_recipient: None,
enable_keymanager: false,
builder_proposals: false,
builder_boost_factor: 100,
prefer_builder_proposals: false,
init_slashing_protection: false,
}
}

/// Parse a command line the way the binary does, so `requires` and
/// `conflicts_with` are exercised rather than assumed.
fn parse(extra: &[&str]) -> Result<ValidatorOptions, clap::Error> {
use clap::Parser as _;

#[derive(clap::Parser)]
struct Cli {
#[command(flatten)]
options: ValidatorOptions,
}
let base = [
"ethlambda",
"--beacon-nodes",
"http://localhost:5052",
"--validators-dir",
"/tmp/v",
"--secrets-dir",
"/tmp/s",
];
Cli::try_parse_from(base.iter().chain(extra)).map(|cli| cli.options)
}

#[test]
fn builder_proposals_are_off_by_default() {
assert_eq!(parse(&[]).expect("parses").builder(), None);
}

#[test]
fn builder_proposals_default_to_a_factor_of_100() {
let options = parse(&["--builder-proposals"]).expect("parses");
assert_eq!(
options.builder(),
Some(BuilderProposals { boost_factor: 100 })
);
}

#[test]
fn an_explicit_factor_is_used() {
let options =
parse(&["--builder-proposals", "--builder-boost-factor", "250"]).expect("parses");
assert_eq!(
options.builder(),
Some(BuilderProposals { boost_factor: 250 })
);
}

#[test]
fn preferring_the_builder_sends_the_maximum_factor() {
let options =
parse(&["--builder-proposals", "--prefer-builder-proposals"]).expect("parses");
assert_eq!(
options.builder(),
Some(BuilderProposals {
boost_factor: u64::MAX
})
);
}

#[test]
fn the_factor_and_the_preference_need_builder_proposals() {
parse(&["--builder-boost-factor", "250"])
.expect_err("a factor with builder proposals off is a mistake");
parse(&["--prefer-builder-proposals"])
.expect_err("a preference with builder proposals off is a mistake");
}

#[test]
fn the_factor_and_the_preference_conflict() {
parse(&[
"--builder-proposals",
"--builder-boost-factor",
"250",
"--prefer-builder-proposals",
])
.expect_err("the two say different things");
}

#[test]
fn the_default_graffiti_is_empty() {
let bytes = options("").graffiti().expect("valid");
Expand Down
1 change: 1 addition & 0 deletions crates/common/types/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ pub mod enr;
pub mod genesis;
pub mod primitives;
pub mod state;
pub mod text;
pub mod time;

/// Display helper for truncated root hashes (8 hex chars)
Expand Down
103 changes: 103 additions & 0 deletions crates/common/types/src/text.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
//! Text from a remote peer, made safe to put in a log line.

/// What a cut text ends in.
const CUT: &str = "...";

/// `text` with every character that could break or restyle a line written
/// out, cut to at most `max_bytes` bytes.
///
/// Text a remote server sends (an error body, a relay's message) reaches this
/// node's logs and error messages. There a raw line break would start what
/// reads as a log line of its own, and an ESC would start an ANSI sequence that
/// recolors, moves the cursor in or clears a terminal. So every control
/// character (`char::is_control`: C0, DEL and C1) and the Unicode line and
/// paragraph separators U+2028/U+2029, which some viewers break lines at, are
/// written as Rust escapes: `\n`, `\r` and `\t`, and `\u{1b}` for the rest.
/// Everything else passes through unchanged, quotes and backslashes included.
///
/// The cap is applied to the escaped text, and never cuts a character or an
/// escape in two. A text that does not fit ends in `...`, within the cap, so
/// a cut one does not read as all that was sent; one that fits exactly is
/// left unmarked. The walk stops at the cap, so a large body costs no more
/// than the text it keeps.
pub fn one_line(text: &str, max_bytes: usize) -> String {
let mut written = String::with_capacity(text.len().min(max_bytes));
// What `written` is cut back to if the text does not fit: the longest
// part of it that leaves room for the marker.
let mut kept_if_cut = 0;
for c in text.chars() {
let breaks_the_line = c.is_control() || matches!(c, '\u{2028}' | '\u{2029}');
let escaped = breaks_the_line.then(|| c.escape_default());
let len = escaped
.as_ref()
.map_or(c.len_utf8(), ExactSizeIterator::len);
if written.len() + len > max_bytes {
written.truncate(kept_if_cut);
// All of the marker, unless the cap is smaller than the marker.
let room = max_bytes - kept_if_cut;
written.push_str(&CUT[..room.min(CUT.len())]);
break;
}
match escaped {
Some(escaped) => written.extend(escaped),
None => written.push(c),
}
if written.len() + CUT.len() <= max_bytes {
kept_if_cut = written.len();
}
}
written
}

#[cfg(test)]
mod tests {
use super::one_line;

#[test]
fn control_characters_and_line_separators_are_written_out() {
let text = "\x1b[31mred\x1b[0m\ttab\x07bell\u{85}nel\u{2028}ls\u{2029}ps \"q\" \\ ok\r\n";
assert_eq!(
one_line(text, 1024),
r#"\u{1b}[31mred\u{1b}[0m\ttab\u{7}bell\u{85}nel\u{2028}ls\u{2029}ps "q" \ ok\r\n"#
);
}

/// A cut text ends in the marker, counted within the cap; a text that
/// fits exactly is not marked.
#[test]
fn a_cut_text_ends_in_the_marker() {
let text = "x".repeat(1024);
assert_eq!(one_line(&text, 1024), text);
let text = "x".repeat(1025);
assert_eq!(one_line(&text, 1024), format!("{}...", "x".repeat(1021)));
assert_eq!(one_line("short", 1024), "short");
// A cap smaller than the marker keeps as much of it as fits.
assert_eq!(one_line("abcdef", 2), "..");
}

#[test]
fn the_cap_never_cuts_an_escape_in_two() {
// 1018 bytes, then a six-byte escape that ends right at the cap.
let text = format!("{}\x1b", "x".repeat(1018));
assert_eq!(
one_line(&text, 1024),
format!("{}\\u{{1b}}", "x".repeat(1018))
);
// A byte more and the escape does not fit: it is left out whole, not
// cut to `\u{` ahead of the marker.
let text = format!("{}\x1b", "x".repeat(1019));
assert_eq!(one_line(&text, 1024), format!("{}...", "x".repeat(1019)));
// The escape fits but leaves the marker no room once the next
// character does not: the cut backs up over the whole escape.
let text = format!("{}\x1by", "x".repeat(1018));
assert_eq!(one_line(&text, 1024), format!("{}...", "x".repeat(1018)));
}

#[test]
fn the_cap_never_cuts_a_character_in_two() {
// 'é' is two bytes. 1023 bytes hold 510 of them and the marker, and
// never half of a 511th.
let text = "é".repeat(1024);
assert_eq!(one_line(&text, 1023), format!("{}...", "é".repeat(510)));
}
}
34 changes: 6 additions & 28 deletions crates/net/rpc/src/beacon/builder_client/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -467,37 +467,15 @@ pub(super) async fn read_body(
Ok(body)
}

/// `text` with every character that could break or restyle a line written
/// out, cut to at most [`MAX_ERROR_TEXT`] bytes.
/// `text` as [`ethlambda_types::text::one_line`] writes it, cut to at most
/// [`MAX_ERROR_TEXT`] bytes.
///
/// A builder's text reaches this node's logs and a validator client's error
/// message. There a raw line break would start what reads as a log line of
/// its own, and an ESC would start an ANSI sequence that recolors, moves the
/// cursor in or clears a terminal. So every control character
/// (`char::is_control`: C0, DEL and C1) and the Unicode line and paragraph
/// separators U+2028/U+2029, which some viewers break lines at, are written
/// as Rust escapes: `\n`, `\r` and `\t`, and `\u{1b}` for the rest. Everything
/// else passes through unchanged, quotes and backslashes included.
///
/// The cap is applied to the escaped text, and never cuts a character or an
/// escape in two.
/// message, so no line break or terminal escape in it may reach either as
/// itself. The validator client writes a beacon node's error text through the
/// same function.
pub(super) fn error_text(text: String) -> String {
let mut written = String::with_capacity(text.len().min(MAX_ERROR_TEXT));
for c in text.chars() {
if c.is_control() || matches!(c, '\u{2028}' | '\u{2029}') {
let escaped = c.escape_default();
if written.len() + escaped.len() > MAX_ERROR_TEXT {
break;
}
written.extend(escaped);
} else {
if written.len() + c.len_utf8() > MAX_ERROR_TEXT {
break;
}
written.push(c);
}
}
written
ethlambda_types::text::one_line(&text, MAX_ERROR_TEXT)
}

/// The fork `version` names, if its bids have the shape [`SignedBuilderBid`]
Expand Down
12 changes: 7 additions & 5 deletions crates/net/rpc/src/beacon/builder_client/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -480,11 +480,12 @@ async fn a_long_error_is_cut_short() {
let Err(BuilderError::BadRequest(message)) = get_header(&client_for(&relay)).await else {
panic!("expected a bad request");
};
assert_eq!(message.len(), 1024);
assert_eq!(message, format!("{}...", "x".repeat(1021)));
}

/// Line breaks are written out, so a builder's text cannot start a log line of
/// its own, and the escaped text is what the length cap applies to.
/// its own, and the escaped text is what the length cap applies to: 510 of
/// the two-byte escapes, then the marker.
#[tokio::test]
async fn line_breaks_in_an_error_are_written_out() {
let relay = MockRelay::start(GENESIS_FORK_VERSION).await;
Expand All @@ -500,7 +501,7 @@ async fn line_breaks_in_an_error_are_written_out() {
let Err(BuilderError::BadRequest(message)) = get_header(&client_for(&relay)).await else {
panic!("expected a bad request");
};
assert_eq!(message.len(), 1024);
assert_eq!(message, format!("{}...", r"\n".repeat(510)));
}

/// Every other control character is written out too (an ESC would start an
Expand Down Expand Up @@ -534,9 +535,10 @@ async fn control_characters_in_an_error_are_written_out() {
/// The cap never leaves half an escape behind.
#[test]
fn the_cap_never_cuts_an_escape_in_two() {
// 1020 bytes, then a six-byte escape that would end past the cap.
// 1020 bytes, then a six-byte escape that would end past the cap: it is
// left out whole, and the marker ends the text.
let text = format!("{}\x1b", "x".repeat(1020));
assert_eq!(super::error_text(text), "x".repeat(1020));
assert_eq!(super::error_text(text), format!("{}...", "x".repeat(1020)));
let text = format!("{}\x1b", "x".repeat(1018));
assert_eq!(
super::error_text(text),
Expand Down
Loading
Loading