execution-apis: Add EIP-7594 (PeerDAS) related changes

src/engine/openrpc/schemas/blob.yaml

@@ -5,10 +5,25 @@ BlobAndProofV1:
     - blob
     - proof
   properties:
-    blob: 
+    blob:
       title: Blob
-      $ref: '#/components/schemas/bytes'
+      $ref: "#/components/schemas/bytes"
     proof:
       title: proof
-      $ref: '#/components/schemas/bytes48'
-
+      $ref: "#/components/schemas/bytes48"
+
+BlobAndProofV2:
+  title: Blob and proof object V2
+  type: object
+  required:
+    - blob
+    - proofs
+  properties:
+    blob:
+      title: Blob
+      $ref: "#/components/schemas/bytes"
+    proofs:
+      title: Cell Proofs
+      type: array
+      items:
+        $ref: "#/components/schemas/bytes48"

src/engine/openrpc/schemas/payload.yaml

@@ -281,6 +281,29 @@ BlobsBundleV1:
       type: array
       items:
         $ref: '#/components/schemas/bytes'
+BlobsBundleV2:
+  title: Blobs bundle object V2
+  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'
 DepositRequestV1:
   title: Deposit request object V1
   type: object

src/engine/osaka.md

@@ -0,0 +1,142 @@
+# Engine API -- Osaka
+
+Engine API changes introduced in Osaka.
+
+This specification is based on and extends [Engine API - Prague](./prague.md) specification.
+
+<!-- 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**
+
+- [Structures](#structures)
+  - [BlobsBundleV2](#blobsbundlev2)
+  - [BlobAndProofV2](#blobandproofv2)
+- [Methods](#methods)
+  - [engine_getPayloadV5](#engine_getpayloadv5)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_getBlobsV2](#engine_getblobsv2)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+  - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
+    - [Cancun API](#cancun-api)
+    - [Prague API](#prague-api)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Structures
+
+### BlobsBundleV2
+
+The fields are encoded as follows:
+
+- `commitments`: `Array of DATA` - Array of `KZGCommitment` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`).
+- `proofs`: `Array of DATA` - Array of `KZGProof` (48 bytes each, type defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), semantics defined in [EIP-7594](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7594.md)).
+- `blobs`: `Array of DATA` - Array of blobs, each blob is `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)
+
+`blobs` and `commitments` arrays **MUST** be of same length and `proofs` **MUST** contain exactly `CELLS_PER_EXT_BLOB` * `len(blobs)` cell proofs.
+
+### BlobAndProofV2
+
+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).
+- `proofs`: `Array of DATA` - Array of `KZGProof` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`).
+
+`proofs` **MUST** contain exactly `CELLS_PER_EXT_BLOB` cell proofs.
+
+## Methods
+
+### engine_getPayloadV5
+
+This method is updated in a backward incompatible way. Instead of returning `BlobBundleV1`, it returns `BlobsBundleV2`.
+
+#### Request
+
+* method: `engine_getPayloadV5`
+* params:
+  1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
+* timeout: 1s
+
+#### Response
+
+* result: `object`
+  - `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3)
+  - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
+  - `blobsBundle`: [`BlobsBundleV2`](#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.
+* error: code and message set in case an exception happens while getting the payload.
+
+#### Specification
+
+This method follows the same specification as [`engine_getPayloadV4`](./prague.md#engine_getpayloadv4) with changes of the following:
+
+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 Osaka fork.
+
+2. The call **MUST** return `BlobsBundleV2` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions.
+
+3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. 
+   1. `assert len(blobsBundle.commitments) == len(blobsBundle.blobs)` and
+   2. `assert len(blobsBundle.proofs) == len(blobsBundle.blobs) * CELLS_PER_EXT_BLOB` and
+   3. `assert verify_cell_kzg_proof_batch(commitments, cell_indices, cells, blobsBundle.proofs)` (see [EIP-7594 consensus-specs](https://github.com/ethereum/consensus-specs/blob/36d80adb44c21c66379c6207a9578f9b1dcc8a2d/specs/fulu/polynomial-commitments-sampling.md#verify_cell_kzg_proof_batch))
+      1. `commitments` should list each commitment `CELLS_PER_EXT_BLOB` times, repeating it for every cell. In python, `[blobsBundle.commitments[i] for i in range(len(blobsBundle.blobs)) for _ in range(CELLS_PER_EXT_BLOB)]`
+      2. `cell_indices` should be `[0, ..., CELLS_PER_EXT_BLOB, 0, ..., CELLS_PER_EXT_BLOB, ...]`. In python, `list(range(CELLS_PER_EXT_BLOB)) * len(blobsBundle.blobs)`
+      3. `cells` is the list of cells for an extended blob. In python, `[cell for blob in blobsBundle.blobs for cell in compute_cells(blob)]` (see [compute_cells](https://github.com/ethereum/consensus-specs/blob/v1.5.0-beta.3/specs/fulu/polynomial-commitments-sampling.md#compute_cells) in consensus-specs)
+      4. All of the inputs to `verify_cell_kzg_proof_batch` have the same length, `CELLS_PER_EXT_BLOB * len(blobsBundle.blobs)`
+
+### engine_getBlobsV2
+
+Consensus layer clients **MAY** use this method to fetch blobs from the execution layer blob pool.
+
+#### Request
+
+* method: `engine_getBlobsV2`
+* params:
+  1. `Array of DATA`, 32 Bytes - Array of blob versioned hashes.
+* timeout: 1s
+
+#### Response
+
+* result: `Array of BlobAndProofV2` - Array of [`BlobAndProofV2`](#BlobAndProofV2) or `null` in case of any missing blobs.
+* error: code and message set in case an error occurs during processing of the request.
+
+#### Specification
+
+Refer to the specification for [`engine_getBlobsV1`](./cancun.md#engine_getblobsv1) with changes of the following:
+
+1. Given an array of blob versioned hashes client software **MUST** respond with an array of `BlobAndProofV2` objects with matching versioned hashes, respecting the order of versioned hashes in the input array.
+2. Client software **MUST** return `null` in case of any missing or older version blobs. For instance, 
+   1. 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 `null`.
+   2. if the request is `[A_versioned_hash_for_blob_with_blob_proof]`, the response **MUST** be `null` as well.
+3. 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.
+4. Client software **MUST** return `null` if syncing or otherwise unable to serve blob pool data.
+5. 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.
+
+### Update the methods of previous forks
+
+#### Cancun API
+
+This section defines how Osaka payload should be handled by the ['Cancun API'](./cancun.md).
+
+For the following methods:
+
+- [`engine_getBlobsV1`](./cancun.md#engine_getblobsv1)
+
+a validation **MUST** be added:
+
+1. Client software **MUST** return `-38005: Unsupported fork` error if the Osaka fork has been activated.
+
+#### Prague API
+
+This section defines how Osaka payload should be handled by the ['Prague API'](./prague.md).
+
+For the following methods:
+
+- [`engine_getPayloadV4`](./prague.md#engine_getpayloadv4)
+
+a validation **MUST** be added:
+
+1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload greater or equal to the Osaka activation timestamp.

src/eth/submit.yaml

@@ -30,6 +30,16 @@
     [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) transactions, the raw
     form must be the network form. This means it includes the blobs, KZG
     commitments, and KZG proofs.
+    For [EIP-7594](https://eips.ethereum.org/EIPS/eip-7594) transactions, the raw format
+    must be the network form. This means it includes the blobs, KZG commitments, and cell proofs.
+    The logic for handling the new transaction during fork boundaries are
+    1. When receiving an encoded transaction with cell proofs before the PeerDAS fork activates, we reject it. Only blob proofs are accepted into the pool.
+    2. At the time of fork activation, the implementer could (not mandatory)
+      - Drop all old-format transactions
+      - Convert old proofs to new format (computationally expensive)
+      - Convert only when including in a locally produced block
+    3. After the fork has activated, only txs with cell proofs are accepted via p2p relay.
+    4. On RPC (eth_sendRawTransaction), txs with blob proofs may still be accepted and will be auto-converted by the node. At implementer discretion, this facility can be deprecated later when users have switched to new client libraries that can create cell proofs.
   params:
     - name: Transaction
       required: true

wordlist.txt

@@ -68,3 +68,4 @@ src
 https
 forkchoiceupdatedresponsev
 exitv
+txs