Repository navigation
Open
Description
Per-validator graffiti already changes at runtime through the keymanager API (#780). What the client lacks is a way to change graffiti without that API: the default can only change with a restart, and there is no file a script can rewrite, as Lighthouse's --graffiti-file allows. This is low priority. The API covers the common case, and this issue is for the cases it leaves out.
Code references are at bf66e86c.
What happens today
- The keymanager API is the interface. With
--enable-keymanager,GET,POSTandDELETE /eth/v1/validator/{pubkey}/graffitiread, set and clear one validator's graffiti (crates/validator/src/http_api/mod.rs:182-186, handlers atcrates/validator/src/http_api/proposer.rs:332-376). A change is written to the validator's entry invalidator_definitions.ymlbefore it takes effect, so it survives a restart, and it is read when the next block is requested (crates/validator/src/proposer_settings.rs:7-29, read atcrates/validator/src/proposal.rs:451).GETanswers the validator's own value, or the default. - The default comes from
--graffiti(bin/ethlambda/src/validator.rs:51-62). Changing it takes a restart; no API route sets it. - The API is all or nothing. It is off by default because it also imports and deletes keys (
validator.rs:94-101). An operator who only wants to rotate graffiti has to serve the whole surface and manage its bearer token. - Every block request carries
graffiti, zeros when nothing is set (crates/validator/src/beacon_node/http.rs:472-477,:769-774). A beacon node cannot tell "not set" from "set to empty", so a node that applies its own default only when the request has none never gets to. - An ethlambda beacon node appends its own and its execution client's version codes to every block's graffiti, with no opt-out; it does not read Lighthouse's
graffiti_policyquery parameter (crates/net/rpc/src/beacon/graffiti.rs:11-16).
What other clients do
| Client | Behavior | Read at |
|---|---|---|
| Lighthouse | --graffiti-file, which conflicts with --graffiti (validator_client/src/cli.rs:175-182). Lines are default: <text> and <0xpubkey>: <text>, and the file is read again for every proposal (validator_client/graffiti_file/src/lib.rs:48-53, called from validator_client/validator_services/src/block_service.rs:650-655). Each read inserts into a copy of the map loaded at startup without clearing it (graffiti_file/src/lib.rs:60-80; loaded at validator_client/src/config.rs:220-225, handed to the block service at validator_client/src/lib.rs:546), so an entry deleted from the file stays in effect until a restart. Precedence: the file, then validator_definitions.yml (which the keymanager writes), then --graffiti, then the beacon node (graffiti_file/src/lib.rs:108-124). While the file is set, the keymanager's graffiti POST and DELETE are refused (validator_client/http_api/src/lib.rs:1278-1281, :1303-1306), and GET still answers from the definitions and the flag, ignoring the file (validator_client/http_api/src/graffiti.rs:7-27). The book names drawing on the beaconcha.in graffiti wall as an example use (book/src/validator_graffiti.md:7). --graffiti-append (default true) leaves the beacon node's client-version suffix on; when false the client sends graffiti_policy=PreserveUserGraffiti (validator_client/src/cli.rs:164-173, common/eth2/src/lib.rs:2957-2963) |
unstable @ 11813cfb |
| Teku | --validators-graffiti-file holds one graffiti for every validator (32 bytes, the file at most 40 with surrounding whitespace). It is read on every lookup, and when it cannot be read --validators-graffiti is used instead (teku/src/main/java/tech/pegasys/teku/cli/options/ValidatorOptions.java:55-62, validator/api/src/main/java/tech/pegasys/teku/validator/api/FileBackedGraffitiProvider.java:49-51, GraffitiParser.java:34-46). A graffiti set through the keymanager API wins over both (UpdatableGraffitiProvider.java:31-33, wired in validator/client/src/main/java/tech/pegasys/teku/validator/client/loader/ValidatorLoader.java:225-231 over the file-backed provider from ValidatorOptions.java:215-217). --validators-graffiti-client-append-format is AUTO (default), CLIENT_CODES or DISABLED (ValidatorOptions.java:64-73, ValidatorConfig.java:67-68) |
master @ 62a54b96 |
| Prysm | --graffiti-file is YAML with default, ordered (each entry used once, in order, with the position saved in the validator database), random and specific (keyed by validator index), parsed at startup (validator/graffiti/parse_graffiti.go:19-26, validator/node/node.go:416-423). Precedence: proposer settings, which the keymanager writes (the key's own, then their default), then --graffiti, then the file's specific, ordered, random and default (validator/client/propose.go:535-600). The beacon node appends execution and consensus client codes (beacon-chain/execution/graffiti_info.go:28, :40-57) |
develop @ 0c1e3d24 |
Proposal
--graffiti-file <path>in Lighthouse's format (default: <text>,<0xpubkey>: <text>), so a file written for Lighthouse works unchanged.- Read it again before every proposal, at the point where
proposal.rs:451reads the graffiti today, and replace the whole map on each read, so a deleted line stops applying. - Fail loudly at startup, softly afterwards. A file that does not parse, or a graffiti over 32 bytes, refuses startup, as an over-long
--graffitidoes (validator.rs:182-189). Once running, a bad read logs a warning and falls back to the next source, as Lighthouse and Teku do. - Make
GET /eth/v1/validator/{pubkey}/graffitianswer what the next proposal would use, the file included. - Send
graffitionly when one is set, as Lighthouse does (its block request takes anOption,common/eth2/src/lib.rs:2973), so a beacon node's own default can apply.
To decide
- Is a file worth it at all? The alternative is to document the keymanager API as the way to change graffiti dynamically, and add only what it cannot do: a runtime default, or a graffiti-only mode of the API.
- Precedence against the keymanager. Lighthouse puts the file first and refuses keymanager graffiti writes while it is set. Teku and Prysm put the keymanager's value first. Either way the file becomes a second source of truth beside
validator_definitions.yml, and the API must not report one value while proposals use another. - Rotation. Prysm's
orderedandrandomlists are a separate feature. A file reread before each proposal already lets an external script rotate. - The beacon node's suffix. An opt-out (
graffiti_policy=PreserveUserGraffiti, or Teku'sDISABLED) needs the ethlambda node to honour it, whichgraffiti.rsrules out today. That is a separate node-side issue, plus a client flag.
Tests
- Parse Lighthouse's own example file (
book/src/validator_graffiti.md), and refuse a line without:, a bad pubkey and a 33-byte graffiti. - Rewrite the file between two proposals against
MockBeaconNode: the second block request carries the new graffiti, and a line deleted from the file no longer applies. - An unreadable file at proposal time: the request carries the validator's keymanager value or the
--graffitidefault, and a warning is logged.
Metadata
Metadata
Assignees
Labels
No labels
Activity