feat: implement gloas builder api

.wordlist.txt

@@ -3,6 +3,7 @@ APIs
 Andreas
 Antonopoulos
 AssemblyScript
+Auth
 BLS
 BeaconNode
 Besu
@@ -51,6 +52,7 @@ Golang
 Gossipsub
 Grafana
 Grandine
+Gwei
 HTTPS
 HackMD
 Hashicorp
@@ -119,6 +121,7 @@ addons
 api
 args
 async
+auth
 backfill
 beaconcha
 blockRoot
@@ -246,8 +249,10 @@ tcp
 testnet
 testnets
 todo
+trustless
 typesafe
 udp
+uint
 unpkg
 util
 utils

docs/pages/run/validator-management/proposer-config.md

@@ -26,6 +26,8 @@ proposer_config:
       gas_limit: "45000000"
       selection: "maxprofit"
       boost_factor: "100"
+      min_bid: "10000000"
+      max_execution_payment: "0"
 default_config:
   graffiti: "default graffiti"
   strict_fee_recipient_check: true
@@ -36,6 +38,22 @@ default_config:
     boost_factor: "90"
 ```
 
+Starting with Gloas, the builder section additionally supports `min_bid` (floor in Gwei on the counted total payment from a builder bid) and `max_execution_payment` (ceiling in Gwei on the execution layer payment counted toward a builder bid, values above `0` require `--allowDangerousTrustedPayments`).
+
+Post-Gloas, an explicitly configured per-validator `boost_factor` takes precedence over `selection`.
+
+The builder section also supports a `builders` list with the same per-builder entries as the keymanager builder config API. Each entry has a required `url` and optional `auth_data`, `builder_pubkeys`, `max_execution_payment`, `min_bid` and `builder_boost_factor`. Multiple entries may share a `url` only if they have distinct `auth_data`. Per-key entries replace the builders the validator client is configured with; setting both `--builder.urls` and `builders` in `default_config` is an error.
+
+```yaml
+builder:
+  min_bid: "10000000"
+  builders:
+    - url: "https://builder-a.example.com"
+    - url: "https://builder-b.example.com"
+      auth_data: "0x0123"
+      builder_boost_factor: "200"
+```
+
 ### Enable Proposer Configuration
 
 After you have configured your proposer configuration YAML file, you can start Lodestar with an additional CLI flag option pointing to the file: `--proposerSettingsFile /path/to/proposer_config.yaml`.

docs/pages/run/validator-management/vc-configuration.md

@@ -110,6 +110,17 @@ Example 2: Setting a `--builder.boostFactor=0` will always prefer the local exec
 
 Example 3: Setting a `--builder.boostFactor=100` is the same as signaling `--builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay.
 
+### Configure external builders (Gloas)
+
+Starting with Gloas, external builders are configured on the validator client and the beacon node requests bids on its behalf. Use [`--builder.urls`](./validator-cli.md#--builderurls) to name the builders to request bids from. Viable bids received over p2p are considered alongside them unless the builder circuit breaker is active, governed by the same selection settings. These are additional settings, the pre-Gloas builder flags still apply.
+
+Every bid request is authenticated with data the builder expects, by default the UTF-8 bytes of the builder URL exactly as configured. If a builder requires different auth data agreed out of band, append it as a hex fragment to its URL, e.g. `--builder.urls https://builder.example.com#0x0123`. The fragment is stripped before the URL is used and never sent to the builder. Auth data that must stay secret is better kept in the [proposer configuration file](./proposer-config.md), as command line arguments are visible to other processes.
+
+- [`--builder.minBid`](./validator-cli.md#--builderminbid): minimum counted total payment in Gwei accepted from a builder bid. The total is `value + min(execution_payment, max_execution_payment)`, capped at max uint64. Bids below the floor are discarded.
+- [`--builder.maxExecutionPayment`](./validator-cli.md#--buildermaxexecutionpayment): maximum execution layer payment in Gwei counted from a builder bid, any payment above it adds nothing to the bid when comparing it with other bids. The default of `0` only counts trustless payments backed by the builder's staked collateral. An execution layer payment is only a promise by the builder to pay as part of the block, so values above `0` require the explicit [`--allowDangerousTrustedPayments`](./validator-cli.md#--allowdangeroustrustedpayments) opt-in.
+
+Builders can also be configured per validator key with per-builder overrides via the [builder config keymanager endpoint](https://ethereum.github.io/keymanager-APIs/#/Builder%20Config) or the [proposer configuration file](./proposer-config.md).
+
 ### Submit a validator deposit
 
 Please use the official Ethereum Launchpad to perform your deposits. Ensure your deposits are sent to the proper beacon chain deposit address on the correct network.

packages/api/src/beacon/routes/beacon/block.ts

@@ -163,8 +163,18 @@ export type Endpoints = {
     {
       signedBlockContents: SignedBlockContents;
       broadcastValidation?: BroadcastValidation;
+      /**
+       * The url of the winning builder as returned by `produceBlockV4`. The beacon node forwards
+       * the signed block to this builder so it can help disseminate the block and learn that
+       * its bid won without waiting for gossip.
+       */
+      builderUrl?: string;
+    },
+    {
+      body: unknown;
+      headers: {[MetaHeader.Version]: string; [MetaHeader.BuilderUrl]?: string};
+      query: {broadcast_validation?: string};
     },
-    {body: unknown; headers: {[MetaHeader.Version]: string}; query: {broadcast_validation?: string}},
     EmptyResponseData,
     EmptyMeta
   >;
@@ -345,7 +355,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       url: "/eth/v2/beacon/blocks",
       method: "POST",
       req: {
-        writeReqJson: ({signedBlockContents, broadcastValidation}) => {
+        writeReqJson: ({signedBlockContents, broadcastValidation, builderUrl}) => {
           const slot = signedBlockContents.signedBlock.message.slot;
           const fork = config.getForkName(slot);
           return {
@@ -359,6 +369,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
                   ),
             headers: {
               [MetaHeader.Version]: fork,
+              ...(builderUrl !== undefined ? {[MetaHeader.BuilderUrl]: builderUrl} : {}),
             },
             query: {broadcast_validation: broadcastValidation},
           };
@@ -371,9 +382,10 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
                 ? sszTypesFor(forkName).SignedBlockContents.fromJson(body)
                 : {signedBlock: ssz[forkName].SignedBeaconBlock.fromJson(body)},
             broadcastValidation: query.broadcast_validation as BroadcastValidation,
+            builderUrl: fromHeaders(headers, MetaHeader.BuilderUrl, false),
           };
         },
-        writeReqSsz: ({signedBlockContents, broadcastValidation}) => {
+        writeReqSsz: ({signedBlockContents, broadcastValidation, builderUrl}) => {
           const slot = signedBlockContents.signedBlock.message.slot;
           const fork = config.getForkName(slot);
 
@@ -388,6 +400,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
                   ),
             headers: {
               [MetaHeader.Version]: fork,
+              ...(builderUrl !== undefined ? {[MetaHeader.BuilderUrl]: builderUrl} : {}),
             },
             query: {broadcast_validation: broadcastValidation},
           };
@@ -400,12 +413,13 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
                 ? sszTypesFor(forkName).SignedBlockContents.deserialize(body)
                 : {signedBlock: ssz[forkName].SignedBeaconBlock.deserialize(body)},
             broadcastValidation: query.broadcast_validation as BroadcastValidation,
+            builderUrl: fromHeaders(headers, MetaHeader.BuilderUrl, false),
           };
         },
         schema: {
           body: Schema.Object,
           query: {broadcast_validation: Schema.String},
-          headers: {[MetaHeader.Version]: Schema.String},
+          headers: {[MetaHeader.Version]: Schema.String, [MetaHeader.BuilderUrl]: Schema.String},
         },
       },
       resp: EmptyResponseCodec,