@aztec/cli 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/cmds/validator_keys/index.ts

@@ -0,0 +1,142 @@
+import type { LogFn } from '@aztec/foundation/log';
+
+import { Command } from 'commander';
+
+import { parseAztecAddress, parseEthereumAddress, parseHex, parseOptionalInteger } from '../../utils/commands.js';
+import { defaultBlsPath } from './utils.js';
+
+export function injectCommands(program: Command, log: LogFn) {
+  const group = program
+    .command('validator-keys')
+    .aliases(['valKeys', 'valkeys'])
+    .description('Manage validator keystores for node operators');
+
+  group
+    .command('new')
+    .summary('Generate a new validator keystore JSON')
+    .description('Generates a new validator keystore with ETH secp256k1 accounts and optional BLS accounts')
+    .option('--data-dir <path>', 'Directory to store keystore(s). Defaults to ~/.aztec/keystore')
+    .option('--file <name>', 'Keystore file name. Defaults to key1.json (or keyN.json if key1.json exists)')
+    .option('--count <N>', 'Number of validators to generate', parseOptionalInteger)
+    .option('--publisher-count <N>', 'Number of publisher accounts per validator (default 0)', value =>
+      parseOptionalInteger(value, 0),
+    )
+    .option('--publishers <privateKeys>', 'Comma-separated list of publisher private keys for all validators.', value =>
+      value.split(',').map((key: string) => key.trim()),
+    )
+    .option('--mnemonic <mnemonic>', 'Mnemonic for ETH/BLS derivation')
+    .option('--passphrase <str>', 'Optional passphrase for mnemonic')
+    .option('--account-index <N>', 'Base account index for ETH/BLS derivation', parseOptionalInteger)
+    .option('--address-index <N>', 'Base address index for ETH/BLS derivation', parseOptionalInteger)
+    .option(
+      '--coinbase <address>',
+      'Coinbase ETH address to use when proposing. Defaults to attester address.',
+      parseEthereumAddress,
+    )
+    // TODO: add funding account back in when implemented
+    // .option('--funding-account <privateKey|address>', 'ETH private key (or address for remote signer setup) to fund publishers')
+    .option('--remote-signer <url>', 'Default remote signer URL for accounts in this file')
+    .option('--ikm <hex>', 'Initial keying material for BLS (alternative to mnemonic)', value => parseHex(value, 32))
+    .option('--bls-path <path>', `EIP-2334 path (default ${defaultBlsPath})`)
+    .option(
+      '--password <str>',
+      'Password for writing keystore files (ETH JSON V3 and BLS EIP-2335). Empty string allowed',
+    )
+    .option('--encrypted-keystore-dir <dir>', 'Output directory for encrypted keystore file(s)')
+    .option('--json', 'Echo resulting JSON to stdout')
+    .option('--staker-output', 'Generate a single staker output JSON file with an array of validator entries')
+    .option('--gse-address <address>', 'GSE contract address (required with --staker-output)', parseEthereumAddress)
+    .option('--l1-rpc-urls <urls>', 'L1 RPC URLs (comma-separated, required with --staker-output)', value =>
+      value.split(','),
+    )
+    .option(
+      '-c, --l1-chain-id <number>',
+      'L1 chain ID (required with --staker-output)',
+      value => parseInt(value),
+      31337,
+    )
+    .requiredOption('--fee-recipient <address>', 'Aztec address that will receive fees', parseAztecAddress)
+    .action(async options => {
+      const { newValidatorKeystore } = await import('./new.js');
+
+      await newValidatorKeystore(options, log);
+    });
+
+  group
+    .command('add')
+    .summary('Augment an existing validator keystore JSON')
+    .description('Adds attester/publisher/BLS entries to an existing keystore using the same flags as new')
+    .argument('<existing>', 'Path to existing keystore JSON')
+    .option('--data-dir <path>', 'Directory where keystore(s) live. (default: ~/.aztec/keystore)')
+    .option('--file <name>', 'Override output file name. (default: key<N>.json)')
+    .option('--count <N>', 'Number of validators to add. (default: 1)', parseOptionalInteger)
+    .option('--publisher-count <N>', 'Number of publisher accounts per validator (default 0)', value =>
+      parseOptionalInteger(value, 0),
+    )
+    .option('--publishers <privateKeys>', 'Comma-separated list of publisher private keys for all validators.', value =>
+      value.split(',').map((key: string) => key.trim()),
+    )
+    .option('--mnemonic <mnemonic>', 'Mnemonic for ETH/BLS derivation')
+    .option('--passphrase <str>', 'Optional passphrase for mnemonic')
+    .option('--account-index <N>', 'Base account index for ETH/BLS derivation', parseOptionalInteger)
+    .option('--address-index <N>', 'Base address index for ETH/BLS derivation', parseOptionalInteger)
+    .option(
+      '--coinbase <address>',
+      'Coinbase ETH address to use when proposing. Defaults to attester address.',
+      parseEthereumAddress,
+    )
+    // TODO: add funding account back in when implemented
+    // .option('--funding-account <privateKey|address>', 'ETH private key (or address for remote signer setup) to fund publishers')
+    .option('--remote-signer <url>', 'Default remote signer URL for accounts in this file')
+    .option('--ikm <hex>', 'Initial keying material for BLS (alternative to mnemonic)', value => parseHex(value, 32))
+    .option('--bls-path <path>', `EIP-2334 path (default ${defaultBlsPath})`)
+    .option('--empty', 'Generate an empty skeleton without keys')
+    .option(
+      '--password <str>',
+      'Password for writing keystore files (ETH JSON V3 and BLS EIP-2335). Empty string allowed',
+    )
+    .option('--encrypted-keystore-dir <dir>', 'Output directory for encrypted keystore file(s)')
+    .option('--json', 'Echo resulting JSON to stdout')
+    .requiredOption('--fee-recipient <address>', 'Aztec address that will receive fees', parseAztecAddress)
+    .action(async (existing: string, options) => {
+      const { addValidatorKeys } = await import('./add.js');
+      await addValidatorKeys(existing, options, log);
+    });
+
+  group
+    .command('staker')
+    .summary('Generate staking JSON from keystore')
+    .description(
+      'Reads a validator keystore and outputs staking data with BLS public keys for each attester (skips mnemonics)',
+    )
+    .requiredOption('--from <keystore>', 'Path to keystore JSON file')
+    .option('--password <password>', 'Password for decrypting encrypted keystores (if not specified in keystore file)')
+    .requiredOption('--gse-address <address>', 'GSE contract address', parseEthereumAddress)
+    .option('--l1-rpc-urls <urls>', 'L1 RPC URLs (comma-separated)', value => value.split(','), [
+      'http://localhost:8545',
+    ])
+    .option('-c, --l1-chain-id <number>', 'L1 chain ID', value => parseInt(value), 31337)
+    .option('--output <file>', 'Output file path (if not specified, JSON is written to stdout)')
+    .action(async options => {
+      const { generateStakerJson } = await import('./staker.js');
+      await generateStakerJson(options, log);
+    });
+
+  // top-level convenience: aztec generate-bls-keypair
+  program
+    .command('generate-bls-keypair')
+    .description('Generate a BLS keypair with convenience flags')
+    .option('--mnemonic <mnemonic>', 'Mnemonic for BLS derivation')
+    .option('--ikm <hex>', 'Initial keying material for BLS (alternative to mnemonic)', value => parseHex(value, 32))
+    .option('--bls-path <path>', `EIP-2334 path (default ${defaultBlsPath})`)
+    .option('--g2', 'Derive on G2 subgroup')
+    .option('--compressed', 'Output compressed public key')
+    .option('--json', 'Print JSON output to stdout')
+    .option('--out <file>', 'Write output to file')
+    .action(async options => {
+      const { generateBlsKeypair } = await import('./generate_bls_keypair.js');
+      await generateBlsKeypair(options, log);
+    });
+
+  return program;
+}

