@lodestar/api 1.50.0-dev.335476095e → 1.50.0-dev.3430a7cf04

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

@@ -6,6 +6,7 @@ import {
   BuilderStatus,
   CommitteeIndex,
   Epoch,
+  GeneralValidatorStatus,
   RootHex,
   Slot,
   StringType,
@@ -16,7 +17,8 @@ import {
   phase0,
   ssz,
 } from "@lodestar/types";
-import {JsonOnlyReq} from "../../../utils/codecs.js";
+import {JsonOnlyReq, WithVersion} from "../../../utils/codecs.js";
+import {getPostElectraForkTypes} from "../../../utils/fork.js";
 import {Endpoint, RequestCodec, RouteDefinitions, Schema} from "../../../utils/index.js";
 import {
   ExecutionOptimisticAndFinalizedCodec,
@@ -43,6 +45,12 @@ export type BuilderId = string | number;
 
 export type {BuilderStatus, ValidatorStatus};
 
+/**
+ * Beacon API `status` filter: oneOf [ValidatorStatus, enum [active, pending, exited, withdrawal]].
+ * https://github.com/ethereum/beacon-APIs/blob/master/apis/beacon/states/validators.yaml
+ */
+export type ValidatorStatusFilter = ValidatorStatus | GeneralValidatorStatus;
+
 export const RandaoResponseType = new ContainerType({
   randao: ssz.Root,
 });
@@ -91,6 +99,10 @@ export const EpochSyncCommitteeResponseType = new ContainerType(
   },
   {jsonCase: "eth2"}
 );
+export const PtcResponseType = new ContainerType({
+  slot: ssz.Slot,
+  validators: ssz.gloas.PayloadTimelinessCommittee,
+});
 export const ValidatorResponseListType = ArrayOf(ValidatorResponseType);
 export const BuilderResponseListType = ArrayOf(BuilderResponseType);
 export const ValidatorIdentitiesType = ArrayOf(ValidatorIdentityType);
@@ -104,6 +116,7 @@ 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 PtcResponse = ValueOf<typeof PtcResponseType>;
 
 export type ValidatorResponseList = ValueOf<typeof ValidatorResponseListType>;
 export type BuilderResponseList = ValueOf<typeof BuilderResponseListType>;
@@ -191,9 +204,9 @@ export type Endpoints = {
       /** Either hex encoded public key (with 0x prefix) or validator index */
       validatorIds?: ValidatorId[];
       /** [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ) */
-      statuses?: ValidatorStatus[];
+      statuses?: ValidatorStatusFilter[];
     },
-    {params: {state_id: string}; query: {id?: ValidatorId[]; status?: ValidatorStatus[]}},
+    {params: {state_id: string}; query: {id?: ValidatorId[]; status?: ValidatorStatusFilter[]}},
     ValidatorResponseList,
     ExecutionOptimisticAndFinalizedMeta
   >;
@@ -208,9 +221,9 @@ export type Endpoints = {
       /** Either hex encoded public key (with 0x prefix) or validator index */
       validatorIds?: ValidatorId[];
       /** [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ) */
-      statuses?: ValidatorStatus[];
+      statuses?: ValidatorStatusFilter[];
     },
-    {params: {state_id: string}; body: {ids?: string[]; statuses?: ValidatorStatus[]}},
+    {params: {state_id: string}; body: {ids?: string[]; statuses?: ValidatorStatusFilter[]}},
     ValidatorResponseList,
     ExecutionOptimisticAndFinalizedMeta
   >;
@@ -316,6 +329,19 @@ export type Endpoints = {
     ExecutionOptimisticAndFinalizedMeta
   >;
 
+  /**
+   * Get the payload timeliness committee for a slot from the given state.
+   *
+   * Defaults to the state's slot. Validator indices are returned in committee order and may contain duplicates.
+   */
+  getStatePtc: Endpoint<
+    "GET",
+    StateArgs & {slot?: Slot},
+    {params: {state_id: string}; query: {slot?: number}},
+    PtcResponse,
+    ExecutionOptimisticAndFinalizedMeta
+  >;
+
   /**
    * Get State Pending Deposits
    *
@@ -444,6 +470,22 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
         meta: ExecutionOptimisticAndFinalizedCodec,
       },
     },
+    getStatePtc: {
+      url: "/eth/v1/beacon/states/{state_id}/ptc",
+      method: "GET",
+      req: {
+        writeReq: ({stateId, slot}) => ({params: {state_id: stateId.toString()}, query: {slot}}),
+        parseReq: ({params, query}) => ({stateId: params.state_id, slot: query.slot}),
+        schema: {
+          params: {state_id: Schema.StringRequired},
+          query: {slot: Schema.Uint},
+        },
+      },
+      resp: {
+        data: PtcResponseType,
+        meta: ExecutionOptimisticAndFinalizedCodec,
+      },
+    },
     getStateFinalityCheckpoints: {
       url: "/eth/v1/beacon/states/{state_id}/finality_checkpoints",
       method: "GET",
@@ -642,7 +684,7 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
       method: "GET",
       req: stateIdOnlyReq,
       resp: {
-        data: ssz.electra.PendingDeposits,
+        data: WithVersion((fork) => getPostElectraForkTypes(fork).PendingDeposits),
         meta: ExecutionOptimisticFinalizedAndVersionCodec,
       },
     },
@@ -651,7 +693,7 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
       method: "GET",
       req: stateIdOnlyReq,
       resp: {
-        data: ssz.electra.PendingPartialWithdrawals,
+        data: WithVersion((fork) => getPostElectraForkTypes(fork).PendingPartialWithdrawals),
         meta: ExecutionOptimisticFinalizedAndVersionCodec,
       },
     },
@@ -660,7 +702,7 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
       method: "GET",
       req: stateIdOnlyReq,
       resp: {
-        data: ssz.electra.PendingConsolidations,
+        data: WithVersion((fork) => getPostElectraForkTypes(fork).PendingConsolidations),
         meta: ExecutionOptimisticFinalizedAndVersionCodec,
       },
     },

package/src/beacon/routes/debug.ts

@@ -80,40 +80,52 @@ const ForkChoiceResponseType = new ContainerType(
 
 const ForkChoiceNodeV2ExtraDataType = new ContainerType(
   {
+    attestationScore: ssz.Gwei,
     executionOptimistic: ssz.Boolean,
+    gasLimit: new OptionalType(ssz.UintNum64),
     timestamp: ssz.UintNum64,
+    stateRoot: stringType,
     target: stringType,
-    justifiedEpoch: ssz.Epoch,
-    finalizedEpoch: ssz.Epoch,
     unrealizedJustifiedEpoch: ssz.Epoch,
+    unrealizedJustifiedRoot: stringType,
     unrealizedFinalizedEpoch: ssz.Epoch,
-    payloadAttesterCount: new OptionalType(ssz.UintNum64),
-    payloadAvailabilityYesCount: new OptionalType(ssz.UintNum64),
-    payloadDataAvailabilityYesCount: new OptionalType(ssz.UintNum64),
-    gasLimit: new OptionalType(ssz.UintNum64),
+    unrealizedFinalizedRoot: stringType,
   },
   {jsonCase: "eth2"}
 );
+const payloadStatusType = new StringType<"pending" | "empty" | "full">();
 const ForkChoiceNodeV2Type = new ContainerType(
   {
-    payloadStatus: new StringType<"pending" | "empty" | "full">(),
     slot: ssz.Slot,
     blockRoot: stringType,
+    payloadStatus: payloadStatusType,
     parentRoot: stringType,
+    parentPayloadStatus: new OptionalType(payloadStatusType),
+    justifiedCheckpoint: ssz.phase0.Checkpoint,
+    finalizedCheckpoint: ssz.phase0.Checkpoint,
     weight: ssz.Gwei,
     validity: new StringType<"valid" | "invalid" | "optimistic">(),
     executionBlockHash: stringType,
+    payloadAttesterCount: ssz.UintNum64,
+    payloadAvailabilityYesCount: ssz.UintNum64,
+    payloadDataAvailabilityYesCount: ssz.UintNum64,
     extraData: ForkChoiceNodeV2ExtraDataType,
   },
   {jsonCase: "eth2"}
 );
 const ForkChoiceExtraDataType = new ContainerType(
   {
-    unrealizedJustifiedCheckpoint: ssz.phase0.Checkpoint,
-    unrealizedFinalizedCheckpoint: ssz.phase0.Checkpoint,
+    head: new ContainerType(
+      {
+        blockRoot: stringType,
+        payloadStatus: payloadStatusType,
+      },
+      {jsonCase: "eth2"}
+    ),
     proposerBoostRoot: stringType,
     previousProposerBoostRoot: stringType,
-    headRoot: stringType,
+    unrealizedJustifiedCheckpoint: ssz.phase0.Checkpoint,
+    unrealizedFinalizedCheckpoint: ssz.phase0.Checkpoint,
   },
   {jsonCase: "eth2"}
 );
@@ -255,14 +267,6 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
         data: ForkChoiceResponseV2Type,
         meta: EmptyMetaCodec,
         onlySupport: WireFormat.json,
-        transform: {
-          toResponse: (data) => ({
-            ...(data as ForkChoiceResponseV2),
-          }),
-          fromResponse: (resp) => ({
-            data: resp as ForkChoiceResponseV2,
-          }),
-        },
       },
     },
     getProtoArrayNodes: {

package/src/beacon/routes/events.ts

@@ -270,6 +270,8 @@ type EventstreamArgs = {
   topics: EventType[];
   signal: AbortSignal;
   onEvent: (event: BeaconEvent) => void;
+  /** Called every time the connection is established, including reconnects */
+  onOpen?: () => void;
   onError?: (err: Error) => void;
   onClose?: () => void;
 };

package/src/beacon/routes/lodestar.ts

@@ -11,6 +11,7 @@ import {
   Slot,
   ValidatorIndex,
   ssz,
+  sszTypesFor,
 } from "@lodestar/types";
 import {
   EmptyArgs,
@@ -672,13 +673,13 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           if (signedBlocks.length === 0) throw new Error("No blocks provided.");
           const fork = config.getForkName(signedBlocks[0].message.slot);
           return {
-            body: ArrayOf(ssz[fork].SignedBeaconBlock).toJson(signedBlocks as SignedBeaconBlock<typeof fork>[]),
+            body: ArrayOf(sszTypesFor(fork).SignedBeaconBlock).toJson(signedBlocks),
             headers: {[MetaHeader.Version]: fork},
           };
         },
         parseReqJson: ({body, headers}) => {
           const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
-          const signedBlocks = ArrayOf(ssz[fork].SignedBeaconBlock).fromJson(body) as SignedBeaconBlock[];
+          const signedBlocks = ArrayOf(sszTypesFor(fork).SignedBeaconBlock).fromJson(body);
           assertBlocksMatchFork(signedBlocks, fork);
           return {signedBlocks};
         },
@@ -686,13 +687,13 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           if (signedBlocks.length === 0) throw new Error("No blocks provided.");
           const fork = config.getForkName(signedBlocks[0].message.slot);
           return {
-            body: ArrayOf(ssz[fork].SignedBeaconBlock).serialize(signedBlocks as SignedBeaconBlock<typeof fork>[]),
+            body: ArrayOf(sszTypesFor(fork).SignedBeaconBlock).serialize(signedBlocks),
             headers: {[MetaHeader.Version]: fork},
           };
         },
         parseReqSsz: ({body, headers}) => {
           const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
-          const signedBlocks = ArrayOf(ssz[fork].SignedBeaconBlock).deserialize(body) as SignedBeaconBlock[];
+          const signedBlocks = ArrayOf(sszTypesFor(fork).SignedBeaconBlock).deserialize(body);
           assertBlocksMatchFork(signedBlocks, fork);
           return {signedBlocks};
         },

