Merge branch 'main' into eip-7742-blob-uncoupling

README.md

@@ -98,7 +98,7 @@ This repository is licensed under [CC0](LICENSE).
 
 [playground]: https://ethereum.github.io/execution-apis/api-documentation/
 [openrpc]: https://open-rpc.org
-[validator]: https://open-rpc.github.io/schema-utils-js/globals.html#validateopenrpcdocument
+[validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html
 [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://raw.githubusercontent.com/ethereum/execution-apis/main/graphql.json
 [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767
 [making-changes]: docs/making-changes.md

graphql.json

@@ -473,22 +473,6 @@
             "isDeprecated": false,
             "deprecationReason": null
           },
-          {
-            "name": "totalDifficulty",
-            "description": "TotalDifficulty is the sum of all difficulty values up to and including\nthis block.",
-            "args": [],
-            "type": {
-              "kind": "NON_NULL",
-              "name": null,
-              "ofType": {
-                "kind": "SCALAR",
-                "name": "BigInt",
-                "ofType": null
-              }
-            },
-            "isDeprecated": false,
-            "deprecationReason": null
-          },
           {
             "name": "ommerCount",
             "description": "OmmerCount is the number of ommers (AKA uncles) associated with this\nblock. If ommers are unavailable, this field will be null.",

schema.graphqls

@@ -122,12 +122,6 @@ type Block {
   """Difficulty is a measure of the difficulty of mining this block."""
   difficulty: BigInt!
 
-  """
-  TotalDifficulty is the sum of all difficulty values up to and including
-  this block.
-  """
-  totalDifficulty: BigInt!
-
   """
   OmmerCount is the number of ommers (AKA uncles) associated with this
   block. If ommers are unavailable, this field will be null.

src/debug/getters.yaml

@@ -108,7 +108,6 @@
               receiptsRoot: '0xccd2d33763dc0ac3fe02d4ecbbcd7d2bdc6f57db635ba31007184679303721d7'
               miner: '0x0000000000000000000000000000000000000000'
               difficulty: '0x1'
-              totalDifficulty: '0x1'
               extraData: '0x00000000000000000000000000000000000000000000000000000000000000008c6a091f07e4ba3930f2f5fabbfc5b1c70986319096760ba200a6abc0d30e33c2d501702d1b58d7f75807bdbf981044557628611319121170b96466ec06bb3fd01'
               size: '0x3a0'
               gasLimit: '0xffffffffffff'
@@ -145,7 +144,6 @@
               receiptsRoot: '0x2b5c77f6e7764d2468178fab7253346b9b8bb6a34b63946f6bdc2f5ad398bfc3'
               miner: '0x0000000000000000000000000000000000000000'
               difficulty: '0x2'
-              totalDifficulty: '0x2'
               extraData: '0x00000000000000000000000000000000000000000000000000000000000000004d04551bdd9ae08af1fd661e49d4ab662c98c532c7ec0e4656a27e4de7d330af578ab1e4f5e49e085ff1d78673c7388ed9ccf017fbe89e53066bfa4018142c0701'
               size: '0x3a0'
               gasLimit: '0xffffffffffff'

src/engine/README.md

@@ -3,7 +3,7 @@
 The Engine JSON-RPC API is a collection of methods that all execution clients implement.
 This interface allows the communication between consensus and execution layers of the two-component post-Merge Ethereum Client.
 
-This API is in *active development* and currently specified in markdown documents specified by fork scopes ([Paris](./paris.md), [Shanghai](./shanghai.md), [Cancun](./cancun.md)).
+This API is in *active development* and currently specified in markdown documents specified by fork scopes ([Paris](./paris.md), [Shanghai](./shanghai.md), [Cancun](./cancun.md), [Prague](./prague.md)).
 
 ## References
 * [Engine API: A Visual Guide](https://hackmd.io/@danielrachi/engine_api)

src/engine/cancun.md

@@ -12,6 +12,7 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
 - [Structures](#structures)
   - [ExecutionPayloadV3](#executionpayloadv3)
   - [BlobsBundleV1](#blobsbundlev1)
+  - [BlobAndProofV1](#blobandproofv1)
   - [PayloadAttributesV3](#payloadattributesv3)
 - [Methods](#methods)
   - [engine_newPayloadV3](#engine_newpayloadv3)
@@ -26,7 +27,12 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
     - [Request](#request-2)
     - [Response](#response-2)
     - [Specification](#specification-2)
+  - [engine_getBlobsV1](#engine_getblobsv1)
+    - [Request](#request-3)
+    - [Response](#response-3)
+    - [Specification](#specification-3)
   - [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1)
+  - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -64,6 +70,13 @@ The fields are encoded as follows:
 
 All of the above three arrays **MUST** be of same length.
 
+### BlobAndProofV1
+
+The fields are encoded as follows:
+
+- `blob`: `DATA` - `FIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded `Blob` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844).
+- `proof`: `DATA` - `KZGProof` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes (`DATA`).
+
 ### PayloadAttributesV3
 
 This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadattributesv2) and appends a single field: `parentBeaconBlockRoot`.
@@ -170,6 +183,36 @@ Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getp
 
 5. Client software **MAY** use any heuristics to decide whether to set `shouldOverrideBuilder` flag or not. If client software does not implement any heuristic this flag **SHOULD** be set to `false`.
 
+### engine_getBlobsV1
+
+Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool.
+
+*Note*: This is a new optional method introduced after Cancun. It is defined here because it is backwards-compatible with Cancun.
+
+#### Request
+
+* method: `engine_getBlobsV1`
+* params:
+  1. `Array of DATA`, 32 Bytes - Array of blob versioned hashes.
+* timeout: 1s
+
+#### Response
+
+* result: `Array of BlobAndProofV1` - Array of [`BlobAndProofV1`](#BlobAndProofV1), items of which may be `null`.
+* error: code and message set in case an error occurs during processing of the request.
+
+#### Specification
+
+1. Given an array of blob versioned hashes client software **MUST** respond with an array of `BlobAndProofV1` objects with matching versioned hashes, respecting the order of versioned hashes in the input array.
+
+1. Client software **MUST** place responses in the order given in the request, using `null` for any missing blobs. For instance, if the request is `[A_versioned_hash, B_versioned_hash, C_versioned_hash]` and client software has data for blobs `A` and `C`, but doesn't have data for `B`, the response **MUST** be `[A, null, C]`.
+
+1. Client software **MUST** support request sizes of at least 128 blob versioned hashes. The client **MUST** return `-38004: Too large request` error if the number of requested blobs is too large.
+
+1. Client software **MAY** return an array of all `null` entries if syncing or otherwise unable to serve blob pool data.
+
+1. Callers **MUST** consider that execution layer clients may prune old blobs from their pool, and will respond with `null` if a blob has been pruned.
+
 ### Deprecate `engine_exchangeTransitionConfigurationV1`
 
 This document introduces deprecation of [`engine_exchangeTransitionConfigurationV1`](./paris.md#engine_exchangetransitionconfigurationv1). The deprecation is specified as follows:
@@ -192,4 +235,4 @@ For the following methods:
 
 a validation **MUST** be added:
 
-1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp.
+1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp.

src/engine/common.md

@@ -161,7 +161,7 @@ Execution layer clients **MUST** support `engine_exchangeCapabilities` method, w
 
 #### Specification
 
-1. Consensus and execution layer client software **MAY** exchange with a list of currently supported Engine API methods. Execution layer client software **MUST NOT** log any error messages if this method has either never been called or haven't been called for a significant amount of time.
+1. Consensus and execution layer client software **MAY** exchange with a list of currently supported Engine API methods. Execution layer client software **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time.
 
 2. Request and response lists **MUST** contain Engine API methods that are currently supported by consensus and execution client software respectively. Name of each method in both lists **MUST** include suffixed version. Consider the following examples:
     * Client software of both layers currently supports `V1` and `V2` versions of `engine_newPayload` method:

src/engine/identification.md

@@ -38,6 +38,7 @@ This enum defines a standard for specifying a client with just two letters. Clie
  - `LS`: lodestar
  - `NM`: nethermind
  - `NB`: nimbus
+ - `TE`: trin-execution
  - `TK`: teku
  - `PM`: prysm
  - `RH`: reth

src/engine/openrpc/schemas/blob.yaml

@@ -0,0 +1,14 @@
+BlobAndProofV1:
+  title: Blob and proof object V1
+  type: object
+  required:
+    - blob
+    - proof
+  properties:
+    blob: 
+      title: Blob
+      $ref: '#/components/schemas/bytes'
+    proof:
+      title: proof
+      $ref: '#/components/schemas/bytes48'
+

src/engine/openrpc/schemas/payload.yaml

@@ -243,80 +243,6 @@ ExecutionPayloadV3:
     excessBlobGas:
       title: Excess blob gas
       $ref: '#/components/schemas/uint64'
-ExecutionPayloadV4:
-  title: Execution payload object V4
-  type: object
-  required:
-    - parentHash
-    - feeRecipient
-    - stateRoot
-    - receiptsRoot
-    - logsBloom
-    - prevRandao
-    - blockNumber
-    - gasLimit
-    - gasUsed
-    - timestamp
-    - extraData
-    - baseFeePerGas
-    - blockHash
-    - transactions
-    - withdrawals
-    - blobGasUsed
-    - excessBlobGas
-    - depositRequests
-    - withdrawalRequests
-    - consolidationRequests
-  properties:
-    parentHash:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/parentHash'
-    feeRecipient:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/feeRecipient'
-    stateRoot:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/stateRoot'
-    receiptsRoot:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/receiptsRoot'
-    logsBloom:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/logsBloom'
-    prevRandao:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/prevRandao'
-    blockNumber:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockNumber'
-    gasLimit:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasLimit'
-    gasUsed:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasUsed'
-    timestamp:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/timestamp'
-    extraData:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/extraData'
-    baseFeePerGas:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/baseFeePerGas'
-    blockHash:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockHash'
-    transactions:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/transactions'
-    withdrawals:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/withdrawals'
-    blobGasUsed:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blobGasUsed'
-    excessBlobGas:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/excessBlobGas'
-    depositRequests:
-      title: Deposit requests
-      type: array
-      items:
-        $ref: '#/components/schemas/DepositRequestV1'
-    withdrawalRequests:
-      title: Withdrawals requests
-      type: array
-      items:
-        $ref: '#/components/schemas/WithdrawalRequestV1'
-    consolidationRequests:
-      title: Consolidation requests
-      type: array
-      items:
-        $ref: '#/components/schemas/ConsolidationRequestV1'
 ExecutionPayloadBodyV1:
   title: Execution payload body object V1
   type: object
@@ -332,44 +258,6 @@ ExecutionPayloadBodyV1:
         - 'null'
       items:
         $ref: '#/components/schemas/WithdrawalV1'
-ExecutionPayloadBodyV2:
-  title: Execution payload body object V2
-  type: object
-  required:
-    - transactions
-  properties:
-    transactions:
-      title: Transactions
-      type: array
-      items:
-        $ref: '#/components/schemas/bytes'
-    withdrawals:
-      title: Withdrawals
-      type:
-        - array
-        - 'null'
-      items:
-        $ref: '#/components/schemas/WithdrawalV1'
-    depositRequests:
-      title: Deposit requests
-      type:
-        - array
-        - 'null'
-      items:
-        $ref: '#/components/schemas/DepositRequestV1'
-    withdrawalRequests:
-      title: Withdrawals requests
-      type:
-        - array
-        - 'null'
-      items:
-        $ref: '#/components/schemas/WithdrawalRequestV1'
-    consolidationRequests:
-      title: Consolidation requests
-        - array
-        - 'null'
-      items:
-        $ref: '#/components/schemas/ConsolidationRequestV1'
 BlobsBundleV1:
   title: Blobs bundle object V1
   type: object

src/engine/paris.md

@@ -222,7 +222,7 @@ The payload build process is specified as follows:
 
     1. Verify that `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by `forkchoiceState.headBlockHash` and return `-38003: Invalid payload attributes` on failure.
 
-    2. If `payloadAttributes` passes all valdiation steps, begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value. The build process is specified in the [Payload building](#payload-building) section.
+    2. If `payloadAttributes` passes all validation steps, begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value. The build process is specified in the [Payload building](#payload-building) section.
 
     3. If `payloadAttributes` validation fails, the `forkchoiceState` update **MUST NOT** be rolled back.