@lodestar/api 1.45.0 → 1.46.0-dev.4191d8e353

package/src/beacon/routes/events.ts

@@ -56,9 +56,23 @@ const gloasDataColumnSidecarSSE = new ContainerType(
   },
   {typeName: "DataColumnSidecarSSE", jsonCase: "eth2"}
 );
+const headV2 = new ContainerType(
+  {
+    slot: ssz.Slot,
+    block: stringType,
+    state: stringType,
+    payloadStatus: new StringType<"empty" | "full">(),
+    epochTransition: ssz.Boolean,
+    currentEpochDependentRoot: stringType,
+    nextEpochDependentRoot: stringType,
+    executionOptimistic: ssz.Boolean,
+  },
+  {typeName: "HeadV2", jsonCase: "eth2"}
+);
 type FuluDataColumnSidecarSSE = ValueOf<typeof fuluDataColumnSidecarSSE>;
 type GloasDataColumnSidecarSSE = ValueOf<typeof gloasDataColumnSidecarSSE>;
 type DataColumnSidecarSSE = FuluDataColumnSidecarSSE | GloasDataColumnSidecarSSE;
+type HeadV2 = ValueOf<typeof headV2>;
 
 export enum EventType {
   /**
@@ -68,6 +82,16 @@ export enum EventType {
    * Both dependent roots use the genesis block root in the case of underflow.
    */
   head = "head",
+  /**
+   * The node's fork choice has selected a new head consisting of a beacon block and its `payload_status`.
+   * The node should emit a second head event for the same beacon block and slot when there is an update
+   * in the `payload_status` from empty to full. Emission on other payload_status transitions (e.g. full to empty)
+   * is optional and implementation-defined. `slot` is the slot of the head block. `current_epoch_dependent_root`
+   * is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and `next_epoch_dependent_root`
+   * is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`, where `epoch` is obtained by
+   * `compute_epoch_at_slot(slot)`. All dependent roots use the genesis block root in the case of underflow.
+   */
+  headV2 = "head_v2",
   /** The node has received a block (from P2P or API) that is successfully imported on the fork-choice `on_block` handler */
   block = "block",
   /** The node has received a block (from P2P or API) that passes validation rules of the `beacon_block` topic */
@@ -118,6 +142,7 @@ export enum EventType {
 
 export const eventTypes: {[K in EventType]: K} = {
   [EventType.head]: EventType.head,
+  [EventType.headV2]: EventType.headV2,
   [EventType.block]: EventType.block,
   [EventType.blockGossip]: EventType.blockGossip,
   [EventType.attestation]: EventType.attestation,
@@ -153,6 +178,10 @@ export type EventData = {
     currentDutyDependentRoot: RootHex;
     executionOptimistic: boolean;
   };
+  [EventType.headV2]: {
+    version: ForkName;
+    data: HeadV2;
+  };
   [EventType.block]: {
     slot: Slot;
     block: RootHex;
@@ -299,6 +328,7 @@ export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: Type
       },
       {jsonCase: "eth2"}
     ),
+    [EventType.headV2]: WithVersion(() => headV2),
 
     [EventType.block]: new ContainerType(
       {

package/src/beacon/routes/validator.ts

@@ -38,6 +38,7 @@ import {
   EmptyResponseCodec,
   EmptyResponseData,
   JsonOnlyReq,
+  WithMeta,
   WithVersion,
 } from "../../utils/codecs.js";
 import {getPostBellatrixForkTypes, getPostGloasForkTypes, toForkName} from "../../utils/fork.js";
@@ -98,6 +99,10 @@ export const ProduceBlockV4MetaType = new ContainerType(
     ...VersionType.fields,
     /** Consensus rewards paid to the proposer for this block, in Wei */
     consensusBlockValue: ssz.UintBn64,
+    /** Local execution payload value when self-building, or builder bid value when committing to a bid, in Wei */
+    executionPayloadValue: ssz.UintBn64,
+    /** Specifies whether the response contains full block contents or only the beacon block */
+    executionPayloadIncluded: ssz.Boolean,
   },
   {jsonCase: "eth2"}
 );
@@ -421,6 +426,12 @@ export type Endpoints = {
    * Post-Gloas, proposers submit execution payload bids rather than full execution payloads,
    * so there is no longer a concept of blinded or unblinded blocks. Builders release the payload later.
    * This endpoint is specific to the post-Gloas forks and is not backwards compatible with previous forks.
+   *
+   * When self-building and `includePayload` is true, the response contains the full `BlockContents`
+   * (block, execution payload envelope, KZG proofs and blobs) which enables stateless envelope
+   * publishing via any beacon node. When `includePayload` is false, only the `BeaconBlock` is
+   * returned and the beacon node caches the envelope and blobs internally.
+   * When committing to a builder bid, only the `BeaconBlock` is returned in either case.
    */
   produceBlockV4: Endpoint<
     "GET",
@@ -433,6 +444,8 @@ export type Endpoints = {
       graffiti?: string;
       skipRandaoVerification?: boolean;
       builderBoostFactor?: UintBn64;
+      /** Include execution payload envelope and blobs in the response when self-building */
+      includePayload: boolean;
     } & Omit<ExtraProduceBlockOpts, "blindedLocal">,
     {
       params: {slot: number};
@@ -444,16 +457,18 @@ export type Endpoints = {
         builder_selection?: string;
         builder_boost_factor?: string;
         strict_fee_recipient_check?: boolean;
+        include_payload: boolean;
       };
     },
-    BeaconBlock<ForkPostGloas>,
+    BeaconBlock<ForkPostGloas> | BlockContents<ForkPostGloas>,
     ProduceBlockV4Meta
   >;
 
   /**
    * Get execution payload envelope.
-   * Retrieves execution payload envelope for a given slot and beacon block root.
-   * The envelope contains the full execution payload along with associated metadata.
+   * Retrieves the cached execution payload envelope for a given slot and beacon block root,
+   * to be signed and published via `publishExecutionPayloadEnvelope`.
+   * Used in the stateful (`includePayload=false`) local build flow.
    */
   getExecutionPayloadEnvelope: Endpoint<
     "GET",
@@ -906,6 +921,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           builderSelection,
           builderBoostFactor,
           strictFeeRecipientCheck,
+          includePayload,
         }) => ({
           params: {slot},
           query: {
@@ -916,6 +932,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
             builder_selection: builderSelection,
             builder_boost_factor: builderBoostFactor?.toString(),
             strict_fee_recipient_check: strictFeeRecipientCheck,
+            include_payload: includePayload,
           },
         }),
         parseReq: ({params, query}) => ({
@@ -927,6 +944,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           builderSelection: query.builder_selection as BuilderSelection,
           builderBoostFactor: parseBuilderBoostFactor(query.builder_boost_factor),
           strictFeeRecipientCheck: query.strict_fee_recipient_check,
+          includePayload: query.include_payload,
         }),
         schema: {
           params: {slot: Schema.UintRequired},
@@ -938,21 +956,33 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
             builder_selection: Schema.String,
             builder_boost_factor: Schema.String,
             strict_fee_recipient_check: Schema.Boolean,
+            include_payload: Schema.BooleanRequired,
           },
         },
       },
       resp: {
-        data: WithVersion((fork) => getPostGloasForkTypes(fork).BeaconBlock),
+        data: WithMeta(
+          ({version, executionPayloadIncluded}) =>
+            (executionPayloadIncluded
+              ? getPostGloasForkTypes(version).BlockContents
+              : getPostGloasForkTypes(version).BeaconBlock) as Type<
+              BeaconBlock<ForkPostGloas> | BlockContents<ForkPostGloas>
+            >
+        ),
         meta: {
           toJson: (meta) => ProduceBlockV4MetaType.toJson(meta),
           fromJson: (val) => ProduceBlockV4MetaType.fromJson(val),
           toHeadersObject: (meta) => ({
             [MetaHeader.Version]: meta.version,
             [MetaHeader.ConsensusBlockValue]: meta.consensusBlockValue.toString(),
+            [MetaHeader.ExecutionPayloadValue]: meta.executionPayloadValue.toString(),
+            [MetaHeader.ExecutionPayloadIncluded]: meta.executionPayloadIncluded.toString(),
           }),
           fromHeaders: (headers) => ({
             version: toForkName(headers.getRequired(MetaHeader.Version)),
             consensusBlockValue: BigInt(headers.getRequired(MetaHeader.ConsensusBlockValue)),
+            executionPayloadValue: BigInt(headers.getRequired(MetaHeader.ExecutionPayloadValue)),
+            executionPayloadIncluded: toBoolean(headers.getRequired(MetaHeader.ExecutionPayloadIncluded)),
           }),
         },
       },

package/src/utils/metadata.ts

@@ -74,8 +74,10 @@ export type ExecutionOptimisticAndDependentRootMeta = ValueOf<typeof ExecutionOp
 
 export enum MetaHeader {
   Version = "Eth-Consensus-Version",
+  BlobDataIncluded = "Eth-Blob-Data-Included",
   ConsensusBlockValue = "Eth-Consensus-Block-Value",
   ExecutionPayloadBlinded = "Eth-Execution-Payload-Blinded",
+  ExecutionPayloadIncluded = "Eth-Execution-Payload-Included",
   ExecutionPayloadValue = "Eth-Execution-Payload-Value",
 
   /* Lodestar-specific (non-standardized) headers */

package/src/utils/schema.ts

@@ -34,6 +34,7 @@ export enum Schema {
   ObjectArray,
   AnyArray,
   Boolean,
+  BooleanRequired,
 }
 
 /**
@@ -71,6 +72,7 @@ function getJsonSchemaItem(schema: Schema): JsonSchema {
       return {type: "array"};
 
     case Schema.Boolean:
+    case Schema.BooleanRequired:
       return {type: "boolean"};
   }
 }
@@ -81,6 +83,7 @@ function isRequired(schema: Schema): boolean {
     case Schema.StringRequired:
     case Schema.UintOrStringRequired:
     case Schema.StringArrayRequired:
+    case Schema.BooleanRequired:
       return true;
 
     default: