@lodestar/api 1.20.0-dev.f6d3bce802 → 1.20.0-dev.fe23f68998

package/lib/beacon/routes/beacon/state.d.ts

@@ -1,289 +1,235 @@
-import { phase0, CommitteeIndex, Slot, ValidatorIndex, Epoch, Root, RootHex } from "@lodestar/types";
-import { ApiClientResponse } from "../../../interfaces.js";
-import { HttpStatusCode } from "../../../utils/client/httpStatusCode.js";
-import { RoutesData, ReturnTypes, ReqSerializers } from "../../../utils/index.js";
+import { ContainerType, ValueOf } from "@chainsafe/ssz";
+import { ChainForkConfig } from "@lodestar/config";
+import { phase0, CommitteeIndex, Slot, Epoch, RootHex, StringType } from "@lodestar/types";
+import { Endpoint, RouteDefinitions } from "../../../utils/index.js";
+import { ExecutionOptimisticAndFinalizedMeta } from "../../../utils/metadata.js";
+import { RootResponse } from "./block.js";
 export type StateId = RootHex | Slot | "head" | "genesis" | "finalized" | "justified";
+export type StateArgs = {
+    /**
+     * State identifier.
+     * Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", \<slot\>, \<hex encoded stateRoot with 0x prefix\>.
+     */
+    stateId: StateId;
+};
 export type ValidatorId = string | number;
-/**
- * True if the response references an unverified execution payload. Optimistic information may be invalidated at
- * a later time. If the field is not present, assume the False value.
- */
-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" | "pending_queued" | "active_ongoing" | "active_exiting" | "active_slashed" | "exited_unslashed" | "exited_slashed" | "withdrawal_possible" | "withdrawal_done";
-export type ValidatorFilters = {
-    id?: ValidatorId[];
-    status?: ValidatorStatus[];
-};
-export type CommitteesFilters = {
-    epoch?: Epoch;
-    index?: CommitteeIndex;
-    slot?: Slot;
-};
-export type FinalityCheckpoints = {
-    previousJustified: phase0.Checkpoint;
-    currentJustified: phase0.Checkpoint;
-    finalized: phase0.Checkpoint;
-};
-export type ValidatorResponse = {
-    index: ValidatorIndex;
-    balance: number;
-    status: ValidatorStatus;
-    validator: phase0.Validator;
-};
-export type ValidatorBalance = {
-    index: ValidatorIndex;
-    balance: number;
-};
-export type EpochCommitteeResponse = {
-    index: CommitteeIndex;
-    slot: Slot;
-    validators: ArrayLike<ValidatorIndex>;
-};
-export type EpochSyncCommitteeResponse = {
-    /** all of the validator indices in the current sync committee */
-    validators: ValidatorIndex[];
+export declare const RandaoResponseType: ContainerType<{
+    randao: import("@chainsafe/ssz").ByteVectorType;
+}>;
+export declare const FinalityCheckpointsType: ContainerType<{
+    previousJustified: ContainerType<{
+        epoch: import("@chainsafe/ssz").UintNumberType;
+        root: import("@chainsafe/ssz").ByteVectorType; /** All of the validator indices in the current sync committee */
+    }>;
+    currentJustified: ContainerType<{
+        epoch: import("@chainsafe/ssz").UintNumberType;
+        root: import("@chainsafe/ssz").ByteVectorType; /** All of the validator indices in the current sync committee */
+    }>;
+    finalized: ContainerType<{
+        epoch: import("@chainsafe/ssz").UintNumberType;
+        root: import("@chainsafe/ssz").ByteVectorType; /** All of the validator indices in the current sync committee */
+    }>;
+}>;
+export declare const ValidatorResponseType: ContainerType<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    balance: import("@chainsafe/ssz").UintNumberType;
+    status: StringType<ValidatorStatus>;
+    validator: import("@lodestar/types/lib/phase0/validator.js").ValidatorNodeStructType;
+}>;
+export declare const EpochCommitteeResponseType: ContainerType<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    slot: import("@chainsafe/ssz").UintNumberType;
+    validators: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<number>, unknown, unknown>;
+}>;
+export declare const ValidatorBalanceType: ContainerType<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    balance: import("@chainsafe/ssz").UintNumberType;
+}>;
+export declare const EpochSyncCommitteeResponseType: ContainerType<{
+    /** All of the validator indices in the current sync committee */
+    validators: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<number>, unknown, unknown>;
     /** Subcommittee slices of the current sync committee */
-    validatorAggregates: ValidatorIndex[][];
-};
-export type Api = {
+    validatorAggregates: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<number[]>, unknown, unknown>;
+}>;
+export declare const ValidatorResponseListType: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<import("@chainsafe/ssz").ValueOfFields<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    balance: import("@chainsafe/ssz").UintNumberType;
+    status: StringType<ValidatorStatus>;
+    validator: import("@lodestar/types/lib/phase0/validator.js").ValidatorNodeStructType;
+}>>, unknown, unknown>;
+export declare const EpochCommitteeResponseListType: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<import("@chainsafe/ssz").ValueOfFields<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    slot: import("@chainsafe/ssz").UintNumberType;
+    validators: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<number>, unknown, unknown>;
+}>>, unknown, unknown>;
+export declare const ValidatorBalanceListType: import("@chainsafe/ssz").ArrayType<import("@chainsafe/ssz").Type<import("@chainsafe/ssz").ValueOfFields<{
+    index: import("@chainsafe/ssz").UintNumberType;
+    balance: import("@chainsafe/ssz").UintNumberType;
+}>>, unknown, unknown>;
+export type RandaoResponse = ValueOf<typeof RandaoResponseType>;
+export type FinalityCheckpoints = ValueOf<typeof FinalityCheckpointsType>;
+export type ValidatorResponse = ValueOf<typeof ValidatorResponseType>;
+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 EpochCommitteeResponseList = ValueOf<typeof EpochCommitteeResponseListType>;
+export type ValidatorBalanceList = ValueOf<typeof ValidatorBalanceListType>;
+export type Endpoints = {
     /**
      * Get state SSZ HashTreeRoot
      * Calculates HashTreeRoot for state with given 'stateId'. If stateId is root, same value will be returned.
-     *
-     * @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<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: {
-                root: Root;
-            };
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateRoot: Endpoint<"GET", StateArgs, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+    }, RootResponse, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get Fork object for requested state
      * Returns [Fork](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/beacon-chain.md#fork) object for state with given 'stateId'.
-     * @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<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: phase0.Fork;
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateFork: Endpoint<"GET", StateArgs, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+    }, phase0.Fork, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Fetch the RANDAO mix for the requested epoch from the state identified by 'stateId'.
-     *
-     * @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\>.
-     * @param epoch Fetch randao mix for the given epoch. If an epoch is not specified then the RANDAO mix for the state's current epoch will be returned.
      */
-    getStateRandao(stateId: StateId, epoch?: Epoch): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: {
-                randao: Root;
-            };
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateRandao: Endpoint<"GET", StateArgs & {
+        /**
+         * Fetch randao mix for the given epoch. If an epoch is not specified
+         * then the RANDAO mix for the state's current epoch will be returned.
+         */
+        epoch?: Epoch;
+    }, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+        query: {
+            epoch?: number;
+        };
+    }, RandaoResponse, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get state finality checkpoints
      * Returns finality checkpoints for state with given 'stateId'.
      * In case finality is not yet achieved, checkpoint should return epoch 0 and ZERO_HASH as root.
