chore: prep for Amsterdam fork (#3352)

* update reth 2.3 and prep for amsterdam fork

* add test

* updates

* updates

* dep updates

* dep updates

* test with pr-266

Author: tac0turtle

docs/ev-reth/engine-api.md

@@ -25,22 +25,22 @@ Configure both sides:
 ```text
 ev-node                                    ev-reth
    │                                          │
-   │  1. engine_forkchoiceUpdatedV3           │
+   │  1. engine_forkchoiceUpdatedV3/V4        │
    │     (headBlockHash, payloadAttributes)   │
    │─────────────────────────────────────────►│
    │                                          │
    │  2. {payloadId}                          │
    │◄─────────────────────────────────────────│
    │                                          │
-   │  3. engine_getPayloadV3(payloadId)       │
+   │  3. engine_getPayloadV4/V5/V6(payloadId) │
    │─────────────────────────────────────────►│
    │                                          │
    │  4. {executionPayload, blockValue}       │
    │◄─────────────────────────────────────────│
    │                                          │
    │  [ev-node broadcasts to P2P, submits DA] │
    │                                          │
-   │  5. engine_newPayloadV3(executionPayload)│
+   │  5. engine_newPayloadV4/V5(payload)      │
    │─────────────────────────────────────────►│
    │                                          │
    │  6. {status: VALID}                      │
@@ -54,15 +54,28 @@ ev-node                                    ev-reth
 
 ## Methods
 
-### engine_forkchoiceUpdatedV3
+| Fork family | Forkchoice | Get payload | New payload |
+|-------------|------------|-------------|-------------|
+| Prague | `engine_forkchoiceUpdatedV3` | `engine_getPayloadV4` | `engine_newPayloadV4` |
+| Osaka/Fusaka | `engine_forkchoiceUpdatedV3` | `engine_getPayloadV5` | `engine_newPayloadV4` |
+| Amsterdam | `engine_forkchoiceUpdatedV4` | `engine_getPayloadV6` | `engine_newPayloadV5` |
+
+Amsterdam support is more than a method rename: payload attributes include
+`slotNumber`, and built payloads include `executionPayload.blockAccessList`.
+ev-node preserves the raw Amsterdam `executionPayload` returned by ev-reth and
+submits it unchanged to `engine_newPayloadV5`.
+ev-node detects Amsterdam by retrying `engine_forkchoiceUpdatedV4` after an
+unsupported-fork response from `engine_forkchoiceUpdatedV3`, then caches V4.
+
+### engine_forkchoiceUpdatedV3 / V4
 
 Update the fork choice and optionally start building a new block.
 
 **Request:**
 
 ```json
 {
-  "method": "engine_forkchoiceUpdatedV3",
+  "method": "engine_forkchoiceUpdatedV4",
   "params": [
     {
       "headBlockHash": "0x...",
@@ -74,7 +87,8 @@ Update the fork choice and optionally start building a new block.
       "prevRandao": "0x...",
       "suggestedFeeRecipient": "0x...",
       "withdrawals": [],
-      "parentBeaconBlockRoot": "0x..."
+      "parentBeaconBlockRoot": "0x...",
+      "slotNumber": "0x..."
     }
   ]
 }
@@ -92,15 +106,15 @@ Update the fork choice and optionally start building a new block.
 }
 ```
 
-### engine_getPayloadV3
+### engine_getPayloadV4 / V5 / V6
 
 Retrieve a built payload.
 
 **Request:**
 
 ```json
 {
-  "method": "engine_getPayloadV3",
+  "method": "engine_getPayloadV6",
   "params": ["0x...payloadId"]
 }
 ```
@@ -123,25 +137,33 @@ Retrieve a built payload.
     "extraData": "0x",
     "baseFeePerGas": "0x...",
     "blockHash": "0x...",
-    "transactions": ["0x..."]
+    "transactions": ["0x..."],
+    "slotNumber": "0x...",
+    "blockAccessList": []
   },
   "blockValue": "0x..."
 }
 ```
 
