From 5655e033faf22eee3cadee6feb989a36d4fe928a Mon Sep 17 00:00:00 2001
From: Mikhail Kalinin <noblesse.knight@gmail.com>
Date: Thu, 30 Mar 2023 16:39:29 +0600
Subject: [PATCH] Add getPayloadV3 with builder override flag

---
 src/engine/builder-override.md          | 43 +++++++++++++++++++++++++
 src/engine/openrpc/methods/payload.yaml | 36 +++++++++++++++++++--
 2 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 src/engine/builder-override.md

diff --git a/src/engine/builder-override.md b/src/engine/builder-override.md
new file mode 100644
index 00000000..63839d88
--- /dev/null
+++ b/src/engine/builder-override.md
@@ -0,0 +1,43 @@
+# Engine API -- Builder Override
+
+Engine API spec for builder override feature.
+
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Methods](#methods)
+  - [engine_getPayloadV3](#engine_getpayloadv3)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Methods
+
+### engine_getPayloadV3
+
+#### Request
+
+* method: `engine_getPayloadV3`
+* params:
+  1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
+* timeout: 1s
+
+#### Response
+
+* result: `object`
+  - `executionPayload`: [`ExecutionPayloadV1`](./paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](#./shanghai.md#ExecutionPayloadV2) where:
+      - `ExecutionPayloadV1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp
+      - `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp
+  - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
+  - `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the EL to use this `executionPayload` instead of an externally provided one
+* error: code and message set in case an exception happens while getting the payload.
+
+#### Specification
+
+This method follows the same specification as [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with the addition of the following:
+
+  1. Client software **MAY** use any heuristics to decide `shouldOverrideBuilder`.
diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml
index 1cd3f50c..dc5117dd 100644
--- a/src/engine/openrpc/methods/payload.yaml
+++ b/src/engine/openrpc/methods/payload.yaml
@@ -32,7 +32,7 @@
     - code: -32602
       message: Invalid params
 - name: engine_getPayloadV1
-  summary: Obtains execution payload from payload build process
+  summary: Obtains execution payload from payload build process, V1
   externalDocs:
     description: Method specification
     url: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_getpayloadv1
@@ -49,7 +49,7 @@
     - code: -38001
       message: Unknown payload
 - name: engine_getPayloadV2
-  summary: Obtains execution payload from payload build process
+  summary: Obtains execution payload from payload build process, V2
   externalDocs:
     description: Method specification
     url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2
@@ -77,6 +77,38 @@
   errors:
     - code: -38001
       message: Unknown payload
+- name: engine_getPayloadV3
+  summary: Obtains execution payload from payload build process, V3
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/builder-override.md#engine_getpayloadv3
+  params:
+    - name: Payload id
+      required: true
+      schema:
+        $ref: '#/components/schemas/bytes8'
+  result:
+    name: Response object
+    schema:
+      type: object
+      required:
+        - executionPayload
+        - blockValue
+      properties:
+        executionPayload:
+          title: Execution payload
+          oneOf:
+            - $ref: '#/components/schemas/ExecutionPayloadV1'
+            - $ref: '#/components/schemas/ExecutionPayloadV2'
+        blockValue:
+          title: Expected fee value
+          $ref: '#/components/schemas/uint256'
+        shouldOverrideBuilder:
+          title: Should override builder flag
+          type: boolean
+  errors:
+    - code: -38001
+      message: Unknown payload
 - name: engine_getPayloadBodiesByHashV1
   summary: Given block hashes returns bodies of the corresponding execution payloads
   externalDocs: