feat: add finalized metadata field to HTTP API responses (#6645)

* feat: add finalized metadata field to HTTP API responses * Clean up getState type casts * Fix finalized when getting block root * Add comment for block from hot db * Fix case where slot equals finalized block slot * Calculate epoch from unmodded slot
ChainSafe · Apr 11, 2024 · cdc92b2 · cdc92b2
1 parent 6f7e865
commit cdc92b2
Show file tree

Hide file tree

Showing 25 changed files with 317 additions and 156 deletions.
diff --git a/packages/api/src/beacon/routes/beacon/block.ts b/packages/api/src/beacon/routes/beacon/block.ts
@@ -16,6 +16,7 @@ import {
   ContainerDataExecutionOptimistic,
   WithExecutionOptimistic,
   ContainerData,
+  WithFinalized,
 } from "../../../utils/index.js";
 import {HttpStatusCode} from "../../../utils/client/httpStatusCode.js";
 import {parseAcceptHeader, writeAcceptHeader} from "../../../utils/acceptHeader.js";
@@ -32,6 +33,11 @@ export type BlockId = RootHex | Slot | "head" | "genesis" | "finalized";
  */
 export type ExecutionOptimistic = boolean;
 
+/**
+ * True if the response references the finalized history of the chain, as determined by fork choice.
+ */
+export type Finalized = boolean;
+
 export type BlockHeaderResponse = {
   root: Root;
   canonical: boolean;
@@ -66,6 +72,7 @@ export type BlockV2Response<T extends ResponseFormat = "json"> = T extends "ssz"
         [HttpStatusCode.OK]: {
           data: allForks.SignedBeaconBlock;
           executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
           version: ForkName;
         };
       },
@@ -103,6 +110,7 @@ export type Api = {
         [HttpStatusCode.OK]: {
           data: phase0.Attestation[];
           executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
         };
       },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
@@ -121,6 +129,7 @@ export type Api = {
         [HttpStatusCode.OK]: {
           data: BlockHeaderResponse;
           executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
         };
       },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
@@ -139,6 +148,7 @@ export type Api = {
         [HttpStatusCode.OK]: {
           data: BlockHeaderResponse[];
           executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
         };
       },
       HttpStatusCode.BAD_REQUEST
@@ -157,6 +167,7 @@ export type Api = {
         [HttpStatusCode.OK]: {
           data: {root: Root};
           executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
         };
       },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
@@ -236,7 +247,11 @@ export type Api = {
     indices?: number[]
   ): Promise<
     ApiClientResponse<{
-      [HttpStatusCode.OK]: {executionOptimistic: ExecutionOptimistic; data: deneb.BlobSidecars};
+      [HttpStatusCode.OK]: {
+        data: deneb.BlobSidecars;
+        executionOptimistic: ExecutionOptimistic;
+        finalized: Finalized;
+      };
     }>
   >;
 };
@@ -395,11 +410,11 @@ export function getReturnTypes(): ReturnTypes<Api> {
 
   return {
     getBlock: ContainerData(ssz.phase0.SignedBeaconBlock),
-    getBlockV2: WithExecutionOptimistic(WithVersion((fork) => ssz[fork].SignedBeaconBlock)),
-    getBlockAttestations: ContainerDataExecutionOptimistic(ArrayOf(ssz.phase0.Attestation)),
-    getBlockHeader: ContainerDataExecutionOptimistic(BeaconHeaderResType),
-    getBlockHeaders: ContainerDataExecutionOptimistic(ArrayOf(BeaconHeaderResType)),
-    getBlockRoot: ContainerDataExecutionOptimistic(RootContainer),
-    getBlobSidecars: ContainerDataExecutionOptimistic(ssz.deneb.BlobSidecars),
+    getBlockV2: WithFinalized(WithExecutionOptimistic(WithVersion((fork) => ssz[fork].SignedBeaconBlock))),
+    getBlockAttestations: WithFinalized(ContainerDataExecutionOptimistic(ArrayOf(ssz.phase0.Attestation))),
+    getBlockHeader: WithFinalized(ContainerDataExecutionOptimistic(BeaconHeaderResType)),
+    getBlockHeaders: WithFinalized(ContainerDataExecutionOptimistic(ArrayOf(BeaconHeaderResType))),
+    getBlockRoot: WithFinalized(ContainerDataExecutionOptimistic(RootContainer)),
+    getBlobSidecars: WithFinalized(ContainerDataExecutionOptimistic(ssz.deneb.BlobSidecars)),
   };
 }
diff --git a/packages/api/src/beacon/routes/beacon/rewards.ts b/packages/api/src/beacon/routes/beacon/rewards.ts
@@ -8,6 +8,7 @@ import {
   ReqSerializers,
   ContainerDataExecutionOptimistic,
   ArrayOf,
+  WithFinalized,
 } from "../../../utils/index.js";
 import {HttpStatusCode} from "../../../utils/client/httpStatusCode.js";
 import {ApiClientResponse} from "../../../interfaces.js";
@@ -22,6 +23,11 @@ import {ValidatorId} from "./state.js";
  */
 export type ExecutionOptimistic = boolean;
 
+/**
+ * True if the response references the finalized history of the chain, as determined by fork choice.
+ */
+export type Finalized = boolean;
+
 /**
  * Rewards info for a single block. Every reward value is in Gwei.
  */
@@ -88,11 +94,15 @@ export type Api = {
    * @param blockId Block identifier.
    * Can be one of: "head" (canonical head in node's view), "genesis", "finalized", \<slot\>, \<hex encoded blockRoot with 0x prefix\>.
    */
-  getBlockRewards(
-    blockId: BlockId
-  ): Promise<
+  getBlockRewards(blockId: BlockId): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: BlockRewards; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: BlockRewards;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -108,7 +118,13 @@ export type Api = {
     validatorIds?: ValidatorId[]
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: AttestationsRewards; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: AttestationsRewards;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -126,7 +142,13 @@ export type Api = {
     validatorIds?: ValidatorId[]
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: SyncCommitteeRewards; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: SyncCommitteeRewards;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -228,8 +250,8 @@ export function getReturnTypes(): ReturnTypes<Api> {
   );
 
   return {
-    getBlockRewards: ContainerDataExecutionOptimistic(BlockRewardsResponse),
-    getAttestationsRewards: ContainerDataExecutionOptimistic(AttestationsRewardsResponse),
-    getSyncCommitteeRewards: ContainerDataExecutionOptimistic(ArrayOf(SyncCommitteeRewardsResponse)),
+    getBlockRewards: WithFinalized(ContainerDataExecutionOptimistic(BlockRewardsResponse)),
+    getAttestationsRewards: WithFinalized(ContainerDataExecutionOptimistic(AttestationsRewardsResponse)),
+    getSyncCommitteeRewards: WithFinalized(ContainerDataExecutionOptimistic(ArrayOf(SyncCommitteeRewardsResponse))),
   };
 }
diff --git a/packages/api/src/beacon/routes/beacon/state.ts b/packages/api/src/beacon/routes/beacon/state.ts
@@ -11,6 +11,7 @@ import {
   Schema,
   ReqSerializers,
   ReqSerializer,
+  WithFinalized,
 } from "../../../utils/index.js";
 
 // See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
@@ -24,6 +25,11 @@ export type ValidatorId = string | number;
  */
 export type ExecutionOptimistic = boolean;
 
+/**
+ * True if the response references the finalized history of the chain, as determined by fork choice.
+ */
+export type Finalized = boolean;
+
 export type ValidatorStatus =
   | "active"
   | "pending_initialized"
@@ -86,11 +92,15 @@ export type Api = {
    * @param stateId State identifier.
    * Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", \<slot\>, \<hex encoded stateRoot with 0x prefix\>.
    */
-  getStateRoot(
-    stateId: StateId
-  ): Promise<
+  getStateRoot(stateId: StateId): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: {root: Root}; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: {root: Root};
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -101,11 +111,15 @@ export type Api = {
    * @param stateId State identifier.
    * Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", \<slot\>, \<hex encoded stateRoot with 0x prefix\>.
    */
-  getStateFork(
-    stateId: StateId
-  ): Promise<
+  getStateFork(stateId: StateId): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: phase0.Fork; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: phase0.Fork;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -122,7 +136,13 @@ export type Api = {
     epoch?: Epoch
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: {randao: Root}; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: {randao: Root};
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -134,11 +154,15 @@ export type Api = {
    * @param stateId State identifier.
    * Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", \<slot\>, \<hex encoded stateRoot with 0x prefix\>.
    */
-  getStateFinalityCheckpoints(
-    stateId: StateId
-  ): Promise<
+  getStateFinalityCheckpoints(stateId: StateId): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: FinalityCheckpoints; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: FinalityCheckpoints;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -156,7 +180,13 @@ export type Api = {
     filters?: ValidatorFilters
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: ValidatorResponse[]; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: ValidatorResponse[];
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -197,7 +227,13 @@ export type Api = {
     validatorId: ValidatorId
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: ValidatorResponse; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: ValidatorResponse;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -214,7 +250,13 @@ export type Api = {
     indices?: ValidatorId[]
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: ValidatorBalance[]; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: ValidatorBalance[];
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST
     >
   >;
@@ -256,7 +298,13 @@ export type Api = {
     filters?: CommitteesFilters
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: EpochCommitteeResponse[]; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: EpochCommitteeResponse[];
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;
@@ -266,7 +314,13 @@ export type Api = {
     epoch?: Epoch
   ): Promise<
     ApiClientResponse<
-      {[HttpStatusCode.OK]: {data: EpochSyncCommitteeResponse; executionOptimistic: ExecutionOptimistic}},
+      {
+        [HttpStatusCode.OK]: {
+          data: EpochSyncCommitteeResponse;
+          executionOptimistic: ExecutionOptimistic;
+          finalized: Finalized;
+        };
+      },
       HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND
     >
   >;