-     * @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<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: FinalityCheckpoints;
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateFinalityCheckpoints: Endpoint<"GET", StateArgs, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+    }, FinalityCheckpoints, ExecutionOptimisticAndFinalizedMeta>;
     /**
-     * Get validators from state
-     * Returns filterable list of validators with their balance, status and index.
-     * @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\>.
-     * @param id Either hex encoded public key (with 0x prefix) or validator index
-     * @param status [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
+     * Get validator from state by id
+     * Returns validator specified by state and id or public key along with status and balance.
      */
-    getStateValidators(stateId: StateId, filters?: ValidatorFilters): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: ValidatorResponse[];
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateValidator: Endpoint<"GET", StateArgs & {
+        /** Either hex encoded public key (with 0x prefix) or validator index */
+        validatorId: ValidatorId;
+    }, {
+        params: {
+            state_id: string;
+            validator_id: ValidatorId;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+    }, ValidatorResponse, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get validators from state
      * Returns filterable list of validators with their balance, status and index.
-     * @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\>.
-     * @param id Either hex encoded public key (with 0x prefix) or validator index
-     * @param status [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
      */
-    postStateValidators(stateId: StateId, filters?: ValidatorFilters): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: ValidatorResponse[];
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateValidators: Endpoint<"GET", StateArgs & {
+        /** Either hex encoded public key (with 0x prefix) or validator index */
+        validatorIds?: ValidatorId[];
+        /** [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ) */
+        statuses?: ValidatorStatus[];
+    }, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+        query: {
+            id?: ValidatorId[];
+            status?: ValidatorStatus[];
+        };
+    }, ValidatorResponseList, ExecutionOptimisticAndFinalizedMeta>;
     /**
-     * Get validator from state by id
-     * Returns validator specified by state and id or public key along with status and balance.
-     * @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\>.
-     * @param validatorId Either hex encoded public key (with 0x prefix) or validator index
+     * Get validators from state
+     * Returns filterable list of validators with their balance, status and index.
      */
-    getStateValidator(stateId: StateId, validatorId: ValidatorId): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: ValidatorResponse;
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    postStateValidators: Endpoint<"POST", StateArgs & {
+        /** Either hex encoded public key (with 0x prefix) or validator index */
+        validatorIds?: ValidatorId[];
+        /** [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ) */
+        statuses?: ValidatorStatus[];
+    }, {
+        params: {
+            state_id: string;
+        };
+        body: {
+            ids?: string[];
+            statuses?: ValidatorStatus[];
         };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
+    }, ValidatorResponseList, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get validator balances from state
      * Returns filterable list of validator balances.
-     * @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\>.
-     * @param id Either hex encoded public key (with 0x prefix) or validator index
      */
-    getStateValidatorBalances(stateId: StateId, indices?: ValidatorId[]): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: ValidatorBalance[];
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    getStateValidatorBalances: Endpoint<"GET", StateArgs & {
+        /** Either hex encoded public key (with 0x prefix) or validator index */
+        validatorIds?: ValidatorId[];
+    }, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST>>;
+        query: {
+            id?: ValidatorId[];
+        };
+    }, ValidatorBalanceList, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get validator balances from state
      * Returns filterable list of validator balances.
