@lodestar/api
Version:
A Typescript REST client for the Ethereum Consensus API
350 lines • 13.7 kB
TypeScript
import { ContainerType, ValueOf } from "@chainsafe/ssz";
import { ChainForkConfig } from "@lodestar/config";
import { Epoch, phase0 } from "@lodestar/types";
import { EmptyArgs, EmptyMeta, EmptyRequest, EmptyResponseData } from "../utils/codecs.js";
import { Endpoint, RouteDefinitions } from "../utils/index.js";
export declare enum ImportStatus {
/** Keystore successfully decrypted and imported to keymanager permanent storage */
imported = "imported",
/** Keystore's pubkey is already known to the keymanager */
duplicate = "duplicate",
/** Any other status different to the above: decrypting error, I/O errors, etc. */
error = "error"
}
export declare enum DeletionStatus {
/** key was active and removed */
deleted = "deleted",
/** slashing protection data returned but key was not active */
not_active = "not_active",
/** key was not found to be removed, and no slashing data can be returned */
not_found = "not_found",
/** unexpected condition meant the key could not be removed (the key was actually found, but we couldn't stop using it) - this would be a sign that making it active elsewhere would almost certainly cause you headaches / slashing conditions etc. */
error = "error"
}
export declare enum ImportRemoteKeyStatus {
/** Remote key successfully imported to validator client permanent storage */
imported = "imported",
/** Remote key's pubkey is already known to the validator client */
duplicate = "duplicate",
/** Any other status different to the above: I/O errors, etc. */
error = "error"
}
export declare enum DeleteRemoteKeyStatus {
/** key was active and removed */
deleted = "deleted",
/** key was not found to be removed */
not_found = "not_found",
/**
* unexpected condition meant the key could not be removed (the key was actually found,
* but we couldn't stop using it) - this would be a sign that making it active elsewhere would
* almost certainly cause you headaches / slashing conditions etc.
*/
error = "error"
}
export type ResponseStatus<Status> = {
status: Status;
message?: string;
};
export declare const FeeRecipientDataType: ContainerType<{
pubkey: import("@lodestar/types").StringType<string>;
ethaddress: import("@lodestar/types").StringType<string>;
}>;
export declare const GraffitiDataType: ContainerType<{
pubkey: import("@lodestar/types").StringType<string>;
graffiti: import("@lodestar/types").StringType<string>;
}>;
export declare const GasLimitDataType: ContainerType<{
pubkey: import("@lodestar/types").StringType<string>;
gasLimit: import("@chainsafe/ssz").UintNumberType;
}>;
export declare const BuilderBoostFactorDataType: ContainerType<{
pubkey: import("@lodestar/types").StringType<string>;
builderBoostFactor: import("@chainsafe/ssz").UintBigintType;
}>;
export type FeeRecipientData = ValueOf<typeof FeeRecipientDataType>;
export type GraffitiData = ValueOf<typeof GraffitiDataType>;
export type GasLimitData = ValueOf<typeof GasLimitDataType>;
export type BuilderBoostFactorData = ValueOf<typeof BuilderBoostFactorDataType>;
export type SignerDefinition = {
pubkey: PubkeyHex;
/**
* URL to API implementing EIP-3030: BLS Remote Signer HTTP API
* `"https://remote.signer"`
*/
url: string;
/** The signer associated with this pubkey cannot be deleted from the API */
readonly: boolean;
};
export type RemoteSignerDefinition = Pick<SignerDefinition, "pubkey" | "url">;
export type ProposerConfigResponse = {
graffiti?: string;
strictFeeRecipientCheck?: boolean;
feeRecipient?: string;
builder?: {
gasLimit?: number;
selection?: string;
boostFactor?: string;
};
};
/**
* JSON serialized representation of a single keystore in EIP-2335: BLS12-381 Keystore format.
* ```
* '{"version":4,"uuid":"9f75a3fa-1e5a-49f9-be3d-f5a19779c6fa","path":"m/12381/3600/0/0/0","pubkey":"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a","crypto":{"kdf":{"function":"pbkdf2","params":{"dklen":32,"c":262144,"prf":"hmac-sha256","salt":"8ff8f22ef522a40f99c6ce07fdcfc1db489d54dfbc6ec35613edf5d836fa1407"},"message":""},"checksum":{"function":"sha256","params":{},"message":"9678a69833d2576e3461dd5fa80f6ac73935ae30d69d07659a709b3cd3eddbe3"},"cipher":{"function":"aes-128-ctr","params":{"iv":"31b69f0ac97261e44141b26aa0da693f"},"message":"e8228bafec4fcbaca3b827e586daad381d53339155b034e5eaae676b715ab05e"}}}'
* ```
*/
export type KeystoreStr = string;
/**
* JSON serialized representation of the slash protection data in format defined in EIP-3076: Slashing Protection Interchange Format.
* ```
* '{"metadata":{"interchange_format_version":"5","genesis_validators_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"},"data":[{"pubkey":"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a","signed_blocks":[],"signed_attestations":[]}]}'
* ```
*/
export type SlashingProtectionData = string;
/**
* The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._
* ```
* "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
* ```
*/
export type PubkeyHex = string;
/**
* An address on the execution (Ethereum 1) network.
* ```
* "0xAbcF8e0d4e9587369b2301D0790347320302cc09"
* ```
*/
export type EthAddress = string;
/**
* Arbitrary data to set in the graffiti field of BeaconBlockBody
* ```
* "plain text value"
* ```
*/
export type Graffiti = string;
export type Endpoints = {
/**
* List all validating pubkeys known to and decrypted by this keymanager binary
*
* https://github.com/ethereum/keymanager-APIs/blob/0c975dae2ac6053c8245ebdb6a9f27c2f114f407/keymanager-oapi.yaml
*/
listKeys: Endpoint<"GET", EmptyArgs, EmptyRequest, {
validatingPubkey: PubkeyHex;
/** The derivation path (if present in the imported keystore) */
derivationPath?: string;
/** The key associated with this pubkey cannot be deleted from the API */
readonly?: boolean;
}[], EmptyMeta>;
/**
* Import keystores generated by the Eth2.0 deposit CLI tooling. `passwords[i]` must unlock `keystores[i]`.
*
* Users SHOULD send slashing_protection data associated with the imported pubkeys. MUST follow the format defined in
* EIP-3076: Slashing Protection Interchange Format.
*
* Returns status result of each `request.keystores` with same length and order of `request.keystores`
*
* https://github.com/ethereum/keymanager-APIs/blob/0c975dae2ac6053c8245ebdb6a9f27c2f114f407/keymanager-oapi.yaml
*/
importKeystores: Endpoint<"POST", {
/** JSON-encoded keystore files generated with the Launchpad */
keystores: KeystoreStr[];
/** Passwords to unlock imported keystore files. `passwords[i]` must unlock `keystores[i]` */
passwords: string[];
/** Slashing protection data for some of the keys of `keystores` */
slashingProtection?: SlashingProtectionData;
}, {
body: {
keystores: KeystoreStr[];
passwords: string[];
slashing_protection?: SlashingProtectionData;
};
}, ResponseStatus<ImportStatus>[], EmptyMeta>;
/**
* DELETE must delete all keys from `request.pubkeys` that are known to the keymanager and exist in its
* persistent storage. Additionally, DELETE must fetch the slashing protection data for the requested keys from
* persistent storage, which must be retained (and not deleted) after the response has been sent. Therefore in the
* case of two identical delete requests being made, both will have access to slashing protection data.
*
* In a single atomic sequential operation the keymanager must:
* 1. Guarantee that key(s) can not produce any more signature; only then
* 2. Delete key(s) and serialize its associated slashing protection data
*
* DELETE should never return a 404 response, even if all pubkeys from request.pubkeys have no extant keystores
* nor slashing protection data.
*
* Slashing protection data must only be returned for keys from `request.pubkeys` for which a
* `deleted` or `not_active` status is returned.
*
* Returns deletion status of all keys in `request.pubkeys` in the same order.
*
* https://github.com/ethereum/keymanager-APIs/blob/0c975dae2ac6053c8245ebdb6a9f27c2f114f407/keymanager-oapi.yaml
*/
deleteKeys: Endpoint<"DELETE", {
/** List of public keys to delete */
pubkeys: PubkeyHex[];
}, {
body: {
pubkeys: string[];
};
}, {
statuses: ResponseStatus<DeletionStatus>[];
slashingProtection: SlashingProtectionData;
}, EmptyMeta>;
/**
* List all remote validating pubkeys known to this validator client binary
*/
listRemoteKeys: Endpoint<"GET", EmptyArgs, EmptyRequest, SignerDefinition[], EmptyMeta>;
/**
* Import remote keys for the validator client to request duties for
*/
importRemoteKeys: Endpoint<"POST", {
remoteSigners: RemoteSignerDefinition[];
}, {
body: {
remote_keys: RemoteSignerDefinition[];
};
}, ResponseStatus<ImportRemoteKeyStatus>[], EmptyMeta>;
/**
* DELETE must delete all keys from `request.pubkeys` that are known to the validator client and exist in its
* persistent storage.
*
* DELETE should never return a 404 response, even if all pubkeys from `request.pubkeys` have no existing keystores.
*/
deleteRemoteKeys: Endpoint<"DELETE", {
pubkeys: PubkeyHex[];
}, {
body: {
pubkeys: string[];
};
}, ResponseStatus<DeleteRemoteKeyStatus>[], EmptyMeta>;
listFeeRecipient: Endpoint<"GET", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, FeeRecipientData, EmptyMeta>;
setFeeRecipient: Endpoint<"POST", {
pubkey: PubkeyHex;
ethaddress: EthAddress;
}, {
params: {
pubkey: string;
};
body: {
ethaddress: string;
};
}, EmptyResponseData, EmptyMeta>;
deleteFeeRecipient: Endpoint<"DELETE", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, EmptyResponseData, EmptyMeta>;
getGraffiti: Endpoint<"GET", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, GraffitiData, EmptyMeta>;
setGraffiti: Endpoint<"POST", {
pubkey: PubkeyHex;
graffiti: Graffiti;
}, {
params: {
pubkey: string;
};
body: {
graffiti: string;
};
}, EmptyResponseData, EmptyMeta>;
deleteGraffiti: Endpoint<"DELETE", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, EmptyResponseData, EmptyMeta>;
getGasLimit: Endpoint<"GET", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, GasLimitData, EmptyMeta>;
setGasLimit: Endpoint<"POST", {
pubkey: PubkeyHex;
gasLimit: number;
}, {
params: {
pubkey: string;
};
body: {
gas_limit: string;
};
}, EmptyResponseData, EmptyMeta>;
deleteGasLimit: Endpoint<"DELETE", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, EmptyResponseData, EmptyMeta>;
getBuilderBoostFactor: Endpoint<"GET", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, BuilderBoostFactorData, EmptyMeta>;
setBuilderBoostFactor: Endpoint<"POST", {
pubkey: PubkeyHex;
builderBoostFactor: bigint;
}, {
params: {
pubkey: string;
};
body: {
builder_boost_factor: string;
};
}, EmptyResponseData, EmptyMeta>;
deleteBuilderBoostFactor: Endpoint<"DELETE", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, EmptyResponseData, EmptyMeta>;
getProposerConfig: Endpoint<"GET", {
pubkey: PubkeyHex;
}, {
params: {
pubkey: string;
};
}, ProposerConfigResponse, EmptyMeta>;
/**
* Create a signed voluntary exit message for an active validator, identified by a public key known to the validator
* client. This endpoint returns a `SignedVoluntaryExit` object, which can be used to initiate voluntary exit via the
* beacon node's [submitPoolVoluntaryExit](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolVoluntaryExit) endpoint.
*
* Returns the signed voluntary exit message
*
* https://github.com/ethereum/keymanager-APIs/blob/7105e749e11dd78032ea275cc09bf62ecd548fca/keymanager-oapi.yaml
*/
signVoluntaryExit: Endpoint<"POST", {
/** Public key of an active validator known to the validator client */
pubkey: PubkeyHex;
/** Minimum epoch for processing exit. Defaults to the current epoch if not set */
epoch?: Epoch;
}, {
params: {
pubkey: string;
};
query: {
epoch?: number;
};
}, phase0.SignedVoluntaryExit, EmptyMeta>;
};
export declare function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints>;
//# sourceMappingURL=routes.d.ts.map