package/src/cmds/validator_keys/new.ts

@@ -0,0 +1,207 @@
+import { prettyPrintJSON } from '@aztec/cli/utils';
+import { createEthereumChain } from '@aztec/ethereum/chain';
+import { GSEContract } from '@aztec/ethereum/contracts';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { LogFn } from '@aztec/foundation/log';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { writeFile } from 'fs/promises';
+import { basename, dirname, join } from 'path';
+import { createPublicClient, fallback, http } from 'viem';
+import { generateMnemonic, mnemonicToAccount } from 'viem/accounts';
+
+import {
+  buildValidatorEntries,
+  logValidatorSummaries,
+  maybePrintJson,
+  resolveKeystoreOutputPath,
+  writeBlsBn254ToFile,
+  writeEthJsonV3ToFile,
+  writeKeystoreFile,
+} from './shared.js';
+import { processAttesterAccounts } from './staker.js';
+import {
+  validateBlsPathOptions,
+  validatePublisherOptions,
+  validateRemoteSignerOptions,
+  validateStakerOutputOptions,
+} from './utils.js';
+
+export type NewValidatorKeystoreOptions = {
+  dataDir?: string;
+  file?: string;
+  count?: number;
+  publisherCount?: number;
+  publishers?: string[];
+  mnemonic?: string;
+  passphrase?: string;
+  accountIndex?: number;
+  addressIndex?: number;
+  separatePublisher?: boolean;
+  ikm?: string;
+  blsPath?: string;
+  password?: string;
+  encryptedKeystoreDir?: string;
+  json?: boolean;
+  feeRecipient: AztecAddress;
+  coinbase?: EthAddress;
+  remoteSigner?: string;
+  stakerOutput?: boolean;
+  gseAddress?: EthAddress;
+  l1RpcUrls?: string[];
+  l1ChainId?: number;
+};
+
+export async function newValidatorKeystore(options: NewValidatorKeystoreOptions, log: LogFn) {
+  // validate bls-path inputs before proceeding with key generation
+  validateBlsPathOptions(options);
+  // validate staker output options before proceeding with key generation
+  validateStakerOutputOptions(options);
+  // validate publisher options
+  validatePublisherOptions(options);
+  // validate remote signer options
+  validateRemoteSignerOptions(options);
+
+  const {
+    dataDir,
+    file,
+    count,
+    publisherCount = 0,
+    publishers,
+    json,
+    coinbase,
+    accountIndex = 0,
+    addressIndex = 0,
+    feeRecipient,
+    remoteSigner,
+    blsPath,
+    ikm,
+    mnemonic: _mnemonic,
+    password,
+    encryptedKeystoreDir,
+    stakerOutput,
+    gseAddress,
+    l1RpcUrls,
+    l1ChainId,
+  } = options;
+
+  const mnemonic = _mnemonic ?? generateMnemonic(wordlist);
+
+  if (!_mnemonic && !json) {
+    log('No mnemonic provided, generating new one...');
+    log(`Using new mnemonic:`);
+    log('');
+    log(mnemonic);
+    log('');
+  }
+
+  const validatorCount = typeof count === 'number' && Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
+  const { outputPath } = await resolveKeystoreOutputPath(dataDir, file);
+  const keystoreOutDir = dirname(outputPath);
+
+  const { validators, summaries } = await buildValidatorEntries({
+    validatorCount,
+    publisherCount,
+    publishers,
+    accountIndex,
+    baseAddressIndex: addressIndex,
+    mnemonic,
+    ikm,
+    blsPath,
+    feeRecipient,
+    coinbase,
+    remoteSigner,
+  });
+
+  // If password provided, write ETH JSON V3 and BLS BN254 keystores and replace plaintext
+  if (password !== undefined) {
+    const encryptedKeystoreOutDir =
+      encryptedKeystoreDir && encryptedKeystoreDir.length > 0 ? encryptedKeystoreDir : keystoreOutDir;
+    await writeEthJsonV3ToFile(validators, { outDir: encryptedKeystoreOutDir, password });
+    await writeBlsBn254ToFile(validators, { outDir: encryptedKeystoreOutDir, password });
+  }
+
+  const keystore = {
+    schemaVersion: 1,
+    validators,
+  };
+
+  await writeKeystoreFile(outputPath, keystore);
+
+  // Generate staker outputs if requested
+  const allStakerOutputs: any[] = [];
+  if (stakerOutput && gseAddress && l1RpcUrls && l1ChainId !== undefined) {
+    const chain = createEthereumChain(l1RpcUrls, l1ChainId);
+    const publicClient = createPublicClient({
+      chain: chain.chainInfo,
+      transport: fallback(l1RpcUrls.map(url => http(url, { batch: false }))),
+    });
+    const gse = new GSEContract(publicClient, gseAddress);
+
+    // Extract keystore base name without extension for unique staker output filenames
+    const keystoreBaseName = basename(outputPath, '.json');
+
+    // Process each validator
+    for (let i = 0; i < validators.length; i++) {
+      const validator = validators[i];
+      const outputs = await processAttesterAccounts(validator.attester, gse, password);
+
+      // Collect all staker outputs
+      for (let j = 0; j < outputs.length; j++) {
+        allStakerOutputs.push(outputs[j]);
+      }
+    }
+
+    // Write a single JSON file with all staker outputs
+    if (allStakerOutputs.length > 0) {
+      const stakerOutputPath = join(keystoreOutDir, `${keystoreBaseName}_staker_output.json`);
+      await writeFile(stakerOutputPath, prettyPrintJSON(allStakerOutputs), 'utf-8');
+    }
+  }
+
+  const outputData = !_mnemonic ? { ...keystore, generatedMnemonic: mnemonic } : keystore;
+
+  // Handle JSON output
+  if (json) {
+    if (stakerOutput && allStakerOutputs.length > 0) {
+      const combinedOutput = {
+        keystore: outputData,
+        staker: allStakerOutputs,
+      };
+      maybePrintJson(log, json, combinedOutput as unknown as Record<string, any>);
+    } else {
+      maybePrintJson(log, json, outputData as unknown as Record<string, any>);
+    }
+  } else {
+    log(`Wrote validator keystore to ${outputPath}`);
+    if (stakerOutput && allStakerOutputs.length > 0) {
+      const keystoreBaseName = basename(outputPath, '.json');
+      const stakerOutputPath = join(keystoreOutDir, `${keystoreBaseName}_staker_output.json`);
+      log(`Wrote staker output for ${allStakerOutputs.length} validator(s) to ${stakerOutputPath}`);
+      log('');
+    }
+  }
+
+  // print a concise summary of public keys (addresses and BLS pubkeys) if no --json options was selected
+  if (!json) {
+    logValidatorSummaries(log, summaries);
+  }
+
+  if (mnemonic && remoteSigner && !json) {
+    for (let i = 0; i < validatorCount; i++) {
+      const addrIdx = addressIndex + i;
+      const acct = mnemonicToAccount(mnemonic, {
+        accountIndex,
+        addressIndex: addrIdx,
+      });
+      log(`attester address: ${acct.address} remoteSignerUrl: ${remoteSigner}`);
+    }
+  }
+
+  // Log staker outputs if not in JSON mode
+  if (!json && stakerOutput && allStakerOutputs.length > 0) {
+    log('\nStaker outputs:');
+    log(prettyPrintJSON(allStakerOutputs));
+  }
+}