package/src/index.ts

@@ -1,6 +1,6 @@
 // Re-exporting beacon only for backwards compatibility
 export * from "./beacon/index.js";
-export {ApiError} from "./utils/client/error.js";
+export {ApiError, type ApiFailure} from "./utils/client/error.js";
 export type {
   ApiClientMethods,
   HttpClientModules,

package/src/utils/client/error.ts

@@ -1,10 +1,16 @@
+/** Failure of a single item of a batch request, `index` refers to the submitted array */
+export type ApiFailure = {index: number; message: string};
+
 export class ApiError extends Error {
   status: number;
   operationId: string;
+  /** Set if the server rejected only some items of a batch request */
+  failures?: ApiFailure[];
 
-  constructor(message: string, status: number, operationId: string) {
+  constructor(message: string, status: number, operationId: string, failures?: ApiFailure[]) {
     super(`${operationId} failed with status ${status}: ${message}`);
     this.status = status;
     this.operationId = operationId;
+    this.failures = failures;
   }
 }

package/src/utils/client/response.ts

@@ -2,7 +2,7 @@ import {HeadersExtra, HttpHeader, parseContentTypeHeader} from "../headers.js";
 import {HttpStatusCode} from "../httpStatusCode.js";
 import {Endpoint} from "../types.js";
 import {WireFormat, getWireFormat} from "../wireFormat.js";
-import {ApiError} from "./error.js";
+import {ApiError, ApiFailure} from "./error.js";
 import {RouteDefinitionExtra} from "./request.js";
 
 export type RawBody =
@@ -162,7 +162,8 @@ export class ApiResponse<E extends Endpoint> extends Response {
       return null;
     }
 
-    return new ApiError(this.getErrorMessage(), this.status, this.definition.operationId);
+    const {message, failures} = this.parseErrorBody();
+    return new ApiError(message, this.status, this.definition.operationId, failures);
   }
 
   async errorBody(): Promise<string> {
@@ -187,19 +188,22 @@ export class ApiResponse<E extends Endpoint> extends Response {
     return this._errorBody;
   }
 
-  private getErrorMessage(): string {
+  private parseErrorBody(): {message: string; failures?: ApiFailure[]} {
     const errBody = this.resolvedErrorBody();
     try {
-      const errJson = JSON.parse(errBody) as {message?: string; failures?: {message: string}[]};
+      const errJson = JSON.parse(errBody) as {message?: string; failures?: ApiFailure[]};
       if (errJson.message) {
-        if (errJson.failures) {
-          return `${errJson.message}\n` + errJson.failures.map((e) => e.message).join("\n");
+        if (Array.isArray(errJson.failures)) {
+          return {
+            message: `${errJson.message}\n` + errJson.failures.map((e) => e.message).join("\n"),
+            failures: errJson.failures,
+          };
         }
-        return errJson.message;
+        return {message: errJson.message};
       }
-      return errBody;
+      return {message: errBody};
     } catch (_e) {
-      return errBody || this.statusText;
+      return {message: errBody || this.statusText};
     }
   }
 }

package/src/utils/fork.ts

@@ -3,10 +3,12 @@ import {
   ForkPostAltair,
   ForkPostBellatrix,
   ForkPostDeneb,
+  ForkPostElectra,
   ForkPostGloas,
   isForkPostAltair,
   isForkPostBellatrix,
   isForkPostDeneb,
+  isForkPostElectra,
   isForkPostGloas,
 } from "@lodestar/params";
 import {SSZTypesFor, sszTypesFor} from "@lodestar/types";
@@ -45,6 +47,14 @@ export function getPostDenebForkTypes(fork: ForkName): SSZTypesFor<ForkPostDeneb
   return sszTypesFor(fork);
 }
 
+export function getPostElectraForkTypes(fork: ForkName): SSZTypesFor<ForkPostElectra> {
+  if (!isForkPostElectra(fork)) {
+    throw Error(`Invalid fork=${fork} for post-electra fork types`);
+  }
+
+  return sszTypesFor(fork);
+}
+
 export function getPostGloasForkTypes(fork: ForkName): SSZTypesFor<ForkPostGloas> {
   if (!isForkPostGloas(fork)) {
     throw Error(`Invalid fork=${fork} for post-gloas fork types`);