From 7c769530a7565dc739675e308a9a0f5e5961f5c7 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 11 Dec 2023 11:04:51 +1100 Subject: [PATCH 1/5] Specify `builder_comparison_factor` --- apis/validator/block.v3.yaml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index c7b8ff76..f62a6035 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -43,6 +43,38 @@ get: is a flag and does not take a value. schema: {} allowEmptyValue: true + - name: builder_comparison_factor + in: query + required: false + description: | + Percentage multiplier to apply to the builder's payload value when choosing between a + builder payload header and a local payload. 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 local execution node. When these + pre-conditions are met, the server MUST act as follows: + + * if `local_payload_value >= builder_comparison_factor * builder_payload_value // 100`, then + return a full (unblinded) block containing the local 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 local 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 local block, which the caller can choose to reject + if it wishes. + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: "200": description: Success response From bfb254ce91a85fc188d1637bce366d7e6d9bd1a6 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 11 Dec 2023 11:11:59 +1100 Subject: [PATCH 2/5] Spellcheck --- apis/validator/block.v3.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index f62a6035..805c2ec7 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -51,7 +51,7 @@ get: builder payload header and a local payload. 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 local execution node. When these - pre-conditions are met, the server MUST act as follows: + preconditions are met, the server MUST act as follows: * if `local_payload_value >= builder_comparison_factor * builder_payload_value // 100`, then return a full (unblinded) block containing the local payload. From b0cbcc9c5f20714a7f5f3b5ed13c59f3339f6154 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 11 Dec 2023 12:42:15 +1100 Subject: [PATCH 3/5] Clarify default & error behaviour --- apis/validator/block.v3.yaml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 805c2ec7..30de548e 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -67,12 +67,13 @@ get: * `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 local block, which the caller can choose to reject - if it wishes. + 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 local 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: From e5b1045ecf5ed474a38ac857937dc593efee269c Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Tue, 12 Dec 2023 11:36:48 +1100 Subject: [PATCH 4/5] Clarify local terminology & improve rounding behaviour --- apis/validator/block.v3.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 30de548e..8f73c32c 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -48,29 +48,29 @@ get: required: false description: | Percentage multiplier to apply to the builder's payload value when choosing between a - builder payload header and a local payload. 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 local execution node. When these - preconditions are met, the server MUST act as follows: + 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 `local_payload_value >= builder_comparison_factor * builder_payload_value // 100`, then - return a full (unblinded) block containing the local payload. + * 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 local payload unless an error makes it - unviable. + * `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. + 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 local block, which the caller can choose to reject if it wishes. If this + 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. From 6f687429204cb808554baf21f69cedab3470c8e7 Mon Sep 17 00:00:00 2001 From: Paul Harris Date: Thu, 21 Dec 2023 11:27:49 +1000 Subject: [PATCH 5/5] Update apis/validator/block.v3.yaml roughly agreed on discord Co-authored-by: g11tech --- apis/validator/block.v3.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 8f73c32c..c7b0596c 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -43,7 +43,7 @@ get: is a flag and does not take a value. schema: {} allowEmptyValue: true - - name: builder_comparison_factor + - name: builder_boost_factor in: query required: false description: |