engine: define EIP-7928 API methods

docs/reference/quickstart.md

@@ -139,9 +139,9 @@ This repository is licensed under [CC0][license].
 [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
-[contributors-guide]: ../contributors-guide
+[contributors-guide]: ./contributors-guide.md
 [json-schema]: https://json-schema.org
 [hive]: https://github.com/ethereum/hive
 [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
-[test-gen]: ../tests
+[test-gen]: ./tests.md
 [license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE

src/engine/amsterdam.md

@@ -11,6 +11,7 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
 
 - [Structures](#structures)
   - [ExecutionPayloadV4](#executionpayloadv4)
+  - [ExecutionPayloadBodyV2](#executionpayloadbodyv2)
 - [Methods](#methods)
   - [engine_newPayloadV5](#engine_newpayloadv5)
     - [Request](#request)
@@ -20,6 +21,14 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec
     - [Request](#request-1)
     - [Response](#response-1)
     - [Specification](#specification-1)
+  - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
+  - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2)
+    - [Request](#request-3)
+    - [Response](#response-3)
+    - [Specification](#specification-3)
   - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
     - [Osaka API](#osaka-api)
 
@@ -50,6 +59,14 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay
 - `excessBlobGas`: `QUANTITY`, 64 Bits
 - `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)
 
+### ExecutionPayloadBodyV2
+
+This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#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](https://eips.ethereum.org/EIPS/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](https://eips.ethereum.org/EIPS/eip-7928). Value is `null` for blocks produced before Amsterdam or if the data has been pruned.
+
 ## Methods
 
 ### engine_newPayloadV5
@@ -109,6 +126,59 @@ This method follows the same specification as [`engine_getPayloadV5`](./osaka.md
 
 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`](#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`](./shanghai.md#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.
+
+3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution.
+
+### 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`](#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`](./shanghai.md#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.
+
+3. Client software **MUST** retain block access lists for at least 3533 epochs (the weak subjectivity period) to support synchronization with re-execution.
+
 ### Update the methods of previous forks
 
 #### Osaka API

src/engine/openrpc/methods/capabilities.yaml

@@ -25,6 +25,8 @@
             - 'engine_forkchoiceUpdatedV1'
             - 'engine_getPayloadBodiesByHashV1'
             - 'engine_getPayloadBodiesByRangeV1'
+            - 'engine_getPayloadBodiesByHashV2'
+            - 'engine_getPayloadBodiesByRangeV2'
             - 'engine_getPayloadV1'
             - 'engine_newPayloadV1'
       result:
@@ -40,3 +42,5 @@
           - 'engine_exchangeTransitionConfigurationV1'
           - 'engine_getPayloadBodiesByHashV1'
           - 'engine_getPayloadBodiesByRangeV1'
+          - 'engine_getPayloadBodiesByHashV2'
+          - 'engine_getPayloadBodiesByRangeV2'

src/engine/openrpc/methods/payload.yaml

@@ -886,6 +886,102 @@
                 validatorIndex: '0xf3'
                 address: '0x00000000000000000000000000000000000010f3'
                 amount: '0x1'
+- name: engine_getPayloadBodiesByHashV2
+  summary: Given block hashes returns bodies of the corresponding execution payloads including block access lists
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getpayloadbodiesbyhashv2
+  params:
+    - name: Array of block hashes
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '#/components/schemas/hash32'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV2'
+  errors:
+    - code: -38004
+      message: Too large request
+  examples:
+    - name: engine_getPayloadBodiesByHashV2 example
+      params:
+        - name: Array of block hashes
+          value:
+            - '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
+            - '0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553'
+      result:
+        name: Execution payload bodies
+        value:
+          - transactions:
+              - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
+            withdrawals:
+              - index: '0xf0'
+                validatorIndex: '0xf0'
+                address: '0x00000000000000000000000000000000000010f0'
+                amount: '0x1'
+            blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a02222222222222222222222222222222222222222222222222222222222222222a03333333333333333333333333333333333333333333333333333333333333333a04444444444444444444444444444444444444444444444444444444444444444'
+          - transactions:
+              - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
+            withdrawals:
+              - index: '0xf1'
+                validatorIndex: '0xf1'
+                address: '0x00000000000000000000000000000000000010f1'
+                amount: '0x1'
+            blockAccessList: null
+- name: engine_getPayloadBodiesByRangeV2
+  summary: Given a range of block numbers returns bodies of the corresponding execution payloads including block access lists
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getpayloadbodiesbyrangev2
+  params:
+    - name: Starting block number
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+    - name: Number of blocks to return
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV2'
+  errors:
+    - code: -38004
+      message: Too large request
+  examples:
+    - name: engine_getPayloadBodiesByRangeV2 example
+      params:
+        - name: Starting block number
+          value: '0x20'
+        - name: Number of blocks to return
+          value: '0x2'
+      result:
+        name: Execution payload bodies
+        value:
+          - transactions:
+              - '0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65'
+            withdrawals:
+              - index: '0xf0'
+                validatorIndex: '0xf0'
+                address: '0x00000000000000000000000000000000000010f0'
+                amount: '0x1'
+            blockAccessList: null
+          - transactions:
+              - '0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe'
+            withdrawals:
+              - index: '0xf1'
+                validatorIndex: '0xf1'
+                address: '0x00000000000000000000000000000000000010f1'
+                amount: '0x1'
+            blockAccessList: '0xf8daf8d8f8d6a000000000000000000000000000000000000000000000000000000000000000a0f8a7a05555555555555555555555555555555555555555555555555555555555555555a06666666666666666666666666666666666666666666666666666666666666666a07777777777777777777777777777777777777777777777777777777777777777'
 - name: engine_newPayloadV5
   summary: Runs execution payload validation
   externalDocs:

src/engine/openrpc/schemas/payload.yaml

@@ -318,6 +318,27 @@ ExecutionPayloadBodyV1:
         - 'null'
       items:
         $ref: '#/components/schemas/WithdrawalV1'
+ExecutionPayloadBodyV2:
+  title: Execution payload body object V2
+  type: object
+  required:
+    - transactions
+  properties:
+    transactions:
+      $ref: '#/components/schemas/ExecutionPayloadV1/properties/transactions'
+    withdrawals:
+      title: Withdrawals
+      type:
+        - array
+        - 'null'
+      items:
+        $ref: '#/components/schemas/WithdrawalV1'
+    blockAccessList:
+      title: Block access list
+      description: RLP-encoded block access list as defined in EIP-7928, or null if unavailable
+      oneOf:
+        - $ref: '#/components/schemas/bytes'
+        - type: 'null'
 BlobsBundleV1:
   title: Blobs bundle object V1
   type: object

wordlist.txt

@@ -1,82 +1,84 @@
 apis
 attributesv
-bodyv
-bodiesbyrangev
+besu
+blobandproofv
+blobsbundlev
+blockaccesslist
+blockAccessList
+BlockAccessList
 bodiesbyhashv
+bodiesbyrangev
+bodyv
 bytecode
+CL
+cli
 clientversionv
+CLs
 configurationv
 crypto
+DocToc
 eg
 eip
+eips
+EIPS
+EL
 endian
 enum
+EOA
+EOA's
+ERC
+erigon
 eth
 ethereum
 ethereumjs
-erigon
-getclientversionv
+EVM
+exitv
+feeRecipient
+forkchoiceupdatedresponsev
+getblobsbundlev
 getblobsv
+getclientversionv
+graphql
+gwei
+https
 interop
+ipc
 js
 json
+JWT
+kzg
 mempool
 merkle
+multicallV
 npm
 ommers
 openrpc
 params
 pos
 pre
+prevrandao
 pyspelling
+randao
 rlp
 rpc
 schemas
 secp
+sha
+simulateV
+src
+ssz
 statev
 statusv
-sha
 teku
+txs
 uint
 updatedv
 url
+UX
 validator
+VM
 wei
+withdrawalv
+WS
 yaml
 yParity
-eips
-EIPS
-EL
-CL
-CLs
-JWT
-WS
-ipc
-cli
-blobsbundlev
-getblobsbundlev
-blobandproofv
-ssz
-kzg
-besu
-graphql
-gwei
-withdrawalv
-DocToc
-prevrandao
-randao
-src
-https
-forkchoiceupdatedresponsev
-feeRecipient
-multicallV
-EOA
-EOA's
-EVM
-ERC
-VM
-exitv
-txs
-UX
-simulateV
-EOA's