From f6a782c72c16194cae30f63f695c1480f39dc83b Mon Sep 17 00:00:00 2001 From: Marcin Sobczak Date: Mon, 17 Nov 2025 12:34:10 +0100 Subject: [PATCH 01/16] add draft of testing_buildBlockV1 --- src/testing/testing_buildBlockV1.md | 115 ++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 src/testing/testing_buildBlockV1.md diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md new file mode 100644 index 000000000..a1757065d --- /dev/null +++ b/src/testing/testing_buildBlockV1.md @@ -0,0 +1,115 @@ +# `testing_buildBlockV1` + +This document specifies the `testing_buildBlockV1` RPC method. This method is a debugging and testing tool that simplifies the block production process into a single call. It is intended to replace the multi-step workflow of sending transactions, calling `engine_forkchoiceUpdated` with `payloadAttributes`, and then calling `engine_getPayload`. + +This method is considered sensitive and is intended for testing environments only. See **Security Considerations** for more details. + +## Method: `testing_buildBlockV1` + +### Parameters + +1. `buildBlockParams`: `object` - An object containing the parameters for building the block: + + * `parentBlockHash`: `DATA, 32 Bytes` - (Required) The hash of the parent block upon which to build the new block. + + * `payloadAttributes`: `OBJECT` - (Required) The `PayloadAttributesV3` object, as defined in [`engine_forkchoiceUpdated`](../engine-apis/forkchoiceUpdated.md#payloadattributesv3). + + * `transactions`: `Array of DATA` - (Required) An array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. + + * `extraData`: `DATA, 0 to 32 Bytes` - (Optional) A hex-encoded `0x...` string to be set as the `extraData` field of the built block. If this field is provided, it MUST override any default `extraData` the client would normally insert. + + * `skipValidation`: `boolean` - (Optional, default: `false`) If `true`, the client MUST attempt to build the block even if the provided transactions are invalid (e.g., incorrect nonce, insufficient balance, or invalid signature). If `false`, the method MUST return an error if any transaction fails state validation. + +### Returns + +`result`: `OBJECT` - The constructed `ExecutionPayloadV3`, as defined in [`engine_getPayload`](../engine-apis/getPayload.md#executionpayloadv3). + +### Behavior + +* The client MUST build a new execution payload using the block specified by `parentBlockHash` as its parent. + +* The client MUST use the provided `payloadAttributes` to define the context of the new block (e.g., `timestamp`, `prevRandao`, `suggestedFeeRecipient`). + +* The client MUST include all transactions from the `transactions` array at the beginning of the block's transaction list, in the order they were provided. + +* The client MUST NOT include any transactions from its local transaction pool. The resulting block MUST only contain the transactions specified in the `transactions` array. + +* If `extraData` is provided, the client MUST set the `extraData` field of the resulting payload to this value. + +* If `skipValidation` is `false` (or omitted), the client MUST validate all transactions in the `transactions` array against the state at the `parentBlockHash`. If any transaction is invalid, the method MUST return a standard JSON-RPC error. + +* If `skipValidation` is `true`, the client MUST skip state-dependent validation (e.g., nonce, balance) for the transactions in the `transactions` array. The client SHOULD still perform basic format validation. The client MUST attempt to build and return the payload, even if this payload would be considered invalid by consensus rules. + +* This method MUST NOT modify the client's canonical chain or head block. It is a read-only method for payload generation. It does not run the equivalent of `engine_newPayload` or `engine_forkchoiceUpdated`. + +### Security Considerations + +* **HIGHLY SENSITIVE**: This method is a powerful debugging tool intended for testing environments ONLY. + +* It allows for the creation of arbitrary, and potentially invalid, blocks. It can be in used to bypass transaction pool validation and forcibly include any transaction. + +* This method MUST NOT be exposed on public-facing RPC APIs. + +* It is strongly recommended that this method, and its `testing_` namespace, be disabled by default. Enabling it should require an explicit command-line flag or configuration setting by the node operator. + +### Example + +#### Request + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "testing_buildBlockV1", + "params": [ + { + "parentBlockHash": "0x3b8fb240d288781d4f1e1d32f4c1550BEEFDEADBEEFDEADBEEFDEADBEEFDEAD", + "payloadAttributes": { + "timestamp": "0x6705D918", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "suggestedFeeRecipient": "0x0000000000000000000000000000000000000000", + "withdrawals": [], + "parentBeaconBlockRoot": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884365149a42212e8822" + }, + "transactions": [ + "0xf86c0a8504a817c80082520894...cb61163c917540a0c64c12b8f50015", + "0xf86b0f8504a817c80082520894...5443c01e69d3b0c5112101564914a2" + ], + "extraData": "0x746573745F6E616D65", + "skipValidation": false + } + ] +} +``` + +#### Response (Success) + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "blockHash": "0x8980a3a7f8b16053c4dec86e1050e6378e176272517852f8c5b56f34e9a0f9b6", + "parentHash": "0x3b8fb240d288781d4f1e1d32f4c1550BEEFDEADBEEFDEADBEEFDEADBEEFDEAD", + "feeRecipient": "0x0000000000000000000000000000000000000000", + "stateRoot": "0xca3699d05d3369680315af1d03c6f8f73188945f3c83756bde2575ddc25c6040", + "receiptsRoot": "0x2e0617b0c3545d1668e8d8cb530a6c71b0a8f82875b1d0b38c352718016feff6", + "logsBloom": "0x00...00", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1b4", + "gasLimit": "0x1c9c380", + "gasUsed": "0xa410", + "timestamp": "0x6705D918", + "extraData": "0x746573745F6E616D65", + "baseFeePerGas": "0x7", + "excessBlobGas": "0x0", + "blobGasUsed": "0x0", + "transactions": [ + "0xf86c0a8504a817c80082520894...cb61163c917540a0c64c12b8f50015", + "0xf86b0f8504a817c80082520894...5443c01e69d3b0c5112101564914a2" + ], + "withdrawals": [], + "parentBeaconBlockRoot": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884365149a42212e8822" + } +} +``` \ No newline at end of file From fd7c82b2b978243492693af67839d375c3042b0e Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Mon, 17 Nov 2025 12:41:12 +0100 Subject: [PATCH 02/16] fix refs --- src/testing/testing_buildBlockV1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index a1757065d..32b829cf2 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -12,7 +12,7 @@ This method is considered sensitive and is intended for testing environments onl * `parentBlockHash`: `DATA, 32 Bytes` - (Required) The hash of the parent block upon which to build the new block. - * `payloadAttributes`: `OBJECT` - (Required) The `PayloadAttributesV3` object, as defined in [`engine_forkchoiceUpdated`](../engine-apis/forkchoiceUpdated.md#payloadattributesv3). + * `payloadAttributes`: `OBJECT` - (Required) The `PayloadAttributesV3` object, as defined in [`engine_forkchoiceUpdated`](../engine/cancun.md#payloadattributesv3). * `transactions`: `Array of DATA` - (Required) An array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. @@ -22,7 +22,7 @@ This method is considered sensitive and is intended for testing environments onl ### Returns -`result`: `OBJECT` - The constructed `ExecutionPayloadV3`, as defined in [`engine_getPayload`](../engine-apis/getPayload.md#executionpayloadv3). +`result`: `OBJECT` - The constructed `ExecutionPayloadV3`, as defined in [`engine_getPayload`](../engine/cancun.md#executionpayloadv3). ### Behavior @@ -112,4 +112,4 @@ This method is considered sensitive and is intended for testing environments onl "parentBeaconBlockRoot": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884365149a42212e8822" } } -``` \ No newline at end of file +``` From 30f28de4b8e6e674fd24439e57917bf161cdae4f Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Mon, 17 Nov 2025 12:58:04 +0100 Subject: [PATCH 03/16] fix response --- src/testing/testing_buildBlockV1.md | 57 +++++++++++++++++------------ 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 32b829cf2..3c3fd388f 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -12,7 +12,7 @@ This method is considered sensitive and is intended for testing environments onl * `parentBlockHash`: `DATA, 32 Bytes` - (Required) The hash of the parent block upon which to build the new block. - * `payloadAttributes`: `OBJECT` - (Required) The `PayloadAttributesV3` object, as defined in [`engine_forkchoiceUpdated`](../engine/cancun.md#payloadattributesv3). + * `payloadAttributes`: `OBJECT` - (Required) The [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) object, as defined in [`engine_forkchoiceUpdatedV3`](../engine/cancun.md#engine_forkchoiceupdatedv3). * `transactions`: `Array of DATA` - (Required) An array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. @@ -22,7 +22,7 @@ This method is considered sensitive and is intended for testing environments onl ### Returns -`result`: `OBJECT` - The constructed `ExecutionPayloadV3`, as defined in [`engine_getPayload`](../engine/cancun.md#executionpayloadv3). +`result`: `OBJECT` - The constructed object matching the response to [`engine_getPayloadV4`](../engine/prague.md#response-1). ### Behavior @@ -89,27 +89,38 @@ This method is considered sensitive and is intended for testing environments onl "id": 1, "jsonrpc": "2.0", "result": { - "blockHash": "0x8980a3a7f8b16053c4dec86e1050e6378e176272517852f8c5b56f34e9a0f9b6", - "parentHash": "0x3b8fb240d288781d4f1e1d32f4c1550BEEFDEADBEEFDEADBEEFDEADBEEFDEAD", - "feeRecipient": "0x0000000000000000000000000000000000000000", - "stateRoot": "0xca3699d05d3369680315af1d03c6f8f73188945f3c83756bde2575ddc25c6040", - "receiptsRoot": "0x2e0617b0c3545d1668e8d8cb530a6c71b0a8f82875b1d0b38c352718016feff6", - "logsBloom": "0x00...00", - "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", - "blockNumber": "0x1b4", - "gasLimit": "0x1c9c380", - "gasUsed": "0xa410", - "timestamp": "0x6705D918", - "extraData": "0x746573745F6E616D65", - "baseFeePerGas": "0x7", - "excessBlobGas": "0x0", - "blobGasUsed": "0x0", - "transactions": [ - "0xf86c0a8504a817c80082520894...cb61163c917540a0c64c12b8f50015", - "0xf86b0f8504a817c80082520894...5443c01e69d3b0c5112101564914a2" - ], - "withdrawals": [], - "parentBeaconBlockRoot": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884365149a42212e8822" + "executionPayload": { + "blockHash": "0x8980a3a7f8b16053c4dec86e1050e6378e176272517852f8c5b56f34e9a0f9b6", + "parentHash": "0x3b8fb240d288781d4f1e1d32f4c15509a2b7538b8e0e719541a50a31a2631a01", + "feeRecipient": "0x0000000000000000000000000000000000000000", + "stateRoot": "0xca3699d05d3369680315af1d03c6f8f73188945f3c83756bde2575ddc25c6040", + "receiptsRoot": "0x2e0617b0c3545d1668e8d8cb530a6c71b0a8f82875b1d0b38c352718016feff6", + "logsBloom": "0x00...00", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1b4", + "gasLimit": "0x1c9c380", + "gasUsed": "0xa410", + "timestamp": "0x6705D918", + "extraData": "0x746573745F6E616D65", + "baseFeePerGas": "0x7", + "excessBlobGas": "0x0", + "blobGasUsed": "0x0", + "transactions": [ + "0xf86c0a8504a817c80082520894...cb61163c917540a0c64c12b8f50015", + "0xf86b0f8504a817c80082520894...5443c01e69d3b0c5112101564914a2" + ], + "parentBeaconBlockRoot": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884365149a42212e8822", + "depositRequests": [], + "consolidationRequests": [] + }, + "blockValue": "0x1b681a965684000", + "blobsBundle": { + "commitments": [], + "blobs": [], + "kzgProofs": [] + }, + "shouldOverrideBuilder": false, + "executionRequests": [] } } ``` From 967fc4d12fe58c1ab9f981b55d5230c987a3c6d3 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Mon, 17 Nov 2025 13:01:12 +0100 Subject: [PATCH 04/16] fix ref --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 3c3fd388f..969a387a0 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -2,7 +2,7 @@ This document specifies the `testing_buildBlockV1` RPC method. This method is a debugging and testing tool that simplifies the block production process into a single call. It is intended to replace the multi-step workflow of sending transactions, calling `engine_forkchoiceUpdated` with `payloadAttributes`, and then calling `engine_getPayload`. -This method is considered sensitive and is intended for testing environments only. See **Security Considerations** for more details. +This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#securityconsiderations) for more details. ## Method: `testing_buildBlockV1` From e81918ae6bd455e6f3694bfde703493b22d29e40 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Mon, 17 Nov 2025 13:01:42 +0100 Subject: [PATCH 05/16] fix ref --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 969a387a0..48456449f 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -2,7 +2,7 @@ This document specifies the `testing_buildBlockV1` RPC method. This method is a debugging and testing tool that simplifies the block production process into a single call. It is intended to replace the multi-step workflow of sending transactions, calling `engine_forkchoiceUpdated` with `payloadAttributes`, and then calling `engine_getPayload`. -This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#securityconsiderations) for more details. +This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#security-considerations) for more details. ## Method: `testing_buildBlockV1` From 61698b4c26e6407b7db63127e75f86528d94babd Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:49:19 +0100 Subject: [PATCH 06/16] Simplify --- src/testing/testing_buildBlockV1.md | 38 ++++++++++++++--------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 48456449f..f54f352f5 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -4,42 +4,43 @@ This document specifies the `testing_buildBlockV1` RPC method. This method is a This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#security-considerations) for more details. -## Method: `testing_buildBlockV1` - -### Parameters +## Structures -1. `buildBlockParams`: `object` - An object containing the parameters for building the block: +### BuildBlockParamsV1 - * `parentBlockHash`: `DATA, 32 Bytes` - (Required) The hash of the parent block upon which to build the new block. +This structure encapsulates the params for building a block. The fields are encoded as follows: - * `payloadAttributes`: `OBJECT` - (Required) The [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) object, as defined in [`engine_forkchoiceUpdatedV3`](../engine/cancun.md#engine_forkchoiceupdatedv3). +- `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block +- `safeBlockHash`: `DATA`, 32 Bytes - the "safe" block hash of the canonical chain under certain synchrony and honesty assumptions. This value **MUST** be either equal to or an ancestor of `headBlockHash` +- `finalizedBlockHash`: `DATA`, 32 Bytes - block hash of the most recent finalized block - * `transactions`: `Array of DATA` - (Required) An array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. +## Method: `testing_buildBlockV1` - * `extraData`: `DATA, 0 to 32 Bytes` - (Optional) A hex-encoded `0x...` string to be set as the `extraData` field of the built block. If this field is provided, it MUST override any default `extraData` the client would normally insert. +### Request - * `skipValidation`: `boolean` - (Optional, default: `false`) If `true`, the client MUST attempt to build the block even if the provided transactions are invalid (e.g., incorrect nonce, insufficient balance, or invalid signature). If `false`, the method MUST return an error if any transaction fails state validation. +* method: `testing_buildBlockV1` +* params: + 1. `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block + 2. `payloadAttributes`: `Object` - instance of [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) + 3. `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) + 4. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block -### Returns +### Response `result`: `OBJECT` - The constructed object matching the response to [`engine_getPayloadV4`](../engine/prague.md#response-1). -### Behavior +### Specification * The client MUST build a new execution payload using the block specified by `parentBlockHash` as its parent. -* The client MUST use the provided `payloadAttributes` to define the context of the new block (e.g., `timestamp`, `prevRandao`, `suggestedFeeRecipient`). +* The client MUST use the provided `payloadAttributes` to define the context of the new block. -* The client MUST include all transactions from the `transactions` array at the beginning of the block's transaction list, in the order they were provided. +* The client MUST include all transactions from the `transactions` array on the block's transaction list, in the order they were provided. * The client MUST NOT include any transactions from its local transaction pool. The resulting block MUST only contain the transactions specified in the `transactions` array. * If `extraData` is provided, the client MUST set the `extraData` field of the resulting payload to this value. -* If `skipValidation` is `false` (or omitted), the client MUST validate all transactions in the `transactions` array against the state at the `parentBlockHash`. If any transaction is invalid, the method MUST return a standard JSON-RPC error. - -* If `skipValidation` is `true`, the client MUST skip state-dependent validation (e.g., nonce, balance) for the transactions in the `transactions` array. The client SHOULD still perform basic format validation. The client MUST attempt to build and return the payload, even if this payload would be considered invalid by consensus rules. - * This method MUST NOT modify the client's canonical chain or head block. It is a read-only method for payload generation. It does not run the equivalent of `engine_newPayload` or `engine_forkchoiceUpdated`. ### Security Considerations @@ -75,8 +76,7 @@ This method is considered sensitive and is intended for testing environments onl "0xf86c0a8504a817c80082520894...cb61163c917540a0c64c12b8f50015", "0xf86b0f8504a817c80082520894...5443c01e69d3b0c5112101564914a2" ], - "extraData": "0x746573745F6E616D65", - "skipValidation": false + "extraData": "0x746573745F6E616D65" } ] } From 72730583b9c74655b01dc2e81f664ea3865e358f Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:49:58 +0100 Subject: [PATCH 07/16] fix --- src/testing/testing_buildBlockV1.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index f54f352f5..aed5db4a9 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -4,16 +4,6 @@ This document specifies the `testing_buildBlockV1` RPC method. This method is a This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#security-considerations) for more details. -## Structures - -### BuildBlockParamsV1 - -This structure encapsulates the params for building a block. The fields are encoded as follows: - -- `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block -- `safeBlockHash`: `DATA`, 32 Bytes - the "safe" block hash of the canonical chain under certain synchrony and honesty assumptions. This value **MUST** be either equal to or an ancestor of `headBlockHash` -- `finalizedBlockHash`: `DATA`, 32 Bytes - block hash of the most recent finalized block - ## Method: `testing_buildBlockV1` ### Request From cadd123546540c8bcd1b1a59cec03a4398582755 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:51:21 +0100 Subject: [PATCH 08/16] simplify --- src/testing/testing_buildBlockV1.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index aed5db4a9..fd28954e6 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -4,8 +4,6 @@ This document specifies the `testing_buildBlockV1` RPC method. This method is a This method is considered sensitive and is intended for testing environments only. See [**Security Considerations**](#security-considerations) for more details. -## Method: `testing_buildBlockV1` - ### Request * method: `testing_buildBlockV1` From 41855df6c9b5a92c7ff055d4b9ea1e231cf2099f Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 11:55:44 +0100 Subject: [PATCH 09/16] fix --- src/testing/testing_buildBlockV1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index fd28954e6..612477c88 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -10,8 +10,8 @@ This method is considered sensitive and is intended for testing environments onl * params: 1. `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block 2. `payloadAttributes`: `Object` - instance of [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) - 3. `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) - 4. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block + 3. `transactions`: `Array of DATA` - an array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block + 5. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block ### Response From 519429bda07764568809b484ef02bc7a76a92233 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 12:03:02 +0100 Subject: [PATCH 10/16] nitpicks --- src/testing/testing_buildBlockV1.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 612477c88..6b8924758 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -8,14 +8,15 @@ This method is considered sensitive and is intended for testing environments onl * method: `testing_buildBlockV1` * params: - 1. `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block - 2. `payloadAttributes`: `Object` - instance of [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) - 3. `transactions`: `Array of DATA` - an array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block - 5. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block + 1. `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block. + 2. `payloadAttributes`: `Object` - instance of [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) + 3. `transactions`: `Array of DATA` - an array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. + 5. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block. ### Response -`result`: `OBJECT` - The constructed object matching the response to [`engine_getPayloadV4`](../engine/prague.md#response-1). +* `result`: `OBJECT` - instance of [`engine_getPayloadV4`](../engine/prague.md#response-1) +* error: code and message set in case an exception happens while building the requeste block. ### Specification From 895812499a5c0870aa8731cedb0b6d23b1ca2840 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Tue, 18 Nov 2025 12:04:27 +0100 Subject: [PATCH 11/16] cosmetics --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 6b8924758..558a33a1e 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -15,7 +15,7 @@ This method is considered sensitive and is intended for testing environments onl ### Response -* `result`: `OBJECT` - instance of [`engine_getPayloadV4`](../engine/prague.md#response-1) +* result: `OBJECT` - instance of [`engine_getPayloadV4`](../engine/prague.md#response-1) * error: code and message set in case an exception happens while building the requeste block. ### Specification From bb72039c01fa55eb21bc46ea8ccd0801948e855e Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Wed, 19 Nov 2025 15:05:37 +0100 Subject: [PATCH 12/16] fix --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 558a33a1e..70c826da9 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -36,7 +36,7 @@ This method is considered sensitive and is intended for testing environments onl * **HIGHLY SENSITIVE**: This method is a powerful debugging tool intended for testing environments ONLY. -* It allows for the creation of arbitrary, and potentially invalid, blocks. It can be in used to bypass transaction pool validation and forcibly include any transaction. +* It allows for the creation of arbitrary blocks. It can be in used to bypass transaction pool validation and forcibly include any transaction. * This method MUST NOT be exposed on public-facing RPC APIs. From 27981321adcf4217d1c8aecd87fae6e607c86020 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Wed, 19 Nov 2025 15:07:00 +0100 Subject: [PATCH 13/16] typo --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 70c826da9..2f5a004c2 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -16,7 +16,7 @@ This method is considered sensitive and is intended for testing environments onl ### Response * result: `OBJECT` - instance of [`engine_getPayloadV4`](../engine/prague.md#response-1) -* error: code and message set in case an exception happens while building the requeste block. +* error: code and message set in case an exception happens while building the requested block. ### Specification From 20b3be1e2edce557514d697c0fd2284c81bd6db6 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Wed, 19 Nov 2025 15:09:04 +0100 Subject: [PATCH 14/16] concretizy --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index 2f5a004c2..a1b8eac0d 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -36,7 +36,7 @@ This method is considered sensitive and is intended for testing environments onl * **HIGHLY SENSITIVE**: This method is a powerful debugging tool intended for testing environments ONLY. -* It allows for the creation of arbitrary blocks. It can be in used to bypass transaction pool validation and forcibly include any transaction. +* It allows for the creation of arbitrary blocks. It can be in used to forcibly include any valid transaction. * This method MUST NOT be exposed on public-facing RPC APIs. From b73f3813f5b01958e46ad42a40711a3408384f58 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:37:24 +0100 Subject: [PATCH 15/16] Update response to fusaka --- src/testing/testing_buildBlockV1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index a1b8eac0d..e34652b34 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -15,7 +15,7 @@ This method is considered sensitive and is intended for testing environments onl ### Response -* result: `OBJECT` - instance of [`engine_getPayloadV4`](../engine/prague.md#response-1) +* result: `OBJECT` - instance of [`engine_getPayloadV5`](../engine/osaka.md#response) * error: code and message set in case an exception happens while building the requested block. ### Specification From 3c2c6730850df2c4ab6c8c2134f6503523967008 Mon Sep 17 00:00:00 2001 From: Marcin Sobczak <77129288+marcindsobczak@users.noreply.github.com> Date: Thu, 4 Dec 2025 16:27:27 +0100 Subject: [PATCH 16/16] cosmetics --- src/testing/testing_buildBlockV1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/testing/testing_buildBlockV1.md b/src/testing/testing_buildBlockV1.md index e34652b34..c24a45a38 100644 --- a/src/testing/testing_buildBlockV1.md +++ b/src/testing/testing_buildBlockV1.md @@ -11,7 +11,7 @@ This method is considered sensitive and is intended for testing environments onl 1. `parentBlockHash`: `DATA`, 32 Bytes - block hash of the parent of the requested block. 2. `payloadAttributes`: `Object` - instance of [`PayloadAttributesV3`](../engine/cancun.md#payloadattributesv3) 3. `transactions`: `Array of DATA` - an array of raw, signed transactions (hex-encoded `0x...` strings) to forcibly include in the generated block. - 5. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block. + 4. `extraData`: `DATA|null`, 0 to 32 Bytes - data to be set as the `extraData` field of the built block. ### Response @@ -30,7 +30,7 @@ This method is considered sensitive and is intended for testing environments onl * If `extraData` is provided, the client MUST set the `extraData` field of the resulting payload to this value. -* This method MUST NOT modify the client's canonical chain or head block. It is a read-only method for payload generation. It does not run the equivalent of `engine_newPayload` or `engine_forkchoiceUpdated`. +* This method MUST NOT modify the client's canonical chain or head block. It is a read-only method for payload generation. ### Security Considerations