@lodestar/api 1.42.0-rc.0 → 1.43.0-dev.07452fe3b7

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

@@ -226,6 +226,18 @@ export type Endpoints = {
     EmptyMeta
   >;
 
+  /**
+   * Get signed execution payload envelope.
+   * Retrieves signed execution payload envelope for a given block id.
+   */
+  getSignedExecutionPayloadEnvelope: Endpoint<
+    "GET",
+    BlockArgs,
+    {params: {block_id: string}},
+    gloas.SignedExecutionPayloadEnvelope,
+    ExecutionOptimisticFinalizedAndVersionMeta
+  >;
+
   /**
    * Get block BlobSidecar
    * Retrieves BlobSidecar included in requested block.
@@ -594,7 +606,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       method: "POST",
       req: {
         writeReqJson: ({signedExecutionPayloadEnvelope}) => {
-          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.slot);
+          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.payload.slotNumber);
           return {
             body: getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.toJson(signedExecutionPayloadEnvelope),
             headers: {
@@ -609,7 +621,7 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
           };
         },
         writeReqSsz: ({signedExecutionPayloadEnvelope}) => {
-          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.slot);
+          const fork = config.getForkName(signedExecutionPayloadEnvelope.message.payload.slotNumber);
           return {
             body: getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope.serialize(signedExecutionPayloadEnvelope),
             headers: {
@@ -634,6 +646,15 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         requestWireFormat: WireFormat.ssz,
       },
     },
+    getSignedExecutionPayloadEnvelope: {
+      url: "/eth/v1/beacon/execution_payload_envelope/{block_id}",
+      method: "GET",
+      req: blockIdOnlyReq,
+      resp: {
+        data: WithVersion((fork) => getPostGloasForkTypes(fork).SignedExecutionPayloadEnvelope),
+        meta: ExecutionOptimisticFinalizedAndVersionCodec,
+      },
+    },
     getBlobSidecars: {
       url: "/eth/v1/beacon/blob_sidecars/{block_id}",
       method: "GET",

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

@@ -1,6 +1,13 @@
 import {ValueOf} from "@chainsafe/ssz";
 import {ChainForkConfig} from "@lodestar/config";
-import {ForkPostElectra, ForkPreElectra, isForkPostElectra} from "@lodestar/params";
+import {
+  ForkName,
+  ForkPostElectra,
+  ForkPreElectra,
+  MAX_PAYLOAD_ATTESTATIONS,
+  PTC_SIZE,
+  isForkPostElectra,
+} from "@lodestar/params";
 import {
   ArrayOf,
   AttesterSlashing,
@@ -37,6 +44,8 @@ const ProposerSlashingListType = ArrayOf(ssz.phase0.ProposerSlashing);
 const SignedVoluntaryExitListType = ArrayOf(ssz.phase0.SignedVoluntaryExit);
 const SignedBLSToExecutionChangeListType = ArrayOf(ssz.capella.SignedBLSToExecutionChange);
 const SyncCommitteeMessageListType = ArrayOf(ssz.altair.SyncCommitteeMessage);
+const PayloadAttestationListType = ArrayOf(ssz.gloas.PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS);
+const PayloadAttestationMessageListType = ArrayOf(ssz.gloas.PayloadAttestationMessage, PTC_SIZE);
 
 type AttestationListPhase0 = ValueOf<typeof AttestationListTypePhase0>;
 type AttestationListElectra = ValueOf<typeof AttestationListTypeElectra>;
@@ -50,6 +59,8 @@ type ProposerSlashingList = ValueOf<typeof ProposerSlashingListType>;
 type SignedVoluntaryExitList = ValueOf<typeof SignedVoluntaryExitListType>;
 type SignedBLSToExecutionChangeList = ValueOf<typeof SignedBLSToExecutionChangeListType>;
 type SyncCommitteeMessageList = ValueOf<typeof SyncCommitteeMessageListType>;
+type PayloadAttestationList = ValueOf<typeof PayloadAttestationListType>;
+type PayloadAttestationMessageList = ValueOf<typeof PayloadAttestationMessageListType>;
 
 export type Endpoints = {
   /**
@@ -76,6 +87,18 @@ export type Endpoints = {
     VersionMeta
   >;
 
+  /**
+   * Get payload attestations from operations pool
+   * Retrieves payload attestations known by the node but not necessarily incorporated into any block.
+   */
+  getPoolPayloadAttestations: Endpoint<
+    "GET",
+    {slot?: Slot},
+    {query: {slot?: number}},
+    PayloadAttestationList,
+    VersionMeta
+  >;
+
   /**
    * Get AttesterSlashings from operations pool
    * Retrieves attester slashings known by the node but not necessarily incorporated into any block
@@ -244,6 +267,18 @@ export type Endpoints = {
     EmptyResponseData,
     EmptyMeta
   >;
+
+  /**
+   * Submit payload attestation messages
+   * Submits payload attestation messages to the beacon node.
+   */
+  submitPayloadAttestationMessages: Endpoint<
+    "POST",
+    {payloadAttestationMessages: PayloadAttestationMessageList},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
 };
 
 export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
