@aztec/cli 3.0.0-nightly.20251030-2 → 3.0.0-nightly.20251031

package/dest/utils/commands.js

@@ -73,6 +73,27 @@ export const logJson = (log)=>(obj)=>log(JSON.stringify(obj, null, 2));
     }
     return from;
 }
+/**
+ * Parses and validates a hex string. Removes leading 0x if present, checks for hex validity,
+ * and enforces an optional minimum length.
+ * @param hex - The hex string to validate.
+ * @param minLen - Optional minimum length (in hex characters, after stripping '0x').
+ * @returns The normalized hex string (without leading 0x).
+ * @throws InvalidArgumentError if the string is not valid hex or does not meet the minimum length.
+ */ // minLen is now interpreted as the minimum number of bytes (2 hex characters per byte)
+export function parseHex(hex, minLen) {
+    const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (!/^[0-9a-fA-F]*$/.test(normalized)) {
+        throw new InvalidArgumentError('Invalid hex string');
+    }
+    if (minLen !== undefined) {
+        const minHexLen = minLen * 2;
+        if (normalized.length < minHexLen) {
+            throw new InvalidArgumentError(`Hex string is too short (length ${normalized.length}), minimum byte length is ${minLen} (hex chars: ${minHexLen})`);
+        }
+    }
+    return `0x${normalized}`;
+}
 /**
  * Removes the leading 0x from a hex string. If no leading 0x is found the string is returned unchanged.
  * @param hex - A hex string
@@ -117,7 +138,7 @@ export function parseBigint(bigint) {
     try {
         return AztecAddress.fromString(address);
     } catch  {
-        throw new InvalidArgumentError(`Invalid address: ${address}`);
+        throw new InvalidArgumentError(`Invalid Aztec address: ${address}`);
     }
 }
 /**
@@ -129,7 +150,7 @@ export function parseBigint(bigint) {
     try {
         return EthAddress.fromString(address);
     } catch  {
-        throw new InvalidArgumentError(`Invalid address: ${address}`);
+        throw new InvalidArgumentError(`Invalid Ethereumaddress: ${address}`);
     }
 }
 /**
@@ -175,7 +196,7 @@ export function parseBigint(bigint) {
  * @param value - The string to parse into an integer.
  * @returns The parsed integer, or undefined if the input string is falsy.
  * @throws If the input is not a valid integer.
- */ export function parseOptionalInteger(value) {
+ */ export function parseOptionalInteger(value, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
     if (!value) {
         return undefined;
     }
@@ -183,6 +204,12 @@ export function parseBigint(bigint) {
     if (!Number.isInteger(parsed)) {
         throw new InvalidArgumentError('Invalid integer.');
     }
+    if (parsed < min) {
+        throw new InvalidArgumentError(`Value must be greater than ${min}.`);
+    }
+    if (parsed > max) {
+        throw new InvalidArgumentError(`Value must be less than ${max}.`);
+    }
     return parsed;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/cli",
-  "version": "3.0.0-nightly.20251030-2",
+  "version": "3.0.0-nightly.20251031",
   "type": "module",
   "exports": {
     "./contracts": "./dest/cmds/contracts/index.js",
@@ -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",
@@ -70,22 +71,25 @@
     ]
   },
   "dependencies": {
-    "@aztec/accounts": "3.0.0-nightly.20251030-2",
-    "@aztec/archiver": "3.0.0-nightly.20251030-2",
-    "@aztec/aztec.js": "3.0.0-nightly.20251030-2",
-    "@aztec/constants": "3.0.0-nightly.20251030-2",
-    "@aztec/entrypoints": "3.0.0-nightly.20251030-2",
-    "@aztec/ethereum": "3.0.0-nightly.20251030-2",
-    "@aztec/foundation": "3.0.0-nightly.20251030-2",
-    "@aztec/l1-artifacts": "3.0.0-nightly.20251030-2",
-    "@aztec/node-lib": "3.0.0-nightly.20251030-2",
-    "@aztec/p2p": "3.0.0-nightly.20251030-2",
-    "@aztec/protocol-contracts": "3.0.0-nightly.20251030-2",
-    "@aztec/stdlib": "3.0.0-nightly.20251030-2",
-    "@aztec/test-wallet": "3.0.0-nightly.20251030-2",
-    "@aztec/world-state": "3.0.0-nightly.20251030-2",
+    "@aztec/accounts": "3.0.0-nightly.20251031",
+    "@aztec/archiver": "3.0.0-nightly.20251031",
+    "@aztec/aztec.js": "3.0.0-nightly.20251031",
+    "@aztec/constants": "3.0.0-nightly.20251031",
+    "@aztec/entrypoints": "3.0.0-nightly.20251031",
+    "@aztec/ethereum": "3.0.0-nightly.20251031",
+    "@aztec/foundation": "3.0.0-nightly.20251031",
+    "@aztec/l1-artifacts": "3.0.0-nightly.20251031",
+    "@aztec/node-keystore": "3.0.0-nightly.20251031",
+    "@aztec/node-lib": "3.0.0-nightly.20251031",
+    "@aztec/p2p": "3.0.0-nightly.20251031",
+    "@aztec/protocol-contracts": "3.0.0-nightly.20251031",
+    "@aztec/stdlib": "3.0.0-nightly.20251031",
+    "@aztec/test-wallet": "3.0.0-nightly.20251031",
+    "@aztec/world-state": "3.0.0-nightly.20251031",
+    "@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",
@@ -110,15 +114,15 @@
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@aztec/accounts": "3.0.0-nightly.20251030-2",
-    "@aztec/bb-prover": "3.0.0-nightly.20251030-2",
-    "@aztec/ethereum": "3.0.0-nightly.20251030-2",
-    "@aztec/l1-artifacts": "3.0.0-nightly.20251030-2",
-    "@aztec/noir-contracts.js": "3.0.0-nightly.20251030-2",
-    "@aztec/noir-protocol-circuits-types": "3.0.0-nightly.20251030-2",
-    "@aztec/noir-test-contracts.js": "3.0.0-nightly.20251030-2",
-    "@aztec/protocol-contracts": "3.0.0-nightly.20251030-2",
-    "@aztec/stdlib": "3.0.0-nightly.20251030-2"
+    "@aztec/accounts": "3.0.0-nightly.20251031",
+    "@aztec/bb-prover": "3.0.0-nightly.20251031",
+    "@aztec/ethereum": "3.0.0-nightly.20251031",
+    "@aztec/l1-artifacts": "3.0.0-nightly.20251031",
+    "@aztec/noir-contracts.js": "3.0.0-nightly.20251031",
+    "@aztec/noir-protocol-circuits-types": "3.0.0-nightly.20251031",
+    "@aztec/noir-test-contracts.js": "3.0.0-nightly.20251031",
+    "@aztec/protocol-contracts": "3.0.0-nightly.20251031",
+    "@aztec/stdlib": "3.0.0-nightly.20251031"
   },
   "files": [
     "dest",

package/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>);
+}

package/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));
+  }
+}

