further changes to Cancun spec for 4788

src/engine/experimental/blob-extension.md → src/engine/cancun.md

@@ -1,33 +1,35 @@
+# Engine API -- Cancun
+
+Engine API changes introduced in Cancun.
+
+This specificaiton is based on and extends [Engine API - Shanghai](./shanghai.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 -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Shard Blob Extension](#shard-blob-extension)
-  - [Structures](#structures)
-    - [ExecutionPayloadV3](#executionpayloadv3)
-    - [BlobsBundleV1](#blobsbundlev1)
-  - [Methods](#methods)
-    - [engine_newPayloadV3](#engine_newpayloadv3)
-      - [Request](#request)
-      - [Response](#response)
-      - [Specification](#specification)
-    - [engine_getPayloadV3](#engine_getpayloadv3)
-      - [Request](#request-1)
-      - [Response](#response-1)
-      - [Specification](#specification-1)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-# Shard Blob Extension
+- [Structures](#structures)
+  - [ExecutionPayloadV3](#executionpayloadv3)
+  - [BlobsBundleV1](#blobsbundlev1)
+- [Methods](#methods)
+  - [engine_newPayloadV3](#engine_newpayloadv3)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_getPayloadV3](#engine_getpayloadv3)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+  - [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1)
 
-This is an extension specific to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) to the structures and methods as defined in the [Engine API - Paris](../paris.md) and [Engine API - Shanghai](../shanghai.md).
-This extension is backwards-compatible, but not part of the initial Engine API.
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Structures
 
 ### ExecutionPayloadV3
 
-This structure has the syntax of `ExecutionPayloadV2` and append two new fields: `dataGasUsed` and `excessDataGas`.
+This structure has the syntax of [`ExecutionPayloadV2`](./shanghai.md#executionpayloadv2) and append two new fields: `dataGasUsed` and `excessDataGas`.
 
 - `parentHash`: `DATA`, 32 Bytes
 - `feeRecipient`:  `DATA`, 20 Bytes
@@ -46,6 +48,7 @@ This structure has the syntax of `ExecutionPayloadV2` and append two new fields:
 - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
 - `dataGasUsed`: `QUANTITY`, 64 bits
 - `excessDataGas`: `QUANTITY`, 64 Bits
+- `parentBeaconBlockRoot`: `DATA`, 32 Bytes
 
 ### BlobsBundleV1
 
@@ -72,19 +75,19 @@ Client software **MUST** return `-32602: Invalid params` error unless all parame
 
 #### Response
 
-Refer to the response for `engine_newPayloadV2`.
+Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2).
 
 #### Specification
 
-This method follows the same specification as `engine_newPayloadV2` with the addition of the following:
+This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following:
 
 1. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps:
     1. Obtain an actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`.
     2. Return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}` if the expected and the actual arrays don't match.
 
     This validation **MUST** be instantly run in all cases even during active sync process.
 
-2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the EIP-4844 activation timestamp.
+2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp.
 
 ### engine_getPayloadV3
 
@@ -108,13 +111,23 @@ and proofs corresponding to the `versioned_hashes` included in the blob transact
 
 #### Specification
 
-Refer to the specification for `engine_getPayloadV2` with addition of the following:
+Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with addition of the following:
 
-1. The call **MUST** return empty `blobs`, `commitments` and `proofs` if the paylaod doesn't contain any blob transactions.
+1. The call **MUST** return `blobsBundle` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions.
 
 2. The call **MUST** return `commitments` matching the versioned hashes of the transactions list of the execution payload, in the same order,
-   i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, bundle.commitments)` (see EIP-4844 consensus-specs).
+   i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, blobsBundle.commitments)` (see EIP-4844 consensus-specs).
+
+3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(blobsBundle.commitments) == len(blobsBundle.blobs) == len(blobsBundle.proofs)` and `assert verify_blob_kzg_proof_batch(blobsBundle.blobs, blobsBundle.commitments, blobsBundle.proofs)`.
+
+4. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the Cancun activation timestamp.
+
+### Deprecate `engine_exchangeTransitionConfigurationV1`
+
+This document introduces deprecation of [`engine_exchangeTransitionConfigurationV1`](./paris.md#engine_exchangetransitionconfigurationv1). The deprecation is specified as follows:
+
+1. Consensus layer clients **MUST NOT** call this method.
 
-3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(commitments) == len(blobs) == len(proofs)` and `assert verify_blob_kzg_proof_batch(bundle.blobs, bundle.commitments, bundle.proofs)`.
+2. Execution layer clients **MUST NOT** surface an error message to the user if this method is not called.
 
-4. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the EIP-4844 activation timestamp.
+3. Consensus and execution layer clients **MAY** remove support of this method after Cancun. If no longer supported, this method **MUST** be removed from the [`engine_exchangeCapabilities`](./common.md#engine_exchangecapabilities) request or response list depending on whether it is consensus or execution layer client.

src/engine/openrpc/methods/payload.yaml

@@ -31,6 +31,31 @@
   errors:
     - code: -32602
       message: Invalid params
+- name: engine_newPayloadV3
+  summary: Runs execution payload validation
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_newpayloadv3
+  params:
+    - name: Execution payload
+      required: true
+      schema:
+        $ref: '#/components/schemas/ExecutionPayloadV3'
+    - name: Blob versioned hashes
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '#/components/schemas/hash32'
+  result:
+    name: Payload status
+    schema:
+      $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash'
+  errors:
+    - code: -32602
+      message: Invalid params
+    - code: -38005
+      message: Unsupported fork
 - name: engine_getPayloadV1
   summary: Obtains execution payload from payload build process
   externalDocs:
@@ -77,6 +102,39 @@
   errors:
     - code: -38001
       message: Unknown payload
+- name: engine_getPayloadV3
+  summary: Obtains execution payload from payload build process
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_getpayloadv3
+  params:
+    - name: Payload id
+      required: true
+      schema:
+        $ref: '#/components/schemas/bytes8'
+  result:
+    name: Response object
+    schema:
+      type: object
+      required:
+        - executionPayload
+        - blockValue
+        - blobsBundle
+      properties:
+        executionPayload:
+          title: Execution payload
+          $ref: '#/components/schemas/ExecutionPayloadV3'
+        blockValue:
+          title: Expected fee value
+          $ref: '#/components/schemas/uint256'
+        blobsBundle:
+          title: Blobs bundle
+          $ref: '#/components/schemas/BlobsBundleV1'
+  errors:
+    - code: -38001
+      message: Unknown payload
+    - code: -38005
+      message: Unsupported fork
 - name: engine_getPayloadBodiesByHashV1
   summary: Given block hashes returns bodies of the corresponding execution payloads
   externalDocs:

src/engine/openrpc/schemas/payload.yaml

@@ -185,6 +185,68 @@ ExecutionPayloadV2:
       type: array
       items:
         $ref: '#/components/schemas/WithdrawalV1'
+ExecutionPayloadV3:
+  title: Execution payload object V3
+  type: object
+  required:
+    - parentHash
+    - feeRecipient
+    - stateRoot
+    - receiptsRoot
+    - logsBloom
+    - prevRandao
+    - blockNumber
+    - gasLimit
+    - gasUsed
+    - timestamp
+    - extraData
+    - baseFeePerGas
+    - blockHash
+    - transactions
+    - withdrawals
+    - dataGasUsed
+    - excessDataGas
+    - parentBeaconBlockRoot
+  properties:
+    parentHash:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/parentHash'
+    feeRecipient:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/feeRecipient'
+    stateRoot:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/stateRoot'
+    receiptsRoot:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/receiptsRoot'
+    logsBloom:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/logsBloom'
+    prevRandao:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/prevRandao'
+    blockNumber:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/blockNumber'
+    gasLimit:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/gasLimit'
+    gasUsed:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/gasUsed'
+    timestamp:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/timestamp'
+    extraData:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/extraData'
+    baseFeePerGas:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/baseFeePerGas'
+    blockHash:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/blockHash'
+    transactions:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/transactions'
+    withdrawals:
+      $ref: '#/components/schemas/ExecutionPayloadV2/properties/withdrawals'
+    dataGasUsed:
+      title: Data gas used
+      $ref: '#/components/schemas/uint64'
+    excessDataGas:
+      title: Excess data gas
+      $ref: '#/components/schemas/uint64'
+    parentBeaconBlockRoot:
+      title: Root of the parent beacon block
+      $ref: '#/components/schemas/bytes32'
 ExecutionPayloadBodyV1:
   title: Execution payload body object V1
   type: object
@@ -200,3 +262,26 @@ ExecutionPayloadBodyV1:
         - 'null'
       items:
         $ref: '#/components/schemas/WithdrawalV1'
+BlobsBundleV1:
+  title: Blobs bundle object V1
+  type: object
+  required:
+    - commitments
+    - proofs
+    - blobs
+  properties:
+    commitments:
+      title: Commitments
+      type: array
+      items:
+        $ref: '#/components/schemas/bytes48'
+    proofs:
+      title: Proofs
+      type: array
+      items:
+        $ref: '#/components/schemas/bytes48'
+    blobs:
+      title: Blobs
+      type: array
+      items:
+        $ref: '#/components/schemas/bytes'

src/schemas/base-types.yaml

@@ -27,6 +27,10 @@ bytes32:
   title: 32 hex encoded bytes
   type: string
   pattern: ^0x[0-9a-f]{64}$
+bytes48:
+  title: 48 hex encoded bytes
+  type: string
+  pattern: ^0x[0-9a-f]{96}$
 bytes256:
   title: 256 hex encoded bytes
   type: string