@@ -274,6 +309,19 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         meta: VersionCodec,
       },
     },
+    getPoolPayloadAttestations: {
+      url: "/eth/v1/beacon/pool/payload_attestations",
+      method: "GET",
+      req: {
+        writeReq: ({slot}) => ({query: {slot}}),
+        parseReq: ({query}) => ({slot: query.slot}),
+        schema: {query: {slot: Schema.Uint}},
+      },
+      resp: {
+        data: PayloadAttestationListType,
+        meta: VersionCodec,
+      },
+    },
     getPoolAttesterSlashings: {
       url: "/eth/v1/beacon/pool/attester_slashings",
       method: "GET",
@@ -499,5 +547,32 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       },
       resp: EmptyResponseCodec,
     },
+    submitPayloadAttestationMessages: {
+      url: "/eth/v1/beacon/pool/payload_attestations",
+      method: "POST",
+      req: {
+        writeReqJson: ({payloadAttestationMessages}) => ({
+          body: PayloadAttestationMessageListType.toJson(payloadAttestationMessages),
+          headers: {[MetaHeader.Version]: ForkName.gloas},
+        }),
+        parseReqJson: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {payloadAttestationMessages: PayloadAttestationMessageListType.fromJson(body)};
+        },
+        writeReqSsz: ({payloadAttestationMessages}) => ({
+          body: PayloadAttestationMessageListType.serialize(payloadAttestationMessages),
+          headers: {[MetaHeader.Version]: ForkName.gloas},
+        }),
+        parseReqSsz: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {payloadAttestationMessages: PayloadAttestationMessageListType.deserialize(body)};
+        },
+        schema: {
+          body: Schema.ObjectArray,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+    },
   };
 }

package/src/beacon/routes/events.ts

@@ -16,12 +16,13 @@ import {
   altair,
   capella,
   electra,
+  gloas,
   phase0,
   ssz,
   sszTypesFor,
 } from "@lodestar/types";
 import {EmptyMeta, EmptyResponseCodec, EmptyResponseData} from "../../utils/codecs.js";
-import {getPostAltairForkTypes, getPostBellatrixForkTypes} from "../../utils/fork.js";
+import {getPostAltairForkTypes, getPostBellatrixForkTypes, getPostGloasForkTypes} from "../../utils/fork.js";
 import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {VersionType} from "../../utils/metadata.js";
 
@@ -99,12 +100,14 @@ export enum EventType {
   blobSidecar = "blob_sidecar",
   /** The node has received a valid DataColumnSidecar (from P2P or API) */
   dataColumnSidecar = "data_column_sidecar",
-  /** The node has received an execution payload (from P2P or API) that is successfully imported on the fork-choice `on_execution_payload` handler */
+  /** The node has received a `SignedExecutionPayloadEnvelope` (from P2P or API) that is successfully imported on the fork-choice `on_execution_payload` handler */
   executionPayload = "execution_payload",
-  /** The node has received an execution payload (from P2P or API) that passes validation rules of the `execution_payload` topic */
+  /** The node has received a `SignedExecutionPayloadEnvelope` (from P2P or API) that passes validation rules of the `execution_payload` topic */
   executionPayloadGossip = "execution_payload_gossip",
   /** The node has verified that the execution payload and blobs for a block are available and ready for payload attestation */
   executionPayloadAvailable = "execution_payload_available",
+  /** The node has received a `SignedExecutionPayloadBid` (from P2P or API) that passes gossip validation on the `execution_payload_bid` topic */
+  executionPayloadBid = "execution_payload_bid",
 }
 
 export const eventTypes: {[K in EventType]: K} = {
@@ -128,6 +131,7 @@ export const eventTypes: {[K in EventType]: K} = {
   [EventType.executionPayload]: EventType.executionPayload,
   [EventType.executionPayloadGossip]: EventType.executionPayloadGossip,
   [EventType.executionPayloadAvailable]: EventType.executionPayloadAvailable,
+  [EventType.executionPayloadBid]: EventType.executionPayloadBid,
 };
 
 export type EventData = {
@@ -182,7 +186,6 @@ export type EventData = {
     builderIndex: BuilderIndex;
     blockHash: RootHex;
     blockRoot: RootHex;
-    stateRoot: RootHex;
     executionOptimistic: boolean;
   };
   [EventType.executionPayloadGossip]: {
@@ -190,12 +193,12 @@ export type EventData = {
     builderIndex: BuilderIndex;
     blockHash: RootHex;
     blockRoot: RootHex;
-    stateRoot: RootHex;
   };
   [EventType.executionPayloadAvailable]: {
     slot: Slot;
     blockRoot: RootHex;
   };
+  [EventType.executionPayloadBid]: {version: ForkName; data: gloas.SignedExecutionPayloadBid};
 };
 
 export type BeaconEvent = {[K in EventType]: {type: K; message: EventData[K]}}[EventType];
@@ -371,7 +374,6 @@ export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: Type
         builderIndex: ssz.BuilderIndex,
         blockHash: stringType,
         blockRoot: stringType,
-        stateRoot: stringType,
         executionOptimistic: ssz.Boolean,
       },
       {jsonCase: "eth2"}
@@ -382,7 +384,6 @@ export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: Type
         builderIndex: ssz.BuilderIndex,
         blockHash: stringType,
         blockRoot: stringType,
-        stateRoot: stringType,
       },
       {jsonCase: "eth2"}
     ),
@@ -393,6 +394,7 @@ export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: Type
       },
       {jsonCase: "eth2"}
     ),
+    [EventType.executionPayloadBid]: WithVersion((fork) => getPostGloasForkTypes(fork).SignedExecutionPayloadBid),
 
     [EventType.lightClientOptimisticUpdate]: WithVersion(
       (fork) => getPostAltairForkTypes(fork).LightClientOptimisticUpdate

package/src/beacon/routes/lodestar.ts

@@ -1,6 +1,17 @@
 import {ContainerType, Type, ValueOf} from "@chainsafe/ssz";
 import {ChainForkConfig} from "@lodestar/config";
-import {ArrayOf, BeaconState, Epoch, RootHex, Slot, ValidatorIndex, ssz} from "@lodestar/types";
+import {ForkName} from "@lodestar/params";
+import {
+  ArrayOf,
+  AttesterSlashing,
+  BeaconState,
+  Epoch,
+  RootHex,
+  SignedBeaconBlock,
+  Slot,
+  ValidatorIndex,
+  ssz,
+} from "@lodestar/types";
 import {
   EmptyArgs,
   EmptyMeta,
@@ -11,10 +22,13 @@ import {
   JsonOnlyResponseCodec,
   WithVersion,
 } from "../../utils/codecs.js";
+import {toForkName} from "../../utils/fork.js";
+import {fromHeaders} from "../../utils/headers.js";
 import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {
   ExecutionOptimisticFinalizedAndVersionCodec,
   ExecutionOptimisticFinalizedAndVersionMeta,
+  MetaHeader,
   VersionCodec,
   VersionMeta,
 } from "../../utils/metadata.js";
@@ -382,9 +396,27 @@ export type Endpoints = {
     CustodyInfo,
     EmptyMeta
   >;
+
+  /** Craft attester slashings from the attestations in the provided blocks */
+  getAttesterSlashingsFromBlocks: Endpoint<
+    "POST",
+    {signedBlocks: SignedBeaconBlock[]},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    AttesterSlashing[],
+    VersionMeta
+  >;
 };
 
-export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints> {
+export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  function assertBlocksMatchFork(signedBlocks: SignedBeaconBlock[], expectedFork: ForkName): void {
+    for (const block of signedBlocks) {
+      const blockFork = config.getForkName(block.message.slot);
+      if (blockFork !== expectedFork) {
+        throw new Error(`Block at slot ${block.message.slot} is from fork ${blockFork}, expected ${expectedFork}`);
+      }
+    }
+  }
+
   return {
     writeHeapdump: {
       url: "/eth/v1/lodestar/write_heapdump",
@@ -602,5 +634,47 @@ export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpo
       req: EmptyRequestCodec,
       resp: JsonOnlyResponseCodec,
     },
+    getAttesterSlashingsFromBlocks: {
+      url: "/eth/v1/lodestar/blocks/attester_slashings",
+      method: "POST",
+      req: {
+        writeReqJson: ({signedBlocks}) => {
+          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>[]),
+            headers: {[MetaHeader.Version]: fork},
+          };
+        },
+        parseReqJson: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          const signedBlocks = ArrayOf(ssz[fork].SignedBeaconBlock).fromJson(body) as SignedBeaconBlock[];
+          assertBlocksMatchFork(signedBlocks, fork);
+          return {signedBlocks};
+        },
+        writeReqSsz: ({signedBlocks}) => {
+          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>[]),
+            headers: {[MetaHeader.Version]: fork},
+          };
+        },
+        parseReqSsz: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          const signedBlocks = ArrayOf(ssz[fork].SignedBeaconBlock).deserialize(body) as SignedBeaconBlock[];
+          assertBlocksMatchFork(signedBlocks, fork);
+          return {signedBlocks};
+        },
+        schema: {
+          body: Schema.ObjectArray,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: {
+        data: WithVersion((fork) => ArrayOf(ssz[fork].AttesterSlashing)),
+        meta: VersionCodec,
+      },
+    },
   };
 }

