@lodestar/api 1.45.0-dev.f535421f29 → 1.45.0-rc.0

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,
@@ -246,6 +248,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 +279,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 = {
   /**
@@ -482,8 +495,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 +659,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> {
@@ -972,17 +999,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 +1237,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/serdes.ts

@@ -75,6 +75,9 @@ export function fromValidatorIdsStr(ids?: string[]): (string | number)[] | undef
   return ids?.map((id) => (typeof id === "string" && id.startsWith("0x") ? id : fromU64Str(id)));
 }
 
+export const toBuilderIdsStr = toValidatorIdsStr;
+export const fromBuilderIdsStr = fromValidatorIdsStr;
+
 const GRAFFITI_HEX_LENGTH = 66;
 
 export function toGraffitiHex(utf8?: string): string | undefined {

package/src/utils/server/handler.ts

@@ -111,6 +111,11 @@ export function createFastifyHandler<E extends Endpoint>(
       resp.statusCode = response.status;
     }
 
+    // A 204 No Content response has no body
+    if (resp.statusCode === 204) {
+      return;
+    }
+
     switch (responseWireFormat) {
       case WireFormat.json: {
         const metaHeaders = definition.resp.meta.toHeadersObject(response?.meta);