-### engine_newPayloadV3
+### engine_newPayloadV4 / V5
 
 Validate and execute a payload.
 
 **Request:**
 
 ```json
 {
-  "method": "engine_newPayloadV3",
+  "method": "engine_newPayloadV5",
   "params": [
-    { "executionPayload": "..." },
+    {
+      "parentHash": "0x...",
+      "blockHash": "0x...",
+      "slotNumber": "0x...",
+      "blockAccessList": []
+    },
     ["0x...versionedHashes"],
-    "0x...parentBeaconBlockRoot"
+    "0x...parentBeaconBlockRoot",
+    []
   ]
 }
 ```
@@ -155,6 +177,19 @@ Validate and execute a payload.
 }
 ```
 
+## Amsterdam Enablement Checklist
+
+Before setting `amsterdamTime` in an ev-reth chainspec, verify:
+
+- [ ] ev-node can call `engine_forkchoiceUpdatedV4`.
+- [ ] ev-node sends `slotNumber` in Amsterdam payload attributes.
+- [ ] ev-node can call `engine_getPayloadV6`.
+- [ ] ev-node preserves `executionPayload.blockAccessList`.
+- [ ] ev-node can call `engine_newPayloadV5`.
+- [ ] Tracing and logs report the selected Engine API version.
+- [ ] Unit tests cover V4/V5/V6 version selection and `blockAccessList` passthrough.
+- [ ] E2E tests pass against an Amsterdam-enabled ev-reth chainspec.
+
 ## Status Codes
 
 | Status | Meaning |

docs/reference/api/engine-api.md

@@ -18,16 +18,29 @@ openssl rand -hex 32 > jwt.hex
 
 ## Methods
 
-### engine_forkchoiceUpdatedV3
+ev-node selects Engine API methods by fork:
+
+| Fork family | Forkchoice | Get payload | New payload |
+|-------------|------------|-------------|-------------|
+| Prague | `engine_forkchoiceUpdatedV3` | `engine_getPayloadV4` | `engine_newPayloadV4` |
+| Osaka/Fusaka | `engine_forkchoiceUpdatedV3` | `engine_getPayloadV5` | `engine_newPayloadV4` |
+| Amsterdam | `engine_forkchoiceUpdatedV4` | `engine_getPayloadV6` | `engine_newPayloadV5` |
+
+### engine_forkchoiceUpdatedV3 / V4
 
 Update fork choice and optionally build a new block.
 
+Payload builds start with `engine_forkchoiceUpdatedV3`. If the execution layer
+returns unsupported fork, ev-node retries `engine_forkchoiceUpdatedV4` with
+`slotNumber` in the payload attributes and caches V4 for future calls.
+`slotNumber` is derived deterministically from rollup block height.
+
 **Request:**
 
 ```json
 {
   "jsonrpc": "2.0",
-  "method": "engine_forkchoiceUpdatedV3",
+  "method": "engine_forkchoiceUpdatedV4",
   "params": [
     {
       "headBlockHash": "0x...",
@@ -39,7 +52,8 @@ Update fork choice and optionally build a new block.
       "prevRandao": "0x...",
       "suggestedFeeRecipient": "0x...",
       "withdrawals": [],
-      "parentBeaconBlockRoot": "0x..."
+      "parentBeaconBlockRoot": "0x...",
+      "slotNumber": "0x..."
     }
   ],
   "id": 1
@@ -62,16 +76,20 @@ Update fork choice and optionally build a new block.
 }
 ```
 
-### engine_getPayloadV3
+### engine_getPayloadV4 / V5 / V6
 
 Get a built payload.
 
+ev-node starts with `engine_getPayloadV4`, caches `engine_getPayloadV5` or
+`engine_getPayloadV6` after successful unsupported-fork fallback, and switches
+directly to V6 after an Amsterdam `forkchoiceUpdatedV4` build request.
+
 **Request:**
 
 ```json
 {
   "jsonrpc": "2.0",
-  "method": "engine_getPayloadV3",
+  "method": "engine_getPayloadV6",
   "params": ["0x...payloadId"],
   "id": 1
 }
@@ -100,7 +118,9 @@ Get a built payload.
       "transactions": ["0x..."],
       "withdrawals": [],
       "blobGasUsed": "0x0",
