diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index c7b8ff76..c7b0596c 100644 --- a/apis/validator/block.v3.yaml +++ b/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