@chainsafe/lodestar 1.35.0-dev.e18102ed8c → 1.35.0-dev.f45a2be721

package/src/cmds/validator/keymanager/decryptKeystores/threadPool.ts

@@ -0,0 +1,75 @@
+import path from "node:path";
+import {ModuleThread, Pool, QueuedTask, Worker, spawn} from "@chainsafe/threads";
+import {maxPoolSize} from "./poolSize.js";
+import {DecryptKeystoreArgs, DecryptKeystoreWorkerAPI} from "./types.js";
+
+// Worker constructor consider the path relative to the current working directory
+const workerDir =
+  process.env.NODE_ENV === "test" ? "../../../../../lib/cmds/validator/keymanager/decryptKeystores" : "./";
+
+/**
+ * Thread pool to decrypt keystores
+ */
+export class DecryptKeystoresThreadPool {
+  private pool: Pool<ModuleThread<DecryptKeystoreWorkerAPI>>;
+  private tasks: QueuedTask<ModuleThread<DecryptKeystoreWorkerAPI>, Uint8Array>[] = [];
+  private terminatePoolHandler: () => void;
+
+  constructor(
+    keystoreCount: number,
+    private readonly signal: AbortSignal
+  ) {
+    this.pool = Pool(
+      () =>
+        spawn<DecryptKeystoreWorkerAPI>(new Worker(path.join(workerDir, "worker.js")), {
+          // The number below is big enough to almost disable the timeout
+          // which helps during tests run on unpredictably slow hosts
+          timeout: 5 * 60 * 1000,
+        }),
+      {
+        // Adjust worker pool size based on keystore count
+        size: Math.min(keystoreCount, maxPoolSize),
+        // Decrypt keystores in sequence, increasing concurrency does not improve performance
+        concurrency: 1,
+      }
+    );
+    // Terminate worker threads when process receives exit signal
+    this.terminatePoolHandler = () => {
+      void this.pool.terminate(true);
+    };
+    signal.addEventListener("abort", this.terminatePoolHandler, {once: true});
+  }
+
+  /**
+   * Add keystore to the task queue to be decrypted
+   */
+  queue(
+    args: DecryptKeystoreArgs,
+    onDecrypted: (secretKeyBytes: Uint8Array) => void,
+    onError: (e: Error) => void
+  ): void {
+    const task = this.pool.queue((thread) => thread.decryptKeystore(args));
+    this.tasks.push(task);
+    task.then(onDecrypted).catch(onError);
+  }
+
+  /**
+   * Resolves once all queued tasks are completed and terminates worker threads.
+   * Errors during executing can be captured in `onError` handler for each task.
+   */
+  async completed(): Promise<void> {
+    await this.pool.settled(true);
+    await this.pool.terminate();
+    this.signal.removeEventListener("abort", this.terminatePoolHandler);
+  }
+
+  /**
+   * Cancel all pending tasks
+   */
+  cancel(): void {
+    for (const task of this.tasks) {
+      task.cancel();
+    }
+    this.tasks = [];
+  }
+}

package/src/cmds/validator/keymanager/decryptKeystores/types.ts

@@ -0,0 +1,12 @@
+import {KeystoreStr} from "@lodestar/api/keymanager";
+import {LocalKeystoreDefinition} from "../interface.js";
+
+export type DecryptKeystoreWorkerAPI = {
+  decryptKeystore(args: DecryptKeystoreArgs): Promise<Uint8Array>;
+};
+
+export type DecryptKeystoreArgs = LocalKeystoreDefinition | {keystoreStr: KeystoreStr; password: string};
+
+export function isLocalKeystoreDefinition(args: DecryptKeystoreArgs): args is LocalKeystoreDefinition {
+  return (args as LocalKeystoreDefinition).keystorePath !== undefined;
+}

