Skip to content

osaka.md

Latest commit

 

History

History
174 lines (116 loc) · 9.91 KB

osaka.md

File metadata and controls

174 lines (116 loc) · 9.91 KB

Engine API -- Osaka

Engine API changes introduced in Osaka.

This specification is based on and extends Engine API - Prague specification.

Table of Contents

Structures

BlobsBundleV2

The fields are encoded as follows:

  • commitments: Array of DATA - Array of KZGCommitment as defined in EIP-4844, 48 bytes each (DATA).
  • proofs: Array of DATA - Array of KZGProof (48 bytes each, type defined in EIP-4844, semantics defined in EIP-7594).
  • 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

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.
  • proofs: Array of DATA - Array of KZGProof as defined in 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
    • blockValue : QUANTITY, 256 Bits - The expected value to be received by the feeRecipient in wei
    • blobsBundle: 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 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)
      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 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 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 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.

engine_getBlobsV3

Consensus layer clients MAY use this method to fetch blobs from the execution layer blob pool, with support for partial responses. For an all-or-nothing query style, refer to engine_getBlobsV2.

Request

  • method: engine_getBlobsV3
  • params:
    1. Array of DATA, 32 Bytes - Array of blob versioned hashes.
  • timeout: 1s

Response

  • result: Array of BlobAndProofV2 - Array of BlobAndProofV2, inserting null only at the positions of the missing blobs, or a null literal in the designated cases specified below.
  • error: code and message set in case an error occurs during processing of the request.

Specification

To assist the reader, we highlight differences against engine_getBlobsV2 using italic.

  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. Given an array of blob versioned hashes, if client software has every one of the requested blobs, it MUST return an array of BlobAndProofV2 objects whose order exactly matches the input array. For instance, if the request is [A_versioned_hash, B_versioned_hash, C_versioned_hash] and client software has A, B and C available, the response MUST be [A, B, C].
  3. If one or more of the requested blobs are unavailable, the client MUST return an array of the same length and order, inserting null only at the positions of the 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]. If all blobs are missing, the client software must return an array of matching length, filled with null at all positions.
  4. 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.
  5. Client software MUST return null if syncing or otherwise unable to generally serve blob pool data.
  6. Callers MUST consider that execution layer clients may prune old blobs from their pool, and will respond with null at the corresponding position 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'.

For the following methods:

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'.

For the following methods:

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 Osaka activation timestamp.