diff --git a/src/engine/bogota.md b/src/engine/bogota.md new file mode 100644 index 000000000..f27dfbe6b --- /dev/null +++ b/src/engine/bogota.md @@ -0,0 +1,159 @@ +# Engine API -- Bogota + +Engine API changes introduced in Bogota. + +This specification is based on and extends [Engine API - Amsterdam](./amsterdam.md) specification. + +## Table of contents + + + + +- [Constants](#constants) +- [Structures](#structures) + - [PayloadAttributesV5](#payloadattributesv5) +- [Routines](#routines) + - [Payload building](#payload-building) +- [Methods](#methods) + - [engine_newPayloadV6](#engine_newpayloadv6) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + - [engine_getInclusionListV1](#engine_getinclusionlistv1) + - [Request](#request-1) + - [Response](#response-1) + - [Specification](#specification-1) + - [engine_forkchoiceUpdatedV5](#engine_forkchoiceupdatedv5) + - [Request](#request-2) + - [Response](#response-2) + - [Specification](#specification-2) + - [Update the methods of previous forks](#update-the-methods-of-previous-forks) + - [Amsterdam API](#amsterdam-api) + + + +## Constants + +| Name | Value | +| - | - | +| `MAX_BYTES_PER_INCLUSION_LIST` | `uint64(8192) = 2**13` | + +## Structures + +### PayloadAttributesV5 + +This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloadattributesv4) and appends a single field: `inclusionListTransactions`. + +- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload +- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload +- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload +- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. +- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. +- `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload +- `targetGasLimit`: `QUANTITY`, 64 Bits - target value for the `gasLimit` field of the new payload +- `inclusionListTransactions`: `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). + +## Routines + +### Payload building + +This routine follows the same specification as [Payload building](./paris.md#payload-building) with the following changes to the processing flow: + +1. Client software **SHOULD** take `inclusionListTransactions` into account during the payload build process. The built `ExecutionPayload` **MUST** satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). + +## Methods + +### engine_newPayloadV6 + +Method parameter list is extended with `inclusionListTransactions`. + +#### Request + +* method: `engine_newPayloadV6` +* params: + 1. `executionPayload`: [`ExecutionPayloadV4`](./amsterdam.md#executionpayloadv4). + 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. Each list element is a `requests` byte array as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). The first byte of each element is the `request_type` and the remaining bytes are the `request_data`. Elements of the list **MUST** be ordered by `request_type` in ascending order. Elements with empty `request_data` **MUST** be excluded from the list. + 5. `inclusionListTransactions`: `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). + +#### Response + +* result: [`PayloadStatusV1`](./paris.md#payloadstatusv1), values of the `status` field are modified in the following way: + - `INCLUSION_LIST_UNSATISFIED` status value is appended. +* error: code and message set in case an exception happens while processing the payload. + +#### Specification + +This method follows the same specification as [`engine_newPayloadV5`](./amsterdam.md#engine_newpayloadv5) with the following changes: + +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Bogota fork. + +2. Client software **MUST** return `{status: INCLUSION_LIST_UNSATISFIED, latestValidHash: null, validationError: null}` if `executionPayload` passed [payload validation](./paris.md#payload-validation) process and deemed `VALID` but fails to satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). + +### engine_getInclusionListV1 + +#### Request + +* method: `engine_getInclusionListV1` +* params: + 1. `blockHash`: `DATA`, 32 Bytes - block hash of the block upon which the inclusion list should be built. + +* timeout: 1s + +#### Response + +* result: `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). +* error: code and message set in case an exception happens while getting the inclusion list. + +#### Specification + +1. Client software **MUST** return `-38001: Unknown payload` error if a block with the given `blockHash` does not exist. + +2. Client software **MUST** provide a list of transactions for the inclusion list based on the local view of the mempool. The strategy for selecting which transactions to include is implementation dependent. + +3. Client software **MUST** ensure the byte length of the RLP encoding of the returned transaction list does not exceed `MAX_BYTES_PER_INCLUSION_LIST`. + +4. Client software **MUST NOT** include any [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) in the returned transaction list. + +### engine_forkchoiceUpdatedV5 + +#### Request + +* method: `engine_forkchoiceUpdatedV5` +* params: + 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#forkchoicestatev1). + 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV5`](#payloadattributesv5) or `null`. + 3. `custodyColumns`: `DATA|null`, 16 Bytes - Interpreted as a bitarray of length `CELLS_PER_EXT_BLOB` indicating which column indices form the CL's custody set, or `null` if the CL does not provide custody services. +* timeout: 8s + +#### Response + +Refer to the response for [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4). + +#### Specification + +This method follows the same specification as [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4) with the following changes to the processing flow: + +1. Extend point (8) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining the following sequence of checks that **MUST** be run over `payloadAttributes`: + + 1. `payloadAttributes` matches the [`PayloadAttributesV5`](#payloadattributesv5) structure, return `-38003: Invalid payload attributes` on failure. + + 2. `payloadAttributes.timestamp` does not fall within the time frame of the Bogota fork, return `-38005: Unsupported fork` on failure. + + 3. `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by `forkchoiceState.headBlockHash`, return `-38003: Invalid payload attributes` on failure. + + 4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled back. + +### Update the methods of previous forks + +#### Amsterdam API + +For the following methods: + +- [`engine_newPayloadV5`](./amsterdam.md#engine_newpayloadv5) +- [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4) + +a validation **MUST** be added: + +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload is greater than or equal to the Bogota activation timestamp. diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index ce3de624a..30e6c8e70 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/src/engine/openrpc/methods/forkchoice.yaml @@ -196,3 +196,38 @@ message: Unsupported fork - code: -38006 message: Too deep reorg +- name: engine_forkchoiceUpdatedV5 + summary: Updates the forkchoice state + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_forkchoiceupdatedv5 + params: + - name: Forkchoice state + required: true + schema: + $ref: '#/components/schemas/ForkchoiceStateV1' + - name: Payload attributes + required: false + schema: + $ref: '#/components/schemas/PayloadAttributesV5' + - name: Custody columns + required: false + schema: + oneOf: + - $ref: '#/components/schemas/bytes16' + - type: 'null' + result: + name: Response object + schema: + $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1' + errors: + - code: -38002 + message: Invalid forkchoice state + - code: -38003 + message: Invalid payload attributes + - code: -32602 + message: Invalid params + - code: -38005 + message: Unsupported fork + - code: -38006 + message: Too deep reorg diff --git a/src/engine/openrpc/methods/inclusion_list.yaml b/src/engine/openrpc/methods/inclusion_list.yaml new file mode 100644 index 000000000..00420821c --- /dev/null +++ b/src/engine/openrpc/methods/inclusion_list.yaml @@ -0,0 +1,19 @@ +- name: engine_getInclusionListV1 + summary: Obtains an inclusion list built upon the given block hash + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_getinclusionlistv1 + params: + - name: Block hash + required: true + schema: + $ref: '#/components/schemas/hash32' + result: + name: Inclusion list transactions + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + errors: + - code: -38001 + message: Unknown payload diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 7335ae4ad..757ffe68a 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -1070,6 +1070,47 @@ status: VALID latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' validationError: null +- name: engine_newPayloadV6 + summary: Runs execution payload validation + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_newpayloadv6 + params: + - name: Execution payload + required: true + schema: + $ref: '#/components/schemas/ExecutionPayloadV4' + - name: Expected blob versioned hashes + required: true + schema: + type: array + items: + $ref: '#/components/schemas/hash32' + - name: Parent beacon block root + required: true + schema: + $ref: '#/components/schemas/hash32' + - name: Execution requests + required: true + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + - name: Inclusion list transactions + required: true + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + result: + name: Payload status + schema: + $ref: '#/components/schemas/PayloadStatusInclusionListUnsatisfied' + errors: + - code: -32602 + message: Invalid params + - code: -38005 + message: Unsupported fork - name: engine_getPayloadV6 summary: Obtains execution payload from payload build process externalDocs: diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index af9f7d067..b893deb93 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/src/engine/openrpc/schemas/forkchoice.yaml @@ -113,3 +113,35 @@ PayloadAttributesV4: targetGasLimit: title: Target gas limit $ref: '#/components/schemas/uint64' +PayloadAttributesV5: + title: Payload attributes object V5 + type: object + required: + - timestamp + - prevRandao + - suggestedFeeRecipient + - withdrawals + - parentBeaconBlockRoot + - slotNumber + - targetGasLimit + - inclusionListTransactions + properties: + timestamp: + $ref: '#/components/schemas/PayloadAttributesV4/properties/timestamp' + prevRandao: + $ref: '#/components/schemas/PayloadAttributesV4/properties/prevRandao' + suggestedFeeRecipient: + $ref: '#/components/schemas/PayloadAttributesV4/properties/suggestedFeeRecipient' + withdrawals: + $ref: '#/components/schemas/PayloadAttributesV4/properties/withdrawals' + parentBeaconBlockRoot: + $ref: '#/components/schemas/PayloadAttributesV4/properties/parentBeaconBlockRoot' + slotNumber: + $ref: '#/components/schemas/PayloadAttributesV4/properties/slotNumber' + targetGasLimit: + $ref: '#/components/schemas/PayloadAttributesV4/properties/targetGasLimit' + inclusionListTransactions: + title: Inclusion list transactions + type: array + items: + $ref: '#/components/schemas/bytes' diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 182e2ce40..eb80f4215 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -48,6 +48,22 @@ PayloadStatusNoInvalidBlockHash: $ref: '#/components/schemas/PayloadStatusV1/properties/latestValidHash' validationError: $ref: '#/components/schemas/PayloadStatusV1/properties/validationError' +PayloadStatusInclusionListUnsatisfied: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash' + title: Payload status object appending INCLUSION_LIST_UNSATISFIED status + properties: + status: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/status' + enum: + - VALID + - INVALID + - SYNCING + - ACCEPTED + - INCLUSION_LIST_UNSATISFIED + latestValidHash: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/latestValidHash' + validationError: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/validationError' ExecutionPayloadV1: title: Execution payload object V1 type: object diff --git a/wordlist.txt b/wordlist.txt index 0120c9686..e91e1b8c7 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -46,6 +46,8 @@ FP getblobsbundlev getblobsv getclientversionv +getinclusionlistv +getInclusionListV graphql gwei https