package/src/cmds/validator/keymanager/decryptKeystores/worker.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import {Keystore} from "@chainsafe/bls-keystore";
+import {Transfer, TransferDescriptor} from "@chainsafe/threads";
+import {expose} from "@chainsafe/threads/worker";
+import {DecryptKeystoreArgs, DecryptKeystoreWorkerAPI, isLocalKeystoreDefinition} from "./types.js";
+
+/**
+ * Decrypt a single keystore, returning the secret key as a Uint8Array
+ *
+ * NOTE: This is a memory (and cpu) -intensive process, since decrypting the keystore involves running a key derivation function (either pbkdf2 or scrypt)
+ */
+export async function decryptKeystore(args: DecryptKeystoreArgs): Promise<TransferDescriptor<Uint8Array>> {
+  const keystore = Keystore.parse(
+    isLocalKeystoreDefinition(args) ? fs.readFileSync(args.keystorePath, "utf8") : args.keystoreStr
+  );
+
+  // Memory-hogging function
+  const secret = await keystore.decrypt(args.password);
+  // Transfer the underlying ArrayBuffer back to the main thread: https://threads.js.org/usage-advanced#transferable-objects
+  // This small performance gain may help in cases where this is run for many keystores
+  return Transfer(secret, [secret.buffer]);
+}
+
+expose({decryptKeystore} as unknown as DecryptKeystoreWorkerAPI);

package/src/cmds/validator/keymanager/impl.ts

