Add initial FOCIL spec

src/engine/bogota.md

@@ -0,0 +1,179 @@
+# 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
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Constants](#constants)
+- [Structures](#structures)
+  - [PayloadAttributesV5](#payloadattributesv5)
+  - [PayloadStatusV2](#payloadstatusv2)
+- [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)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 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).
+
+### PayloadStatusV2
+
+This structure has the syntax of `PayloadStatusV1` and appends a single field: `inclusionListSatisfied`
+
+- `status`: `enum` - `"VALID" | "INVALID" | "SYNCING" | "ACCEPTED"`
+- `latestValidHash`: `DATA|null`, 32 Bytes - the hash of the most recent *valid* block in the branch defined by payload and its ancestors
+- `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID`.
+- `inclusionListSatisfied`: `BOOLEAN|null` - whether the payload satisfied the inclusion list constraints if it is deemed `VALID`; `null` otherwise.
+
+## 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 **MUST** 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: [`PayloadStatusV2`](#payloadstatusv2)
+* 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** set `inclusionListSatisfied` in the following way:
+
+    1. If the payload is deemed `VALID`, `inclusionListSatisfied` **MUST** be set to whether the payload satisfied the inclusion list constraints.
+
+    2. Otherwise, `inclusionListSatisfied` **MUST** be `null`.
+
+3. Client software **MUST** retain `inclusionListTransactions` for a payload with `ACCEPTED` status. Client software **MAY** discard them once the payload is no longer the tip of a branch. Client software **MUST** use the retained `inclusionListTransactions` if it later checks whether the payload satisfies the inclusion list constraints.
+
+### 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
+
+* result: `object`
+  - `payloadStatus`: [`PayloadStatusV2`](#payloadstatusv2), with the same `status` value restrictions as [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4).
+  - `payloadId`: `DATA|null`, 8 Bytes - identifier of the payload build process or `null`
+* error: code and message set in case an exception happens while the validating payload, updating the forkchoice or initiating the payload build process.
+
+#### 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.
+
+2. Extend point (9) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining `payloadStatus.inclusionListSatisfied`:
+
+    1. If the payload referenced by `forkchoiceState.headBlockHash` is deemed `VALID`, `payloadStatus.inclusionListSatisfied` **MUST** be set to whether the payload satisfied the inclusion list constraints.
+
+    2. Otherwise, `payloadStatus.inclusionListSatisfied` **MUST** be `null`.
+
+### 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.

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/ForkchoiceUpdatedResponseV2'
+  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

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

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/PayloadStatusV2'
+  errors:
+    - code: -32602
+      message: Invalid params
+    - code: -38005
+      message: Unsupported fork
 - name: engine_getPayloadV6
   summary: Obtains execution payload from payload build process
   externalDocs:

src/engine/openrpc/schemas/forkchoice.yaml

@@ -16,7 +16,7 @@ ForkchoiceStateV1:
       title: Finalized block hash
       $ref: '#/components/schemas/hash32'
 ForkchoiceUpdatedResponseV1:
-  title: Forkchoice updated response
+  title: Forkchoice updated response object V1
   type: object
   required:
     - payloadStatus
@@ -27,6 +27,18 @@ ForkchoiceUpdatedResponseV1:
     payloadId:
       title: Payload id
       $ref: '#/components/schemas/bytes8'
+ForkchoiceUpdatedResponseV2:
+  title: Forkchoice updated response object V2
+  type: object
+  required:
+    - payloadStatus
+  properties:
+    payloadStatus:
+      title: Payload status
+      $ref: '#/components/schemas/PayloadStatusV2'
+    payloadId:
+      title: Payload id
+      $ref: '#/components/schemas/bytes8'
 PayloadAttributesV1:
   title: Payload attributes object V1
   type: object
@@ -113,3 +125,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'

src/engine/openrpc/schemas/payload.yaml

@@ -48,6 +48,21 @@ PayloadStatusNoInvalidBlockHash:
       $ref: '#/components/schemas/PayloadStatusV1/properties/latestValidHash'
     validationError:
       $ref: '#/components/schemas/PayloadStatusV1/properties/validationError'
+PayloadStatusV2:
+  $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash'
+  title: Payload status object V2
+  properties:
+    status:
+      $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/status'
+    latestValidHash:
+      $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/latestValidHash'
+    validationError:
+      $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/validationError'
+    inclusionListSatisfied:
+      title: Whether the payload satisfied the inclusion list constraints
+      oneOf:
+        - type: boolean
+        - type: 'null'
 ExecutionPayloadV1:
   title: Execution payload object V1
   type: object

wordlist.txt

@@ -46,6 +46,8 @@ FP
 getblobsbundlev
 getblobsv
 getclientversionv
+getinclusionlistv
+getInclusionListV
 graphql
 gwei
 https