package/src/cmds/validator_keys/shared.ts

@@ -0,0 +1,326 @@
+import { prettyPrintJSON } from '@aztec/cli/utils';
+import { deriveBlsPrivateKey } from '@aztec/foundation/crypto/bls';
+import { createBn254Keystore } from '@aztec/foundation/crypto/bls/bn254_keystore';
+import { computeBn254G1PublicKeyCompressed } from '@aztec/foundation/crypto/bn254';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { LogFn } from '@aztec/foundation/log';
+import type { EthAccount, EthPrivateKey, ValidatorKeyStore } from '@aztec/node-keystore/types';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import { Wallet } from '@ethersproject/wallet';
+import { constants as fsConstants, mkdirSync } from 'fs';
+import { access, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, isAbsolute, join } from 'path';
+import { mnemonicToAccount } from 'viem/accounts';
+
+import { defaultBlsPath } from './utils.js';
+
+export type ValidatorSummary = { attesterEth?: string; attesterBls?: string; publisherEth?: string[] };
+
+export type BuildValidatorsInput = {
+  validatorCount: number;
+  publisherCount?: number;
+  publishers?: string[];
+  accountIndex: number;
+  baseAddressIndex: number;
+  mnemonic: string;
+  ikm?: string;
+  blsPath?: string;
+  feeRecipient: AztecAddress;
+  coinbase?: EthAddress;
+  remoteSigner?: string;
+};
+
+export function withValidatorIndex(path: string, accountIndex: number = 0, addressIndex: number = 0) {
+  // NOTE: The legacy BLS CLI is to allow users who generated keys in 2.1.4 to be able to use the same command
+  // to re-generate their keys. In 2.1.5 we switched how we append addresses to the path so this is to maintain backwards compatibility.
+  const useLegacyBlsCli = ['true', '1', 'yes', 'y'].includes(process.env.LEGACY_BLS_CLI ?? '');
+
+  const defaultBlsPathParts = defaultBlsPath.split('/');
+
+  const parts = path.split('/');
+  if (parts.length == defaultBlsPathParts.length && parts.every((part, index) => part === defaultBlsPathParts[index])) {
+    if (useLegacyBlsCli) {
+      // In 2.1.4, we were using address-index in parts[3] and did NOT use account-index, check lines 32 & 84
+      // https://github.com/AztecProtocol/aztec-packages/blob/v2.1.4/yarn-project/cli/src/cmds/validator_keys/shared.ts
+
+      parts[3] = String(addressIndex);
+    } else {
+      parts[3] = String(accountIndex);
+      parts[5] = String(addressIndex);
+    }
+    return parts.join('/');
+  }
+  return path;
+}
+
+/**
+ * Compute a compressed BN254 G1 public key from a private key.
+ * @param privateKeyHex - Private key as 0x-prefixed hex string
+ * @returns Compressed G1 point (32 bytes with sign bit in MSB)
+ */
+export async function computeBlsPublicKeyCompressed(privateKeyHex: string): Promise<string> {
+  return await computeBn254G1PublicKeyCompressed(privateKeyHex);
+}
+
+export function deriveEthAttester(
+  mnemonic: string,
+  baseAccountIndex: number,
+  addressIndex: number,
+  remoteSigner?: string,
+): EthAccount | EthPrivateKey {
+  const acct = mnemonicToAccount(mnemonic, { accountIndex: baseAccountIndex, addressIndex });
+  return remoteSigner
+    ? ({ address: acct.address as unknown as EthAddress, remoteSignerUrl: remoteSigner } as EthAccount)
+    : (('0x' + Buffer.from(acct.getHdKey().privateKey!).toString('hex')) as EthPrivateKey);
+}
+
+export async function buildValidatorEntries(input: BuildValidatorsInput) {
+  const {
+    validatorCount,
+    publisherCount = 0,
+    publishers,
+    accountIndex,
+    baseAddressIndex,
+    mnemonic,
+    ikm,
+    blsPath,
+    feeRecipient,
+    coinbase,
+    remoteSigner,
+  } = input;
+
+  const summaries: ValidatorSummary[] = [];
+
+  const validators = await Promise.all(
+    Array.from({ length: validatorCount }, async (_unused, i) => {
+      const addressIndex = baseAddressIndex + i;
+      const basePath = blsPath ?? defaultBlsPath;
+      const perValidatorPath = withValidatorIndex(basePath, accountIndex, addressIndex);
+
+      const blsPrivKey = ikm || mnemonic ? deriveBlsPrivateKey(mnemonic, ikm, perValidatorPath) : undefined;
+      const blsPubCompressed = blsPrivKey ? await computeBlsPublicKeyCompressed(blsPrivKey) : undefined;
+
+      const ethAttester = deriveEthAttester(mnemonic, accountIndex, addressIndex, remoteSigner);
+      const attester = blsPrivKey ? { eth: ethAttester, bls: blsPrivKey } : ethAttester;
+
+      let publisherField: EthAccount | EthPrivateKey | (EthAccount | EthPrivateKey)[] | undefined;
+      const publisherAddresses: string[] = [];
+      if (publishers && publishers.length > 0) {
+        publisherAddresses.push(...publishers);
+        publisherField = publishers.length === 1 ? (publishers[0] as EthPrivateKey) : (publishers as EthPrivateKey[]);
+      } else if (publisherCount > 0) {
+        const publishersBaseIndex = baseAddressIndex + validatorCount + i * publisherCount;
+        const publisherAccounts = Array.from({ length: publisherCount }, (_unused2, j) => {
+          const publisherAddressIndex = publishersBaseIndex + j;
+          const pubAcct = mnemonicToAccount(mnemonic, {
+            accountIndex,
+            addressIndex: publisherAddressIndex,
+          });
+          publisherAddresses.push(pubAcct.address as unknown as string);
+          return remoteSigner
+            ? ({ address: pubAcct.address as unknown as EthAddress, remoteSignerUrl: remoteSigner } as EthAccount)
+            : (('0x' + Buffer.from(pubAcct.getHdKey().privateKey!).toString('hex')) as EthPrivateKey);
+        });
+        publisherField = publisherCount === 1 ? publisherAccounts[0] : publisherAccounts;
+      }
+
+      const acct = mnemonicToAccount(mnemonic, {
+        accountIndex,
+        addressIndex,
+      });
+      const attesterEthAddress = acct.address as unknown as string;
+      summaries.push({
+        attesterEth: attesterEthAddress,
+        attesterBls: blsPubCompressed,
+        publisherEth: publisherAddresses.length > 0 ? publisherAddresses : undefined,
+      });
+
+      return {
+        attester,
+        ...(publisherField !== undefined ? { publisher: publisherField } : {}),
+        feeRecipient,
+        coinbase: coinbase ?? attesterEthAddress,
+      } as ValidatorKeyStore;
+    }),
+  );
+
+  return { validators, summaries };
+}
+
+export async function resolveKeystoreOutputPath(dataDir?: string, file?: string) {
+  const defaultDataDir = join(homedir(), '.aztec', 'keystore');
+  const resolvedDir = dataDir && dataDir.length > 0 ? dataDir : defaultDataDir;
+  let outputPath: string;
+  if (file && file.length > 0) {
+    outputPath = isAbsolute(file) ? file : join(resolvedDir, file);
+  } else {
+    let index = 1;
+    while (true) {
+      const candidate = join(resolvedDir, `key${index}.json`);
+      try {
+        await access(candidate, fsConstants.F_OK);
+        index += 1;
+      } catch {
+        outputPath = candidate;
+        break;
+      }
+    }
+  }
+  return { resolvedDir, outputPath: outputPath! };
+}
+
+export async function writeKeystoreFile(path: string, keystore: unknown) {
+  mkdirSync(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(keystore, null, 2), { encoding: 'utf-8' });
+}
+
+export function logValidatorSummaries(log: LogFn, summaries: ValidatorSummary[]) {
+  const lines: string[] = [];
+  for (let i = 0; i < summaries.length; i++) {
+    const v = summaries[i];
+    lines.push(`acc${i + 1}:`);
+    lines.push(`  attester:`);
+    if (v.attesterEth) {
+      lines.push(`    eth: ${v.attesterEth}`);
+    }
+    if (v.attesterBls) {
+      lines.push(`    bls: ${v.attesterBls}`);
+    }
+    if (v.publisherEth && v.publisherEth.length > 0) {
+      lines.push(`  publisher:`);
+      for (const addr of v.publisherEth) {
+        lines.push(`    - ${addr}`);
+      }
+    }
+  }
+  if (lines.length > 0) {
+    log(lines.join('\n'));
+  }
+}
+
+export function maybePrintJson(log: LogFn, jsonFlag: boolean | undefined, obj: unknown) {
+  if (jsonFlag) {
+    log(prettyPrintJSON(obj as Record<string, any>));
+  }
+}
+
+/**
+ * Writes a BN254 keystore file for a BN254 BLS private key.
+ * Returns the absolute path to the written file.
+ *
+ * @param outDir - Directory to write the keystore file to
+ * @param fileNameBase - Base name for the keystore file (will be sanitized)
+ * @param password - Password for encrypting the private key
+ * @param privateKeyHex - Private key as 0x-prefixed hex string (32 bytes)
+ * @param pubkeyHex - Public key as hex string
+ * @param derivationPath - BIP-44 style derivation path
+ * @returns Absolute path to the written keystore file
+ */
+export async function writeBn254BlsKeystore(
+  outDir: string,
+  fileNameBase: string,
+  password: string,
+  privateKeyHex: string,
+  pubkeyHex: string,
+  derivationPath: string,
+): Promise<string> {
+  mkdirSync(outDir, { recursive: true });
+
+  const keystore = createBn254Keystore(password, privateKeyHex, pubkeyHex, derivationPath);
+
+  const safeBase = fileNameBase.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const outPath = join(outDir, `keystore-${safeBase}.json`);
+  await writeFile(outPath, JSON.stringify(keystore, null, 2), { encoding: 'utf-8' });
+  return outPath;
+}
+
+/** Replace plaintext BLS keys in validators with { path, password } pointing to BN254 keystore files. */
+export async function writeBlsBn254ToFile(
+  validators: ValidatorKeyStore[],
+  options: { outDir: string; password: string; blsPath?: string },
+): Promise<void> {
+  for (let i = 0; i < validators.length; i++) {
+    const v = validators[i];
+    if (!v || typeof v !== 'object' || !('attester' in v)) {
+      continue;
+    }
+    const att = (v as any).attester;
+
+    // Shapes: { bls: <hex> } or { eth: <ethAccount>, bls?: <hex> } or plain EthAccount
+    const blsKey: string | undefined = typeof att === 'object' && 'bls' in att ? (att as any).bls : undefined;
+    if (!blsKey || typeof blsKey !== 'string') {
+      continue;
+    }
+
+    const pub = await computeBlsPublicKeyCompressed(blsKey);
+    const path = options.blsPath ?? defaultBlsPath;
+    const fileBase = `${String(i + 1)}_${pub.slice(2, 18)}`;
+    const keystorePath = await writeBn254BlsKeystore(options.outDir, fileBase, options.password, blsKey, pub, path);
+
+    if (typeof att === 'object') {
+      (att as any).bls = { path: keystorePath, password: options.password };
+    }
+  }
+}
+
+/** Writes an Ethereum JSON V3 keystore using ethers, returns absolute path */
+export async function writeEthJsonV3Keystore(
+  outDir: string,
+  fileNameBase: string,
+  password: string,
+  privateKeyHex: string,
+): Promise<string> {
+  const safeBase = fileNameBase.replace(/[^a-zA-Z0-9_-]/g, '_');
+  mkdirSync(outDir, { recursive: true });
+  const wallet = new Wallet(privateKeyHex);
+  const json = await wallet.encrypt(password);
+  const outPath = join(outDir, `keystore-eth-${safeBase}.json`);
+  await writeFile(outPath, json, { encoding: 'utf-8' });
+  return outPath;
+}
+
+/** Replace plaintext ETH keys in validators with { path, password } pointing to JSON V3 files. */
+export async function writeEthJsonV3ToFile(
+  validators: ValidatorKeyStore[],
+  options: { outDir: string; password: string },
+): Promise<void> {
+  const maybeEncryptEth = async (account: any, label: string) => {
+    if (typeof account === 'string' && account.startsWith('0x') && account.length === 66) {
+      const fileBase = `${label}_${account.slice(2, 10)}`;
+      const p = await writeEthJsonV3Keystore(options.outDir, fileBase, options.password, account);
+      return { path: p, password: options.password };
+    }
+    return account;
+  };
+
+  for (let i = 0; i < validators.length; i++) {
+    const v = validators[i];
+    if (!v || typeof v !== 'object') {
+      continue;
+    }
+
+    // attester may be string (eth), object with eth, or remote signer
+    const att = (v as any).attester;
+    if (typeof att === 'string') {
+      (v as any).attester = await maybeEncryptEth(att, `attester_${i + 1}`);
+    } else if (att && typeof att === 'object' && 'eth' in att) {
+      (att as any).eth = await maybeEncryptEth((att as any).eth, `attester_${i + 1}`);
+    }
+
+    // publisher can be single or array
+    if ('publisher' in v) {
+      const pub = (v as any).publisher;
+      if (Array.isArray(pub)) {
+        const out: any[] = [];
+        for (let j = 0; j < pub.length; j++) {
+          out.push(await maybeEncryptEth(pub[j], `publisher_${i + 1}_${j + 1}`));
+        }
+        (v as any).publisher = out;
+      } else if (pub !== undefined) {
+        (v as any).publisher = await maybeEncryptEth(pub, `publisher_${i + 1}`);
+      }
+    }
+  }
+}