Skip to content

Update EIP-7928: Move Block Access List outside ExecutionPayload #720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nerolation wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update EIP-7928: Move Block Access List outside ExecutionPayload #720

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c5710d
Update EIP-7928: Move BAL from payload
nerolation Dec 11, 2025
f9128d9
clean up
nerolation Dec 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 9 additions & 34 deletions src/engine/amsterdam.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Structures](#structures)
- [ExecutionPayloadV4](#executionpayloadv4)
- [Methods](#methods)
- [engine_newPayloadV5](#engine_newpayloadv5)
- [Request](#request)
Expand All @@ -25,45 +23,21 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec

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

## Structures

### ExecutionPayloadV4

This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
- `stateRoot`: `DATA`, 32 Bytes
- `receiptsRoot`: `DATA`, 32 Bytes
- `logsBloom`: `DATA`, 256 Bytes
- `prevRandao`: `DATA`, 32 Bytes
- `blockNumber`: `QUANTITY`, 64 Bits
- `gasLimit`: `QUANTITY`, 64 Bits
- `gasUsed`: `QUANTITY`, 64 Bits
- `timestamp`: `QUANTITY`, 64 Bits
- `extraData`: `DATA`, 0 to 32 Bytes
- `baseFeePerGas`: `QUANTITY`, 256 Bits
- `blockHash`: `DATA`, 32 Bytes
- `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.
- `blobGasUsed`: `QUANTITY`, 64 Bits
- `excessBlobGas`: `QUANTITY`, 64 Bits
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)

## Methods

### engine_newPayloadV5

This method is updated to support the new `ExecutionPayloadV4` structure.
This method supports the `ExecutionPayloadV3` structure and block access list validation.

#### Request

* method: `engine_newPayloadV5`
* params:
1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4).
1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests.
5. `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)

#### Response

Expand All @@ -75,14 +49,14 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m

1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Amsterdam activation.

2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` field is missing.
2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` parameter is missing or not provided as the 5th parameter.

3. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one.
3. Client software **MUST** validate the `blockAccessList` parameter by executing the payload's transactions and verifying that the computed access list matches the provided one.
If this validation fails, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.

### engine_getPayloadV6

This method is updated to return the new `ExecutionPayloadV4` structure.
This method returns the `ExecutionPayloadV3` structure and block access list.

#### Request

Expand All @@ -94,11 +68,12 @@ This method is updated to return the new `ExecutionPayloadV4` structure.
#### Response

* result: `object`
- `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4)
- `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3)
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
- `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload`
- `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
- `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution.
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)
* error: code and message set in case an exception happens while getting the payload.

#### Specification
Expand All @@ -107,7 +82,7 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md

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 Amsterdam activation.

2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list.
2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and return the RLP-encoded access list in the `blockAccessList` field of the response.

### Update the methods of previous forks

Expand Down
45 changes: 11 additions & 34 deletions src/engine/eip7928.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Structures](#structures)
- [ExecutionPayloadV4](#executionpayloadv4)
- [Methods](#methods)
- [engine_newPayloadV5](#engine_newpayloadv5)
- [Request](#request)
Expand All @@ -25,45 +23,21 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec

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

## Structures

### ExecutionPayloadV4

This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
- `stateRoot`: `DATA`, 32 Bytes
- `receiptsRoot`: `DATA`, 32 Bytes
- `logsBloom`: `DATA`, 256 Bytes
- `prevRandao`: `DATA`, 32 Bytes
- `blockNumber`: `QUANTITY`, 64 Bits
- `gasLimit`: `QUANTITY`, 64 Bits
- `gasUsed`: `QUANTITY`, 64 Bits
- `timestamp`: `QUANTITY`, 64 Bits
- `extraData`: `DATA`, 0 to 32 Bytes
- `baseFeePerGas`: `QUANTITY`, 256 Bits
- `blockHash`: `DATA`, 32 Bytes
- `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.
- `blobGasUsed`: `QUANTITY`, 64 Bits
- `excessBlobGas`: `QUANTITY`, 64 Bits
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)

## Methods

### engine_newPayloadV5

This method is updated to support the new `ExecutionPayloadV4` structure.
This method supports the `ExecutionPayloadV3` structure and block access list validation.

#### Request

* method: `engine_newPayloadV5`
* params:
1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4).
1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests.
5. `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)

#### Response

Expand All @@ -75,13 +49,15 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m

1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the EIP-7928 activation.

2. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one.
2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` parameter is missing or not provided as the 5th parameter.

3. Client software **MUST** validate the `blockAccessList` parameter by executing the payload's transactions and verifying that the computed access list matches the provided one.

3. If the `blockAccessList` field is missing, malformed, or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.
4. If the `blockAccessList` parameter is malformed or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.

### engine_getPayloadV6

This method is updated to return the new `ExecutionPayloadV4` structure.
This method returns the `ExecutionPayloadV3` structure and block access list.

#### Request

Expand All @@ -93,11 +69,12 @@ This method is updated to return the new `ExecutionPayloadV4` structure.
#### Response

* result: `object`
- `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4)
- `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3)
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
- `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload`
- `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
- `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution.
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)
* error: code and message set in case an exception happens while getting the payload.

#### Specification
Expand All @@ -106,7 +83,7 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md

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 EIP-7928 activation.

2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list.
2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and return the RLP-encoded access list in the `blockAccessList` field of the response.

### Update the methods of previous forks

Expand Down
16 changes: 12 additions & 4 deletions src/engine/openrpc/methods/payload.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -895,7 +895,7 @@
- name: Execution payload
required: true
schema:
$ref: '#/components/schemas/ExecutionPayloadV4'
$ref: '#/components/schemas/ExecutionPayloadV3'
- name: Expected blob versioned hashes
required: true
schema:
Expand All @@ -912,6 +912,10 @@
type: array
items:
$ref: '#/components/schemas/bytes'
- name: Block access list
required: true
schema:
$ref: '#/components/schemas/bytes'
result:
name: Payload status
schema:
Expand Down Expand Up @@ -954,7 +958,6 @@
amount: '0x1'
blobGasUsed: '0x20000'
excessBlobGas: '0x0'
blockAccessList: '0xf90244f90241f8f79400000000000000000000000000000000000001f8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000001f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000100c22180a00000000000000000000000000000000000000000000000000000000000000200c780c22180c680c221890056bc75e2d63100000c080c22180f90145f90142f8f794a94f5374fce5edbc8e2a8697c15331677e6ebf0bf8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000100f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000200c22180a00000000000000000000000000000000000000000000000000000000000000300c780c22180c680c2218901152d02c7e14af680c080c22180'
- name: Expected blob versioned hashes
value:
- '0x000657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014'
Expand All @@ -964,6 +967,8 @@
value:
- '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef20100000000000000b1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9f000000000000000a5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca01000000000000009561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1f100000000000000'
- '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0000000000000000000000000000000000000000000000000000010f698daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a75530100000000000000'
- name: Block access list
value: '0xf90244f90241f8f79400000000000000000000000000000000000001f8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000001f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000100c22180a00000000000000000000000000000000000000000000000000000000000000200c780c22180c680c221890056bc75e2d63100000c080c22180f90145f90142f8f794a94f5374fce5edbc8e2a8697c15331677e6ebf0bf8e8f843a00000000000000000000000000000000000000000000000000000000000000000f838c22080a00000000000000000000000000000000000000000000000000000000000000000c22180a00000000000000000000000000000000000000000000000000000000000000100f843a00000000000000000000000000000000000000000000000000000000000000001f838c22080a00000000000000000000000000000000000000000000000000000000000000200c22180a00000000000000000000000000000000000000000000000000000000000000300c780c22180c680c2218901152d02c7e14af680c080c22180'
result:
name: Payload status
value:
Expand All @@ -990,9 +995,10 @@
- blobsBundle
- shouldOverrideBuilder
- executionRequests
- blockAccessList
properties:
executionPayload:
$ref: '#/components/schemas/ExecutionPayloadV4'
$ref: '#/components/schemas/ExecutionPayloadV3'
blockValue:
$ref: '#/components/schemas/uint256'
blobsBundle:
Expand All @@ -1003,6 +1009,8 @@
type: array
items:
$ref: '#/components/schemas/bytes'
blockAccessList:
$ref: '#/components/schemas/bytes'
errors:
- code: -38001
message: Unknown payload
Expand Down Expand Up @@ -1053,7 +1061,6 @@
amount: '0x1'
blobGasUsed: '0x60000'
excessBlobGas: '0x0'
blockAccessList: '0xc0'
blockValue: '0x10a741a46278014d'
blobsBundle:
commitments:
Expand All @@ -1066,3 +1073,4 @@
executionRequests:
- '0x96a96086cff07df17668f35f7418ef8798079167e3f4f9b72ecde17b28226137cf454ab1dd20ef5d924786ab3483c2f9003f5102dabe0a27b1746098d1dc17a5d3fbd478759fea9287e4e419b3c3cef20100000000000000b1acdb2c4d3df3f1b8d3bfd33421660df358d84d78d16c4603551935f4b67643373e7eb63dcb16ec359be0ec41fee33b03a16e80745f2374ff1d3c352508ac5d857c6476d3c3bcf7e6ca37427c9209f17be3af5264c0e2132b3dd1156c28b4e9f000000000000000a5c85a60ba2905c215f6a12872e62b1ee037051364244043a5f639aa81b04a204c55e7cc851f29c7c183be253ea1510b001db70c485b6264692f26b8aeaab5b0c384180df8e2184a21a808a3ec8e86ca01000000000000009561731785b48cf1886412234531e4940064584463e96ac63a1a154320227e333fb51addc4a89b7e0d3f862d7c1fd4ea03bd8eb3d8806f1e7daf591cbbbb92b0beb74d13c01617f22c5026b4f9f9f294a8a7c32db895de3b01bee0132c9209e1f100000000000000'
- '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b85103a5617937691dfeeb89b86a80d5dc9e3c9d3a1a0e7ce311e26e0bb732eabaa47ffa288f0d54de28209a62a7d29d0000000000000000000000000000000000000000000000000000010f698daeed734da114470da559bd4b4c7259e1f7952555241dcbc90cf194a2ef676fc6005f3672fada2a3645edb297a75530100000000000000'
blockAccessList: '0xc0'
Loading
Loading