package/src/beacon/routes/validator.ts

@@ -131,6 +131,18 @@ export const ProposerDutyType = new ContainerType(
   {jsonCase: "eth2"}
 );
 
+export const PtcDutyType = new ContainerType(
+  {
+    /** Public key of the validator in the registry  */
+    pubkey: ssz.BLSPubkey,
+    /** Index of validator in the registry. */
+    validatorIndex: ssz.ValidatorIndex,
+    /** The slot at which the validator must perform PTC duties. */
+    slot: ssz.Slot,
+  },
+  {jsonCase: "eth2"}
+);
+
 /**
  * From https://github.com/ethereum/beacon-APIs/pull/134
  */
@@ -219,6 +231,7 @@ export const LivenessResponseDataType = new ContainerType(
 export const ValidatorIndicesType = ArrayOf(ssz.ValidatorIndex);
 export const AttesterDutyListType = ArrayOf(AttesterDutyType);
 export const ProposerDutyListType = ArrayOf(ProposerDutyType);
+export const PtcDutyListType = ArrayOf(PtcDutyType);
 export const SyncDutyListType = ArrayOf(SyncDutyType);
 export const SignedAggregateAndProofListPhase0Type = ArrayOf(ssz.phase0.SignedAggregateAndProof);
 export const SignedAggregateAndProofListElectraType = ArrayOf(ssz.electra.SignedAggregateAndProof);
@@ -239,6 +252,8 @@ export type AttesterDuty = ValueOf<typeof AttesterDutyType>;
 export type AttesterDutyList = ValueOf<typeof AttesterDutyListType>;
 export type ProposerDuty = ValueOf<typeof ProposerDutyType>;
 export type ProposerDutyList = ValueOf<typeof ProposerDutyListType>;
+export type PtcDuty = ValueOf<typeof PtcDutyType>;
+export type PtcDutyList = ValueOf<typeof PtcDutyListType>;
 export type SyncDuty = ValueOf<typeof SyncDutyType>;
 export type SyncDutyList = ValueOf<typeof SyncDutyListType>;
 export type SignedAggregateAndProofListPhase0 = ValueOf<typeof SignedAggregateAndProofListPhase0Type>;
@@ -336,6 +351,23 @@ export type Endpoints = {
     ExecutionOptimisticMeta
   >;
 
+  /**
+   * Get PTC duties
+   * Requests the beacon node to provide a set of Payload Timeliness Committee duties for a particular epoch.
+   */
+  getPtcDuties: Endpoint<
+    "POST",
+    {
+      /** Must not be greater than the next epoch */
+      epoch: Epoch;
+      /** An array of the validator indices for which to obtain the duties */
+      indices: ValidatorIndices;
+    },
+    {params: {epoch: Epoch}; body: unknown},
+    PtcDutyList,
+    ExecutionOptimisticAndDependentRootMeta
+  >;
+
   /**
    * 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
@@ -440,6 +472,21 @@ export type Endpoints = {
     EmptyMeta
   >;
 
+  /**
+   * Produce payload attestation data
+   * Requests that the beacon node produce a PayloadAttestationData.
+   */
+  producePayloadAttestationData: Endpoint<
+    "GET",
+    {
+      /** The slot for which payload attestation data should be created */
+      slot: Slot;
+    },
+    {params: {slot: Slot}},
+    gloas.PayloadAttestationData,
+    VersionMeta
+  >;
+
   produceSyncCommitteeContribution: Endpoint<
     "GET",
     {
@@ -698,6 +745,24 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         meta: ExecutionOptimisticCodec,
       },
     },
+    getPtcDuties: {
+      url: "/eth/v1/validator/duties/ptc/{epoch}",
+      method: "POST",
+      req: {
+        writeReqJson: ({epoch, indices}) => ({params: {epoch}, body: ValidatorIndicesType.toJson(indices)}),
+        parseReqJson: ({params, body}) => ({epoch: params.epoch, indices: ValidatorIndicesType.fromJson(body)}),
+        writeReqSsz: ({epoch, indices}) => ({params: {epoch}, body: ValidatorIndicesType.serialize(indices)}),
+        parseReqSsz: ({params, body}) => ({epoch: params.epoch, indices: ValidatorIndicesType.deserialize(body)}),
+        schema: {
+          params: {epoch: Schema.UintRequired},
+          body: Schema.StringArray,
+        },
+      },
+      resp: {
+        data: PtcDutyListType,
+        meta: ExecutionOptimisticAndDependentRootCodec,
+      },
+    },
     produceBlockV3: {
       url: "/eth/v3/validator/blocks/{slot}",
       method: "GET",
@@ -780,7 +845,8 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
                     (data as BlockContents).block as BeaconBlock<ForkPreDeneb> // <- tranformation
                   );
           },
