Skip to content

Commit 03911ff

Browse files
mkalininmkalinin
authored
engine: Extend payload bodies with deposit and withdrawal requests (#545)
Add payload bodies V2
1 parent c4e7da7 commit 03911ff

File tree

3 files changed

+269
-19
lines changed

3 files changed

+269
-19
lines changed

‎src/engine/openrpc/methods/payload.yaml

Lines changed: 160 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@
252252
amount: '0x1'
253253
blobGasUsed: '0x0'
254254
excessBlobGas: '0x0'
255-
depositReceipts:
255+
depositRequests:
256256
- pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
257257
withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
258258
amount: '0x1'
@@ -263,11 +263,13 @@
263263
amount: '0x1'
264264
signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
265265
index: '0xf1'
266-
exits:
266+
withdrawalRequests:
267267
- sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
268268
validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
269+
amount: '0x0'
269270
- sourceAddress: '0x00000000000000000000000000000000000010f6'
270271
validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
272+
amount: '0x1'
271273
- name: Expected blob versioned hashes
272274
value:
273275
- '0x000657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014'
@@ -540,7 +542,7 @@
540542
amount: '0x1'
541543
blobGasUsed: '0x60000'
542544
excessBlobGas: '0x0'
543-
depositReceipts:
545+
depositRequests:
544546
- pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
545547
withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
546548
amount: '0x1'
@@ -551,11 +553,13 @@
551553
amount: '0x1'
552554
signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
553555
index: '0xf1'
554-
exits:
556+
withdrawalRequests:
555557
- sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
556558
validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
559+
amount: '0x0'
557560
- sourceAddress: '0x00000000000000000000000000000000000010f6'
558561
validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
562+
amount: '0x1'
559563
blockValue: '0x10a741a46278014d'
560564
blobsBundle:
561565
commitments:
@@ -620,6 +624,81 @@
620624
validatorIndex: '0xf3'
621625
address: '0x00000000000000000000000000000000000010f3'
622626
amount: '0x1'
627+
- name: engine_getPayloadBodiesByHashV2
628+
summary: Given block hashes returns bodies of the corresponding execution payloads
629+
externalDocs:
630+
description: Method specification
631+
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_getpayloadbodiesbyhashv2
632+
params:
633+
- name: Array of block hashes
634+
required: true
635+
schema:
636+
type: array
637+
items:
638+
$ref: '#/components/schemas/hash32'
639+
result:
640+
name: Execution payload bodies
641+
schema:
642+
type: array
643+
items:
644+
$ref: '#/components/schemas/ExecutionPayloadBodyV2'
645+
errors:
646+
- code: -38004
647+
message: Too large request
648+
examples:
649+
- name: engine_getPayloadBodiesByHashV2 example
650+
params:
651+
- name: Array of block hashes
652+
value:
653+
- '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
654+
- '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553'
655+
result:
656+
name: Execution payload bodies
657+
value:
658+
- transactions:
659+
- '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
660+
- '0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95'
661+
withdrawals:
662+
- index: '0xf0'
663+
validatorIndex: '0xf0'
664+
address: '0x00000000000000000000000000000000000010f0'
665+
amount: '0x1'
666+
- index: '0xf1'
667+
validatorIndex: '0xf1'
668+
address: '0x00000000000000000000000000000000000010f1'
669+
amount: '0x1'
670+
depositRequests:
671+
- pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
672+
withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
673+
amount: '0x1'
674+
signature: '0xb1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9'
675+
index: '0xf0'
676+
withdrawalRequests:
677+
- sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
678+
validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
679+
amount: '0x0'
680+
- transactions:
681+
- '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
682+
- '0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29'
683+
withdrawals:
684+
- index: '0xf2'
685+
validatorIndex: '0xf2'
686+
address: '0x00000000000000000000000000000000000010f2'
687+
amount: '0x1'
688+
- index: '0xf3'
689+
validatorIndex: '0xf3'
690+
address: '0x00000000000000000000000000000000000010f3'
691+
amount: '0x1'
692+
depositRequests:
693+
- pubkey: '0xa5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b'
694+
withdrawalCredentials: '0x001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca'
695+
amount: '0x1'
696+
signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
697+
index: '0xf1'
698+
withdrawalRequests:
699+
- sourceAddress: '0x00000000000000000000000000000000000010f6'
700+
validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
701+
amount: '0x1'
623702
- name: engine_getPayloadBodiesByRangeV1
624703
summary: Given a range of block numbers returns bodies of the corresponding execution payloads
625704
externalDocs:
@@ -677,3 +756,80 @@
677756
validatorIndex: '0xf3'
678757
address: '0x00000000000000000000000000000000000010f3'
679758
amount: '0x1'
759+
- name: engine_getPayloadBodiesByRangeV2
760+
summary: Given a range of block numbers returns bodies of the corresponding execution payloads
761+
externalDocs:
762+
description: Method specification
763+
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_getpayloadbodiesbyrangev2
764+
params:
765+
- name: Starting block number
766+
required: true
767+
schema:
768+
$ref: '#/components/schemas/uint64'
769+
- name: Number of blocks to return
770+
required: true
771+
schema:
772+
$ref: '#/components/schemas/uint64'
773+
result:
774+
name: Execution payload bodies
775+
schema:
776+
type: array
777+
items:
778+
$ref: '#/components/schemas/ExecutionPayloadBodyV1'
779+
errors:
780+
- code: -38004
781+
message: Too large request
782+
examples:
783+
- name: engine_getPayloadBodiesByRangeV2 example
784+
params:
785+
- name: Starting block number
786+
value: '0x20'
787+
- name: Number of blocks to return
788+
value: '0x2'
789+
result:
790+
name: Execution payload bodies
791+
value:
792+
- transactions:
793+
- '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
794+
- '0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95'
795+
withdrawals:
796+
- index: '0xf0'
797+
validatorIndex: '0xf0'
798+
address: '0x00000000000000000000000000000000000010f0'
799+
amount: '0x1'
800+
- index: '0xf1'
801+
validatorIndex: '0xf1'
802+
address: '0x00000000000000000000000000000000000010f1'
803+
amount: '0x1'
804+
depositRequests:
805+
- pubkey: '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9'
806+
withdrawalCredentials: '0x003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef2'
807+
amount: '0x1'
808+
signature: '0xb1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9'
809+
index: '0xf0'
810+
withdrawalRequests:
811+
- sourceAddress: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
812+
validatorPublicKey: '0x85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0'
813+
amount: '0x0'
814+
- transactions:
815+
- '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
816+
- '0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29'
817+
withdrawals:
818+
- index: '0xf2'
819+
validatorIndex: '0xf2'
820+
address: '0x00000000000000000000000000000000000010f2'
821+
amount: '0x1'
822+
- index: '0xf3'
823+
validatorIndex: '0xf3'
824+
address: '0x00000000000000000000000000000000000010f3'
825+
amount: '0x1'
826+
depositRequests:
827+
- pubkey: '0xa5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b'
828+
withdrawalCredentials: '0x001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca'
829+
amount: '0x1'
830+
signature: '0x9561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1'
831+
index: '0xf1'
832+
withdrawalRequests:
833+
- sourceAddress: '0x00000000000000000000000000000000000010f6'
834+
validatorPublicKey: '0x98daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a7553'
835+
amount: '0x1'

‎src/engine/openrpc/schemas/payload.yaml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,38 @@ ExecutionPayloadBodyV1:
326326
- 'null'
327327
items:
328328
$ref: '#/components/schemas/WithdrawalV1'
329+
ExecutionPayloadBodyV2:
330+
title: Execution payload body object V2
331+
type: object
332+
required:
333+
- transactions
334+
properties:
335+
transactions:
336+
title: Transactions
337+
type: array
338+
items:
339+
$ref: '#/components/schemas/bytes'
340+
withdrawals:
341+
title: Withdrawals
342+
type:
343+
- array
344+
- 'null'
345+
items:
346+
$ref: '#/components/schemas/WithdrawalV1'
347+
depositRequests:
348+
title: Deposit requests
349+
type:
350+
- array
351+
- 'null'
352+
items:
353+
$ref: '#/components/schemas/DepositRequestV1'
354+
withdrawalRequests:
355+
title: Withdrawals requests
356+
type:
357+
- array
358+
- 'null'
359+
items:
360+
$ref: '#/components/schemas/WithdrawalRequestV1'
329361
BlobsBundleV1:
330362
title: Blobs bundle object V1
331363
type: object

‎src/engine/prague.md

Lines changed: 77 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,29 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
99
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
1010
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1111

12-
- [Engine API -- Prague](#engine-api----prague)
13-
- [Table of contents](#table-of-contents)
14-
- [Structures](#structures)
15-
- [DepositRequestV1](#depositrequestv1)
16-
- [WithdrawalRequestV1](#withdrawalrequestv1)
17-
- [ExecutionPayloadV4](#executionpayloadv4)
18-
- [Methods](#methods)
19-
- [engine\_newPayloadV4](#engine_newpayloadv4)
20-
- [Request](#request)
21-
- [Response](#response)
22-
- [Specification](#specification)
23-
- [engine\_getPayloadV4](#engine_getpayloadv4)
24-
- [Request](#request-1)
25-
- [Response](#response-1)
26-
- [Specification](#specification-1)
12+
- [Structures](#structures)
13+
- [DepositRequestV1](#depositrequestv1)
14+
- [WithdrawalRequestV1](#withdrawalrequestv1)
15+
- [ExecutionPayloadV4](#executionpayloadv4)
16+
- [ExecutionPayloadBodyV2](#executionpayloadbodyv2)
17+
- [Methods](#methods)
18+
- [engine_newPayloadV4](#engine_newpayloadv4)
19+
- [Request](#request)
20+
- [Response](#response)
21+
- [Specification](#specification)
22+
- [engine_getPayloadV4](#engine_getpayloadv4)
23+
- [Request](#request-1)
24+
- [Response](#response-1)
25+
- [Specification](#specification-1)
26+
- [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2)
27+
- [Request](#request-2)
28+
- [Response](#response-2)
29+
- [Specification](#specification-2)
30+
- [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2)
31+
- [Request](#request-3)
32+
- [Response](#response-3)
33+
- [Specification](#specification-3)
34+
- [Update the methods of previous forks](#update-the-methods-of-previous-forks)
2735

2836
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2937

@@ -75,6 +83,15 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay
7583
- `depositRequests`: `Array of DepositRequestV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositRequestV1` structure.
7684
- `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure.
7785

86+
### ExecutionPayloadBodyV2
87+
88+
This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadv1) and appends the new fields: `depositRequests` and `withdrawalRequests`.
89+
90+
- `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)
91+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
92+
- `depositRequests`: `Array of DepositRequestV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositRequestV1` structure.
93+
- `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure.
94+
7895
## Methods
7996

8097
### engine_newPayloadV4
@@ -125,6 +142,51 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m
125142

126143
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.
127144

145+
### engine_getPayloadBodiesByHashV2
146+
147+
The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2).
148+
149+
#### Request
150+
151+
* method: `engine_getPayloadBodiesByHashV2`
152+
* params:
153+
1. `Array of DATA`, 32 Bytes - Array of `block_hash` field values of the `ExecutionPayload` structure
154+
* timeout: 10s
155+
156+
#### Response
157+
158+
* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects.
159+
* error: code and message set in case an exception happens while processing the method call.
160+
161+
#### Specification
162+
163+
This method follows the same specification as [`engine_getPayloadBodiesByHashV1`](./shanghai.md#engine_getpayloadbodiesbyhashv1) with the addition of the following:
164+
165+
1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks.
166+
167+
### engine_getPayloadBodiesByRangeV2
168+
169+
The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2).
170+
171+
#### Request
172+
173+
* method: `engine_getPayloadBodiesByRangeV2`
174+
* params:
175+
1. `start`: `QUANTITY`, 64 bits - Starting block number
176+
1. `count`: `QUANITTY`, 64 bits - Number of blocks to return
177+
* timeout: 10s
178+
179+
#### Response
180+
181+
* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects.
182+
* error: code and message set in case an exception happens while processing the method call.
183+
184+
#### Specification
185+
186+
This method follows the same specification as [`engine_getPayloadBodiesByRangeV2`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the addition of the following:
187+
188+
1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks.
189+
128190
### Update the methods of previous forks
129191

130192
This document defines how Prague payload should be handled by the [`Cancun API`](./cancun.md).

0 commit comments

Comments
 (0)