-      "excessBlobGas": "0x0"
+      "excessBlobGas": "0x0",
+      "slotNumber": "0x...",
+      "blockAccessList": []
     },
     "blockValue": "0x...",
     "blobsBundle": {
@@ -114,16 +134,20 @@ Get a built payload.
 }
 ```
 
-### engine_newPayloadV3
+### engine_newPayloadV4 / V5
 
 Validate and execute a payload.
 
+Amsterdam payloads use `engine_newPayloadV5`. ev-node passes through the raw
+`executionPayload` object returned by `engine_getPayloadV6` so
+`blockAccessList` is preserved.
+
 **Request:**
 
 ```json
 {
   "jsonrpc": "2.0",
-  "method": "engine_newPayloadV3",
+  "method": "engine_newPayloadV5",
   "params": [
     {
       "parentHash": "0x...",
@@ -142,10 +166,13 @@ Validate and execute a payload.
       "transactions": ["0x..."],
       "withdrawals": [],
       "blobGasUsed": "0x0",
-      "excessBlobGas": "0x0"
+      "excessBlobGas": "0x0",
+      "slotNumber": "0x...",
+      "blockAccessList": []
     },
     ["0x...expectedBlobVersionedHashes"],
-    "0x...parentBeaconBlockRoot"
+    "0x...parentBeaconBlockRoot",
+    []
   ],
   "id": 1
 }

execution/evm/README.md

@@ -20,7 +20,7 @@ Since the `PureEngineClient` relies on the Engine API, the genesis configuration
 1. The genesis file must include post-merge hardfork configurations
 2. `terminalTotalDifficulty` must be set to 0
 3. `terminalTotalDifficultyPassed` must be set to true
-4. Hardforks like `mergeNetsplitBlock`, `shanghaiTime`, `cancunTime` and `pragueTime` should be properly configured
+4. Hardforks like `mergeNetsplitBlock`, `shanghaiTime`, `cancunTime`, `pragueTime`, and optionally `amsterdamTime` should be properly configured
 
 Example of required genesis configuration:
 
@@ -43,18 +43,31 @@ Example of required genesis configuration:
     "terminalTotalDifficultyPassed": true,
     "shanghaiTime": 0,
     "cancunTime": 0,
-    "pragueTime": 0
+    "pragueTime": 0,
+    "amsterdamTime": 0
   }
 }
 ```
 
 Without these settings, the Engine API will not be available, and the `PureEngineClient` will not function correctly.
 
+### Engine API Versions
+
+ev-node uses fork-aware Engine API methods:
+
+- Prague payloads use `engine_forkchoiceUpdatedV3`, `engine_getPayloadV4`, and `engine_newPayloadV4`.
+- Osaka/Fusaka payloads fall forward from `engine_getPayloadV4` to `engine_getPayloadV5` on unsupported-fork responses.
+- Amsterdam payloads use `engine_forkchoiceUpdatedV4`, `engine_getPayloadV6`, and `engine_newPayloadV5`.
+
+ev-node auto-detects Engine API versions by retrying on unsupported-fork responses. For payload builds, it first tries `engine_forkchoiceUpdatedV3`; if the execution layer rejects that method for Amsterdam, ev-node retries `engine_forkchoiceUpdatedV4` with a deterministic `slotNumber` derived from rollup block height and caches V4 for future calls.
+
+Amsterdam adds `slotNumber` to payload attributes and `executionPayload.blockAccessList` to built payloads. ev-node does not compute the block access list; it preserves the raw `executionPayload` returned by ev-reth and submits that object unchanged to `engine_newPayloadV5`.
+
 ### PayloadID Storage
 
 The `PureEngineClient` maintains the `payloadID` between calls:
 
-1. During `InitChain`, a payload ID is obtained from the Engine API via `engine_forkchoiceUpdatedV3`
+1. During `InitChain`, the genesis forkchoice is acknowledged through the Engine API
 2. This payload ID is stored in the client instance as `c.payloadID`
 3. The stored payload ID is used in subsequent calls to `GetTxs` to retrieve the current execution payload
 4. After each `ExecuteTxs` call, a new payload ID is obtained and stored for the next block
@@ -66,7 +79,7 @@ The `PureEngineClient` implements a unique approach to transaction execution:
 1. In `GetTxs`, the entire execution payload is serialized to JSON and returned as the first transaction
 2. In `ExecuteTxs`, this first transaction is deserialized back into an execution payload
 3. The remaining transactions are added to the payload's transaction list
-4. The complete payload is then submitted to the execution client via `engine_newPayloadV4`
+4. The complete payload is then submitted to the execution client via the fork-appropriate `engine_newPayload` method
 
 This approach ensures that: