diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 13745599..f45bbd12 100644 --- 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 index a2469017..28955fdb 100644 --- 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 index 1b550b2a..aa0d666e 100644 --- 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 -- [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) @@ -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).