engine: Extend payload bodies with deposit and withdrawal requests (#545

) Add payload bodies V2
ethereum · May 15, 2024 · 03911ff · 03911ff
1 parent c4e7da7
commit 03911ff
Show file tree

Hide file tree

Showing 3 changed files with 269 additions and 19 deletions.
diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml
@@ -252,7 +252,7 @@
                 amount: '0x1'
             blobGasUsed: '0x0'
             excessBlobGas: '0x0'
-            depositReceipts:
+            depositRequests:
               - pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
                 withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
                 amount: '0x1'
@@ -263,11 +263,13 @@
                 amount: '0x1'
                 signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
                 index: '0xf1'
-            exits:
+            withdrawalRequests:
               - sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
                 validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
+                amount: '0x0'
               - sourceAddress: '0x00000000000000000000000000000000000010f6'
                 validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
+                amount: '0x1'
         - name: Expected blob versioned hashes
           value:
             - '0x000657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014'
@@ -540,7 +542,7 @@
                 amount: '0x1'
             blobGasUsed: '0x60000'
             excessBlobGas: '0x0'
-            depositReceipts:
+            depositRequests:
               - pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
                 withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
                 amount: '0x1'
@@ -551,11 +553,13 @@
                 amount: '0x1'
                 signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
                 index: '0xf1'
-            exits:
+            withdrawalRequests:
               - sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
                 validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
+                amount: '0x0'
               - sourceAddress: '0x00000000000000000000000000000000000010f6'
                 validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
+                amount: '0x1'
           blockValue: '0x10a741a46278014d'
           blobsBundle:
             commitments:
@@ -620,6 +624,81 @@
                 validatorIndex: '0xf3'
                 address: '0x00000000000000000000000000000000000010f3'
                 amount: '0x1'
+- name: engine_getPayloadBodiesByHashV2
+  summary: Given block hashes returns bodies of the corresponding execution payloads
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_getpayloadbodiesbyhashv2
+  params:
+    - name: Array of block hashes
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '#/components/schemas/hash32'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV2'
+  errors:
+    - code: -38004
+      message: Too large request
+  examples:
+    - name: engine_getPayloadBodiesByHashV2 example
+      params:
+        - name: Array of block hashes
+          value:
+            - '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
+            - '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553'
+      result:
+        name: Execution payload bodies
+        value:
+          - transactions:
+              - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
+              - '0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95'
+            withdrawals:
+              - index: '0xf0'
+                validatorIndex: '0xf0'
+                address: '0x00000000000000000000000000000000000010f0'
+                amount: '0x1'
+              - index: '0xf1'
+                validatorIndex: '0xf1'
+                address: '0x00000000000000000000000000000000000010f1'
+                amount: '0x1'
+            depositRequests:
+              - pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
+                withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
+                amount: '0x1'
+                signature: '0xb1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9'
+                index: '0xf0'
+            withdrawalRequests:
+              - sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
+                validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
+                amount: '0x0'
+          - transactions:
+              - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
+              - '0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29'
+            withdrawals:
+              - index: '0xf2'
+                validatorIndex: '0xf2'
+                address: '0x00000000000000000000000000000000000010f2'
+                amount: '0x1'
+              - index: '0xf3'
+                validatorIndex: '0xf3'
+                address: '0x00000000000000000000000000000000000010f3'
+                amount: '0x1'
+            depositRequests:
+              - pubkey: '0xa5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b'
+                withdrawalCredentials: '0x001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca'
+                amount: '0x1'
+                signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
+                index: '0xf1'
+            withdrawalRequests:
+              - sourceAddress: '0x00000000000000000000000000000000000010f6'
+                validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
+                amount: '0x1'
 - name: engine_getPayloadBodiesByRangeV1
   summary: Given a range of block numbers returns bodies of the corresponding execution payloads
   externalDocs:
@@ -677,3 +756,80 @@
                 validatorIndex: '0xf3'
                 address: '0x00000000000000000000000000000000000010f3'
                 amount: '0x1'
+- name: engine_getPayloadBodiesByRangeV2
+  summary: Given a range of block numbers returns bodies of the corresponding execution payloads
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_getpayloadbodiesbyrangev2
+  params:
+    - name: Starting block number
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+    - name: Number of blocks to return
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV1'
+  errors:
+    - code: -38004
+      message: Too large request
+  examples:
+    - name: engine_getPayloadBodiesByRangeV2 example
+      params:
+        - name: Starting block number
+          value: '0x20'
+        - name: Number of blocks to return
+          value: '0x2'
+      result:
+        name: Execution payload bodies
+        value:
+          - transactions:
+              - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
+              - '0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95'
+            withdrawals:
+              - index: '0xf0'
+                validatorIndex: '0xf0'
+                address: '0x00000000000000000000000000000000000010f0'
+                amount: '0x1'
+              - index: '0xf1'
+                validatorIndex: '0xf1'
+                address: '0x00000000000000000000000000000000000010f1'
+                amount: '0x1'
+            depositRequests:
+              - pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
+                withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
+                amount: '0x1'
+                signature: '0xb1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9'
+                index: '0xf0'
+            withdrawalRequests:
+              - sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
+                validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
+                amount: '0x0'
+          - transactions:
+              - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
+              - '0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29'
+            withdrawals:
+              - index: '0xf2'
+                validatorIndex: '0xf2'
+                address: '0x00000000000000000000000000000000000010f2'
+                amount: '0x1'
+              - index: '0xf3'
+                validatorIndex: '0xf3'
+                address: '0x00000000000000000000000000000000000010f3'
+                amount: '0x1'
+            depositRequests:
+              - pubkey: '0xa5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b'
+                withdrawalCredentials: '0x001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca'
+                amount: '0x1'
+                signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
+                index: '0xf1'
+            withdrawalRequests:
+              - sourceAddress: '0x00000000000000000000000000000000000010f6'
+                validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
+                amount: '0x1'
diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml
@@ -326,6 +326,38 @@ ExecutionPayloadBodyV1:
         - 'null'
       items:
         $ref: '#/components/schemas/WithdrawalV1'
+ExecutionPayloadBodyV2:
+  title: Execution payload body object V2
+  type: object
+  required:
+    - transactions
+  properties:
+    transactions:
+      title: Transactions
+      type: array
+      items:
+        $ref: '#/components/schemas/bytes'
+    withdrawals:
+      title: Withdrawals
+      type:
+        - array
+        - 'null'
+      items:
+        $ref: '#/components/schemas/WithdrawalV1'
+    depositRequests:
+      title: Deposit requests
+      type:
+        - array
+        - 'null'
+      items:
+        $ref: '#/components/schemas/DepositRequestV1'
+    withdrawalRequests:
+      title: Withdrawals requests
+      type:
+        - array
+        - 'null'
+      items:
+        $ref: '#/components/schemas/WithdrawalRequestV1'
 BlobsBundleV1:
   title: Blobs bundle object V1
   type: object

diff --git a/src/engine/prague.md b/src/engine/prague.md
@@ -9,21 +9,29 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Engine API -- Prague](#engine-api----prague)
-  - [Table of contents](#table-of-contents)
-  - [Structures](#structures)
-    - [DepositRequestV1](#depositrequestv1)
-    - [WithdrawalRequestV1](#withdrawalrequestv1)
-    - [ExecutionPayloadV4](#executionpayloadv4)
-  - [Methods](#methods)
-    - [engine\_newPayloadV4](#engine_newpayloadv4)
-      - [Request](#request)
-      - [Response](#response)
-      - [Specification](#specification)
-    - [engine\_getPayloadV4](#engine_getpayloadv4)
-      - [Request](#request-1)
-      - [Response](#response-1)
-      - [Specification](#specification-1)
+- [Structures](#structures)
+  - [DepositRequestV1](#depositrequestv1)
+  - [WithdrawalRequestV1](#withdrawalrequestv1)
+  - [ExecutionPayloadV4](#executionpayloadv4)
+  - [ExecutionPayloadBodyV2](#executionpayloadbodyv2)
+- [Methods](#methods)
+  - [engine_newPayloadV4](#engine_newpayloadv4)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_getPayloadV4](#engine_getpayloadv4)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+  - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
+  - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2)
+    - [Request](#request-3)
+    - [Response](#response-3)
+    - [Specification](#specification-3)
+  - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -75,6 +83,15 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay
 - `depositRequests`: `Array of DepositRequestV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositRequestV1` structure.
 - `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure.
 
+### ExecutionPayloadBodyV2
+
+This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadv1) and appends the new fields: `depositRequests` and `withdrawalRequests`.
+
+- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
+- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
+- `depositRequests`: `Array of DepositRequestV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositRequestV1` structure.
+- `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure.
+
 ## Methods
 
 ### engine_newPayloadV4
@@ -125,6 +142,51 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m
 
 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the Prague fork.
 
+### engine_getPayloadBodiesByHashV2
+
+The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2).
+
+#### Request
+
+* method: `engine_getPayloadBodiesByHashV2`
+* params:
+  1. `Array of DATA`, 32 Bytes - Array of `block_hash` field values of the `ExecutionPayload` structure
+* timeout: 10s
+
+#### Response
+
+* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects.
+* error: code and message set in case an exception happens while processing the method call.
+
+#### Specification
+
+This method follows the same specification as [`engine_getPayloadBodiesByHashV1`](./shanghai.md#engine_getpayloadbodiesbyhashv1) with the addition of the following:
+
+1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks.
+
+### engine_getPayloadBodiesByRangeV2
+
+The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2).
+
+#### Request
+
+* method: `engine_getPayloadBodiesByRangeV2`
+* params:
+  1. `start`: `QUANTITY`, 64 bits - Starting block number
+  1. `count`: `QUANITTY`, 64 bits - Number of blocks to return
+* timeout: 10s
+
+#### Response
+
+* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects.
+* error: code and message set in case an exception happens while processing the method call.
+
+#### Specification
+
+This method follows the same specification as [`engine_getPayloadBodiesByRangeV2`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the addition of the following:
+
+1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks.
+
 ### Update the methods of previous forks
 
 This document defines how Prague payload should be handled by the [`Cancun API`](./cancun.md).