diff --git a/specs/gloas/builder.md b/specs/gloas/builder.md index d7105497..5418e41c 100644 --- a/specs/gloas/builder.md +++ b/specs/gloas/builder.md @@ -106,7 +106,8 @@ containing: `auth.message.slot` is the proposal slot the preferences apply to. The builder MUST verify the BLS signature against the `proposer_pubkey` path parameter and MUST check that `auth.message.data` matches the value it agreed with the - proposer, so that an unauthenticated or replayed request cannot skew a + proposer, or the [default auth data][default-auth-data] of its own URL when + none was agreed, so that an unauthenticated or replayed request cannot skew a proposer's preferences away from the value the proposer chose. If the signature fails to verify, the builder MUST return a 401 response; if the `auth.message.data` check fails, the builder MUST return a 400 response. The @@ -161,8 +162,9 @@ the builder MAY serve a bid with any `execution_payment`. Builders MUST verify the `SignedBuilderRequestAuth` signature against the `proposer_pubkey` path parameter, and MUST check that `auth.message.data` -matches the value they agreed with the proposer and that `auth.message.slot` -matches the proposal `slot` path parameter (see +matches the value they agreed with the proposer, or the +[default auth data][default-auth-data] of their own URL when none was agreed, +and that `auth.message.slot` matches the proposal `slot` path parameter (see [Constructing the `BuilderRequestAuth`][constructing-builder-request-auth]). The signature is verified with [`verify_builder_request_auth_signature`](#signing). If the signature fails to verify, the builder MUST return a 401 response; if the @@ -257,6 +259,7 @@ documented in the [Gloas consensus specs][gloas-builder-specs]. [bls]: https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#bls-signatures [constructing-builder-request-auth]: ./validator.md#constructing-the-builderrequestauth +[default-auth-data]: ./validator.md#default-auth-data [get-execution-payload-bid-api]: ./../../apis/builder/execution_payload_bid.yaml [gloas-builder-specs]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/builder.md [gloas-consensus-specs]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas diff --git a/specs/gloas/validator.md b/specs/gloas/validator.md index 5a7646b3..18b3dbbd 100644 --- a/specs/gloas/validator.md +++ b/specs/gloas/validator.md @@ -14,6 +14,7 @@ - [`max_execution_payment`](#max_execution_payment) - [Bid Request](#bid-request) - [Constructing the `BuilderRequestAuth`](#constructing-the-builderrequestauth) + - [Default auth data](#default-auth-data) - [Proposer Preferences](#proposer-preferences) - [Validating a `SignedExecutionPayloadBid`](#validating-a-signedexecutionpayloadbid) - [Block proposal](#block-proposal) @@ -145,9 +146,9 @@ The validator constructs a `BuilderRequestAuth` with the following fields: meaning is left to the two parties. It is not tied to an endpoint, so one `SignedBuilderRequestAuth` can authenticate the proposer for both `getExecutionPayloadBid` and `submitBuilderPreferences`. When no value has - been agreed out of band, the validator SHOULD use the UTF-8 bytes of the - builder's own advertised URL, exactly as advertised. A zero-length `data` is - invalid. + been agreed out of band, the validator SHOULD use the + [default auth data](#default-auth-data) derived from the builder URL. A + zero-length `data` is invalid. - `slot`: The proposal slot this request is authorized for, not the slot at which the request is signed or sent. @@ -159,6 +160,38 @@ The validator then constructs the `SignedBuilderRequestAuth` by signing the validator and discard requests from other parties (e.g. DDOS or replay attempts from competing builders). +#### Default auth data + +The default `data` for a builder URL is the builder's hostname: the lowercased +ASCII hostname of the URL, an IPv6 literal written in its compressed form +([RFC 5952][rfc-5952]) inside brackets. Scheme, userinfo, port, path, query and +fragment are not part of the builder's identity and are dropped, so differences +in how the URL is written, such as a trailing `/` or an explicit default port, +do not change the signed bytes. An internationalized hostname MUST be given in +its punycode form. + +```python +def get_default_auth_data(url: str) -> bytes: + host = urlsplit(url).hostname # lowercased, userinfo and port removed + assert host is not None and host.isascii() + if ":" in host: # IPv6 literal + host = f"[{IPv6Address(host).compressed}]" + return host.encode("ascii") +``` + +| URL | `data` | +| ------------------------------------------ | --------------------- | +| `https://builder.example.com/` | `builder.example.com` | +| `HTTPS://Builder.Example.com:443/bids?x=1` | `builder.example.com` | +| `https://builder.example.com:8080` | `builder.example.com` | +| `https://user:pw@builder.example.com/` | `builder.example.com` | +| `https://10.0.0.5:18550/eth/v1/builder` | `10.0.0.5` | +| `https://[0:0:0:0:0:0:0:1]:8443/` | `[::1]` | + +A builder that needs a finer identity than its hostname, for example one host +serving several builders on different paths or ports, agrees `data` with its +proposers out of band instead. + ## Proposer Preferences *Note*: Validator registrations (`ValidatorRegistrationV1`) are **deprecated** @@ -260,6 +293,7 @@ block on top of a beacon `state` must take the following actions: [is-active-builder]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#new-is_active_builder [proposer-preferences]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/p2p-interface.md#new-proposerpreferences [proposer-preferences-topic]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/p2p-interface.md#new-proposer_preferences +[rfc-5952]: https://www.rfc-editor.org/rfc/rfc5952 [signed-execution-payload-bid]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadbid [signed-execution-payload-envelope]: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope [submit-builder-preferences-api]: ./../../apis/builder/builder_preferences.yaml diff --git a/types/gloas/request_auth.yaml b/types/gloas/request_auth.yaml index e5e5e242..f901be00 100644 --- a/types/gloas/request_auth.yaml +++ b/types/gloas/request_auth.yaml @@ -11,10 +11,10 @@ Gloas: band. The meaning of the up to `MAX_BUILDER_AUTH_DATA_SIZE` (4096) bytes is left to the two parties; the builder checks the exact bytes when it verifies. When no value has been agreed out of band, implementations - SHOULD default to the UTF-8 bytes of the builder's own advertised - URL, exactly as advertised, so proposers with no prior relationship - can construct an identical `data` deterministically. A zero-length - `data` is invalid. + SHOULD default to the builder's hostname derived from its URL, see + [default auth data](https://github.com/ethereum/builder-specs/blob/master/specs/gloas/validator.md#default-auth-data), + so proposers with no prior relationship can construct an identical + `data` deterministically. A zero-length `data` is invalid. example: "0x1234567890abcdef" pattern: "^0x(?:[a-fA-F0-9]{2}){1,4096}$" slot: diff --git a/wordlist.txt b/wordlist.txt index f57d5419..29bbcd60 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -7,6 +7,7 @@ capella cli dev eth +hostname http https json @@ -16,6 +17,7 @@ nodejs npm oapi openapi +punycode ssz tbh ui @@ -23,6 +25,7 @@ uint unblind unblinded url +userinfo validators validator's vc @@ -34,7 +37,7 @@ fulu Gloas gloas Gwei +IPv PTC -UTF submitBlindedBlockV ValidatorRegistrationsV \ No newline at end of file