util,block,client,evm,vm: add EIP 7251 el triggered consolidations request type (#3477)

* util,block,client,vm: add EIP 7251 el triggered consolidations request type

* add eip 7251 el triggered consolidations plumbing

* accumulate the consolidations into requests from the 7251 system contract

* add and debug the  newpayloadv4 spec with consolidation related fixes

* apply feedback

Author: g11tech

packages/block/src/block.ts

@@ -6,6 +6,7 @@ import {
   BIGINT_0,
   CLRequestFactory,
   CLRequestType,
+  ConsolidationRequest,
   DepositRequest,
   KECCAK256_RLP,
   KECCAK256_RLP_ARRAY,
@@ -424,6 +425,7 @@ export class Block {
       withdrawals: withdrawalsData,
       depositRequests,
       withdrawalRequests,
+      consolidationRequests,
       executionWitness,
     } = payload
 
@@ -454,8 +456,13 @@ export class Block {
 
     const hasDepositRequests = depositRequests !== undefined && depositRequests !== null
     const hasWithdrawalRequests = withdrawalRequests !== undefined && withdrawalRequests !== null
+    const hasConsolidationRequests =
+      consolidationRequests !== undefined && consolidationRequests !== null
+
     const requests =
-      hasDepositRequests || hasWithdrawalRequests ? ([] as CLRequest<CLRequestType>[]) : undefined
+      hasDepositRequests || hasWithdrawalRequests || hasConsolidationRequests
+        ? ([] as CLRequest<CLRequestType>[])
+        : undefined
 
     if (depositRequests !== undefined && depositRequests !== null) {
       for (const dJson of depositRequests) {
@@ -467,6 +474,11 @@ export class Block {
         requests!.push(WithdrawalRequest.fromJSON(wJson))
       }
     }
+    if (consolidationRequests !== undefined && consolidationRequests !== null) {
+      for (const cJson of consolidationRequests) {
+        requests!.push(ConsolidationRequest.fromJSON(cJson))
+      }
+    }
 
     const requestsRoot = requests
       ? await Block.genRequestsTrieRoot(requests, new Trie({ common: opts?.common }))
@@ -1006,6 +1018,7 @@ export class Block {
       // lets add the  request fields first and then iterate over requests to fill them up
       depositRequests: this.common.isActivatedEIP(6110) ? [] : undefined,
       withdrawalRequests: this.common.isActivatedEIP(7002) ? [] : undefined,
+      consolidationRequests: this.common.isActivatedEIP(7251) ? [] : undefined,
     }
 
     if (this.requests !== undefined) {
@@ -1018,11 +1031,16 @@ export class Block {
           case CLRequestType.Withdrawal:
             executionPayload.withdrawalRequests!.push((request as WithdrawalRequest).toJSON())
             continue
+
+          case CLRequestType.Consolidation:
+            executionPayload.consolidationRequests!.push((request as ConsolidationRequest).toJSON())
+            continue
         }
       }
     } else if (
       executionPayload.depositRequests !== undefined ||
-      executionPayload.withdrawalRequests !== undefined
+      executionPayload.withdrawalRequests !== undefined ||
+      executionPayload.consolidationRequests !== undefined
     ) {
       throw Error(`Undefined requests for activated deposit or withdrawal requests`)
     }

packages/block/src/from-beacon-payload.ts

@@ -24,6 +24,12 @@ type BeaconWithdrawalRequest = {
   amount: PrefixedHexString
 }
 
+type BeaconConsolidationRequest = {
+  source_address: PrefixedHexString
+  source_pubkey: PrefixedHexString
+  target_pubkey: PrefixedHexString
+}
+
 // Payload json that one gets using the beacon apis
 // curl localhost:5052/eth/v2/beacon/blocks/56610 | jq .data.message.body.execution_payload
 export type BeaconPayloadJson = {
@@ -48,6 +54,7 @@ export type BeaconPayloadJson = {
   // requests data
   deposit_requests?: BeaconDepositRequest[]
   withdrawal_requests?: BeaconWithdrawalRequest[]
+  consolidation_requests?: BeaconConsolidationRequest[]
 
   // the casing of VerkleExecutionWitness remains same camel case for now
   execution_witness?: VerkleExecutionWitness
@@ -164,6 +171,13 @@ export function executionPayloadFromBeaconPayload(payload: BeaconPayloadJson): E
       amount: breq.amount,
     }))
   }
+  if (payload.consolidation_requests !== undefined && payload.consolidation_requests !== null) {
+    executionPayload.consolidationRequests = payload.consolidation_requests.map((breq) => ({
+      sourceAddress: breq.source_address,
+      sourcePubkey: breq.source_pubkey,
+      targetPubkey: breq.target_pubkey,
+    }))
+  }
 
   if (payload.execution_witness !== undefined && payload.execution_witness !== null) {
     // the casing structure in payload could be camel case or snake depending upon the CL

packages/block/src/types.ts

@@ -7,6 +7,7 @@ import type {
   BytesLike,
   CLRequest,
   CLRequestType,
+  ConsolidationRequestV1,
   DepositRequestV1,
   JsonRpcWithdrawal,
   PrefixedHexString,
@@ -269,4 +270,5 @@ export type ExecutionPayload = {
   executionWitness?: VerkleExecutionWitness | null // QUANTITY, 64 Bits, null implies not available
   depositRequests?: DepositRequestV1[] // Array of 6110 deposit requests
   withdrawalRequests?: WithdrawalRequestV1[] // Array of 7002 withdrawal requests
+  consolidationRequests?: ConsolidationRequestV1[] // Array of 7251 consolidation requests
 }

packages/block/test/eip7685block.spec.ts

@@ -26,7 +26,7 @@ function getRandomDepositRequest(): CLRequest<CLRequestType> {
 function getRandomWithdrawalRequest(): CLRequest<CLRequestType> {
   const withdrawalRequestData = {
     sourceAddress: randomBytes(20),
-    validatorPubkey: randomBytes(48),
+    validatorPublicKey: randomBytes(48),
     amount: bytesToBigInt(randomBytes(8)),
   }
   return WithdrawalRequest.fromRequestData(withdrawalRequestData) as CLRequest<CLRequestType>

packages/client/src/rpc/modules/engine/types.ts

@@ -2,7 +2,12 @@ import { UNKNOWN_PAYLOAD } from '../../error-code.js'
 
 import type { Skeleton } from '../../../service/index.js'
 import type { Block, ExecutionPayload } from '@ethereumjs/block'
-import type { DepositRequestV1, PrefixedHexString, WithdrawalRequestV1 } from '@ethereumjs/util'
+import type {
+  ConsolidationRequestV1,
+  DepositRequestV1,
+  PrefixedHexString,
+  WithdrawalRequestV1,
+} from '@ethereumjs/util'
 
 export enum Status {
   ACCEPTED = 'ACCEPTED',
@@ -31,6 +36,7 @@ export type ExecutionPayloadV3 = ExecutionPayloadV2 & { excessBlobGas: Uint64; b
 export type ExecutionPayloadV4 = ExecutionPayloadV3 & {
   depositRequests: DepositRequestV1[]
   withdrawalRequests: WithdrawalRequestV1[]
+  consolidationRequests: ConsolidationRequestV1[]
 }
 
 export type ForkchoiceStateV1 = {

packages/client/src/rpc/modules/engine/validators.ts

@@ -30,6 +30,7 @@ export const executionPayloadV4FieldValidators = {
   ...executionPayloadV3FieldValidators,
   depositRequests: validators.array(validators.depositRequest()),
   withdrawalRequests: validators.array(validators.withdrawalRequest()),
+  consolidationRequests: validators.array(validators.consolidationRequest()),
 }
 
 export const forkchoiceFieldValidators = {

packages/client/src/rpc/validation.ts

@@ -440,10 +440,10 @@ export const validators = {
           }
         }
 
-        const wt = params[index]
+        const clReq = params[index]
 
         for (const field of requiredFields) {
-          if (wt[field] === undefined) {
+          if (clReq[field] === undefined) {
             return {
               code: INVALID_PARAMS,
               message: `invalid argument ${index}: required field ${field}`,
@@ -458,25 +458,25 @@ export const validators = {
         }
 
         // validate pubkey
-        for (const field of [wt.pubkey]) {
+        for (const field of [clReq.pubkey]) {
           const v = validate(field, this.bytes48)
           if (v !== undefined) return v
         }
 
         // validate withdrawalCredentials
-        for (const field of [wt.withdrawalCredentials]) {
+        for (const field of [clReq.withdrawalCredentials]) {
           const v = validate(field, this.bytes32)
           if (v !== undefined) return v
         }
 
         // validate amount, index
-        for (const field of [wt.amount, wt.index]) {
+        for (const field of [clReq.amount, clReq.index]) {
           const v = validate(field, this.bytes8)
           if (v !== undefined) return v
         }
 
         // validate signature
-        for (const field of [wt.signature]) {
+        for (const field of [clReq.signature]) {
           const v = validate(field, this.bytes96)
           if (v !== undefined) return v
         }
@@ -494,10 +494,10 @@ export const validators = {
           }
         }
 
-        const wt = params[index]
+        const clReq = params[index]
 
         for (const field of requiredFields) {
-          if (wt[field] === undefined) {
+          if (clReq[field] === undefined) {
             return {
               code: INVALID_PARAMS,
               message: `invalid argument ${index}: required field ${field}`,
@@ -512,26 +512,74 @@ export const validators = {
         }
 
         // validate sourceAddress
-        for (const field of [wt.sourceAddress]) {
+        for (const field of [clReq.sourceAddress]) {
           const v = validate(field, this.address)
           if (v !== undefined) return v
         }
 
         // validate validatorPubkey
-        for (const field of [wt.validatorPubkey]) {
+        for (const field of [clReq.validatorPubkey]) {
           const v = validate(field, this.bytes48)
           if (v !== undefined) return v
         }
 
         // validate amount
-        for (const field of [wt.amount]) {
+        for (const field of [clReq.amount]) {
           const v = validate(field, this.bytes8)
           if (v !== undefined) return v
         }
       }
     }
   },
 
+  get consolidationRequest() {
+    return (requiredFields: string[] = ['sourceAddress', 'sourcePubkey', 'targetPubkey']) => {
+      return (params: any[], index: number) => {
+        if (typeof params[index] !== 'object') {
+          return {
+            code: INVALID_PARAMS,
+            message: `invalid argument ${index}: argument must be an object`,
+          }
+        }
+
+        const clReq = params[index]
+
+        for (const field of requiredFields) {
+          if (clReq[field] === undefined) {
+            return {
+              code: INVALID_PARAMS,
+              message: `invalid argument ${index}: required field ${field}`,
+            }
+          }
+        }
+
+        const validate = (field: any, validator: Function) => {
+          if (field === undefined) return
+          const v = validator([field], 0)
+          if (v !== undefined) return v
+        }
+
+        // validate sourceAddress
+        for (const field of [clReq.sourceAddress]) {
+          const v = validate(field, this.address)
+          if (v !== undefined) return v
+        }
+
+        // validate validatorPubkey
+        for (const field of [clReq.sourcePubkey]) {
+          const v = validate(field, this.bytes48)
+          if (v !== undefined) return v
+        }
+
+        // validate amount
+        for (const field of [clReq.targetPubkey]) {
+          const v = validate(field, this.bytes48)
+          if (v !== undefined) return v
+        }
+      }
+    }
+  },
+
   /**
    * object validator to check if type is object with
    * required keys and expected validation of values

packages/client/test/rpc/engine/newPayloadV4.spec.ts

@@ -601,6 +601,27 @@ export const EIPs: EIPsDict = {
       },
     },
   },
+  7251: {
+    comment: 'Execution layer triggered consolidations (experimental)',
+    url: 'https://eips.ethereum.org/EIPS/eip-7251',
+    status: Status.Draft,
+    minimumHardfork: Hardfork.Paris,
+    requiredEIPs: [7685],
+    vm: {
+      consolidationRequestType: {
+        v: BigInt(0x02),
+        d: 'The withdrawal request type for EIP-7685',
+      },
+      systemAddress: {
+        v: BigInt('0xfffffffffffffffffffffffffffffffffffffffe'),
+        d: 'The system address to perform operations on the consolidation requests predeploy address',
+      },
+      consolidationRequestPredeployAddress: {
+        v: BigInt('0x00b42dbF2194e931E80326D950320f7d9Dbeac02'),
+        d: 'Address of the consolidations contract',
+      },
+    },
+  },
   7516: {
     comment: 'BLOBBASEFEE opcode',
     url: 'https://eips.ethereum.org/EIPS/eip-7516',

packages/common/src/eips.ts

@@ -841,7 +841,7 @@ export const hardforks: HardforksDict = {
       'Next feature hardfork after cancun, internally used for pectra testing/implementation (incomplete/experimental)',
     url: 'https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/prague.md',
     status: Status.Draft,
-    eips: [2537, 2935, 3074, 6110, 7002, 7685],
+    eips: [2537, 2935, 3074, 6110, 7002, 7251, 7685],
   },
   osaka: {
     name: 'osaka',