package/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;
+}

package/src/cmds/validator_keys/new.ts

@@ -0,0 +1,120 @@
+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 { dirname } from 'path';
+import { generateMnemonic, mnemonicToAccount } from 'viem/accounts';
+
+import {
+  buildValidatorEntries,
+  logValidatorSummaries,
+  maybePrintJson,
+  resolveKeystoreOutputPath,
+  writeBlsBn254ToFile,
+  writeEthJsonV3ToFile,
+  writeKeystoreFile,
+} from './shared.js';
+
+export type NewValidatorKeystoreOptions = {
+  dataDir?: string;
+  file?: string;
+  count?: number;
+  publisherCount?: number;
+  mnemonic?: string;
+  passphrase?: string;
+  accountIndex?: number;
+  addressIndex?: number;
+  separatePublisher?: boolean;
+  ikm?: string;
+  blsPath?: string;
+  blsOnly?: boolean;
+  password?: string;
+  outDir?: string;
+  json?: boolean;
+  feeRecipient: AztecAddress;
+  coinbase?: EthAddress;
+  remoteSigner?: string;
+  fundingAccount?: EthAddress;
+};
+
+export async function newValidatorKeystore(options: NewValidatorKeystoreOptions, log: LogFn) {
+  const {
+    dataDir,
+    file,
+    count,
+    publisherCount = 0,
+    json,
+    coinbase,
+    accountIndex = 0,
+    addressIndex = 0,
+    feeRecipient,
+    remoteSigner,
+    fundingAccount,
+    blsOnly,
+    blsPath,
+    ikm,
+    mnemonic: _mnemonic,
+    password,
+    outDir,
+  } = options;
+
+  if (remoteSigner && !_mnemonic) {
+    throw new Error(
+      'Using --remote-signer requires a deterministic key source. Provide --mnemonic to derive keys, or omit --remote-signer to write new private keys to keystore.',
+    );
+  }
+
+  const mnemonic = _mnemonic ?? generateMnemonic(wordlist);
+
+  const validatorCount = typeof count === 'number' && Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
+  const { outputPath } = await resolveKeystoreOutputPath(dataDir, file);
+
+  const { validators, summaries } = await buildValidatorEntries({
+    validatorCount,
+    publisherCount,
+    accountIndex,
+    baseAddressIndex: addressIndex,
+    mnemonic,
+    ikm,
+    blsPath,
+    blsOnly,
+    feeRecipient,
+    coinbase,
+    remoteSigner,
+    fundingAccount,
+  });
+
+  // If password provided, write ETH JSON V3 and BLS BN254 keystores and replace plaintext
+  if (password !== undefined) {
+    const keystoreOutDir = outDir && outDir.length > 0 ? outDir : dirname(outputPath);
+    await writeEthJsonV3ToFile(validators, { outDir: keystoreOutDir, password });
+    await writeBlsBn254ToFile(validators, { outDir: keystoreOutDir, password });
+  }
+
+  const keystore = {
+    schemaVersion: 1,
+    validators,
+  };
+
+  await writeKeystoreFile(outputPath, keystore);
+
+  maybePrintJson(log, json, keystore as unknown as Record<string, any>);
+  if (!json) {
+    log(`Wrote validator keystore to ${outputPath}`);
+  }
+
+  // Always print a concise summary of public keys (addresses and BLS pubkeys)
+  logValidatorSummaries(log, summaries);
+
+  if (!blsOnly && mnemonic && remoteSigner) {
+    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}`);
+    }
+  }
+}