-     * @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\>.
-     * @param id Either hex encoded public key (with 0x prefix) or validator index
      */
-    postStateValidatorBalances(stateId: StateId, indices?: ValidatorId[]): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: ValidatorBalance[];
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
+    postStateValidatorBalances: Endpoint<"POST", StateArgs & {
+        /** Either hex encoded public key (with 0x prefix) or validator index */
+        validatorIds?: ValidatorId[];
+    }, {
+        params: {
+            state_id: string;
         };
-    }, HttpStatusCode.BAD_REQUEST>>;
+        body: string[];
+    }, ValidatorBalanceList, ExecutionOptimisticAndFinalizedMeta>;
     /**
      * Get all committees for a state.
      * Retrieves the committees for the given state.
-     * @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\>.
-     * @param epoch Fetch committees for the given epoch.  If not present then the committees for the epoch of the state will be obtained.
-     * @param index Restrict returned values to those matching the supplied committee index.
-     * @param slot Restrict returned values to those matching the supplied slot.
      */
-    getEpochCommittees(stateId: StateId, filters?: CommitteesFilters): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: EpochCommitteeResponse[];
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
-        };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
-    getEpochSyncCommittees(stateId: StateId, epoch?: Epoch): Promise<ApiClientResponse<{
-        [HttpStatusCode.OK]: {
-            data: EpochSyncCommitteeResponse;
-            executionOptimistic: ExecutionOptimistic;
-            finalized: Finalized;
-        };
-    }, HttpStatusCode.BAD_REQUEST | HttpStatusCode.NOT_FOUND>>;
-};
-/**
- * Define javascript values for each route
- */
-export declare const routesData: RoutesData<Api>;
-type StateIdOnlyReq = {
-    params: {
-        state_id: string;
-    };
-};
-export type ReqTypes = {
-    getEpochCommittees: {
+    getEpochCommittees: Endpoint<"GET", StateArgs & {
+        /** Fetch committees for the given epoch. If not present then the committees for the epoch of the state will be obtained. */
+        epoch?: Epoch;
+        /** Restrict returned values to those matching the supplied committee index. */
+        index?: CommitteeIndex;
+        /** Restrict returned values to those matching the supplied slot. */
+        slot?: Slot;
+    }, {
         params: {
-            state_id: StateId;
+            state_id: string;
         };
         query: {
             slot?: number;
             epoch?: number;
             index?: number;
         };
-    };
-    getEpochSyncCommittees: {
-        params: {
-            state_id: StateId;
-        };
-        query: {
-            epoch?: number;
-        };
-    };
-    getStateFinalityCheckpoints: StateIdOnlyReq;
-    getStateFork: StateIdOnlyReq;
-    getStateRoot: StateIdOnlyReq;
-    getStateRandao: {
+    }, EpochCommitteeResponseList, ExecutionOptimisticAndFinalizedMeta>;
+    getEpochSyncCommittees: Endpoint<"GET", StateArgs & {
+        epoch?: Epoch;
+    }, {
         params: {
-            state_id: StateId;
+            state_id: string;
         };
         query: {
             epoch?: number;
         };
-    };
-    getStateValidator: {
-        params: {
-            state_id: StateId;
-            validator_id: ValidatorId;
-        };
-    };
-    getStateValidators: {
-        params: {
-            state_id: StateId;
-        };
-        query: {
-            id?: ValidatorId[];
-            status?: ValidatorStatus[];
-        };
-    };
-    postStateValidators: {
-        params: {
-            state_id: StateId;
-        };
-        body: {
-            ids?: string[];
-            statuses?: ValidatorStatus[];
-        };
-    };
-    getStateValidatorBalances: {
-        params: {
-            state_id: StateId;
-        };
-        query: {
-            id?: ValidatorId[];
-        };
-    };
-    postStateValidatorBalances: {
-        params: {
-            state_id: StateId;
-        };
-        body?: string[];
-    };
+    }, EpochSyncCommitteeResponse, ExecutionOptimisticAndFinalizedMeta>;
 };
-export declare function getReqSerializers(): ReqSerializers<Api, ReqTypes>;
-export declare function getReturnTypes(): ReturnTypes<Api>;
-export {};
+export declare function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints>;
 //# sourceMappingURL=state.d.ts.map