@@ -0,0 +1,425 @@
+import {Keystore} from "@chainsafe/bls-keystore";
+import {SecretKey} from "@chainsafe/blst";
+import {
+  BuilderBoostFactorData,
+  DeleteRemoteKeyStatus,
+  DeletionStatus,
+  FeeRecipientData,
+  GasLimitData,
+  GraffitiData,
+  ImportRemoteKeyStatus,
+  ImportStatus,
+  KeystoreStr,
+  ProposerConfigResponse,
+  PubkeyHex,
+  RemoteSignerDefinition,
+  ResponseStatus,
+  SignerDefinition,
+  SlashingProtectionData,
+} from "@lodestar/api/keymanager";
+import {KeymanagerApiMethods as Api} from "@lodestar/api/keymanager/server";
+import {ApiError} from "@lodestar/api/server";
+import {Epoch} from "@lodestar/types";
+import {fromHex, isValidHttpUrl} from "@lodestar/utils";
+import {Interchange, SignerType, Validator} from "@lodestar/validator";
+import {getPubkeyHexFromKeystore, isValidatePubkeyHex} from "../../../util/format.js";
+import {parseFeeRecipient} from "../../../util/index.js";
+import {DecryptKeystoresThreadPool} from "./decryptKeystores/index.js";
+import {IPersistedKeysBackend} from "./interface.js";
+
+export class KeymanagerApi implements Api {
+  constructor(
+    private readonly validator: Validator,
+    private readonly persistedKeysBackend: IPersistedKeysBackend,
+    private readonly signal: AbortSignal,
+    private readonly proposerConfigWriteDisabled?: boolean
+  ) {}
+
+  private checkIfProposerWriteEnabled(): void {
+    if (this.proposerConfigWriteDisabled === true) {
+      throw Error("proposerSettingsFile option activated");
+    }
+  }
+
+  async listFeeRecipient({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["listFeeRecipient"]> {
+    this.assertValidKnownPubkey(pubkey);
+    return {data: {pubkey, ethaddress: this.validator.validatorStore.getFeeRecipient(pubkey)}};
+  }
+
+  async setFeeRecipient({pubkey, ethaddress}: FeeRecipientData): ReturnType<Api["setFeeRecipient"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.setFeeRecipient(pubkey, parseFeeRecipient(ethaddress));
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 202};
+  }
+
+  async deleteFeeRecipient({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["deleteFeeRecipient"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.deleteFeeRecipient(pubkey);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 204};
+  }
+
+  async getGraffiti({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["getGraffiti"]> {
+    this.assertValidKnownPubkey(pubkey);
+    const graffiti = this.validator.validatorStore.getGraffiti(pubkey);
+    if (graffiti === undefined) {
+      throw new ApiError(404, `No graffiti for pubkey ${pubkey}`);
+    }
+    return {data: {pubkey, graffiti}};
+  }
+
+  async setGraffiti({pubkey, graffiti}: GraffitiData): ReturnType<Api["setGraffiti"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.setGraffiti(pubkey, graffiti);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 202};
+  }
+
+  async deleteGraffiti({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["deleteGraffiti"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.deleteGraffiti(pubkey);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 204};
+  }
+
+  async getGasLimit({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["getGasLimit"]> {
+    this.assertValidKnownPubkey(pubkey);
+    const gasLimit = this.validator.validatorStore.getGasLimit(pubkey);
+    return {data: {pubkey, gasLimit}};
+  }
+
+  async setGasLimit({pubkey, gasLimit}: GasLimitData): ReturnType<Api["setGasLimit"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.setGasLimit(pubkey, gasLimit);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 202};
+  }
+
+  async deleteGasLimit({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["deleteGasLimit"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.deleteGasLimit(pubkey);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 204};
+  }
+
+  async listKeys(): ReturnType<Api["listKeys"]> {
+    const localKeys = this.validator.validatorStore
+      .votingPubkeys()
+      .filter((pubkey) => this.validator.validatorStore.getSigner(pubkey)?.type === SignerType.Local);
+
+    return {
+      data: localKeys.map((pubkey) => ({
+        validatingPubkey: pubkey,
+        derivationPath: "",
+        readonly: false,
+      })),
+    };
+  }
+
+  async importKeystores({
+    keystores,
+    passwords,
+    slashingProtection,
+  }: {
+    keystores: KeystoreStr[];
+    passwords: string[];
+    slashingProtection?: SlashingProtectionData;
+  }): ReturnType<Api["importKeystores"]> {
+    if (slashingProtection) {
+      // The arguments to this function is passed in within the body of an HTTP request
+      // hence fastify will parse it into an object before this function is called.
+      // Even though the slashingProtection is typed as SlashingProtectionData,
+      // at runtime, when the handler for the request is selected, it would see slashingProtection
+      // as an object, hence trying to parse it using JSON.parse won't work. Instead, we cast straight to Interchange
+      const interchange = ensureJSON<Interchange>(slashingProtection);
+      await this.validator.importInterchange(interchange);
+    }
+
+    const statuses: {status: ImportStatus; message?: string}[] = [];
+    const decryptKeystores = new DecryptKeystoresThreadPool(keystores.length, this.signal);
+
+    for (let i = 0; i < keystores.length; i++) {
+      try {
+        const keystoreStr = keystores[i];
+        const password = passwords[i];
+        if (password === undefined) {
+          throw new ApiError(400, `No password for keystores[${i}]`);
+        }
+
+        const keystore = Keystore.parse(keystoreStr);
+        const pubkeyHex = getPubkeyHexFromKeystore(keystore);
+
+        // Check for duplicates and skip keystore before decrypting
+        if (this.validator.validatorStore.hasVotingPubkey(pubkeyHex)) {
+          statuses[i] = {status: ImportStatus.duplicate};
+          continue;
+        }
+
+        decryptKeystores.queue(
+          {keystoreStr, password},
+          async (secretKeyBytes: Uint8Array) => {
+            const secretKey = SecretKey.fromBytes(secretKeyBytes);
+
+            // Persist the key to disk for restarts, before adding to in-memory store
+            // If the keystore exist and has a lock it will throw
+            this.persistedKeysBackend.writeKeystore({
+              keystoreStr,
+              password,
+              // Lock immediately since it's gonna be used
+              lockBeforeWrite: true,
+              // Always write, even if it's already persisted for consistency.
+              // The in-memory validatorStore is the ground truth to decide duplicates
+              persistIfDuplicate: true,
+            });
+
+            // Add to in-memory store to start validating immediately
+            await this.validator.validatorStore.addSigner({type: SignerType.Local, secretKey});
+
+            statuses[i] = {status: ImportStatus.imported};
+          },
+          (e: Error) => {
+            statuses[i] = {status: ImportStatus.error, message: e.message};
+          }
+        );
+      } catch (e) {
+        statuses[i] = {status: ImportStatus.error, message: (e as Error).message};
+      }
+    }
+
+    await decryptKeystores.completed();
+
+    return {data: statuses};
+  }
+
+  async deleteKeys({pubkeys}: {pubkeys: PubkeyHex[]}): ReturnType<Api["deleteKeys"]> {
+    const deletedKey: boolean[] = [];
+    const statuses = new Array<{status: DeletionStatus; message?: string}>(pubkeys.length);
+
+    for (let i = 0; i < pubkeys.length; i++) {
+      try {
+        const pubkeyHex = pubkeys[i];
+
+        if (!isValidatePubkeyHex(pubkeyHex)) {
+          throw new ApiError(400, `Invalid pubkey ${pubkeyHex}`);
+        }
+
+        // Skip unknown keys or remote signers
+        const signer = this.validator.validatorStore.getSigner(pubkeyHex);
+        if (signer && signer.type === SignerType.Local) {
+          // Remove key from live local signer
+          deletedKey[i] = this.validator.validatorStore.removeSigner(pubkeyHex);
+
+          // Remove key from block duties
+          // Remove from attestation duties
+          // Remove from Sync committee duties
+          // Remove from indices
+          this.validator.removeDutiesForKey(pubkeyHex);
+        }
+
+        // Attempts to delete everything first, and returns status.
+        // This unlocks the keystore, so perform after deleting from in-memory store
+        const diskDeleteStatus = this.persistedKeysBackend.deleteKeystore(pubkeyHex);
+
+        if (diskDeleteStatus) {
+          // TODO: What if the diskDeleteStatus status is inconsistent?
+          deletedKey[i] = true;
+        }
+      } catch (e) {
+        statuses[i] = {status: DeletionStatus.error, message: (e as Error).message};
+      }
+    }
+
+    const pubkeysBytes = pubkeys.map((pubkeyHex) => fromHex(pubkeyHex));
+
+    const interchangeV5 = await this.validator.exportInterchange(pubkeysBytes, {
+      version: "5",
+    });
+
+    // After exporting slashing protection data in bulk, render the status
+    const pubkeysWithSlashingProtectionData = new Set(interchangeV5.data.map((data) => data.pubkey));
+    for (let i = 0; i < pubkeys.length; i++) {
+      if (statuses[i]?.status === DeletionStatus.error) {
+        continue;
+      }
+      const status = deletedKey[i]
+        ? DeletionStatus.deleted
+        : pubkeysWithSlashingProtectionData.has(pubkeys[i])
+          ? DeletionStatus.not_active
+          : DeletionStatus.not_found;
+      statuses[i] = {status};
+    }
+
+    return {
+      data: {
+        statuses,
+        slashingProtection: JSON.stringify(interchangeV5),
+      },
+    };
+  }
+
+  async listRemoteKeys(): ReturnType<Api["listRemoteKeys"]> {
+    const remoteKeys: SignerDefinition[] = [];
+
+    for (const pubkeyHex of this.validator.validatorStore.votingPubkeys()) {
+      const signer = this.validator.validatorStore.getSigner(pubkeyHex);
+      if (signer && signer.type === SignerType.Remote) {
+        remoteKeys.push({pubkey: signer.pubkey, url: signer.url, readonly: false});
+      }
+    }
+
+    return {
+      data: remoteKeys,
+    };
+  }
+
+  async importRemoteKeys({
+    remoteSigners,
+  }: {
+    remoteSigners: RemoteSignerDefinition[];
+  }): ReturnType<Api["importRemoteKeys"]> {
+    const importPromises = remoteSigners.map(async ({pubkey, url}): Promise<ResponseStatus<ImportRemoteKeyStatus>> => {
+      try {
+        if (!isValidatePubkeyHex(pubkey)) {
+          throw new ApiError(400, `Invalid pubkey ${pubkey}`);
+        }
+        if (!isValidHttpUrl(url)) {
+          throw new ApiError(400, `Invalid URL ${url}`);
+        }
+
+        // Check if key exists
+        if (this.validator.validatorStore.hasVotingPubkey(pubkey)) {
+          return {status: ImportRemoteKeyStatus.duplicate};
+        }
+
+        // Else try to add it
+
+        await this.validator.validatorStore.addSigner({type: SignerType.Remote, pubkey, url});
+
+        this.persistedKeysBackend.writeRemoteKey({
+          pubkey,
+          url,
+          // Always write, even if it's already persisted for consistency.
+          // The in-memory validatorStore is the ground truth to decide duplicates
+          persistIfDuplicate: true,
+        });
+
+        return {status: ImportRemoteKeyStatus.imported};
+      } catch (e) {
+        return {status: ImportRemoteKeyStatus.error, message: (e as Error).message};
+      }
+    });
+
+    return {
+      data: await Promise.all(importPromises),
+    };
+  }
+
+  async deleteRemoteKeys({pubkeys}: {pubkeys: PubkeyHex[]}): ReturnType<Api["deleteRemoteKeys"]> {
+    const results = pubkeys.map((pubkeyHex): ResponseStatus<DeleteRemoteKeyStatus> => {
+      try {
+        if (!isValidatePubkeyHex(pubkeyHex)) {
+          throw new ApiError(400, `Invalid pubkey ${pubkeyHex}`);
+        }
+
+        const signer = this.validator.validatorStore.getSigner(pubkeyHex);
+
+        // Remove key from live local signer
+        const deletedFromMemory =
+          signer && signer.type === SignerType.Remote ? this.validator.validatorStore.removeSigner(pubkeyHex) : false;
+
+        if (deletedFromMemory) {
+          // Remove duties if key was deleted from in-memory store
+          this.validator.removeDutiesForKey(pubkeyHex);
+        }
+
+        const deletedFromDisk = this.persistedKeysBackend.deleteRemoteKey(pubkeyHex);
+
+        return {
+          status:
+            deletedFromMemory || deletedFromDisk ? DeleteRemoteKeyStatus.deleted : DeleteRemoteKeyStatus.not_found,
+        };
+      } catch (e) {
+        return {status: DeleteRemoteKeyStatus.error, message: (e as Error).message};
+      }
+    });
+
+    return {
+      data: results,
+    };
+  }
+
+  async getBuilderBoostFactor({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["getBuilderBoostFactor"]> {
+    this.assertValidKnownPubkey(pubkey);
+    const builderBoostFactor = this.validator.validatorStore.getBuilderBoostFactor(pubkey);
+    return {data: {pubkey, builderBoostFactor}};
+  }
+
+  async setBuilderBoostFactor({
+    pubkey,
+    builderBoostFactor,
+  }: BuilderBoostFactorData): ReturnType<Api["setBuilderBoostFactor"]> {
+    this.checkIfProposerWriteEnabled();
+    this.assertValidKnownPubkey(pubkey);
+    this.validator.validatorStore.setBuilderBoostFactor(pubkey, builderBoostFactor);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 202};
+  }
+
+  async deleteBuilderBoostFactor({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["deleteBuilderBoostFactor"]> {
+    this.checkIfProposerWriteEnabled();
+    this.validator.validatorStore.deleteBuilderBoostFactor(pubkey);
+    this.persistedKeysBackend.writeProposerConfig(pubkey, this.validator.validatorStore.getProposerConfig(pubkey));
+    return {status: 204};
+  }
+
+  async getProposerConfig({pubkey}: {pubkey: PubkeyHex}): ReturnType<Api["getProposerConfig"]> {
+    this.assertValidKnownPubkey(pubkey);
+
+    const config = this.validator.validatorStore.getProposerConfig(pubkey);
+
+    const data: ProposerConfigResponse = {
+      ...config,
+      builder: config?.builder
+        ? {
+            ...config.builder,
+            // Default JSON serialization can't handle BigInt
+            boostFactor: config.builder.boostFactor ? config.builder.boostFactor.toString() : undefined,
+          }
+        : undefined,
+    };
+
+    return {data};
+  }
+
+  async signVoluntaryExit({pubkey, epoch}: {pubkey: PubkeyHex; epoch?: Epoch}): ReturnType<Api["signVoluntaryExit"]> {
+    this.assertValidKnownPubkey(pubkey);
+    return {data: await this.validator.signVoluntaryExit(pubkey, epoch)};
+  }
+
+  private assertValidKnownPubkey(pubkey: PubkeyHex): void {
+    if (!isValidatePubkeyHex(pubkey)) {
+      throw new ApiError(400, `Invalid pubkey ${pubkey}`);
+    }
+
+    if (!this.validator.validatorStore.hasVotingPubkey(pubkey)) {
+      throw new ApiError(404, `Validator pubkey ${pubkey} not known`);
+    }
+  }
+}
+
+/**
+ * Given a variable with JSON that maybe stringified or not, return parsed JSON
+ */
+function ensureJSON<T>(strOrJson: string | T): T {
+  if (typeof strOrJson === "string") {
+    return JSON.parse(strOrJson) as T;
+  }
+  return strOrJson;
+}

package/src/cmds/validator/keymanager/interface.ts

@@ -0,0 +1,35 @@
+import {PubkeyHex, SignerDefinition} from "@lodestar/api/keymanager";
+import {ProposerConfig} from "@lodestar/validator";
+
+export type LocalKeystoreDefinition = {
+  keystorePath: string;
+  password: string;
+};
+
+export interface IPersistedKeysBackend {
+  readAllKeystores(): LocalKeystoreDefinition[];
+
+  /** Returns true some item is written to disk */
+  writeKeystore(args: {
+    keystoreStr: string;
+    password: string;
+    lockBeforeWrite: boolean;
+    persistIfDuplicate: boolean;
+  }): boolean;
+
+  /** Returns true some item is deleted from disk */
+  deleteKeystore(pubkey: PubkeyHex): boolean;
+
+  readAllRemoteKeys(): SignerDefinition[];
+
+  /** Returns true some item is written to disk */
+  writeRemoteKey(args: {pubkey: PubkeyHex; url: string; persistIfDuplicate: boolean}): boolean;
+
+  /** Returns true some item is deleted from disk */
+  deleteRemoteKey(pubkey: PubkeyHex): boolean;
+
+  writeProposerConfig(pubkey: PubkeyHex, proposerConfig: ProposerConfig | null): void;
+  deleteProposerConfig(pubkeyHex: PubkeyHex): void;
+  readProposerConfigs(): {[index: string]: ProposerConfig};
+  deleteProposerConfigs(): void;
+}

package/src/cmds/validator/keymanager/keystoreCache.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import {Keystore} from "@chainsafe/bls-keystore";
+import {SecretKey} from "@chainsafe/blst";
+import {fromHex, toHex, toPubkeyHex} from "@lodestar/utils";
+import {SignerLocal, SignerType} from "@lodestar/validator";
+import {writeFile600Perm} from "../../../util/file.js";
+import {lockFilepath, unlockFilepath} from "../../../util/lockfile.js";
+import {LocalKeystoreDefinition} from "./interface.js";
+
+export async function loadKeystoreCache(
+  cacheFilepath: string,
+  keystoreDefinitions: LocalKeystoreDefinition[]
+): Promise<SignerLocal[]> {
+  const keystores: Keystore[] = [];
+  const passwords: string[] = [];
+  for (const {keystorePath, password} of keystoreDefinitions) {
+    keystores.push(Keystore.parse(fs.readFileSync(keystorePath, "utf8")));
+    passwords.push(password);
+  }
+
+  if (keystores.length !== passwords.length) {
+    throw new Error(
+      `Number of keystores and passwords must be equal. keystores=${keystores.length}, passwords=${passwords.length}`
+    );
+  }
+
+  if (!fs.existsSync(cacheFilepath)) {
+    throw new Error(`Cache file ${cacheFilepath} does not exists.`);
+  }
+
+  lockFilepath(cacheFilepath);
+
+  const password = passwords.join("");
+  // We can't use Keystore.parse as it validates the `encrypted message` to be only 32 bytes.
+  const keystore = new Keystore(JSON.parse(fs.readFileSync(cacheFilepath, "utf8")));
+  const secretKeyConcatenatedBytes = await keystore.decrypt(password);
+
+  const result: SignerLocal[] = [];
+  for (const [index, k] of keystores.entries()) {
+    const secretKeyBytes = Uint8Array.prototype.slice.call(secretKeyConcatenatedBytes, index * 32, (index + 1) * 32);
+    const secretKey = SecretKey.fromBytes(secretKeyBytes);
+    const publicKey = secretKey.toPublicKey().toBytes();
+
+    if (toPubkeyHex(publicKey) !== toPubkeyHex(fromHex(k.pubkey))) {
+      throw new Error(
+        `Keystore ${k.uuid} does not match the expected pubkey. expected=${toPubkeyHex(fromHex(k.pubkey))}, found=${toHex(
+          publicKey
+        )}`
+      );
+    }
+
+    result.push({
+      type: SignerType.Local,
+      secretKey,
+    });
+  }
+
+  unlockFilepath(cacheFilepath);
+
+  return result;
+}
+
+export async function writeKeystoreCache(
+  cacheFilepath: string,
+  signers: SignerLocal[],
+  passwords: string[]
+): Promise<void> {
+  if (signers.length !== passwords.length) {
+    throw new Error(
+      `Number of signers and passwords must be equal. signers=${signers.length}, passwords=${passwords.length}`
+    );
+  }
+  const secretKeys = signers.map((s) => s.secretKey.toBytes());
+  const publicKeys = signers.map((s) => s.secretKey.toPublicKey().toBytes());
+  const password = passwords.join("");
+  const secretKeyConcatenatedBytes = Buffer.concat(secretKeys);
+  const publicConcatenatedBytes = Buffer.concat(publicKeys);
+  const keystore = await Keystore.create(password, secretKeyConcatenatedBytes, publicConcatenatedBytes, cacheFilepath);
+  if (!fs.existsSync(path.dirname(cacheFilepath))) fs.mkdirSync(path.dirname(cacheFilepath), {recursive: true});
+  lockFilepath(cacheFilepath);
+  writeFile600Perm(cacheFilepath, keystore.stringify());
+  unlockFilepath(cacheFilepath);
+}
+
+export async function clearKeystoreCache(cacheFilepath: string): Promise<void> {
+  if (fs.existsSync(cacheFilepath)) {
+    unlockFilepath(cacheFilepath);
+    fs.unlinkSync(cacheFilepath);
+  }
+}