Skip to content

amsterdam.md

Latest commit

 

History

History
235 lines (159 loc) · 10.9 KB

amsterdam.md

File metadata and controls

235 lines (159 loc) · 10.9 KB

Engine API -- Amsterdam

Engine API changes introduced in Amsterdam.

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

Table of contents

Structures

ExecutionPayloadV4

This structure has the syntax of ExecutionPayloadV3 and appends the new field: blockAccessList.

  • parentHash: DATA, 32 Bytes
  • feeRecipient: DATA, 20 Bytes
  • stateRoot: DATA, 32 Bytes
  • receiptsRoot: DATA, 32 Bytes
  • logsBloom: DATA, 256 Bytes
  • prevRandao: DATA, 32 Bytes
  • blockNumber: QUANTITY, 64 Bits
  • gasLimit: QUANTITY, 64 Bits
  • gasUsed: QUANTITY, 64 Bits
  • timestamp: QUANTITY, 64 Bits
  • extraData: DATA, 0 to 32 Bytes
  • baseFeePerGas: QUANTITY, 256 Bits
  • blockHash: DATA, 32 Bytes
  • transactions: Array of DATA - Array of transaction objects, each object is a byte list (DATA) representing TransactionType || TransactionPayload or LegacyTransaction as defined in EIP-2718
  • withdrawals: Array of WithdrawalV1 - Array of withdrawals, each object is an OBJECT containing the fields of a WithdrawalV1 structure.
  • blobGasUsed: QUANTITY, 64 Bits
  • excessBlobGas: QUANTITY, 64 Bits
  • blockAccessList: DATA - RLP-encoded block access list as defined in EIP-7928
  • slotNumber: QUANTITY, 64 Bits

ExecutionPayloadBodyV2

This structure has the syntax of ExecutionPayloadBodyV1 and appends the new field: blockAccessList.

  • transactions: Array of DATA - Array of transaction objects, each object is a byte list (DATA) representing TransactionType || TransactionPayload or LegacyTransaction as defined in EIP-2718
  • withdrawals: Array of WithdrawalV1 - Array of withdrawals, each object is an OBJECT containing the fields of a WithdrawalV1 structure. Value is null for blocks produced before Shanghai.
  • blockAccessList: DATA|null - RLP-encoded block access list as defined in EIP-7928. Value is null for blocks produced before Amsterdam or if the data has been pruned.

PayloadAttributesV4

This structure has the syntax of PayloadAttributesV3 and appends a single field: slotNumber.

  • 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

Methods

engine_newPayloadV5

This method is updated to support the new ExecutionPayloadV4 structure.

Request

  • method: engine_newPayloadV5
  • params:
    1. executionPayload: 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.

Response

Refer to the response for engine_newPayloadV4.

Specification

This method follows the same specification as engine_newPayloadV4 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 Amsterdam fork.

  2. Client software MUST return -32602: Invalid params error if the blockAccessList field is missing.

  3. Client software MUST validate the blockAccessList field by executing the payload's transactions and verifying that the computed access list matches the provided one. If this validation fails, the call MUST return {status: INVALID, latestValidHash: null, validationError: errorMessage | null}.

engine_getPayloadV6

This method is updated to return the new ExecutionPayloadV4 structure.

Request

  • method: engine_getPayloadV6
  • params:
    1. payloadId: DATA, 8 Bytes - Identifier of the payload build process
  • timeout: 1s

Response

  • result: object
    • executionPayload: ExecutionPayloadV4
    • 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_getPayloadV5 with the following changes:

  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 Amsterdam fork.

  2. When building the block, client software MUST collect all account accesses and state changes during transaction execution and populate the blockAccessList field in the returned ExecutionPayloadV4 with the RLP-encoded access list.

engine_getPayloadBodiesByHashV2

This method retrieves execution payload bodies including block access lists for specified blocks.

Request

  • method: engine_getPayloadBodiesByHashV2
  • params:
    1. blockHashes: Array of DATA, 32 Bytes - Array of block hashes to retrieve payload bodies for
  • timeout: 10s

Response

  • result: Array of ExecutionPayloadBodyV2 - Array of ExecutionPayloadBodyV2 objects or null for blocks that are unavailable
  • error: code and message set in case an exception happens while getting the payload bodies.

Specification

This method follows the same specification as engine_getPayloadBodiesByHashV1 with the following additions:

  1. Client software MUST set the blockAccessList field to null for blocks that predate the Amsterdam fork activation.

  2. Client software MUST set the blockAccessList field to null if the block access list has been pruned from storage.

engine_getPayloadBodiesByRangeV2

This method retrieves execution payload bodies including block access lists for a range of blocks.

Request

  • method: engine_getPayloadBodiesByRangeV2
  • params:
    1. start: QUANTITY, 64 Bits - Starting block number
    2. count: QUANTITY, 64 Bits - Number of blocks to retrieve payload bodies for
  • timeout: 10s

Response

  • result: Array of ExecutionPayloadBodyV2 - Array of ExecutionPayloadBodyV2 objects or null for blocks that are unavailable
  • error: code and message set in case an exception happens while getting the payload bodies.

Specification

This method follows the same specification as engine_getPayloadBodiesByRangeV1 with the following additions:

  1. Client software MUST set the blockAccessList field to null for blocks that predate the Amsterdam fork activation.

  2. Client software MUST set the blockAccessList field to null if the block access list has been pruned from storage.

engine_forkchoiceUpdatedV4

Request

Response

Refer to the response for engine_forkchoiceUpdatedV3.

Specification

This method follows the same specification as engine_forkchoiceUpdatedV3 with the following changes to the processing flow:

  1. Extend point (7) of the engine_forkchoiceUpdatedV1 specification by defining the following sequence of checks that MUST be run over payloadAttributes:

    1. payloadAttributes matches the PayloadAttributesV4 structure, return -38003: Invalid payload attributes on failure.

    2. payloadAttributes.timestamp does not fall within the time frame of the Amsterdam fork, return -38005: Unsupported fork on failure.

    3. payloadAttributes.timestamp is greater than timestamp of a block referenced by forkchoiceState.headBlockHash, return -38003: Invalid payload attributes on failure.

    4. If any of the above checks fails, the forkchoiceState update MUST NOT be rolled back.

Update the methods of previous forks

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