Skip to content

validator: a graffiti file reloaded before each proposal #838

Open

Description

@MegaRedHand

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, POST and DELETE /eth/v1/validator/{pubkey}/graffiti read, set and clear one validator's graffiti (crates/validator/src/http_api/mod.rs:182-186, handlers at crates/validator/src/http_api/proposer.rs:332-376). A change is written to the validator's entry in validator_definitions.yml before 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 at crates/validator/src/proposal.rs:451). GET answers 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_policy query 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:451 reads 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 --graffiti does (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}/graffiti answer what the next proposal would use, the file included.
  • Send graffiti only when one is set, as Lighthouse does (its block request takes an Option, 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 ordered and random lists 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's DISABLED) needs the ethlambda node to honour it, which graffiti.rs rules 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 --graffiti default, and a warning is logged.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions