Specify builder_boost_factor (#386)

Co-authored-by: Paul Harris <[email protected]>
Co-authored-by: g11tech <[email protected]>

Author: 3 people

apis/validator/block.v3.yaml

@@ -43,6 +43,39 @@ get:
         is a flag and does not take a value.
       schema: {}
       allowEmptyValue: true
+    - name: builder_boost_factor
+      in: query
+      required: false
+      description: |
+        Percentage multiplier to apply to the builder's payload value when choosing between a
+        builder payload header and payload from the paired execution node. This parameter is only
+        relevant if the beacon node is connected to a builder, deems it safe to produce a builder
+        payload, and receives valid responses from both the builder endpoint _and_ the paired
+        execution node. When these preconditions are met, the server MUST act as follows:
+
+        * if `exec_node_payload_value >= builder_comparison_factor * (builder_payload_value // 100)`,
+          then return a full (unblinded) block containing the execution node payload.
+        * otherwise, return a blinded block containing the builder payload header.
+
+        Servers must support the following values of the comparison factor which encode common
+        preferences:
+
+        * `builder_comparison_factor=0`: prefer the execution node payload unless an error makes it
+          unviable.
+        * `builder_comparison_factor=100`: default profit maximization mode; choose whichever
+          payload pays more.
+        * `builder_comparison_factor=2**64 - 1`: prefer the builder payload unless an error or
+          beacon node health check makes it unviable.
+
+        Servers should use saturating arithmetic or another technique to ensure that large values of
+        the `builder_comparison_factor` do not trigger overflows or errors. If this parameter is
+        provided and the beacon node is not configured with a builder then the beacon node MUST
+        respond with a full block, which the caller can choose to reject if it wishes. If this
+        parameter is **not** provided then it should be treated as having the default value of 100.
+        If the value is provided but out of range for a 64-bit unsigned integer, then an error
+        response with status code 400 MUST be returned.
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
   responses:
     "200":
       description: Success response