@aztec-labs/cli 6.0.0-rc.3 → 6.0.0

package/src/cmds/infrastructure/sequencers.ts

@@ -5,6 +5,7 @@ import { createAztecNodeClient } from '@aztec-labs/aztec.js/node';
 import { createEthereumChain } from '@aztec-labs/ethereum/chain';
 import { getL1ContractsConfigEnvVars } from '@aztec-labs/ethereum/config';
 import { GSEContract, RollupContract } from '@aztec-labs/ethereum/contracts';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
 import type { LogFn } from '@aztec-labs/foundation/log';
 import { createPublicClient, createWalletClient, fallback, getContract, http } from 'viem';
 import { mnemonicToAccount } from 'viem/accounts';
@@ -12,6 +13,8 @@ import { mnemonicToAccount } from 'viem/accounts';
 export async function sequencers(opts: {
   command: 'list' | 'add' | 'remove' | 'who-next' | 'flush';
   who?: string;
+  /** Address that receives the withdrawn stake. Required for `remove`. */
+  recipient?: EthAddress;
   mnemonic?: string;
   bn254SecretKey?: bigint;
   nodeUrl: string;
@@ -19,7 +22,11 @@ export async function sequencers(opts: {
   chainId: number;
   log: LogFn;
 }) {
-  const { command, who: maybeWho, mnemonic, bn254SecretKey, nodeUrl, l1RpcUrls, chainId, log } = opts;
+  const { command, who: maybeWho, recipient, mnemonic, bn254SecretKey, nodeUrl, l1RpcUrls, chainId, log } = opts;
+  const missingRecipient = 'Missing --recipient: the address that receives the withdrawn stake';
+  if (command === 'remove' && !recipient) {
+    throw new Error(missingRecipient);
+  }
   const client = createAztecNodeClient(nodeUrl);
   const { l1ContractAddresses } = await client.getNodeInfo();
 
@@ -47,7 +54,7 @@ export async function sequencers(opts: {
       })
     : undefined;
 
-  const who = (maybeWho as `0x{string}`) ?? walletClient?.account.address.toString();
+  const who = (maybeWho as `0x${string}`) ?? walletClient?.account.address.toString();
 
   if (command === 'list') {
     const sequencers = await rollup.getAttesters();
@@ -109,8 +116,11 @@ export async function sequencers(opts: {
     if (!who || !writeableRollup) {
       throw new Error(`Missing sequencer address`);
     }
-    log(`Removing ${who} as sequencer`);
-    const hash = await writeableRollup.write.initiateWithdraw([who, who]);
+    if (!recipient) {
+      throw new Error(missingRecipient);
+    }
+    log(`Removing ${who} as sequencer, withdrawing its stake to ${recipient}`);
+    const hash = await writeableRollup.write.initiateWithdraw([who, recipient.toString()]);
     await publicClient.waitForTransactionReceipt({ hash });
     log(`Removed in tx ${hash}`);
   } else if (command === 'who-next') {

package/src/cmds/l1/deploy_l1_contracts_cmd.ts

@@ -7,6 +7,7 @@ import { SecretValue } from '@aztec-labs/foundation/config';
 import type { LogFn, Logger } from '@aztec-labs/foundation/log';
 import { protocolContractsHash } from '@aztec-labs/protocol-contracts';
 import { getGenesisValues } from '@aztec-labs/world-state/testing';
+import { Buffer } from 'buffer';
 import { mnemonicToAccount } from 'viem/accounts';
 
 import { addLeadingHex } from '../../utils/aztec.js';

package/src/cmds/l1/index.ts

@@ -489,6 +489,11 @@ Note: DEADLINE is a future Unix timestamp in seconds. Run append commands sequen
     )
     .addOption(l1ChainIdOption)
     .option('--validator <address>', 'ethereum address of the validator', parseEthereumAddress)
+    .requiredOption(
+      '--recipient <address>',
+      'Address that receives the withdrawn stake; it cannot be changed once set',
+      parseEthereumAddress,
+    )
     .option('--rollup <address>', 'ethereum address of the rollup contract', parseEthereumAddress)
     .action(async options => {
       const { removeL1Validator } = await import('./update_l1_validators.js');
@@ -498,6 +503,7 @@ Note: DEADLINE is a future Unix timestamp in seconds. Run append commands sequen
         privateKey: options.privateKey,
         mnemonic: options.mnemonic,
         validatorAddress: options.validator,
+        recipientAddress: options.recipient,
         rollupAddress: options.rollup,
         log,
         debugLogger,

package/src/cmds/l1/l1_rpc_test_utils.ts

@@ -1,6 +1,10 @@
-import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { RollupAbi } from '@aztec-foundation/l1-artifacts';
+
+import { getPublicClient } from '@aztec-labs/ethereum/client';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
 import { createServer } from 'node:http';
-import { encodeAbiParameters } from 'viem';
+import { decodeFunctionData, encodeAbiParameters } from 'viem';
+import { foundry } from 'viem/chains';
 
 /**
  * Starts a JSON-RPC server that reports `chainId` and, when `canonicalRollup` is given, answers every `eth_call` with
@@ -41,3 +45,22 @@ export async function serveL1Rpc(chainId: number, canonicalRollup?: EthAddress)
     close: () => new Promise(resolve => server.close(resolve)),
   };
 }
+
+/**
+ * Returns the `(attester, recipient)` arguments of the `initiateWithdraw` call that the latest block on an anvil chain
+ * sent to `rollup`, failing if that block holds no such call.
+ */
+export async function getLatestInitiateWithdrawArgs(rpcUrl: string, rollup: EthAddress) {
+  const client = getPublicClient({ l1RpcUrls: [rpcUrl], l1ChainId: foundry.id });
+  const block = await client.getBlock({ includeTransactions: true });
+  const tx = block.transactions.find(({ to }) => to !== null && rollup.equals(EthAddress.fromString(to)));
+  if (!tx) {
+    throw new Error(`No transaction to ${rollup} in the latest block`);
+  }
+  const decoded = decodeFunctionData({ abi: RollupAbi, data: tx.input });
+  if (decoded.functionName !== 'initiateWithdraw') {
+    throw new Error(`Expected initiateWithdraw, got ${decoded.functionName}`);
+  }
+  const [attester, recipient] = decoded.args;
+  return { attester: EthAddress.fromString(attester), recipient: EthAddress.fromString(recipient) };
+}

package/src/cmds/l1/prover_stats.ts

@@ -2,6 +2,7 @@ import { RollupAbi } from '@aztec-foundation/l1-artifacts';
 
 import { retrieveL2ProofVerifiedEvents } from '@aztec-labs/archiver';
 import { createEthereumChain } from '@aztec-labs/ethereum/chain';
+import { makeL1HttpTransport } from '@aztec-labs/ethereum/client';
 import type { ViemPublicClient } from '@aztec-labs/ethereum/types';
 import { compactArray, mapValues, unique } from '@aztec-labs/foundation/collection';
 import { EthAddress } from '@aztec-labs/foundation/eth-address';
@@ -9,7 +10,7 @@ import { type LogFn, type Logger, createLogger } from '@aztec-labs/foundation/lo
 import { createAztecNodeClient } from '@aztec-labs/stdlib/interfaces/client';
 import chunk from 'lodash.chunk';
 import groupBy from 'lodash.groupby';
-import { createPublicClient, fallback, getAbiItem, getAddress, http } from 'viem';
+import { createPublicClient, getAbiItem, getAddress } from 'viem';
 
 export async function proverStats(opts: {
   l1RpcUrls: string[];
@@ -49,7 +50,7 @@ export async function proverStats(opts: {
   const chain = createEthereumChain(l1RpcUrls, chainId).chainInfo;
   const publicClient = createPublicClient({
     chain,
-    transport: fallback(l1RpcUrls.map(url => http(url, { batch: false }))),
+    transport: makeL1HttpTransport(l1RpcUrls),
   });
   const lastBlockNum = endBlock ?? (await publicClient.getBlockNumber());
   debugLog.verbose(`Querying events on rollup at ${rollup.toString()} from ${startBlock} up to ${lastBlockNum}`);

package/src/cmds/l1/update_l1_validators.ts

@@ -12,6 +12,7 @@ import {
 import { createL1TxUtils } from '@aztec-labs/ethereum/l1-tx-utils';
 import { EthCheatCodes } from '@aztec-labs/ethereum/test';
 import { getActiveNetworkName } from '@aztec-labs/foundation/config';
+import { getEnv } from '@aztec-labs/foundation/config/env';
 import { EthAddress } from '@aztec-labs/foundation/eth-address';
 import { Signature } from '@aztec-labs/foundation/eth-signature';
 import type { LogFn, Logger } from '@aztec-labs/foundation/log';
@@ -253,23 +254,27 @@ export async function removeL1Validator({
   privateKey,
   mnemonic,
   validatorAddress,
+  recipientAddress,
   rollupAddress,
   log,
   debugLogger,
-}: RollupCommandArgs & LoggerArgs & { validatorAddress: EthAddress }) {
+}: RollupCommandArgs & LoggerArgs & { validatorAddress: EthAddress; recipientAddress: EthAddress }) {
   const dualLog = makeDualLog(log, debugLogger);
   const account = getAccount(privateKey, mnemonic);
   const chain = createEthereumChain(rpcUrls, chainId);
   const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
   const l1TxUtils = createL1TxUtils(l1Client, { logger: debugLogger });
 
-  dualLog(`Removing validator ${validatorAddress.toString()} from rollup ${rollupAddress.toString()}`);
+  dualLog(
+    `Removing validator ${validatorAddress.toString()} from rollup ${rollupAddress.toString()}, ` +
+      `withdrawing its stake to ${recipientAddress.toString()}`,
+  );
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
     to: rollupAddress.toString(),
     data: encodeFunctionData({
       abi: RollupAbi,
       functionName: 'initiateWithdraw',
-      args: [validatorAddress.toString(), validatorAddress.toString()],
+      args: [validatorAddress.toString(), recipientAddress.toString()],
     }),
   });
   dualLog(`Transaction hash: ${receipt.transactionHash}`);
@@ -285,7 +290,8 @@ export type AttesterExitNetwork = {
 /** Loads the published config of the network selected with --network, which takes precedence over the environment. */
 export async function getAttesterExitNetwork(name: string): Promise<AttesterExitNetwork> {
   const networkName = getActiveNetworkName(name);
-  const cacheDir = process.env.DATA_DIRECTORY ? join(process.env.DATA_DIRECTORY, 'cache') : undefined;
+  const { DATA_DIRECTORY } = getEnv();
+  const cacheDir = DATA_DIRECTORY ? join(DATA_DIRECTORY, 'cache') : undefined;
   const config = networkName === 'local' ? undefined : await getNetworkConfig(networkName, cacheDir);
   if (networkName !== 'local' && !config) {
     throw new Error(`Network ${networkName} has no published config`);

package/src/cmds/misc/generate_p2p_private_key.ts

@@ -1,5 +1,6 @@
 import type { LogFn } from '@aztec-labs/foundation/log';
 import { createSecp256k1PeerId } from '@libp2p/peer-id-factory';
+import { Buffer } from 'buffer';
 
 export async function generateP2PPrivateKey(log: LogFn) {
   const peerId = await createSecp256k1PeerId();

package/src/cmds/validator_keys/add.ts

@@ -6,9 +6,12 @@ import { wordlist } from '@scure/bip39/wordlists/english.js';
 import { dirname, isAbsolute, join } from 'path';
 import { generateMnemonic } from 'viem/accounts';
 
+import { resolveBlsKeyDerivationPolicy } from './bls_key_derivation.js';
 import type { NewValidatorKeystoreOptions } from './new.js';
 import {
   buildValidatorEntries,
+  getBlsDerivationPaths,
+  getBlsKeyCandidates,
   logValidatorSummaries,
   maybePrintJson,
   writeBlsBn254ToFile,
@@ -26,6 +29,7 @@ export async function addValidatorKeys(existing: string, options: AddValidatorKe
   validatePublisherOptions(options);
   // validate remote signer options
   validateRemoteSignerOptions(options);
+  const blsKeyDerivation = resolveBlsKeyDerivationPolicy(options);
 
   const {
     dataDir,
@@ -83,6 +87,9 @@ export async function addValidatorKeys(existing: string, options: AddValidatorKe
     feeRecipient,
     coinbase,
     remoteSigner,
+    blsKeyDerivation,
+    // `add` never prints the mnemonic it generates.
+    generatedMnemonic: mnemonic ? undefined : 'hidden',
   });
 
   keystore.validators.push(...validators);
@@ -98,7 +105,11 @@ export async function addValidatorKeys(existing: string, options: AddValidatorKe
       targetDir = dirname(existing);
     }
     await writeEthJsonV3ToFile(keystore.validators, { outDir: targetDir, password });
-    await writeBlsBn254ToFile(keystore.validators, { outDir: targetDir, password, blsPath });
+    await writeBlsBn254ToFile(keystore.validators, {
+      outDir: targetDir,
+      password,
+      derivationPaths: getBlsDerivationPaths(summaries),
+    });
   }
 
   let outputPath = existing;
@@ -118,5 +129,7 @@ export async function addValidatorKeys(existing: string, options: AddValidatorKe
     log(`Updated keystore ${outputPath} with ${validators.length} new validator(s)`);
     logValidatorSummaries(log, summaries);
   }
-  maybePrintJson(log, !!json, keystore as unknown as Record<string, any>);
+  const blsKeyCandidates = getBlsKeyCandidates(summaries);
+  const outputData = blsKeyCandidates.length > 0 ? { ...keystore, blsKeyCandidates } : keystore;
+  maybePrintJson(log, !!json, outputData as unknown as Record<string, any>);
 }

package/src/cmds/validator_keys/bls_key_derivation.ts

@@ -0,0 +1,209 @@
+import {
+  type ProofOfPossessionGasModel,
+  estimateBlsKeyProofOfPossessionGas,
+  minimumProofOfPossessionGas,
+} from '@aztec-labs/ethereum/bn254';
+import { deriveBlsPrivateKey } from '@aztec-labs/foundation/crypto/bls';
+import type { Hex } from '@aztec-labs/foundation/string';
+
+/** What a BLS key derivation version checks: a key fits if its estimated minimum stipend is at most `budget`. */
+export type BlsKeyDerivationVersion = {
+  version: number;
+  gasModel: ProofOfPossessionGasModel;
+  budget: number;
+};
+
+/**
+ * BLS key derivation v6. The gas model is a frozen copy of `AMSTERDAM_PROOF_OF_POSSESSION_GAS_MODEL` from
+ * `@aztec-labs/ethereum/bn254`. The budget is the 300,000 gas `proofOfPossessionGasLimit` that the v6 upgrade
+ * payload sets on the GSE, minus a 10% margin.
+ *
+ * With per-attempt probabilities 0.189030554816 of reaching the square root and 0.094515277408 of succeeding, about
+ * 5.8243e-6 of keys (1 in 171,694) estimate over the budget, so they move to a later candidate under v6.
+ *
+ * Frozen once a CLI release ships it: changing any value changes which BLS key `--bls-key-derivation-v6` selects for
+ * the same mnemonic and indices, so operators could no longer regenerate their keys. Add a new version instead.
+ */
+export const BLS_KEY_DERIVATION_V6: BlsKeyDerivationVersion = {
+  version: 6,
+  gasModel: {
+    fixed: 132_694,
+    perAttempt: 515,
+    perSqrtCall: 4_580,
+    memoryNumerator: 95_975,
+    memoryDenominator: 1_000_000,
+  },
+  budget: 270_000,
+};
+
+/** Version checked when no derivation flag is given. A future version gets its own flag next to `--bls-key-derivation-v6`. */
+export const LATEST_BLS_KEY_DERIVATION = BLS_KEY_DERIVATION_V6;
+
+/** Number of candidates tried per validator before key selection gives up. */
+export const MAX_BLS_KEY_CANDIDATES = 256;
+
+/**
+ * How a validator's BLS key is chosen among its candidates. The budget is `maxGas` when set (a stricter, user-chosen
+ * value), or the version's budget otherwise.
+ * - `check`: candidate 0, failing if it estimates over the budget (no `--bls-key-derivation-v6`).
+ * - `retry`: the first candidate within the budget (`--bls-key-derivation-v6`).
+ * - `none`: candidate 0, unchecked (`--skip-bls-key-gas-check`).
+ */
+export type BlsKeyDerivationPolicy =
+  | { mode: 'check'; version: BlsKeyDerivationVersion; maxGas?: number }
+  | { mode: 'retry'; version: BlsKeyDerivationVersion; maxGas?: number }
+  | { mode: 'none' };
+
+/** CLI options that choose the BLS key derivation policy. */
+export type BlsKeyDerivationOptions = {
+  blsKeyDerivationV6?: boolean;
+  blsKeyDerivationMaxGas?: number;
+  skipBlsKeyGasCheck?: boolean;
+};
+
+/** A BLS key chosen for a validator, with the derivation path and candidate that produced it. */
+export type SelectedBlsKey = {
+  privateKey: Hex<32>;
+  /** Full derivation path, including the candidate component when the candidate is not 0. */
+  path: string;
+  candidate: number;
+  /** The `--bls-key-derivation-max-gas` value, when it took part in selecting a candidate other than 0. */
+  maxGas?: number;
+};
+
+/**
+ * How the CLI handled a mnemonic it generated because none was passed: `shown` when it printed the mnemonic before key
+ * derivation, so the operator can pass it back, and `hidden` otherwise.
+ */
+export type GeneratedMnemonic = 'shown' | 'hidden';
+
+const GENERATED_MNEMONIC_HINTS: Record<GeneratedMnemonic, string> = {
+  shown:
+    ' This run generated its mnemonic, and re-running without --mnemonic generates a new one: to keep this ' +
+    'mnemonic, pass it back with --mnemonic.',
+  hidden: ' This run generated a mnemonic without showing it, so re-running derives new keys from a new mnemonic.',
+};
+
+/** Thrown when candidate 0 estimates over the budget and no flag says what to do about it. */
+export class BlsKeyOverGasBudgetError extends Error {
+  constructor(
+    public readonly path: string,
+    public readonly estimatedGas: number,
+    public readonly version: BlsKeyDerivationVersion,
+    public readonly maxGas: number | undefined,
+    generatedMnemonic: GeneratedMnemonic | undefined,
+  ) {
+    const budget =
+      maxGas === undefined
+        ? `the ${version.budget} budget of BLS key derivation v${version.version}, so it could exceed the L1 gas cap`
+        : `the ${maxGas} budget set by --bls-key-derivation-max-gas`;
+    const remedies =
+      maxGas === undefined
+        ? `Re-run with --bls-key-derivation-v${version.version} to select a cheaper key for this validator, or with ` +
+          `--skip-bls-key-gas-check to keep this key regardless (for example, a key already registered).`
+        : `Re-run with --bls-key-derivation-v${version.version} to select a cheaper key for this validator, or with a ` +
+          `higher --bls-key-derivation-max-gas.`;
+    super(
+      `The proof-of-possession check of the BLS key derived at ${path} is estimated at ${estimatedGas} gas, above ` +
+        `${budget}. ${remedies}` +
+        (generatedMnemonic ? GENERATED_MNEMONIC_HINTS[generatedMnemonic] : ''),
+    );
+    this.name = 'BlsKeyOverGasBudgetError';
+  }
+}
+
+/** Validates the BLS key derivation flags and turns them into a policy. */
+export function resolveBlsKeyDerivationPolicy(options: BlsKeyDerivationOptions): BlsKeyDerivationPolicy {
+  const { blsKeyDerivationV6, blsKeyDerivationMaxGas: maxGas, skipBlsKeyGasCheck } = options;
+  const version = LATEST_BLS_KEY_DERIVATION;
+  if (skipBlsKeyGasCheck) {
+    if (blsKeyDerivationV6) {
+      throw new Error('--bls-key-derivation-v6 and --skip-bls-key-gas-check cannot be used together');
+    }
+    if (maxGas !== undefined) {
+      throw new Error('--bls-key-derivation-max-gas and --skip-bls-key-gas-check cannot be used together');
+    }
+    return { mode: 'none' };
+  }
+
+  if (maxGas !== undefined) {
+    if (!Number.isSafeInteger(maxGas)) {
+      throw new Error(`--bls-key-derivation-max-gas must be an integer, got ${maxGas}`);
+    }
+    if (maxGas > version.budget) {
+      throw new Error(
+        `--bls-key-derivation-max-gas can only lower the budget: ${maxGas} is above the ${version.budget} gas budget ` +
+          `of BLS key derivation v${version.version}.`,
+      );
+    }
+    const minimum = minimumProofOfPossessionGas(version.gasModel);
+    if (maxGas < minimum) {
+      throw new Error(
+        `--bls-key-derivation-max-gas ${maxGas} is below ${minimum}, the lowest proof-of-possession gas estimate any ` +
+          `key can have, so no key could fit.`,
+      );
+    }
+  }
+
+  return { mode: blsKeyDerivationV6 ? 'retry' : 'check', version, ...(maxGas !== undefined ? { maxGas } : {}) };
+}
+
+/** Derivation path of a candidate: candidate 0 is the per-validator path itself, others append `/<candidate>`. */
+export function blsCandidatePath(perValidatorPath: string, candidate: number): string {
+  return candidate === 0 ? perValidatorPath : `${perValidatorPath}/${candidate}`;
+}
+
+/** Inputs to {@link selectBlsKey}. */
+export type SelectBlsKeyInput = {
+  mnemonic?: string;
+  ikm?: string;
+  perValidatorPath: string;
+  /** Set when the CLI generated `mnemonic` in this run, to tell the operator how to keep or replace it on error. */
+  generatedMnemonic?: GeneratedMnemonic;
+  maxCandidates?: number;
+};
+
+/**
+ * Derives a validator's BLS key from `perValidatorPath` under the given policy. Only the mnemonic or IKM, the path
+ * and the policy decide the result, so re-running with the same inputs regenerates the same key.
+ */
+export function selectBlsKey(policy: BlsKeyDerivationPolicy, input: SelectBlsKeyInput): SelectedBlsKey {
+  const { mnemonic, ikm, perValidatorPath, generatedMnemonic, maxCandidates = MAX_BLS_KEY_CANDIDATES } = input;
+  const candidate0 = { privateKey: deriveBlsPrivateKey(mnemonic, ikm, perValidatorPath), path: perValidatorPath };
+  if (policy.mode === 'none') {
+    return { ...candidate0, candidate: 0 };
+  }
+
+  const { gasModel } = policy.version;
+  const budget = policy.maxGas ?? policy.version.budget;
+  if (policy.mode === 'check') {
+    const estimatedGas = estimateBlsKeyProofOfPossessionGas(gasModel, candidate0.privateKey);
+    if (estimatedGas > budget) {
+      throw new BlsKeyOverGasBudgetError(
+        perValidatorPath,
+        estimatedGas,
+        policy.version,
+        policy.maxGas,
+        // An IKM takes precedence over the mnemonic, so the mnemonic does not decide the BLS key.
+        ikm ? undefined : generatedMnemonic,
+      );
+    }
+    return { ...candidate0, candidate: 0 };
+  }
+
+  for (let candidate = 0; candidate < maxCandidates; candidate++) {
+    const path = blsCandidatePath(perValidatorPath, candidate);
+    const privateKey = candidate === 0 ? candidate0.privateKey : deriveBlsPrivateKey(mnemonic, ikm, path);
+    if (estimateBlsKeyProofOfPossessionGas(gasModel, privateKey) <= budget) {
+      return {
+        privateKey,
+        path,
+        candidate,
+        ...(candidate > 0 && policy.maxGas !== undefined ? { maxGas: budget } : {}),
+      };
+    }
+  }
+  throw new Error(
+    `No BLS key within the ${budget} gas budget found for ` + `${perValidatorPath} after ${maxCandidates} candidates.`,
+  );
+}

package/src/cmds/validator_keys/generate_bls_keypair.ts

@@ -1,7 +1,7 @@
-import { deriveBlsPrivateKey } from '@aztec-labs/foundation/crypto/bls';
 import type { LogFn } from '@aztec-labs/foundation/log';
 import { writeFile } from 'fs/promises';
 
+import { type BlsKeyDerivationOptions, resolveBlsKeyDerivationPolicy, selectBlsKey } from './bls_key_derivation.js';
 import { computeBlsPublicKeyCompressed, withValidatorIndex } from './shared.js';
 import { defaultBlsPath } from './utils.js';
 
@@ -13,18 +13,39 @@ export type GenerateBlsKeypairOptions = {
   compressed?: boolean;
   json?: boolean;
   out?: string;
-};
+} & BlsKeyDerivationOptions;
 
 export async function generateBlsKeypair(options: GenerateBlsKeypairOptions, log: LogFn) {
   const { mnemonic, ikm, blsPath, compressed = true, json, out } = options;
-  const path = withValidatorIndex(blsPath ?? defaultBlsPath, 0);
-  const priv = deriveBlsPrivateKey(mnemonic, ikm, path);
+  const blsKeyDerivation = resolveBlsKeyDerivationPolicy(options);
+  const {
+    path,
+    privateKey: priv,
+    candidate,
+    maxGas,
+  } = selectBlsKey(blsKeyDerivation, {
+    mnemonic,
+    ikm,
+    perValidatorPath: withValidatorIndex(blsPath ?? defaultBlsPath, 0),
+  });
   const pub = await computeBlsPublicKeyCompressed(priv);
-  const result = { path, privateKey: priv, publicKey: pub, format: compressed ? 'compressed' : 'uncompressed' };
+  const result = {
+    path,
+    ...(candidate > 0 ? { candidate } : {}),
+    ...(maxGas !== undefined ? { maxGas } : {}),
+    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 (candidate > 0) {
+        log(
+          `BLS key derived from candidate ${candidate} at ${path}${maxGas !== undefined ? ` (max gas ${maxGas})` : ''}`,
+        );
+      }
     }
   }
   if (json || !out) {

package/src/cmds/validator_keys/index.ts

@@ -1,9 +1,32 @@
+import { minimumProofOfPossessionGas } from '@aztec-labs/ethereum/bn254';
 import type { LogFn } from '@aztec-labs/foundation/log';
 import { Command, Option } from 'commander';
 
 import { parseAztecAddress, parseEthereumAddress, parseHex, parseOptionalInteger } from '../../utils/commands.js';
+import { BLS_KEY_DERIVATION_V6 } from './bls_key_derivation.js';
 import { defaultBlsPath } from './utils.js';
 
+function blsKeyDerivationV6Option() {
+  return new Option(
+    '--bls-key-derivation-v6',
+    `Replace any BLS key whose estimated proof-of-possession gas exceeds the budget with the next deterministic candidate from the same mnemonic (BLS key derivation v6, budget ${BLS_KEY_DERIVATION_V6.budget} gas). ETH keys never change. Pass it again to regenerate the same keys.`,
+  );
+}
+
+function blsKeyDerivationMaxGasOption() {
+  return new Option(
+    '--bls-key-derivation-max-gas <gas>',
+    `Stricter budget for the estimated proof-of-possession verification gas of each BLS key. The L1 limit (GSE proofOfPossessionGasLimit) is 300,000 gas from the v6 upgrade, and governance may change it; the default budget is ${BLS_KEY_DERIVATION_V6.budget}, that cap minus a 10% margin. Must be between ${minimumProofOfPossessionGas(BLS_KEY_DERIVATION_V6.gasModel)} and ${BLS_KEY_DERIVATION_V6.budget}. Without --bls-key-derivation-v6, an over-budget key is an error. Pass the same value again to regenerate the same keys.`,
+  ).argParser(value => parseOptionalInteger(value));
+}
+
+function skipBlsKeyGasCheckOption() {
+  return new Option(
+    '--skip-bls-key-gas-check',
+    'Keep the first derived BLS key even if its proof-of-possession check could exceed the L1 gas cap (for example, a key already registered).',
+  );
+}
+
 export function injectCommands(program: Command, log: LogFn) {
   const group = program
     .command('validator-keys')
@@ -39,6 +62,9 @@ export function injectCommands(program: Command, log: LogFn) {
     .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(blsKeyDerivationV6Option())
+    .addOption(blsKeyDerivationMaxGasOption())
+    .addOption(skipBlsKeyGasCheckOption())
     .addOption(
       new Option('--password <str>', 'Shared password for writing ETH JSON V3 and BLS EIP-2335 keystore files').env(
         'AZTEC_KEYSTORE_PASSWORD',
@@ -103,6 +129,9 @@ export function injectCommands(program: Command, log: LogFn) {
     .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(blsKeyDerivationV6Option())
+    .addOption(blsKeyDerivationMaxGasOption())
+    .addOption(skipBlsKeyGasCheckOption())
     .option('--empty', 'Generate an empty skeleton without keys')
     .option(
       '--password <str>',
@@ -168,6 +197,9 @@ export function injectCommands(program: Command, log: LogFn) {
     .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})`)
+    .addOption(blsKeyDerivationV6Option())
+    .addOption(blsKeyDerivationMaxGasOption())
+    .addOption(skipBlsKeyGasCheckOption())
     .option('--g2', 'Derive on G2 subgroup')
     .option('--compressed', 'Output compressed public key')
     .option('--json', 'Print JSON output to stdout')