@aztec-labs/cli 6.0.0-nightly.20260829

package/src/cmds/validator_keys/index.ts

@@ -0,0 +1,181 @@
+import type { LogFn } from '@aztec-labs/foundation/log';
+import { Command, Option } 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,
+    )
+    .option(
+      '--funding-account <privateKey|address>',
+      'ETH funding account used to top up publisher EOAs. Provide a private key, or an address together with --remote-signer.',
+    )
+    .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})`)
+    .addOption(
+      new Option('--password <str>', 'Shared password for writing ETH JSON V3 and BLS EIP-2335 keystore files').env(
+        'AZTEC_KEYSTORE_PASSWORD',
+      ),
+    )
+    .option('--password-file <path>', 'File containing the shared password for writing keystore files')
+    .addOption(
+      new Option('--eth-password <str>', 'Password for writing ETH JSON V3 keystore files').env(
+        'AZTEC_ETH_KEYSTORE_PASSWORD',
+      ),
+    )
+    .option('--eth-password-file <path>', 'File containing the password for writing ETH JSON V3 keystore files')
+    .addOption(
+      new Option('--bls-password <str>', 'Password for writing BLS EIP-2335 keystore files').env(
+        'AZTEC_BLS_KEYSTORE_PASSWORD',
+      ),
+    )
+    .option('--bls-password-file <path>', 'File containing the password for writing BLS EIP-2335 keystore files')
+    .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,
+    )
+    .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('set-funding-account')
+    .summary('Set the funding account of an existing keystore')
+    .description(
+      'Sets the keystore-level ETH funding account used to top up publisher EOAs, replacing any existing one',
+    )
+    .argument('<existing>', 'Path to existing keystore JSON')
+    .argument(
+      '<privateKey|address>',
+      'Funding account: a private key, or an address (needs --remote-signer unless the keystore already defines one)',
+    )
+    .option(
+      '--remote-signer <url>',
+      'Remote signer URL for the funding account (required with an address unless the keystore already defines one)',
+    )
+    .option(
+      '--password <str>',
+      'Password for writing the funding key as an encrypted ETH JSON V3 file. Empty string allowed',
+    )
+    .option('--encrypted-keystore-dir <dir>', 'Output directory for the encrypted funding key file')
+    .option('--json', 'Echo resulting JSON to stdout')
+    .action(async (existing: string, fundingAccount: string, options) => {
+      const { setFundingAccount } = await import('./set_funding_account.js');
+      await setFundingAccount(existing, fundingAccount, 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,326 @@
+import { prettyPrintJSON } from '@aztec-labs/cli/utils';
+import { createEthereumChain } from '@aztec-labs/ethereum/chain';
+import { GSEContract } from '@aztec-labs/ethereum/contracts';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { LogFn } from '@aztec-labs/foundation/log';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { readFile, writeFile } from 'fs/promises';
+import { basename, dirname, join } from 'path';
+import { createPublicClient, fallback, http } from 'viem';
+import { generateMnemonic, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
+
+import {
+  buildValidatorEntries,
+  encryptFundingAccountToFile,
+  logValidatorSummaries,
+  maybePrintJson,
+  resolveFundingAccount,
+  resolveKeystoreOutputPath,
+  writeBlsBn254ToFile,
+  writeEthJsonV3ToFile,
+  writeKeystoreFile,
+} from './shared.js';
+import { processAttesterAccounts } from './staker.js';
+import {
+  validateBlsPathOptions,
+  validateFundingAccountOptions,
+  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;
+  passwordFile?: string;
+  ethPassword?: string;
+  ethPasswordFile?: string;
+  blsPassword?: string;
+  blsPasswordFile?: string;
+  encryptedKeystoreDir?: string;
+  json?: boolean;
+  feeRecipient: AztecAddress;
+  coinbase?: EthAddress;
+  fundingAccount?: string;
+  remoteSigner?: string;
+  stakerOutput?: boolean;
+  gseAddress?: EthAddress;
+  l1RpcUrls?: string[];
+  l1ChainId?: number;
+};
+
+type PasswordSourceOptions = Pick<
+  NewValidatorKeystoreOptions,
+  'password' | 'passwordFile' | 'ethPassword' | 'ethPasswordFile' | 'blsPassword' | 'blsPasswordFile'
+>;
+
+type PasswordSource = {
+  password?: string;
+  passwordFile?: string;
+  passwordOption: string;
+  passwordFileOption: string;
+};
+
+function validatePassword(password: string, source: string): string {
+  if (password.length === 0) {
+    throw new Error(`${source} cannot be empty`);
+  }
+  return password;
+}
+
+function stripOneTrailingNewline(password: string): string {
+  if (password.endsWith('\n')) {
+    password = password.slice(0, -1);
+  }
+  if (password.endsWith('\r')) {
+    password = password.slice(0, -1);
+  }
+  return password;
+}
+
+async function resolvePasswordSource(source: PasswordSource): Promise<string | undefined> {
+  if (source.password !== undefined && source.passwordFile !== undefined) {
+    throw new Error(`${source.passwordOption} and ${source.passwordFileOption} cannot be used together`);
+  }
+  if (source.password !== undefined) {
+    return validatePassword(source.password, source.passwordOption);
+  }
+  if (source.passwordFile !== undefined) {
+    if (source.passwordFile.length === 0) {
+      throw new Error(`${source.passwordFileOption} cannot be empty`);
+    }
+    const password = stripOneTrailingNewline(await readFile(source.passwordFile, 'utf-8'));
+    return validatePassword(password, source.passwordFileOption);
+  }
+
+  return undefined;
+}
+
+async function resolvePasswords(options: PasswordSourceOptions) {
+  const sharedPassword = await resolvePasswordSource({
+    password: options.password,
+    passwordFile: options.passwordFile,
+    passwordOption: '--password',
+    passwordFileOption: '--password-file',
+  });
+  const ethPassword =
+    (await resolvePasswordSource({
+      password: options.ethPassword,
+      passwordFile: options.ethPasswordFile,
+      passwordOption: '--eth-password',
+      passwordFileOption: '--eth-password-file',
+    })) ?? sharedPassword;
+  const blsPassword =
+    (await resolvePasswordSource({
+      password: options.blsPassword,
+      passwordFile: options.blsPasswordFile,
+      passwordOption: '--bls-password',
+      passwordFileOption: '--bls-password-file',
+    })) ?? sharedPassword;
+
+  if (ethPassword === undefined && blsPassword === undefined) {
+    return {};
+  }
+  if (ethPassword === undefined || blsPassword === undefined) {
+    throw new Error(
+      'Both ETH and BLS passwords are required when writing encrypted keystores. Provide --password to use one password for both, or provide both --eth-password and --bls-password.',
+    );
+  }
+  return { ethPassword, blsPassword };
+}
+
+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);
+  // validate funding account option
+  validateFundingAccountOptions(options);
+
+  const {
+    dataDir,
+    file,
+    count,
+    publisherCount = 0,
+    publishers,
+    json,
+    coinbase,
+    fundingAccount,
+    accountIndex = 0,
+    addressIndex = 0,
+    feeRecipient,
+    remoteSigner,
+    blsPath,
+    ikm,
+    mnemonic: _mnemonic,
+    password: passwordOption,
+    passwordFile,
+    ethPassword: ethPasswordOption,
+    ethPasswordFile,
+    blsPassword: blsPasswordOption,
+    blsPasswordFile,
+    encryptedKeystoreDir,
+    stakerOutput,
+    gseAddress,
+    l1RpcUrls,
+    l1ChainId,
+  } = options;
+
+  const { ethPassword, blsPassword } = await resolvePasswords({
+    password: passwordOption,
+    passwordFile,
+    ethPassword: ethPasswordOption,
+    ethPasswordFile,
+    blsPassword: blsPasswordOption,
+    blsPasswordFile,
+  });
+  const shouldEncryptKeystores = ethPassword !== undefined && blsPassword !== undefined;
+  const mnemonic = _mnemonic ?? generateMnemonic(wordlist);
+
+  if (!_mnemonic && !json && !shouldEncryptKeystores) {
+    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,
+  });
+
+  let resolvedFundingAccount = fundingAccount ? resolveFundingAccount(fundingAccount, remoteSigner) : undefined;
+
+  // If password provided, write ETH JSON V3 and BLS BN254 keystores and replace plaintext
+  if (shouldEncryptKeystores) {
+    const encryptedKeystoreOutDir =
+      encryptedKeystoreDir && encryptedKeystoreDir.length > 0 ? encryptedKeystoreDir : keystoreOutDir;
+    await writeEthJsonV3ToFile(validators, { outDir: encryptedKeystoreOutDir, password: ethPassword });
+    await writeBlsBn254ToFile(validators, { outDir: encryptedKeystoreOutDir, password: blsPassword });
+    if (resolvedFundingAccount) {
+      resolvedFundingAccount = await encryptFundingAccountToFile(resolvedFundingAccount, {
+        outDir: encryptedKeystoreOutDir,
+        password: ethPassword,
+      });
+    }
+  }
+
+  const keystore = {
+    schemaVersion: 1,
+    validators,
+    ...(resolvedFundingAccount ? { fundingAccount: resolvedFundingAccount } : {}),
+  };
+
+  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);
+
+      // 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 && !shouldEncryptKeystores ? { ...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 (fundingAccount) {
+      const funderAddress =
+        fundingAccount.length === 66 ? privateKeyToAccount(fundingAccount as `0x${string}`).address : fundingAccount;
+      log(`funding account: ${funderAddress}`);
+    }
+  }
+
+  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/set_funding_account.ts

@@ -0,0 +1,54 @@
+import type { LogFn } from '@aztec-labs/foundation/log';
+import { loadKeystoreFile } from '@aztec-labs/node-keystore/loader';
+import type { KeyStore } from '@aztec-labs/node-keystore/types';
+import { dirname } from 'path';
+import { privateKeyToAccount } from 'viem/accounts';
+
+import { encryptFundingAccountToFile, maybePrintJson, resolveFundingAccount, writeKeystoreFile } from './shared.js';
+import { validateFundingAccountOptions } from './utils.js';
+
+export type SetFundingAccountOptions = {
+  remoteSigner?: string;
+  password?: string;
+  encryptedKeystoreDir?: string;
+  json?: boolean;
+};
+
+/**
+ * Sets the top-level funding account of an existing keystore, replacing any previous one. The
+ * account may be a private key, or an address paired with a remote signer URL. With a password,
+ * a plaintext key is encrypted to an ETH JSON V3 file and stored as a { path, password } reference.
+ */
+export async function setFundingAccount(
+  existing: string,
+  fundingAccount: string,
+  options: SetFundingAccountOptions,
+  log: LogFn,
+) {
+  const { remoteSigner, password, encryptedKeystoreDir, json } = options;
+
+  const keystore: KeyStore = loadKeystoreFile(existing);
+
+  const validated = { fundingAccount, remoteSigner };
+  validateFundingAccountOptions(validated, !!keystore.remoteSigner);
+
+  let resolved = resolveFundingAccount(validated.fundingAccount!, remoteSigner);
+  if (password !== undefined) {
+    const outDir = encryptedKeystoreDir && encryptedKeystoreDir.length > 0 ? encryptedKeystoreDir : dirname(existing);
+    resolved = await encryptFundingAccountToFile(resolved, { outDir, password });
+  }
+
+  if (keystore.fundingAccount) {
+    log('Replacing existing funding account in keystore');
+  }
+  keystore.fundingAccount = resolved;
+
+  await writeKeystoreFile(existing, keystore);
+
+  if (!json) {
+    const value = validated.fundingAccount!;
+    const funderAddress = value.length === 66 ? privateKeyToAccount(value as `0x${string}`).address : value;
+    log(`Set funding account ${funderAddress} in ${existing}`);
+  }
+  maybePrintJson(log, !!json, keystore as unknown as Record<string, any>);
+}