feat: aztec valkeys CLI on top of bb.js BN254 ecc (#18018)

Merging #17968 & #17848

Author: AztecBot

yarn-project/aztec/src/bin/index.ts

@@ -7,6 +7,7 @@ import { injectCommands as injectContractCommands } from '@aztec/cli/contracts';
 import { injectCommands as injectInfrastructureCommands } from '@aztec/cli/infrastructure';
 import { injectCommands as injectL1Commands } from '@aztec/cli/l1';
 import { injectCommands as injectMiscCommands } from '@aztec/cli/misc';
+import { injectCommands as injectValidatorKeysCommands } from '@aztec/cli/validator_keys';
 import { getActiveNetworkName } from '@aztec/foundation/config';
 import { createConsoleLogger, createLogger } from '@aztec/foundation/log';
 
@@ -51,6 +52,7 @@ async function main() {
   program = injectL1Commands(program, userLog, debugLogger);
   program = injectAztecNodeCommands(program, userLog, debugLogger);
   program = injectMiscCommands(program, userLog);
+  program = injectValidatorKeysCommands(program, userLog);
 
   await program.parseAsync(process.argv);
 }

yarn-project/cli/package.json

@@ -10,6 +10,7 @@
     "./aztec_node": "./dest/cmds/aztec_node/index.js",
     "./cli-utils": "./dest/utils/index.js",
     "./misc": "./dest/cmds/misc/index.js",
+    "./validator_keys": "./dest/cmds/validator_keys/index.js",
     "./setup-contracts": "./dest/cmds/misc/setup_contracts.js",
     "./utils": "./dest/utils/index.js",
     "./inspect": "./dest/utils/inspect.js",
@@ -78,14 +79,17 @@
     "@aztec/ethereum": "workspace:^",
     "@aztec/foundation": "workspace:^",
     "@aztec/l1-artifacts": "workspace:^",
+    "@aztec/node-keystore": "workspace:^",
     "@aztec/node-lib": "workspace:^",
     "@aztec/p2p": "workspace:^",
     "@aztec/protocol-contracts": "workspace:^",
     "@aztec/stdlib": "workspace:^",
     "@aztec/test-wallet": "workspace:^",
     "@aztec/world-state": "workspace:^",
+    "@ethersproject/wallet": "^5.8.0",
     "@iarna/toml": "^2.2.5",
     "@libp2p/peer-id-factory": "^3.0.4",
+    "@scure/bip39": "^2.0.1",
     "commander": "^12.1.0",
     "lodash.chunk": "^4.2.0",
     "lodash.groupby": "^4.6.0",

yarn-project/cli/src/cmds/validator_keys/add.ts

@@ -0,0 +1,113 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { LogFn } from '@aztec/foundation/log';
+import { loadKeystoreFile } from '@aztec/node-keystore/loader';
+import type { KeyStore } from '@aztec/node-keystore/types';
+
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { dirname, isAbsolute, join } from 'path';
+import { generateMnemonic } from 'viem/accounts';
+
+import type { NewValidatorKeystoreOptions } from './new.js';
+import {
+  buildValidatorEntries,
+  logValidatorSummaries,
+  maybePrintJson,
+  writeBlsBn254ToFile,
+  writeEthJsonV3ToFile,
+  writeKeystoreFile,
+} from './shared.js';
+
+export type AddValidatorKeysOptions = NewValidatorKeystoreOptions;
+
+export async function addValidatorKeys(existing: string, options: AddValidatorKeysOptions, log: LogFn) {
+  const {
+    dataDir,
+    file,
+    count,
+    publisherCount = 0,
+    mnemonic,
+    accountIndex = 0,
+    addressIndex,
+    ikm,
+    blsPath,
+    blsOnly,
+    json,
+    feeRecipient: feeRecipientOpt,
+    coinbase: coinbaseOpt,
+    fundingAccount: fundingAccountOpt,
+    remoteSigner: remoteSignerOpt,
+    password,
+    outDir,
+  } = options;
+
+  const validatorCount = typeof count === 'number' && Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
+  const baseAddressIndex = addressIndex ?? 0;
+
+  const keystore: KeyStore = loadKeystoreFile(existing);
+
+  if (!keystore.validators || !Array.isArray(keystore.validators)) {
+    throw new Error('Invalid keystore: missing validators array');
+  }
+
+  const first = keystore.validators[0] ?? {};
+  const feeRecipient = feeRecipientOpt ?? first.feeRecipient;
+  if (!feeRecipient) {
+    throw new Error('feeRecipient is required (either present in existing file or via --fee-recipient)');
+  }
+  const coinbase = (coinbaseOpt as EthAddress | undefined) ?? (first.coinbase as EthAddress | undefined);
+  const fundingAccount =
+    (fundingAccountOpt as EthAddress | undefined) ?? (first.fundingAccount as EthAddress | undefined);
+  const derivedRemoteSigner = (first.attester as any)?.remoteSignerUrl || (first.attester as any)?.eth?.remoteSignerUrl;
+  const remoteSigner = remoteSignerOpt ?? derivedRemoteSigner;
+
+  // Ensure we always have a mnemonic for key derivation if none was provided
+  const mnemonicToUse = mnemonic ?? generateMnemonic(wordlist);
+
+  // If user explicitly provided --address-index, use it as-is. Otherwise, append after existing validators.
+  const effectiveBaseAddressIndex =
+    addressIndex === undefined ? baseAddressIndex + keystore.validators.length : baseAddressIndex;
+
+  const { validators, summaries } = await buildValidatorEntries({
+    validatorCount,
+    publisherCount,
+    accountIndex,
+    baseAddressIndex: effectiveBaseAddressIndex,
+    mnemonic: mnemonicToUse,
+    ikm,
+    blsPath,
+    blsOnly,
+    feeRecipient,
+    coinbase,
+    remoteSigner,
+    fundingAccount,
+  });
+
+  keystore.validators.push(...validators);
+
+  // If password provided, write ETH JSON V3 and BLS BN254 keystores and replace plaintext
+  if (password !== undefined) {
+    const targetDir =
+      outDir && outDir.length > 0 ? outDir : dataDir && dataDir.length > 0 ? dataDir : dirname(existing);
+    await writeEthJsonV3ToFile(keystore.validators, { outDir: targetDir, password });
+    await writeBlsBn254ToFile(keystore.validators, { outDir: targetDir, password });
+  }
+
+  let outputPath = existing;
+  if (file && file.length > 0) {
+    if (isAbsolute(file)) {
+      outputPath = file;
+    } else if (dataDir && dataDir.length > 0) {
+      outputPath = join(dataDir, file);
+    } else {
+      outputPath = join(dirname(existing), file);
+    }
+  }
+
+  await writeKeystoreFile(outputPath, keystore);
+
+  if (!json) {
+    log(`Updated keystore ${outputPath} with ${validators.length} new validator(s)`);
+    logValidatorSummaries(log, summaries);
+  }
+  maybePrintJson(log, !!json, keystore as unknown as Record<string, any>);
+}

yarn-project/cli/src/cmds/validator_keys/generate_bls_keypair.ts

@@ -0,0 +1,33 @@
+import { deriveBlsPrivateKey } from '@aztec/foundation/crypto';
+import type { LogFn } from '@aztec/foundation/log';
+
+import { writeFile } from 'fs/promises';
+
+import { computeBlsPublicKeyCompressed, withValidatorIndex } from './shared.js';
+
+export type GenerateBlsKeypairOptions = {
+  mnemonic?: string;
+  ikm?: string;
+  blsPath?: string;
+  g2?: boolean;
+  compressed?: boolean;
+  json?: boolean;
+  out?: string;
+};
+
+export async function generateBlsKeypair(options: GenerateBlsKeypairOptions, log: LogFn) {
+  const { mnemonic, ikm, blsPath, compressed = true, json, out } = options;
+  const path = withValidatorIndex(blsPath ?? 'm/12381/3600/0/0/0', 0);
+  const priv = deriveBlsPrivateKey(mnemonic, ikm, path);
+  const pub = await computeBlsPublicKeyCompressed(priv);
+  const result = { path, privateKey: priv, publicKey: pub, format: compressed ? 'compressed' : 'uncompressed' };
+  if (out) {
+    await writeFile(out, JSON.stringify(result, null, 2), { encoding: 'utf-8' });
+    if (!json) {
+      log(`Wrote BLS keypair to ${out}`);
+    }
+  }
+  if (json || !out) {
+    log(JSON.stringify(result, null, 2));
+  }
+}

yarn-project/cli/src/cmds/validator_keys/index.ts

@@ -0,0 +1,96 @@
+import type { LogFn } from '@aztec/foundation/log';
+
+import { Command } from 'commander';
+
+import { parseAztecAddress, parseEthereumAddress, parseHex, parseOptionalInteger } from '../../utils/commands.js';
+
+export function injectCommands(program: Command, log: LogFn) {
+  const group = program
+    .command('validator-keys')
+    .aliases(['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 1)', value =>
+      parseOptionalInteger(value, 0),
+    )
+    .option('--mnemonic <mnemonic>', 'Mnemonic for ETH/BLS derivation')
+    .option('--passphrase <str>', 'Optional passphrase for mnemonic')
+    .option('--account-index <N>', 'Base account index for ETH derivation', parseOptionalInteger)
+    .option('--address-index <N>', 'Base address index for ETH derivation', parseOptionalInteger)
+    .option('--coinbase <address>', 'Coinbase ETH address to use when proposing', parseEthereumAddress)
+    .option('--funding-account <address>', 'ETH account to fund publishers', 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 m/12381/3600/0/0/0)')
+    .option('--bls-only', 'Generate only BLS keys')
+    .option(
+      '--password <str>',
+      'Password for writing keystore files (ETH JSON V3 and BLS EIP-2335). Empty string allowed',
+    )
+    .option('--out-dir <dir>', 'Output directory for generated keystore file(s)')
+    .option('--json', 'Echo resulting JSON to stdout')
+    .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')
+    .option('--file <name>', 'Override output file name')
+    .option('--count <N>', 'Number of validators to add', parseOptionalInteger)
+    .option('--publisher-count <N>', 'Number of publisher accounts per validator (default 1)', value =>
+      parseOptionalInteger(value, 0),
+    )
+    .option('--mnemonic <mnemonic>', 'Mnemonic for ETH/BLS derivation')
+    .option('--passphrase <str>', 'Optional passphrase for mnemonic')
+    .option('--account-index <N>', 'Base account index for ETH derivation', parseOptionalInteger)
+    .option('--address-index <N>', 'Base address index for ETH derivation', parseOptionalInteger)
+    .option('--coinbase <address>', 'Coinbase ETH address to use when proposing', parseEthereumAddress)
+    .option('--funding-account <address>', 'ETH account to fund publishers', 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 m/12381/3600/0/0/0)')
+    .option('--bls-only', 'Generate only BLS keys')
+    .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('--out-dir <dir>', 'Output directory for generated 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);
+    });
+
+  // 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 m/12381/3600/0/0/0)')
+    .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;
+}