From b58d3398bd7599bd23ee4a17f8bc62568c337fbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 5 Nov 2026 15:18:11 -0300 Subject: [PATCH 1/2] docs(rpc): say what the HTTP servers trust their callers with Neither server authenticates its callers. List what the node checks for itself (everything it gossips on a caller's behalf) and what it takes on the caller's word: fee recipients from prepare_beacon_proposer and register_validator, subnet subscriptions, block production, the lean aggregator toggle and heap profiles. Hence the loopback default for --http-address. Claude-Session: https://claude.ai/code/session_011vghNjQ8uikd9KL5Jo5at7 --- docs/rpc.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/rpc.md b/docs/rpc.md index e63a27332..1efea5a2f 100644 --- a/docs/rpc.md +++ b/docs/rpc.md @@ -23,6 +23,47 @@ carry. Roots are serialized as `0x`-prefixed hex strings on both. If `--api-port` and `--metrics-port` are equal, all routers are merged onto a single port. +### What the servers trust + +Neither server authenticates its callers. Anyone who can open a connection to +`--api-port` or `--metrics-port` is treated as this node's operator and its +validator client, which is why `--http-address` defaults to `127.0.0.1`. Bind +it anywhere else only behind something that decides who may call, such as a +firewall rule or an authenticating reverse proxy, and never expose it to the +internet. + +**What the node checks for itself.** Nothing it gossips on a caller's behalf +is taken on the caller's word. A published block's proposer signature, an +envelope's signature and data columns, attestations, aggregates, sync committee +messages and contributions, slashings, exits, BLS changes, payload attestations, +builder bids and proposer preferences are all checked against the chain, +signatures included, before they reach the network; a failure is a `400`. A +caller cannot make this node publish what its peers would refuse. + +**What it takes on the caller's word.** These carry no signature to check, or +one the node does not check: + +- **Where a validator's execution rewards go.** + `POST /eth/v1/validator/prepare_beacon_proposer` sets the fee recipient of + any validator index, and `POST /eth/v1/validator/register_validator` sets it + for any registered key, for the blocks this node builds. A builder + registration is signed, but the node does not verify the signature (neither + does Lighthouse): it forwards the registration to `--builder`, which does, + and sets the fee recipient whatever the builder answers. A caller can + therefore redirect a validator's rewards from locally built blocks until the + validator client sends its own again, which validator clients normally do + every epoch. +- **Which subnets the node joins.** + `POST /eth/v1/validator/beacon_committee_subscriptions` and + `/sync_committee_subscriptions` join gossip subnets on request, which costs + bandwidth and CPU until the subscription ends. +- **When the node builds a block.** Every block production request has the + execution client build a payload. +- **On a lean node, who aggregates.** `POST /lean/v0/admin/aggregator` switches + the aggregator role on or off. +- **On the metrics server, heap profiles.** `/debug/pprof/allocs` and its + flamegraph take a jemalloc heap profile, where profiling is enabled. + ## API Server (`:5052`) | Method | Path | Response | Description | From a276ef1ba21ef14d94f4311887ca82cddf0c88bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Wed, 11 Nov 2026 17:25:50 -0300 Subject: [PATCH 2/2] docs(rpc): say a caller can only get published what passes the node's checks The trust section said a caller cannot make the node publish what its peers would refuse. The checks are not every gossip rule: peers still ignore a duplicate, or a message outside gossip's timing windows, that passed them. Say what holds instead. --- docs/rpc.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/rpc.md b/docs/rpc.md index 3dbb48dc7..1c43a5060 100644 --- a/docs/rpc.md +++ b/docs/rpc.md @@ -38,7 +38,9 @@ envelope's signature and data columns, attestations, aggregates, sync committee messages and contributions, slashings, exits, BLS changes, payload attestations, builder bids and proposer preferences are all checked against the chain, signatures included, before they reach the network; a failure is a `400`. A -caller cannot make this node publish what its peers would refuse. +caller can only make this node publish what passes these checks. They are not +every gossip rule, so peers may still ignore a message that passed them, such +as a duplicate or one outside gossip's timing windows. **What it takes on the caller's word.** These carry no signature to check, or one the node does not check: