@lodestar/api 1.45.0-dev.51a1c44b27 → 1.45.0-dev.6568180f96

package/src/beacon/routes/beacon/block.ts

@@ -18,6 +18,7 @@ import {
   Slot,
   deneb,
   gloas,
+  isSignedExecutionPayloadEnvelopeContents,
   ssz,
   sszTypesFor,
 } from "@lodestar/types";
@@ -32,6 +33,7 @@ import {
   ExecutionOptimisticFinalizedAndVersionMeta,
   MetaHeader,
 } from "../../../utils/metadata.js";
+import {toBoolean} from "../../../utils/serdes.js";
 import {WireFormat} from "../../../utils/wireFormat.js";
 
 export const BlockHeaderResponseType = new ContainerType({
@@ -187,11 +189,22 @@ export type Endpoints = {
    * Instructs the beacon node to broadcast a signed execution payload envelope to the network,
    * to be gossiped for payload validation. A success response (20x) indicates that the envelope
    * passed gossip validation and was successfully broadcast onto the network.
+   *
+   * The request body is either a `SignedExecutionPayloadEnvelopeContents` (envelope with blobs
+   * and KZG proofs, stateless flow) or a `SignedExecutionPayloadEnvelope` (stateful flow,
+   * the beacon node attaches blobs and KZG proofs from its block production cache).
    */
   publishExecutionPayloadEnvelope: Endpoint<
     "POST",
-    {signedExecutionPayloadEnvelope: gloas.SignedExecutionPayloadEnvelope},
-    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    {
+      signedEnvelopeOrContents: gloas.SignedExecutionPayloadEnvelopeContents | gloas.SignedExecutionPayloadEnvelope;
+      broadcastValidation?: BroadcastValidation;
+    },
+    {
+      body: unknown;
+      headers: {[MetaHeader.Version]: string; [MetaHeader.BlobDataIncluded]: string};
+      query: {broadcast_validation?: string};
+    },
     EmptyResponseData,
     EmptyMeta
   >;
@@ -453,40 +466,64 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       url: "/eth/v1/beacon/execution_payload_envelopes",
       method: "POST",
       req: {
-        writeReqJson: ({signedExecutionPayloadEnvelope}) => {
-          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.payload.slotNumber);
+        writeReqJson: ({signedEnvelopeOrContents, broadcastValidation}) => {
+          const blobDataIncluded = isSignedExecutionPayloadEnvelopeContents(signedEnvelopeOrContents);
+          const fork = config.getForkName(
+            (blobDataIncluded ? signedEnvelopeOrContents.signedExecutionPayloadEnvelope : signedEnvelopeOrContents)
+              .message.payload.slotNumber
+          );
           return {
-            body: getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.toJson(signedExecutionPayloadEnvelope),
+            body: blobDataIncluded
+              ? getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelopeContents.toJson(signedEnvelopeOrContents)
+              : getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.toJson(signedEnvelopeOrContents),
             headers: {
               [MetaHeader.Version]: fork,
+              [MetaHeader.BlobDataIncluded]: blobDataIncluded.toString(),
             },
+            query: {broadcast_validation: broadcastValidation},
           };
         },
-        parseReqJson: ({body, headers}) => {
+        parseReqJson: ({body, headers, query}) => {
           const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          const blobDataIncluded = toBoolean(fromHeaders(headers, MetaHeader.BlobDataIncluded));
           return {
-            signedExecutionPayloadEnvelope: getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.fromJson(body),
+            signedEnvelopeOrContents: blobDataIncluded
+              ? getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelopeContents.fromJson(body)
+              : getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.fromJson(body),
+            broadcastValidation: query.broadcast_validation as BroadcastValidation,
           };
         },
-        writeReqSsz: ({signedExecutionPayloadEnvelope}) => {
-          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.payload.slotNumber);
+        writeReqSsz: ({signedEnvelopeOrContents, broadcastValidation}) => {
+          const blobDataIncluded = isSignedExecutionPayloadEnvelopeContents(signedEnvelopeOrContents);
+          const fork = config.getForkName(
+            (blobDataIncluded ? signedEnvelopeOrContents.signedExecutionPayloadEnvelope : signedEnvelopeOrContents)
+              .message.payload.slotNumber
+          );
           return {
-            body: getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.serialize(signedExecutionPayloadEnvelope),
+            body: blobDataIncluded
+              ? getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelopeContents.serialize(signedEnvelopeOrContents)
+              : getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.serialize(signedEnvelopeOrContents),
             headers: {
               [MetaHeader.Version]: fork,
+              [MetaHeader.BlobDataIncluded]: blobDataIncluded.toString(),
             },
+            query: {broadcast_validation: broadcastValidation},
           };
         },
-        parseReqSsz: ({body, headers}) => {
+        parseReqSsz: ({body, headers, query}) => {
           const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          const blobDataIncluded = toBoolean(fromHeaders(headers, MetaHeader.BlobDataIncluded));
           return {
-            signedExecutionPayloadEnvelope:
-              getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.deserialize(body),
+            signedEnvelopeOrContents: blobDataIncluded
+              ? getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelopeContents.deserialize(body)
+              : getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.deserialize(body),
+            broadcastValidation: query.broadcast_validation as BroadcastValidation,
           };
         },
         schema: {
           body: Schema.Object,
-          headers: {[MetaHeader.Version]: Schema.String},
+          query: {broadcast_validation: Schema.String},
+          headers: {[MetaHeader.Version]: Schema.String, [MetaHeader.BlobDataIncluded]: Schema.String},
         },
       },
       resp: EmptyResponseCodec,

package/src/beacon/routes/beacon/index.ts

@@ -15,6 +15,9 @@ export type {BlockHeaderResponse, BlockId} from "./block.js";
 export {BroadcastValidation} from "./block.js";
 // TODO: Review if re-exporting all these types is necessary
 export type {
+  BuilderId,
+  BuilderResponse,
+  BuilderStatus,
   EpochCommitteeResponse,
   EpochSyncCommitteeResponse,
   FinalityCheckpoints,

package/src/beacon/routes/beacon/pool.ts

@@ -6,7 +6,6 @@ import {
   ForkPreElectra,
   MAX_PAYLOAD_ATTESTATIONS,
   PTC_SIZE,
-  SLOTS_PER_EPOCH,
   isForkPostElectra,
 } from "@lodestar/params";
 import {
@@ -47,12 +46,6 @@ const SignedBLSToExecutionChangeListType = ArrayOf(ssz.capella.SignedBLSToExecut
 const SyncCommitteeMessageListType = ArrayOf(ssz.altair.SyncCommitteeMessage);
 const PayloadAttestationListType = ArrayOf(ssz.gloas.PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS);
 const PayloadAttestationMessageListType = ArrayOf(ssz.gloas.PayloadAttestationMessage, PTC_SIZE);
-// 2 * SLOTS_PER_EPOCH max normally; getAll() may return up to 3 * SLOTS_PER_EPOCH during non-finality
-const MAX_PROPOSER_PREFERENCES_PER_REQUEST = 3 * SLOTS_PER_EPOCH;
-const SignedProposerPreferencesListType = ArrayOf(
-  ssz.gloas.SignedProposerPreferences,
-  MAX_PROPOSER_PREFERENCES_PER_REQUEST
-);
 
 type AttestationListPhase0 = ValueOf<typeof AttestationListTypePhase0>;
 type AttestationListElectra = ValueOf<typeof AttestationListTypeElectra>;
@@ -68,7 +61,6 @@ type SignedBLSToExecutionChangeList = ValueOf<typeof SignedBLSToExecutionChangeL
 type SyncCommitteeMessageList = ValueOf<typeof SyncCommitteeMessageListType>;
 type PayloadAttestationList = ValueOf<typeof PayloadAttestationListType>;
 type PayloadAttestationMessageList = ValueOf<typeof PayloadAttestationMessageListType>;
-type SignedProposerPreferencesList = ValueOf<typeof SignedProposerPreferencesListType>;
 
 export type Endpoints = {
   /**
@@ -95,18 +87,6 @@ export type Endpoints = {
     VersionMeta
   >;
 
-  /**
-   * Get signed proposer preferences from operations pool
-   * Retrieves proposer preferences known by the node but not necessarily incorporated into any block.
-   */
-  getPoolProposerPreferences: Endpoint<
-    "GET",
-    {slot?: Slot},
-    {query: {slot?: number}},
-    SignedProposerPreferencesList,
-    VersionMeta
-  >;
-
   /**
    * Get AttesterSlashings from operations pool
    * Retrieves attester slashings known by the node but not necessarily incorporated into any block
@@ -246,18 +226,6 @@ export type Endpoints = {
     EmptyResponseData,
     EmptyMeta
   >;
-
-  /**
-   * Submit signed proposer preferences
-   * Submits signed proposer preferences to the beacon node.
-   */
-  submitSignedProposerPreferences: Endpoint<
-    "POST",
-    {signedProposerPreferences: SignedProposerPreferencesList},
-    {body: unknown; headers: {[MetaHeader.Version]: string}},
-    EmptyResponseData,
-    EmptyMeta
-  >;
 };
 
 export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
@@ -288,19 +256,6 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         meta: VersionCodec,
       },
     },
-    getPoolProposerPreferences: {
-      url: "/eth/v1/beacon/pool/proposer_preferences",
-      method: "GET",
-      req: {
-        writeReq: ({slot}) => ({query: {slot}}),
-        parseReq: ({query}) => ({slot: query.slot}),
-        schema: {query: {slot: Schema.Uint}},
-      },
-      resp: {
-        data: SignedProposerPreferencesListType,
-        meta: VersionCodec,
-      },
-    },
     getPoolAttesterSlashingsV2: {
       url: "/eth/v2/beacon/pool/attester_slashings",
       method: "GET",
@@ -516,32 +471,5 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       },
       resp: EmptyResponseCodec,
     },
-    submitSignedProposerPreferences: {
-      url: "/eth/v1/beacon/pool/proposer_preferences",
-      method: "POST",
-      req: {
-        writeReqJson: ({signedProposerPreferences}) => ({
-          body: SignedProposerPreferencesListType.toJson(signedProposerPreferences),
-          headers: {[MetaHeader.Version]: ForkName.gloas},
-        }),
-        parseReqJson: ({body, headers}) => {
-          toForkName(fromHeaders(headers, MetaHeader.Version));
-          return {signedProposerPreferences: SignedProposerPreferencesListType.fromJson(body)};
-        },
-        writeReqSsz: ({signedProposerPreferences}) => ({
-          body: SignedProposerPreferencesListType.serialize(signedProposerPreferences),
-          headers: {[MetaHeader.Version]: ForkName.gloas},
-        }),
-        parseReqSsz: ({body, headers}) => {
-          toForkName(fromHeaders(headers, MetaHeader.Version));
-          return {signedProposerPreferences: SignedProposerPreferencesListType.deserialize(body)};
-        },
-        schema: {
-          body: Schema.ObjectArray,
-          headers: {[MetaHeader.Version]: Schema.String},
-        },
-      },
-      resp: EmptyResponseCodec,
-    },
   };
 }

package/src/beacon/routes/beacon/state.ts

@@ -3,6 +3,7 @@ import {ChainForkConfig} from "@lodestar/config";
 import {MAX_VALIDATORS_PER_COMMITTEE} from "@lodestar/params";
 import {
   ArrayOf,
+  BuilderStatus,
   CommitteeIndex,
   Epoch,
   RootHex,
@@ -22,7 +23,7 @@ import {
   ExecutionOptimisticFinalizedAndVersionCodec,
   ExecutionOptimisticFinalizedAndVersionMeta,
 } from "../../../utils/metadata.js";
-import {fromValidatorIdsStr, toValidatorIdsStr} from "../../../utils/serdes.js";
+import {fromBuilderIdsStr, fromValidatorIdsStr, toBuilderIdsStr, toValidatorIdsStr} from "../../../utils/serdes.js";
 import {WireFormat} from "../../../utils/wireFormat.js";
 import {RootResponse, RootResponseType} from "./block.js";
 
@@ -37,8 +38,9 @@ export type StateArgs = {
 };
 
 export type ValidatorId = string | number;
+export type BuilderId = string | number;
 
-export type {ValidatorStatus};
+export type {BuilderStatus, ValidatorStatus};
 
 export const RandaoResponseType = new ContainerType({
   randao: ssz.Root,
@@ -57,6 +59,11 @@ export const ValidatorResponseType = new ContainerType({
   status: new StringType<ValidatorStatus>(),
   validator: ssz.phase0.Validator,
 });
+export const BuilderResponseType = new ContainerType({
+  index: ssz.BuilderIndex,
+  status: new StringType<BuilderStatus>(),
+  builder: ssz.gloas.Builder,
+});
 export const ValidatorIdentityType = new ContainerType(
   {
     index: ssz.ValidatorIndex,
@@ -84,6 +91,7 @@ export const EpochSyncCommitteeResponseType = new ContainerType(
   {jsonCase: "eth2"}
 );
 export const ValidatorResponseListType = ArrayOf(ValidatorResponseType);
+export const BuilderResponseListType = ArrayOf(BuilderResponseType);
 export const ValidatorIdentitiesType = ArrayOf(ValidatorIdentityType);
 export const EpochCommitteeResponseListType = ArrayOf(EpochCommitteeResponseType);
 export const ValidatorBalanceListType = ArrayOf(ValidatorBalanceType);
@@ -91,11 +99,13 @@ export const ValidatorBalanceListType = ArrayOf(ValidatorBalanceType);
 export type RandaoResponse = ValueOf<typeof RandaoResponseType>;
 export type FinalityCheckpoints = ValueOf<typeof FinalityCheckpointsType>;
 export type ValidatorResponse = ValueOf<typeof ValidatorResponseType>;
+export type BuilderResponse = ValueOf<typeof BuilderResponseType>;
 export type EpochCommitteeResponse = ValueOf<typeof EpochCommitteeResponseType>;
 export type ValidatorBalance = ValueOf<typeof ValidatorBalanceType>;
 export type EpochSyncCommitteeResponse = ValueOf<typeof EpochSyncCommitteeResponseType>;
 
 export type ValidatorResponseList = ValueOf<typeof ValidatorResponseListType>;
+export type BuilderResponseList = ValueOf<typeof BuilderResponseListType>;
 export type ValidatorIdentities = ValueOf<typeof ValidatorIdentitiesType>;
 export type EpochCommitteeResponseList = ValueOf<typeof EpochCommitteeResponseListType>;
 export type ValidatorBalanceList = ValueOf<typeof ValidatorBalanceListType>;
@@ -204,6 +214,30 @@ export type Endpoints = {
     ExecutionOptimisticAndFinalizedMeta
   >;
 
+  /**
+   * Get builders from state
+   *
+   * Returns filterable list of builders with their status and index.
+   *
+   * Information will be returned for all indices or public keys that match known builders. If an index or public key does not
+   * match any known builder, no information will be returned but this will not cause an error. There are no guarantees for the
+   * returned data in terms of ordering; both the index and public key are returned for each builder, and can be used to confirm
+   * for which inputs a response has been returned.
+   *
+   * Returns 400 if the requested state is prior to Gloas.
+   */
+  getStateBuilders: Endpoint<
+    "POST",
+    StateArgs & {
+      /** Either hex encoded public key (any bytes48 with 0x prefix) or builder index */
+      builderIds?: BuilderId[];
+      statuses?: BuilderStatus[];
+    },
+    {params: {state_id: string}; body: {ids?: string[]; statuses?: BuilderStatus[]}},
+    BuilderResponseList,
+    ExecutionOptimisticAndFinalizedMeta
+  >;
+
   /**
    * Get validator identities from state
    *
@@ -489,6 +523,33 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
         meta: ExecutionOptimisticAndFinalizedCodec,
       },
     },
+    getStateBuilders: {
+      url: "/eth/v1/beacon/states/{state_id}/builders",
+      method: "POST",
+      req: JsonOnlyReq({
+        writeReqJson: ({stateId, builderIds, statuses}) => ({
+          params: {state_id: stateId.toString()},
+          body: {
+            ids: toBuilderIdsStr(builderIds),
+            statuses,
+          },
+        }),
+        parseReqJson: ({params, body = {}}) => ({
+          stateId: params.state_id,
+          builderIds: fromBuilderIdsStr(body.ids),
+          statuses: body.statuses ?? undefined,
+        }),
+        schema: {
+          params: {state_id: Schema.StringRequired},
+          body: Schema.Object,
+        },
+      }),
+      resp: {
+        onlySupport: WireFormat.json,
+        data: BuilderResponseListType,
+        meta: ExecutionOptimisticAndFinalizedCodec,
+      },
+    },
     postStateValidatorIdentities: {
       url: "/eth/v1/beacon/states/{state_id}/validator_identities",
       method: "POST",

package/src/beacon/routes/events.ts

@@ -110,6 +110,8 @@ export enum EventType {
   executionPayloadBid = "execution_payload_bid",
   /** The node has received a `SignedProposerPreferences` (from P2P or API) that passes gossip validation on the `proposer_preferences` topic */
   proposerPreferences = "proposer_preferences",
+  /** The node has received a `PayloadAttestationMessage` (from P2P or API) that passes validation rules of the `payload_attestation_message` topic */
+  payloadAttestationMessage = "payload_attestation_message",
   /** The node has executed the Fast Confirmation Rule and produced a confirmed beacon block */
   fastConfirmation = "fast_confirmation",
 }
@@ -137,6 +139,7 @@ export const eventTypes: {[K in EventType]: K} = {
   [EventType.executionPayloadAvailable]: EventType.executionPayloadAvailable,
   [EventType.executionPayloadBid]: EventType.executionPayloadBid,
   [EventType.proposerPreferences]: EventType.proposerPreferences,
+  [EventType.payloadAttestationMessage]: EventType.payloadAttestationMessage,
   [EventType.fastConfirmation]: EventType.fastConfirmation,
 };
 
@@ -206,6 +209,7 @@ export type EventData = {
   };
   [EventType.executionPayloadBid]: {version: ForkName; data: gloas.SignedExecutionPayloadBid};
   [EventType.proposerPreferences]: {version: ForkName; data: gloas.SignedProposerPreferences};
+  [EventType.payloadAttestationMessage]: {version: ForkName; data: gloas.PayloadAttestationMessage};
   [EventType.fastConfirmation]: {
     block: RootHex;
     slot: Slot;
@@ -408,6 +412,7 @@ export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: Type
     ),
     [EventType.executionPayloadBid]: WithVersion((fork) => getPostGloasForkTypes(fork).SignedExecutionPayloadBid),
     [EventType.proposerPreferences]: WithVersion((fork) => getPostGloasForkTypes(fork).SignedProposerPreferences),
+    [EventType.payloadAttestationMessage]: WithVersion((fork) => getPostGloasForkTypes(fork).PayloadAttestationMessage),
     [EventType.fastConfirmation]: new ContainerType(
       {
         block: stringType,

package/src/beacon/routes/node.ts

@@ -106,6 +106,7 @@ export enum NodeHealth {
  */
 export enum ClientCode {
   BU = "BU", // besu
+  CN = "CN", // caplin
   EJ = "EJ", // ethereumJS
   EG = "EG", // erigon
   EX = "EX", // ethrex
@@ -114,7 +115,8 @@ export enum ClientCode {
   LH = "LH", // lighthouse
   LS = "LS", // lodestar
   NM = "NM", // nethermind
-  NB = "NB", // nimbus
+  NB = "NB", // nimbus CL
+  NE = "NE", // nimbus EL
   TE = "TE", // trin-execution
   TK = "TK", // teku
   PM = "PM", // prysm

package/src/beacon/routes/validator.ts

@@ -4,6 +4,8 @@ import {
   ForkPostDeneb,
   ForkPostGloas,
   ForkPreDeneb,
+  MIN_SEED_LOOKAHEAD,
+  SLOTS_PER_EPOCH,
   VALIDATOR_REGISTRY_LIMIT,
   isForkPostDeneb,
   isForkPostElectra,
@@ -36,6 +38,7 @@ import {
   EmptyResponseCodec,
   EmptyResponseData,
   JsonOnlyReq,
+  WithMeta,
   WithVersion,
 } from "../../utils/codecs.js";
 import {getPostBellatrixForkTypes, getPostGloasForkTypes, toForkName} from "../../utils/fork.js";
@@ -96,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"}
 );
@@ -246,6 +253,10 @@ export const SignedValidatorRegistrationV1ListType = ArrayOf(
   ssz.bellatrix.SignedValidatorRegistrationV1,
   VALIDATOR_REGISTRY_LIMIT
 );
+export const SignedProposerPreferencesListType = ArrayOf(
+  ssz.gloas.SignedProposerPreferences,
+  (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH
+);
 
 export type ValidatorIndices = ValueOf<typeof ValidatorIndicesType>;
 export type AttesterDuty = ValueOf<typeof AttesterDutyType>;
@@ -273,6 +284,13 @@ export type SyncCommitteeSelectionList = ValueOf<typeof SyncCommitteeSelectionLi
 export type LivenessResponseData = ValueOf<typeof LivenessResponseDataType>;
 export type LivenessResponseDataList = ValueOf<typeof LivenessResponseDataListType>;
 export type SignedValidatorRegistrationV1List = ValueOf<typeof SignedValidatorRegistrationV1ListType>;
+export type SignedProposerPreferencesList = ValueOf<typeof SignedProposerPreferencesListType>;
+
+// The beacon node does not return any data if there is no canonical block at the requested slot (missed slot).
+// In this case, we receive a success response (204) which is not handled as an error. The generic response
+// handler already checks the status code and will not attempt to parse the body, but it will return no value.
+// It is important that this type indicates that there might be no value to ensure it is properly handled downstream.
+export type MaybePayloadAttestationData = gloas.PayloadAttestationData | undefined;
 
 export type Endpoints = {
   /**
@@ -408,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",
@@ -420,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};
@@ -431,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",
@@ -482,8 +510,8 @@ export type Endpoints = {
       /** The slot for which payload attestation data should be created */
       slot: Slot;
     },
-    {params: {slot: Slot}},
-    gloas.PayloadAttestationData,
+    {query: {slot: Slot}},
+    MaybePayloadAttestationData,
     VersionMeta
   >;
 
@@ -646,6 +674,20 @@ export type Endpoints = {
     EmptyResponseData,
     EmptyMeta
   >;
+
+  /**
+   * Submit signed proposer preferences
+   *
+   * Verifies given signed proposer preferences and publishes them on the `proposer_preferences`
+   * gossipsub topic. Supersedes `prepareBeaconProposer` and `registerValidator` from Gloas onwards.
+   */
+  submitProposerPreferences: Endpoint<
+    "POST",
+    {signedProposerPreferences: SignedProposerPreferencesList},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
 };
 
 export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
@@ -879,6 +921,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           builderSelection,
           builderBoostFactor,
           strictFeeRecipientCheck,
+          includePayload,
         }) => ({
           params: {slot},
           query: {
@@ -889,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}) => ({
@@ -900,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},
@@ -911,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)),
           }),
         },
       },
@@ -972,17 +1029,17 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       },
     },
     producePayloadAttestationData: {
-      url: "/eth/v1/validator/payload_attestation_data/{slot}",
+      url: "/eth/v1/validator/payload_attestation_data",
       method: "GET",
       req: {
-        writeReq: ({slot}) => ({params: {slot}}),
-        parseReq: ({params}) => ({slot: params.slot}),
+        writeReq: ({slot}) => ({query: {slot}}),
+        parseReq: ({query}) => ({slot: query.slot}),
         schema: {
-          params: {slot: Schema.UintRequired},
+          query: {slot: Schema.UintRequired},
         },
       },
       resp: {
-        data: ssz.gloas.PayloadAttestationData,
+        data: WithVersion<MaybePayloadAttestationData, VersionMeta>(() => ssz.gloas.PayloadAttestationData),
         meta: VersionCodec,
       },
     },
@@ -1210,6 +1267,33 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         requestWireFormat: WireFormat.ssz,
       },
     },
+    submitProposerPreferences: {
+      url: "/eth/v1/validator/proposer_preferences",
+      method: "POST",
+      req: {
+        writeReqJson: ({signedProposerPreferences}) => ({
+          body: SignedProposerPreferencesListType.toJson(signedProposerPreferences),
+          headers: {[MetaHeader.Version]: config.getForkName(signedProposerPreferences[0]?.message.proposalSlot ?? 0)},
+        }),
+        parseReqJson: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {signedProposerPreferences: SignedProposerPreferencesListType.fromJson(body)};
+        },
+        writeReqSsz: ({signedProposerPreferences}) => ({
+          body: SignedProposerPreferencesListType.serialize(signedProposerPreferences),
+          headers: {[MetaHeader.Version]: config.getForkName(signedProposerPreferences[0]?.message.proposalSlot ?? 0)},
+        }),
+        parseReqSsz: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {signedProposerPreferences: SignedProposerPreferencesListType.deserialize(body)};
+        },
+        schema: {
+          body: Schema.ObjectArray,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+    },
   };
 }
 

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 */