@aztec/cli 0.0.0-test.1 → 0.0.1-commit.b655e406

package/src/cmds/l1/update_l1_validators.ts

@@ -1,17 +1,25 @@
 import {
-  EthCheatCodes,
+  GSEContract,
+  RollupContract,
   createEthereumChain,
-  getExpectedAddress,
+  createExtendedL1Client,
+  createL1TxUtilsFromViemWallet,
   getL1ContractsConfigEnvVars,
+  getPublicClient,
   isAnvilTestChain,
 } from '@aztec/ethereum';
+import { EthCheatCodes } from '@aztec/ethereum/test';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { LogFn, Logger } from '@aztec/foundation/log';
-import { ForwarderAbi, ForwarderBytecode, RollupAbi, TestERC20Abi } from '@aztec/l1-artifacts';
+import { DateProvider } from '@aztec/foundation/timer';
+import { RollupAbi, StakingAssetHandlerAbi } from '@aztec/l1-artifacts';
+import { ZkPassportProofParams } from '@aztec/stdlib/zkpassport';
 
-import { createPublicClient, createWalletClient, fallback, getContract, http } from 'viem';
+import { encodeFunctionData, formatEther, getContract } from 'viem';
 import { generatePrivateKey, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
+import { addLeadingHex } from '../../utils/aztec.js';
+
 export interface RollupCommandArgs {
   rpcUrls: string[];
   chainId: number;
@@ -21,6 +29,14 @@ export interface RollupCommandArgs {
   withdrawerAddress?: EthAddress;
 }
 
+export interface StakingAssetHandlerCommandArgs {
+  rpcUrls: string[];
+  chainId: number;
+  privateKey?: string;
+  mnemonic?: string;
+  stakingAssetHandlerAddress: EthAddress;
+}
+
 export interface LoggerArgs {
   log: LogFn;
   debugLogger: Logger;
@@ -41,56 +57,151 @@ export async function addL1Validator({
   chainId,
   privateKey,
   mnemonic,
-  validatorAddress,
-  rollupAddress,
+  attesterAddress,
+  stakingAssetHandlerAddress,
+  merkleProof,
+  proofParams,
+  blsSecretKey,
+  log,
+  debugLogger,
+}: StakingAssetHandlerCommandArgs &
+  LoggerArgs & {
+    blsSecretKey: bigint; // scalar field element of BN254
+    attesterAddress: EthAddress;
+    proofParams: Buffer;
+    merkleProof: string[];
+  }) {
+  const dualLog = makeDualLog(log, debugLogger);
+  const account = getAccount(privateKey, mnemonic);
+  const chain = createEthereumChain(rpcUrls, chainId);
+  const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
+
+  const stakingAssetHandler = getContract({
+    address: stakingAssetHandlerAddress.toString(),
+    abi: StakingAssetHandlerAbi,
+    client: l1Client,
+  });
+
+  const rollupAddress = await stakingAssetHandler.read.getRollup();
+  dualLog(`Adding validator ${attesterAddress} to rollup ${rollupAddress.toString()}`);
+
+  const rollup = getContract({
+    address: rollupAddress,
+    abi: RollupAbi,
+    client: l1Client,
+  });
+
+  const gseAddress = await rollup.read.getGSE();
+
+  const gse = new GSEContract(l1Client, gseAddress);
+
+  const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
+
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+  const proofParamsObj = ZkPassportProofParams.fromBuffer(proofParams);
+  const merkleProofArray = merkleProof.map(proof => addLeadingHex(proof));
+
+  const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+    to: stakingAssetHandlerAddress.toString(),
+    data: encodeFunctionData({
+      abi: StakingAssetHandlerAbi,
+      functionName: 'addValidator',
+      args: [
+        attesterAddress.toString(),
+        merkleProofArray,
+        proofParamsObj.toViem(),
+        registrationTuple.publicKeyInG1,
+        registrationTuple.publicKeyInG2,
+        registrationTuple.proofOfPossession,
+      ],
+    }),
+    abi: StakingAssetHandlerAbi,
+  });
+  dualLog(`Transaction hash: ${receipt.transactionHash}`);
+  await l1Client.waitForTransactionReceipt({ hash: receipt.transactionHash });
+  if (isAnvilTestChain(chainId)) {
+    dualLog(`Funding validator on L1`);
+    const cheatCodes = new EthCheatCodes(rpcUrls, new DateProvider(), debugLogger);
+    await cheatCodes.setBalance(attesterAddress, 10n ** 20n);
+  } else {
+    const balance = await l1Client.getBalance({ address: attesterAddress.toString() });
+    dualLog(`Validator balance: ${formatEther(balance)} ETH`);
+    if (balance === 0n) {
+      dualLog(`WARNING: Proposer has no balance. Remember to fund it!`);
+    }
+  }
+}
+
+export async function addL1ValidatorViaRollup({
+  rpcUrls,
+  chainId,
+  privateKey,
+  mnemonic,
+  attesterAddress,
   withdrawerAddress,
+  blsSecretKey,
+  moveWithLatestRollup,
+  rollupAddress,
   log,
   debugLogger,
-}: RollupCommandArgs & LoggerArgs & { validatorAddress: EthAddress }) {
-  const config = getL1ContractsConfigEnvVars();
+}: RollupCommandArgs &
+  LoggerArgs & {
+    blsSecretKey: bigint; // scalar field element of BN254
+    attesterAddress: EthAddress;
+    moveWithLatestRollup: boolean;
+  }) {
   const dualLog = makeDualLog(log, debugLogger);
-  const publicClient = getPublicClient(rpcUrls, chainId);
-  const walletClient = getWalletClient(rpcUrls, chainId, privateKey, mnemonic);
+  const account = getAccount(privateKey, mnemonic);
+  const chain = createEthereumChain(rpcUrls, chainId);
+  const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
+
+  dualLog(`Adding validator ${attesterAddress} to rollup ${rollupAddress.toString()} via direct deposit`);
+
+  if (!withdrawerAddress) {
+    throw new Error(`Withdrawer address required`);
+  }
+
   const rollup = getContract({
     address: rollupAddress.toString(),
     abi: RollupAbi,
-    client: walletClient,
+    client: l1Client,
   });
 
-  const stakingAsset = getContract({
-    address: await rollup.read.getStakingAsset(),
-    abi: TestERC20Abi,
-    client: walletClient,
-  });
+  const gseAddress = await rollup.read.getGSE();
+
+  const gse = new GSEContract(l1Client, gseAddress);
+
+  const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
 
-  await Promise.all(
-    [
-      await stakingAsset.write.mint([walletClient.account.address, config.minimumStake], {} as any),
-      await stakingAsset.write.approve([rollupAddress.toString(), config.minimumStake], {} as any),
-    ].map(txHash => publicClient.waitForTransactionReceipt({ hash: txHash })),
-  );
-
-  dualLog(`Adding validator ${validatorAddress.toString()} to rollup ${rollupAddress.toString()}`);
-  const txHash = await rollup.write.deposit([
-    validatorAddress.toString(),
-    // TODO(#11451): custom forwarders
-    getExpectedAddress(ForwarderAbi, ForwarderBytecode, [validatorAddress.toString()], validatorAddress.toString())
-      .address,
-    withdrawerAddress?.toString() ?? validatorAddress.toString(),
-    config.minimumStake,
-  ]);
-  dualLog(`Transaction hash: ${txHash}`);
-  await publicClient.waitForTransactionReceipt({ hash: txHash });
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+
+  const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+    to: rollupAddress.toString(),
+    data: encodeFunctionData({
+      abi: RollupAbi,
+      functionName: 'deposit',
+      args: [
+        attesterAddress.toString(),
+        withdrawerAddress.toString(),
+        registrationTuple.publicKeyInG1,
+        registrationTuple.publicKeyInG2,
+        registrationTuple.proofOfPossession,
+        moveWithLatestRollup,
+      ],
+    }),
+    abi: StakingAssetHandlerAbi,
+  });
+  dualLog(`Transaction hash: ${receipt.transactionHash}`);
+  await l1Client.waitForTransactionReceipt({ hash: receipt.transactionHash });
   if (isAnvilTestChain(chainId)) {
     dualLog(`Funding validator on L1`);
-    const cheatCodes = new EthCheatCodes(rpcUrls, debugLogger);
-    await cheatCodes.setBalance(validatorAddress, 10n ** 20n);
+    const cheatCodes = new EthCheatCodes(rpcUrls, new DateProvider(), debugLogger);
+    await cheatCodes.setBalance(attesterAddress, 10n ** 20n);
   } else {
-    const balance = await publicClient.getBalance({ address: validatorAddress.toString() });
-    const balanceInEth = Number(balance) / 10 ** 18;
-    dualLog(`Validator balance: ${balanceInEth.toFixed(6)} ETH`);
-    if (balanceInEth === 0) {
-      dualLog(`WARNING: Validator has no balance. Remember to fund it!`);
+    const balance = await l1Client.getBalance({ address: attesterAddress.toString() });
+    dualLog(`Validator balance: ${formatEther(balance)} ETH`);
+    if (balance === 0n) {
+      dualLog(`WARNING: Proposer has no balance. Remember to fund it!`);
     }
   }
 }
@@ -106,18 +217,21 @@ export async function removeL1Validator({
   debugLogger,
 }: RollupCommandArgs & LoggerArgs & { validatorAddress: EthAddress }) {
   const dualLog = makeDualLog(log, debugLogger);
-  const publicClient = getPublicClient(rpcUrls, chainId);
-  const walletClient = getWalletClient(rpcUrls, chainId, privateKey, mnemonic);
-  const rollup = getContract({
-    address: rollupAddress.toString(),
-    abi: RollupAbi,
-    client: walletClient,
-  });
+  const account = getAccount(privateKey, mnemonic);
+  const chain = createEthereumChain(rpcUrls, chainId);
+  const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
 
   dualLog(`Removing validator ${validatorAddress.toString()} from rollup ${rollupAddress.toString()}`);
-  const txHash = await rollup.write.initiateWithdraw([validatorAddress.toString(), validatorAddress.toString()]);
-  dualLog(`Transaction hash: ${txHash}`);
-  await publicClient.waitForTransactionReceipt({ hash: txHash });
+  const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+    to: rollupAddress.toString(),
+    data: encodeFunctionData({
+      abi: RollupAbi,
+      functionName: 'initiateWithdraw',
+      args: [validatorAddress.toString(), validatorAddress.toString()],
+    }),
+  });
+  dualLog(`Transaction hash: ${receipt.transactionHash}`);
 }
 
 export async function pruneRollup({
@@ -130,18 +244,20 @@ export async function pruneRollup({
   debugLogger,
 }: RollupCommandArgs & LoggerArgs) {
   const dualLog = makeDualLog(log, debugLogger);
-  const publicClient = getPublicClient(rpcUrls, chainId);
-  const walletClient = getWalletClient(rpcUrls, chainId, privateKey, mnemonic);
-  const rollup = getContract({
-    address: rollupAddress.toString(),
-    abi: RollupAbi,
-    client: walletClient,
-  });
+  const account = getAccount(privateKey, mnemonic);
+  const chain = createEthereumChain(rpcUrls, chainId);
+  const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
 
   dualLog(`Trying prune`);
-  const txHash = await rollup.write.prune();
-  dualLog(`Transaction hash: ${txHash}`);
-  await publicClient.waitForTransactionReceipt({ hash: txHash });
+  const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+    to: rollupAddress.toString(),
+    data: encodeFunctionData({
+      abi: RollupAbi,
+      functionName: 'prune',
+    }),
+  });
+  dualLog(`Transaction hash: ${receipt.transactionHash}`);
 }
 
 export async function fastForwardEpochs({
@@ -153,20 +269,20 @@ export async function fastForwardEpochs({
   debugLogger,
 }: RollupCommandArgs & LoggerArgs & { numEpochs: bigint }) {
   const dualLog = makeDualLog(log, debugLogger);
-  const publicClient = getPublicClient(rpcUrls, chainId);
+  const publicClient = getPublicClient({ l1RpcUrls: rpcUrls, l1ChainId: chainId });
   const rollup = getContract({
     address: rollupAddress.toString(),
     abi: RollupAbi,
     client: publicClient,
   });
 
-  const cheatCodes = new EthCheatCodes(rpcUrls, debugLogger);
+  const cheatCodes = new EthCheatCodes(rpcUrls, new DateProvider(), debugLogger);
   const currentSlot = await rollup.read.getCurrentSlot();
   const l2SlotsInEpoch = await rollup.read.getEpochDuration();
   const timestamp = await rollup.read.getTimestampForSlot([currentSlot + l2SlotsInEpoch * numEpochs]);
   dualLog(`Fast forwarding ${numEpochs} epochs to ${timestamp}`);
   try {
-    await cheatCodes.warp(Number(timestamp));
+    await cheatCodes.warp(Number(timestamp), { resetBlockInterval: true });
     dualLog(`Fast forwarded ${numEpochs} epochs to ${timestamp}`);
   } catch (error) {
     if (error instanceof Error && error.message.includes("is lower than or equal to previous block's timestamp")) {
@@ -180,31 +296,27 @@ export async function fastForwardEpochs({
 
 export async function debugRollup({ rpcUrls, chainId, rollupAddress, log }: RollupCommandArgs & LoggerArgs) {
   const config = getL1ContractsConfigEnvVars();
-  const publicClient = getPublicClient(rpcUrls, chainId);
-  const rollup = getContract({
-    address: rollupAddress.toString(),
-    abi: RollupAbi,
-    client: publicClient,
-  });
+  const publicClient = getPublicClient({ l1RpcUrls: rpcUrls, l1ChainId: chainId });
+  const rollup = new RollupContract(publicClient, rollupAddress);
 
-  const pendingNum = await rollup.read.getPendingBlockNumber();
+  const pendingNum = await rollup.getBlockNumber();
   log(`Pending block num: ${pendingNum}`);
-  const provenNum = await rollup.read.getProvenBlockNumber();
+  const provenNum = await rollup.getProvenBlockNumber();
   log(`Proven block num: ${provenNum}`);
-  const validators = await rollup.read.getAttesters();
+  const validators = await rollup.getAttesters();
   log(`Validators: ${validators.map(v => v.toString()).join(', ')}`);
-  const committee = await rollup.read.getCurrentEpochCommittee();
-  log(`Committee: ${committee.map(v => v.toString()).join(', ')}`);
-  const archive = await rollup.read.archive();
+  const committee = await rollup.getCurrentEpochCommittee();
+  log(`Committee: ${committee?.map(v => v.toString()).join(', ')}`);
+  const archive = await rollup.archive();
   log(`Archive: ${archive}`);
-  const epochNum = await rollup.read.getCurrentEpoch();
+  const epochNum = await rollup.getCurrentEpochNumber();
   log(`Current epoch: ${epochNum}`);
-  const slot = await rollup.read.getCurrentSlot();
+  const slot = await rollup.getSlotNumber();
   log(`Current slot: ${slot}`);
-  const proposerDuringPrevL1Block = await rollup.read.getCurrentProposer();
+  const proposerDuringPrevL1Block = await rollup.getCurrentProposer();
   log(`Proposer during previous L1 block: ${proposerDuringPrevL1Block}`);
   const nextBlockTS = BigInt((await publicClient.getBlock()).timestamp + BigInt(config.ethereumSlotDuration));
-  const proposer = await rollup.read.getProposerAt([nextBlockTS]);
+  const proposer = await rollup.getProposerAt(nextBlockTS);
   log(`Proposer NOW: ${proposer.toString()}`);
 }
 
@@ -215,24 +327,12 @@ function makeDualLog(log: LogFn, debugLogger: Logger) {
   };
 }
 
-function getPublicClient(rpcUrls: string[], chainId: number) {
-  const chain = createEthereumChain(rpcUrls, chainId);
-  return createPublicClient({ chain: chain.chainInfo, transport: fallback(rpcUrls.map(url => http(url))) });
-}
-
-function getWalletClient(
-  rpcUrls: string[],
-  chainId: number,
-  privateKey: string | undefined,
-  mnemonic: string | undefined,
-) {
+function getAccount(privateKey: string | undefined, mnemonic: string | undefined) {
   if (!privateKey && !mnemonic) {
     throw new Error('Either privateKey or mnemonic must be provided to create a wallet client');
   }
-
-  const chain = createEthereumChain(rpcUrls, chainId);
   const account = !privateKey
     ? mnemonicToAccount(mnemonic!)
     : privateKeyToAccount(`${privateKey.startsWith('0x') ? '' : '0x'}${privateKey}` as `0x${string}`);
-  return createWalletClient({ account, chain: chain.chainInfo, transport: fallback(rpcUrls.map(url => http(url))) });
+  return account;
 }

package/src/cmds/misc/generate_bootnode_enr.ts

@@ -3,10 +3,11 @@ import { createBootnodeENRandPeerId } from '@aztec/p2p/enr';
 
 export async function generateEncodedBootnodeENR(
   privateKey: string,
-  udpAnnounceAddress: string,
+  p2pIp: string,
+  p2pPort: number,
   l1ChainId: number,
   log: LogFn,
 ) {
-  const { enr } = await createBootnodeENRandPeerId(privateKey, udpAnnounceAddress, l1ChainId);
+  const { enr } = await createBootnodeENRandPeerId(privateKey, p2pIp, p2pPort, l1ChainId);
   log(`ENR: ${enr.encodeTxt()}`);
 }

package/src/cmds/misc/generate_secret_and_hash.ts

@@ -1,12 +1,12 @@
-import { computeSecretHash } from '@aztec/aztec.js';
+import { computeSecretHash } from '@aztec/aztec.js/crypto';
 import { Fr } from '@aztec/foundation/fields';
 import type { LogFn } from '@aztec/foundation/log';
 
-export function generateSecretAndHash(log: LogFn) {
+export async function generateSecretAndHash(log: LogFn) {
   const secret = Fr.random();
 
   // We hash this the same way that aztec nr hash does.
-  const secretHash = computeSecretHash(secret);
+  const secretHash = await computeSecretHash(secret);
 
   log(`
     Secret: ${secret}

package/src/cmds/misc/generate_secret_key.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/aztec.js';
+import { Fr } from '@aztec/aztec.js/fields';
 
 export function generateSecretKey() {
   return { secretKey: Fr.random() };

package/src/cmds/misc/get_canonical_sponsored_fpc_address.ts

@@ -0,0 +1,7 @@
+import type { LogFn } from '@aztec/foundation/log';
+
+import { getSponsoredFPCAddress } from '../../utils/setup_contracts.js';
+
+export async function getCanonicalSponsoredFPCAddress(log: LogFn) {
+  log(`Canonical SponsoredFPC Address: ${(await getSponsoredFPCAddress()).toString()}`);
+}

package/src/cmds/misc/index.ts

@@ -35,11 +35,12 @@ export function injectCommands(program: Command, log: LogFn) {
     .summary('Generates the encoded ENR record for a bootnode.')
     .description('Generates the encoded ENR record for a bootnode.')
     .argument('<privateKey>', 'The peer id private key of the bootnode')
-    .argument('<udpAnnounceAddress>', 'The bootnode UDP announce address')
+    .argument('<p2pIp>', 'The bootnode P2P IP address')
+    .argument('<p2pPort>', 'The bootnode P2P port')
     .addOption(l1ChainIdOption)
-    .action(async (privateKey: string, udpAnnounceAddress: string, options) => {
+    .action(async (privateKey: string, p2pIp: string, p2pPort: number, options) => {
       const { generateEncodedBootnodeENR } = await import('./generate_bootnode_enr.js');
-      await generateEncodedBootnodeENR(privateKey, udpAnnounceAddress, options.l1ChainId, log);
+      await generateEncodedBootnodeENR(privateKey, p2pIp, p2pPort, options.l1ChainId, log);
     });
 
   program
@@ -73,7 +74,15 @@ export function injectCommands(program: Command, log: LogFn) {
     .description('Generates an arbitrary secret (Fr), and its hash (using aztec-nr defaults)')
     .action(async () => {
       const { generateSecretAndHash } = await import('./generate_secret_and_hash.js');
-      generateSecretAndHash(log);
+      await generateSecretAndHash(log);
+    });
+
+  program
+    .command('get-canonical-sponsored-fpc-address')
+    .description('Gets the canonical SponsoredFPC address for this any testnet running on the same version as this CLI')
+    .action(async () => {
+      const { getCanonicalSponsoredFPCAddress } = await import('./get_canonical_sponsored_fpc_address.js');
+      await getCanonicalSponsoredFPCAddress(log);
     });
 
   program

package/src/cmds/misc/update/github.ts

@@ -1,3 +1,2 @@
 export const GITHUB_OWNER = 'AztecProtocol';
 export const GITHUB_REPO = 'aztec-packages';
-export const GITHUB_TAG_PREFIX = 'aztec-packages';

package/src/cmds/misc/update.ts

@@ -1,11 +1,9 @@
-/* eslint-disable jsdoc/require-jsdoc */
 import type { LogFn } from '@aztec/foundation/log';
 
 import { relative, resolve } from 'path';
 import { parse } from 'semver';
 
 import type { DependencyChanges } from './update/common.js';
-import { GITHUB_TAG_PREFIX } from './update/github.js';
 import { updateAztecNr } from './update/noir.js';
 import { getNewestVersion, updateAztecDeps, updateLockfile } from './update/npm.js';
 
@@ -44,11 +42,7 @@ export async function updateProject(
   for (const contract of contracts) {
     try {
       projectDependencyChanges.push(
-        await updateAztecNr(
-          resolve(process.cwd(), projectPath, contract),
-          `${GITHUB_TAG_PREFIX}-v${targetAztecVersion.version}`,
-          log,
-        ),
+        await updateAztecNr(resolve(process.cwd(), projectPath, contract), `v${targetAztecVersion.version}`, log),
       );
     } catch (err) {
       if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {

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