-          deserialize(data, {executionPayloadBlinded, version}) {
+          deserialize(data, meta) {
+            const {executionPayloadBlinded, version} = meta as ProduceBlockV3Meta;
             return executionPayloadBlinded
               ? getPostBellatrixForkTypes(version).BlindedBeaconBlock.deserialize(data)
               : isForkPostDeneb(version)
@@ -934,6 +1000,21 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         meta: EmptyMetaCodec,
       },
     },
+    producePayloadAttestationData: {
+      url: "/eth/v1/validator/payload_attestation_data/{slot}",
+      method: "GET",
+      req: {
+        writeReq: ({slot}) => ({params: {slot}}),
+        parseReq: ({params}) => ({slot: params.slot}),
+        schema: {
+          params: {slot: Schema.UintRequired},
+        },
+      },
+      resp: {
+        data: ssz.gloas.PayloadAttestationData,
+        meta: VersionCodec,
+      },
+    },
     produceSyncCommitteeContribution: {
       url: "/eth/v1/validator/sync_committee_contribution",
       method: "GET",

package/src/utils/types.ts

@@ -118,7 +118,10 @@ export type ResponseDataCodec<T, M> = {
   toJson: (data: T, meta: M) => unknown; // server
   fromJson: (data: unknown, meta: M) => T; // client
   serialize: (data: T, meta: M) => Uint8Array; // server
-  deserialize: (data: Uint8Array, meta: M) => T; // client
+  // `meta` is typed as `any` so SSZ `Type<T>.deserialize(data, opts?)` satisfies the shape.
+  // Route-specific deserializers (e.g. `WithVersion`) cast to their expected meta internally.
+  // biome-ignore lint/suspicious/noExplicitAny: contravariant workaround for ssz Type.deserialize(opts?)
+  deserialize: (data: Uint8Array, meta: any) => T; // client
 };
 
 export type ResponseMetadataCodec<T> = {