feat: switch blinded and full block production to produce block v3

update the impl interfaces

Restore the previous versions

update test

fix oapi spec

fix tests

fix merge tests

fix tests

fix the tests

implement produce blockv3

refac forktypes

plug v3 into vlidator and get it working

mock test produceblockv3 and fix issues

fix lint

fixes

update head opts

cleanup the validator flags

shift fee recipient to extra args as well

typo

fix tests

missed commit

deprecate flag instead of removing

packages/api/src/beacon/routes/validator.ts

@@ -1,5 +1,5 @@
 import {ContainerType, fromHexString, toHexString, Type} from "@chainsafe/ssz";
-import {ForkName, isForkBlobs, isForkExecution} from "@lodestar/params";
+import {ForkName, ForkBlobs, isForkBlobs, isForkExecution, ForkPreBlobs} from "@lodestar/params";
 import {
   allForks,
   altair,
@@ -27,12 +27,13 @@ import {
   ArrayOf,
   Schema,
   WithVersion,
-  WithBlockValue,
+  WithExecutionPayloadValue,
   reqOnlyBody,
   ReqSerializers,
   jsonType,
   ContainerDataExecutionOptimistic,
   ContainerData,
+  TypeJson,
 } from "../../utils/index.js";
 import {fromU64Str, fromGraffitiHex, toU64Str, U64Str, toGraffitiHex} from "../../utils/serdes.js";
 import {
@@ -43,6 +44,34 @@ import {
 } from "../../utils/routes.js";
 import {ExecutionOptimistic} from "./beacon/block.js";
 
+export enum BuilderSelection {
+  BuilderAlways = "builderalways",
+  MaxProfit = "maxprofit",
+  /** Only activate builder flow for DVT block proposal protocols */
+  BuilderOnly = "builderonly",
+  /** Only builds execution block*/
+  ExecutionOnly = "executiononly",
+}
+
+export type ExtraProduceBlockOps = {
+  feeRecipient?: string;
+  builderSelection?: BuilderSelection;
+  strictFeeRecipientCheck?: boolean;
+};
+
+export type ProduceBlockOrContentsRes = {executionPayloadValue: Wei} & (
+  | {data: allForks.BeaconBlock; version: ForkPreBlobs}
+  | {data: BlockContents; version: ForkBlobs}
+);
+export type ProduceBlindedBlockOrContentsRes = {executionPayloadValue: Wei} & (
+  | {data: allForks.BlindedBeaconBlock; version: ForkPreBlobs}
+  | {data: BlindedBlockContents; version: ForkBlobs}
+);
+
+export type ProduceFullOrBlindedBlockOrContentsRes =
+  | (ProduceBlockOrContentsRes & {executionPayloadBlinded: false})
+  | (ProduceBlindedBlockOrContentsRes & {executionPayloadBlinded: true});
+
 // See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
 
 export type BeaconCommitteeSubscription = {
@@ -201,11 +230,10 @@ export type Api = {
   produceBlock(
     slot: Slot,
     randaoReveal: BLSSignature,
-    graffiti: string,
-    feeRecipient?: string
+    graffiti: string
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: allForks.BeaconBlock; blockValue: Wei}},
+      {[HttpStatusCode.OK]: {data: allForks.BeaconBlock}},
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.SERVICE_UNAVAILABLE
     >
   >;
@@ -221,30 +249,49 @@ export type Api = {
    * @throws ApiError
    */
   produceBlockV2(
+    slot: Slot,
+    randaoReveal: BLSSignature,
+    graffiti: string
+  ): Promise<
+    ApiClientResponse<
+      {[HttpStatusCode.OK]: ProduceBlockOrContentsRes},
+      HttpStatusCode.BAD_REQUEST | HttpStatusCode.SERVICE_UNAVAILABLE
+    >
+  >;
+
+  /**
+   * Requests a beacon node to produce a valid block, which can then be signed by a validator.
+   * Metadata in the response indicates the type of block produced, and the supported types of block
+   * will be added to as forks progress.
+   * @param slot The slot for which the block should be proposed.
+   * @param randaoReveal The validator's randao reveal value.
+   * @param graffiti Arbitrary data validator wants to include in block.
+   * @returns any Success response
+   * @throws ApiError
+   */
+  produceBlockV3(
     slot: Slot,
     randaoReveal: BLSSignature,
     graffiti: string,
-    feeRecipient?: string
+    skipRandaoVerification?: boolean,
+    opts?: ExtraProduceBlockOps
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: allForks.BeaconBlock | BlockContents; version: ForkName; blockValue: Wei}},
+      {
+        [HttpStatusCode.OK]: ProduceFullOrBlindedBlockOrContentsRes;
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.SERVICE_UNAVAILABLE
     >
   >;
 
   produceBlindedBlock(
     slot: Slot,
     randaoReveal: BLSSignature,
-    graffiti: string,
-    feeRecipient?: string
+    graffiti: string
   ): Promise<
     ApiClientResponse<
       {
-        [HttpStatusCode.OK]: {
-          data: allForks.BlindedBeaconBlock | BlindedBlockContents;
-          version: ForkName;
-          blockValue: Wei;
-        };
+        [HttpStatusCode.OK]: ProduceBlindedBlockOrContentsRes;
       },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.SERVICE_UNAVAILABLE
     >
@@ -410,6 +457,7 @@ export const routesData: RoutesData<Api> = {
   getSyncCommitteeDuties: {url: "/eth/v1/validator/duties/sync/{epoch}", method: "POST"},
   produceBlock: {url: "/eth/v1/validator/blocks/{slot}", method: "GET"},
   produceBlockV2: {url: "/eth/v2/validator/blocks/{slot}", method: "GET"},
+  produceBlockV3: {url: "/eth/v3/validator/blocks/{slot}", method: "GET"},
   produceBlindedBlock: {url: "/eth/v1/validator/blinded_blocks/{slot}", method: "GET"},
   produceAttestationData: {url: "/eth/v1/validator/attestation_data", method: "GET"},
   produceSyncCommitteeContribution: {url: "/eth/v1/validator/sync_committee_contribution", method: "GET"},
@@ -432,6 +480,17 @@ export type ReqTypes = {
   getSyncCommitteeDuties: {params: {epoch: Epoch}; body: U64Str[]};
   produceBlock: {params: {slot: number}; query: {randao_reveal: string; graffiti: string}};
   produceBlockV2: {params: {slot: number}; query: {randao_reveal: string; graffiti: string; fee_recipient?: string}};
+  produceBlockV3: {
+    params: {slot: number};
+    query: {
+      randao_reveal: string;
+      graffiti: string;
+      skip_randao_verification?: boolean;
+      fee_recipient?: string;
+      builder_selection?: string;
+      strict_fee_recipient_check?: boolean;
+    };
+  };
   produceBlindedBlock: {params: {slot: number}; query: {randao_reveal: string; graffiti: string}};
   produceAttestationData: {query: {slot: number; committee_index: number}};
   produceSyncCommitteeContribution: {query: {slot: number; subcommittee_index: number; beacon_block_root: string}};
@@ -487,20 +546,39 @@ export function getReqSerializers(): ReqSerializers<Api, ReqTypes> {
     {jsonCase: "eth2"}
   );
 
-  const produceBlock: ReqSerializers<Api, ReqTypes>["produceBlockV2"] = {
-    writeReq: (slot, randaoReveal, graffiti, feeRecipient) => ({
+  const produceBlockV3: ReqSerializers<Api, ReqTypes>["produceBlockV3"] = {
+    writeReq: (slot, randaoReveal, graffiti, skipRandaoVerification, opts) => ({
       params: {slot},
-      query: {randao_reveal: toHexString(randaoReveal), graffiti: toGraffitiHex(graffiti), fee_recipient: feeRecipient},
+      query: {
+        randao_reveal: toHexString(randaoReveal),
+        graffiti: toGraffitiHex(graffiti),
+        fee_recipient: opts?.feeRecipient,
+        skip_randao_verification: skipRandaoVerification,
+        builder_selection: opts?.builderSelection,
+        strict_fee_recipient_check: opts?.strictFeeRecipientCheck,
+      },
     }),
     parseReq: ({params, query}) => [
       params.slot,
       fromHexString(query.randao_reveal),
       fromGraffitiHex(query.graffiti),
-      query.fee_recipient,
+      query.skip_randao_verification,
+      {
+        feeRecipient: query.fee_recipient,
+        builderSelection: query.builder_selection as BuilderSelection,
+        strictFeeRecipientCheck: query.strict_fee_recipient_check,
+      },
     ],
     schema: {
       params: {slot: Schema.UintRequired},
-      query: {randao_reveal: Schema.StringRequired, graffiti: Schema.String, fee_recipient: Schema.String},
+      query: {
+        randao_reveal: Schema.StringRequired,
+        graffiti: Schema.String,
+        fee_recipient: Schema.String,
+        skip_randao_verification: Schema.Boolean,
+        builder_selection: Schema.String,
+        strict_fee_recipient_check: Schema.Boolean,
+      },
     },
   };
 
@@ -531,9 +609,10 @@ export function getReqSerializers(): ReqSerializers<Api, ReqTypes> {
       },
     },
 
-    produceBlock: produceBlock,
-    produceBlockV2: produceBlock,
-    produceBlindedBlock: produceBlock,
+    produceBlock: produceBlockV3 as ReqSerializers<Api, ReqTypes>["produceBlock"],
+    produceBlockV2: produceBlockV3 as ReqSerializers<Api, ReqTypes>["produceBlockV2"],
+    produceBlockV3,
+    produceBlindedBlock: produceBlockV3 as ReqSerializers<Api, ReqTypes>["produceBlindedBlock"],
 
     produceAttestationData: {
       writeReq: (index, slot) => ({query: {slot, committee_index: index}}),
@@ -641,23 +720,50 @@ export function getReturnTypes(): ReturnTypes<Api> {
     {jsonCase: "eth2"}
   );
 
+  const produceBlockOrContents = WithExecutionPayloadValue(
+    WithVersion<allForks.BeaconBlock | BlockContents>((fork: ForkName) =>
+      isForkBlobs(fork) ? AllForksBlockContentsResSerializer(() => fork) : ssz[fork].BeaconBlock
+    )
+  ) as TypeJson<ProduceBlockOrContentsRes>;
+  const produceBlindedBlockOrContents = WithExecutionPayloadValue(
+    WithVersion<allForks.BlindedBeaconBlock | BlindedBlockContents>((fork: ForkName) =>
+      isForkBlobs(fork)
+        ? AllForksBlindedBlockContentsResSerializer(() => fork)
+        : ssz.allForksBlinded[isForkExecution(fork) ? fork : ForkName.bellatrix].BeaconBlock
+    )
+  ) as TypeJson<ProduceBlindedBlockOrContentsRes>;
+
   return {
     getAttesterDuties: WithDependentRootExecutionOptimistic(ArrayOf(AttesterDuty)),
     getProposerDuties: WithDependentRootExecutionOptimistic(ArrayOf(ProposerDuty)),
     getSyncCommitteeDuties: ContainerDataExecutionOptimistic(ArrayOf(SyncDuty)),
-    produceBlock: WithBlockValue(ContainerData(ssz.phase0.BeaconBlock)),
-    produceBlockV2: WithBlockValue(
-      WithVersion<allForks.BeaconBlock | BlockContents>((fork: ForkName) =>
-        isForkBlobs(fork) ? AllForksBlockContentsResSerializer(() => fork) : ssz[fork].BeaconBlock
-      )
-    ),
-    produceBlindedBlock: WithBlockValue(
-      WithVersion<allForks.BlindedBeaconBlock | BlindedBlockContents>((fork: ForkName) =>
-        isForkBlobs(fork)
-          ? AllForksBlindedBlockContentsResSerializer(() => fork)
-          : ssz.allForksBlinded[isForkExecution(fork) ? fork : ForkName.bellatrix].BeaconBlock
-      )
-    ),
+
+    produceBlock: ContainerData(ssz.phase0.BeaconBlock),
+    produceBlockV2: produceBlockOrContents,
+    produceBlockV3: {
+      toJson: (data) => {
+        if (data.executionPayloadBlinded) {
+          return {
+            execution_payload_blinded: true,
+            ...(produceBlindedBlockOrContents.toJson(data) as Record<string, unknown>),
+          };
+        } else {
+          return {
+            execution_payload_blinded: false,
+            ...(produceBlockOrContents.toJson(data) as Record<string, unknown>),
+          };
+        }
+      },
+      fromJson: (data) => {
+        if ((data as {execution_payload_blinded: true}).execution_payload_blinded) {
+          return {executionPayloadBlinded: true, ...produceBlindedBlockOrContents.fromJson(data)};
+        } else {
+          return {executionPayloadBlinded: false, ...produceBlockOrContents.fromJson(data)};
+        }
+      },
+    },
+    produceBlindedBlock: produceBlindedBlockOrContents,
+
     produceAttestationData: ContainerData(ssz.phase0.AttestationData),
     produceSyncCommitteeContribution: ContainerData(ssz.altair.SyncCommitteeContribution),
     getAggregatedAttestation: ContainerData(ssz.phase0.Attestation),

packages/api/src/utils/schema.ts

@@ -34,6 +34,7 @@ export enum Schema {
   Object,
   ObjectArray,
   AnyArray,
+  Boolean,
 }
 
 /**
@@ -68,6 +69,9 @@ function getJsonSchemaItem(schema: Schema): JsonSchema {
 
     case Schema.AnyArray:
       return {type: "array"};
+
+    case Schema.Boolean:
+      return {type: "boolean"};
   }
 }
 

packages/api/src/utils/types.ts

@@ -29,7 +29,7 @@ export type RouteDef = {
 
 export type ReqGeneric = {
   params?: Record<string, string | number>;
-  query?: Record<string, string | number | (string | number)[]>;
+  query?: Record<string, string | number | boolean | (string | number)[]>;
   body?: any;
   headers?: Record<string, string[] | string | undefined>;
 };
@@ -179,18 +179,20 @@ export function WithExecutionOptimistic<T extends {data: unknown}>(
 }
 
 /**
- * SSZ factory helper to wrap an existing type with `{blockValue: Wei}`
+ * SSZ factory helper to wrap an existing type with `{executionPayloadValue: Wei}`
  */
-export function WithBlockValue<T extends {data: unknown}>(type: TypeJson<T>): TypeJson<T & {blockValue: bigint}> {
+export function WithExecutionPayloadValue<T extends {data: unknown}>(
+  type: TypeJson<T>
+): TypeJson<T & {executionPayloadValue: bigint}> {
   return {
-    toJson: ({blockValue, ...data}) => ({
+    toJson: ({executionPayloadValue, ...data}) => ({
       ...(type.toJson(data as unknown as T) as Record<string, unknown>),
-      block_value: blockValue.toString(),
+      execution_payload_value: executionPayloadValue.toString(),
     }),
-    fromJson: ({block_value, ...data}: T & {block_value: string}) => ({
+    fromJson: ({execution_payload_value, ...data}: T & {execution_payload_value: string}) => ({
       ...type.fromJson(data),
-      // For cross client usage where beacon or validator are of separate clients, blockValue could be missing
-      blockValue: BigInt(block_value ?? "0"),
+      // For cross client usage where beacon or validator are of separate clients, executionPayloadValue could be missing
+      executionPayloadValue: BigInt(execution_payload_value ?? "0"),
     }),
   };
 }

packages/api/test/unit/beacon/testData/validator.ts

@@ -45,19 +45,38 @@ export const testData: GenericServerTestCases<Api> = {
     },
   },
   produceBlock: {
-    args: [32000, randaoReveal, graffiti, feeRecipient],
-    res: {data: ssz.phase0.BeaconBlock.defaultValue(), blockValue: ssz.Wei.defaultValue()},
+    args: [32000, randaoReveal, graffiti],
+    res: {data: ssz.phase0.BeaconBlock.defaultValue()},
   },
   produceBlockV2: {
-    args: [32000, randaoReveal, graffiti, feeRecipient],
-    res: {data: ssz.altair.BeaconBlock.defaultValue(), version: ForkName.altair, blockValue: ssz.Wei.defaultValue()},
+    args: [32000, randaoReveal, graffiti],
+    res: {
+      data: ssz.altair.BeaconBlock.defaultValue(),
+      version: ForkName.altair,
+      executionPayloadValue: ssz.Wei.defaultValue(),
+    },
+  },
+  produceBlockV3: {
+    args: [
+      32000,
+      randaoReveal,
+      graffiti,
+      true,
+      {feeRecipient, builderSelection: undefined, strictFeeRecipientCheck: undefined},
+    ],
+    res: {
+      data: ssz.altair.BeaconBlock.defaultValue(),
+      version: ForkName.altair,
+      executionPayloadValue: ssz.Wei.defaultValue(),
+      executionPayloadBlinded: false,
+    },
   },
   produceBlindedBlock: {
-    args: [32000, randaoReveal, graffiti, feeRecipient],
+    args: [32000, randaoReveal, graffiti],
     res: {
       data: ssz.bellatrix.BlindedBeaconBlock.defaultValue(),
       version: ForkName.bellatrix,
-      blockValue: ssz.Wei.defaultValue(),
+      executionPayloadValue: ssz.Wei.defaultValue(),
     },
   },
   produceAttestationData: {

packages/api/test/utils/genericServerTest.ts

@@ -58,7 +58,13 @@ export function runGenericServerTest<
 
       // Assert server handler called with correct args
       expect(mockApi[routeId].callCount).to.equal(1, `mockApi[${routeId as string}] must be called once`);
-      expect(mockApi[routeId].getCall(0).args).to.deep.equal(testCase.args, `mockApi[${routeId as string}] wrong args`);
+
+      // if mock api args are > testcase args, there may be some undefined extra args parsed towards the end
+      // to obtain a match, ignore the extra args
+      expect(mockApi[routeId].getCall(0).args.slice(0, testCase.args.length)).to.deep.equal(
+        testCase.args,
+        `mockApi[${routeId as string}] wrong args`
+      );
 
       // Assert returned value is correct
       expect(res.response).to.deep.equal(testCase.res, "Wrong returned value");