@aztec/cli 0.0.1-commit.2ed92850 → 0.0.1-commit.2f68f620

package/src/cmds/l1/update_l1_validators.ts

@@ -2,7 +2,7 @@ import { createEthereumChain, isAnvilTestChain } from '@aztec/ethereum/chain';
 import { createExtendedL1Client, getPublicClient } from '@aztec/ethereum/client';
 import { getL1ContractsConfigEnvVars } from '@aztec/ethereum/config';
 import { GSEContract, RollupContract } from '@aztec/ethereum/contracts';
-import { createL1TxUtilsFromViemWallet } from '@aztec/ethereum/l1-tx-utils';
+import { createL1TxUtils } from '@aztec/ethereum/l1-tx-utils';
 import { EthCheatCodes } from '@aztec/ethereum/test';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { LogFn, Logger } from '@aztec/foundation/log';
@@ -38,7 +38,6 @@ export interface LoggerArgs {
 export function generateL1Account() {
   const privateKey = generatePrivateKey();
   const account = privateKeyToAccount(privateKey);
-  account.address;
   return {
     privateKey,
     address: account.address,
@@ -88,7 +87,7 @@ export async function addL1Validator({
   const gse = new GSEContract(l1Client, gseAddress);
   const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
 
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+  const l1TxUtils = createL1TxUtils(l1Client, { logger: debugLogger });
   const proofParamsObj = ZkPassportProofParams.fromBuffer(proofParams);
 
   // Step 1: Claim STK tokens from the faucet
@@ -194,7 +193,7 @@ export async function addL1ValidatorViaRollup({
 
   const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
 
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+  const l1TxUtils = createL1TxUtils(l1Client, { logger: debugLogger });
 
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
     to: rollupAddress.toString(),
@@ -241,7 +240,7 @@ export async function removeL1Validator({
   const account = getAccount(privateKey, mnemonic);
   const chain = createEthereumChain(rpcUrls, chainId);
   const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+  const l1TxUtils = createL1TxUtils(l1Client, { logger: debugLogger });
 
   dualLog(`Removing validator ${validatorAddress.toString()} from rollup ${rollupAddress.toString()}`);
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
@@ -268,7 +267,7 @@ export async function pruneRollup({
   const account = getAccount(privateKey, mnemonic);
   const chain = createEthereumChain(rpcUrls, chainId);
   const l1Client = createExtendedL1Client(rpcUrls, account, chain.chainInfo);
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
+  const l1TxUtils = createL1TxUtils(l1Client, { logger: debugLogger });
 
   dualLog(`Trying prune`);
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({

package/src/cmds/validator_keys/eth_json_v3_worker.ts

@@ -0,0 +1,30 @@
+import { Wallet } from '@ethersproject/wallet';
+import { parentPort, workerData } from 'worker_threads';
+
+type EthJsonV3WorkerData = {
+  privateKeyHex: string;
+  password: string;
+};
+
+type SerializedError = {
+  message: string;
+  name?: string;
+  stack?: string;
+};
+
+function serializeError(error: unknown): SerializedError {
+  if (error instanceof Error) {
+    return { message: error.message, name: error.name, stack: error.stack };
+  }
+  return { message: String(error) };
+}
+
+void (async () => {
+  try {
+    const { privateKeyHex, password } = workerData as EthJsonV3WorkerData;
+    const json = await new Wallet(privateKeyHex).encrypt(password);
+    parentPort?.postMessage({ json });
+  } catch (error) {
+    parentPort?.postMessage({ error: serializeError(error) });
+  }
+})();

package/src/cmds/validator_keys/index.ts

@@ -1,6 +1,6 @@
 import type { LogFn } from '@aztec/foundation/log';
 
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 
 import { parseAztecAddress, parseEthereumAddress, parseHex, parseOptionalInteger } from '../../utils/commands.js';
 import { defaultBlsPath } from './utils.js';
@@ -38,10 +38,24 @@ 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})`)
-    .option(
-      '--password <str>',
-      'Password for writing keystore files (ETH JSON V3 and BLS EIP-2335). Empty string allowed',
+    .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')

package/src/cmds/validator_keys/new.ts

@@ -6,7 +6,7 @@ import type { LogFn } from '@aztec/foundation/log';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 import { wordlist } from '@scure/bip39/wordlists/english.js';
-import { writeFile } from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
 import { basename, dirname, join } from 'path';
 import { createPublicClient, fallback, http } from 'viem';
 import { generateMnemonic, mnemonicToAccount } from 'viem/accounts';
@@ -42,6 +42,11 @@ export type NewValidatorKeystoreOptions = {
   ikm?: string;
   blsPath?: string;
   password?: string;
+  passwordFile?: string;
+  ethPassword?: string;
+  ethPasswordFile?: string;
+  blsPassword?: string;
+  blsPasswordFile?: string;
   encryptedKeystoreDir?: string;
   json?: boolean;
   feeRecipient: AztecAddress;
@@ -53,6 +58,86 @@ export type NewValidatorKeystoreOptions = {
   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);
@@ -78,7 +163,12 @@ export async function newValidatorKeystore(options: NewValidatorKeystoreOptions,
     blsPath,
     ikm,
     mnemonic: _mnemonic,
-    password,
+    password: passwordOption,
+    passwordFile,
+    ethPassword: ethPasswordOption,
+    ethPasswordFile,
+    blsPassword: blsPasswordOption,
+    blsPasswordFile,
     encryptedKeystoreDir,
     stakerOutput,
     gseAddress,
@@ -86,9 +176,18 @@ export async function newValidatorKeystore(options: NewValidatorKeystoreOptions,
     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) {
+  if (!_mnemonic && !json && !shouldEncryptKeystores) {
     log('No mnemonic provided, generating new one...');
     log(`Using new mnemonic:`);
     log('');
@@ -115,11 +214,11 @@ export async function newValidatorKeystore(options: NewValidatorKeystoreOptions,
   });
 
   // If password provided, write ETH JSON V3 and BLS BN254 keystores and replace plaintext
-  if (password !== undefined) {
+  if (shouldEncryptKeystores) {
     const encryptedKeystoreOutDir =
       encryptedKeystoreDir && encryptedKeystoreDir.length > 0 ? encryptedKeystoreDir : keystoreOutDir;
-    await writeEthJsonV3ToFile(validators, { outDir: encryptedKeystoreOutDir, password });
-    await writeBlsBn254ToFile(validators, { outDir: encryptedKeystoreOutDir, password });
+    await writeEthJsonV3ToFile(validators, { outDir: encryptedKeystoreOutDir, password: ethPassword });
+    await writeBlsBn254ToFile(validators, { outDir: encryptedKeystoreOutDir, password: blsPassword });
   }
 
   const keystore = {
@@ -145,7 +244,7 @@ export async function newValidatorKeystore(options: NewValidatorKeystoreOptions,
     // Process each validator
     for (let i = 0; i < validators.length; i++) {
       const validator = validators[i];
-      const outputs = await processAttesterAccounts(validator.attester, gse, password);
+      const outputs = await processAttesterAccounts(validator.attester, gse);
 
       // Collect all staker outputs
       for (let j = 0; j < outputs.length; j++) {
@@ -160,7 +259,7 @@ export async function newValidatorKeystore(options: NewValidatorKeystoreOptions,
     }
   }
 
-  const outputData = !_mnemonic ? { ...keystore, generatedMnemonic: mnemonic } : keystore;
+  const outputData = !_mnemonic && !shouldEncryptKeystores ? { ...keystore, generatedMnemonic: mnemonic } : keystore;
 
   // Handle JSON output
   if (json) {

package/src/cmds/validator_keys/shared.ts

@@ -1,4 +1,5 @@
 import { prettyPrintJSON } from '@aztec/cli/utils';
+import { asyncPool } from '@aztec/foundation/async-pool';
 import { deriveBlsPrivateKey } from '@aztec/foundation/crypto/bls';
 import { createBn254Keystore } from '@aztec/foundation/crypto/bls/bn254_keystore';
 import { computeBn254G1PublicKeyCompressed } from '@aztec/foundation/crypto/bn254';
@@ -10,12 +11,60 @@ import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { Wallet } from '@ethersproject/wallet';
 import { constants as fsConstants, mkdirSync } from 'fs';
 import { access, writeFile } from 'fs/promises';
-import { homedir } from 'os';
+import { availableParallelism, homedir } from 'os';
 import { dirname, isAbsolute, join } from 'path';
 import { mnemonicToAccount } from 'viem/accounts';
+import { Worker } from 'worker_threads';
 
 import { defaultBlsPath } from './utils.js';
 
+type EthJsonV3WorkerResult = { json: string } | { error: { message: string; name?: string; stack?: string } };
+
+// ethers' default scrypt parameters use substantial memory, so keep worker fan-out bounded.
+const maxEthKeystoreWorkers = Math.max(1, Math.min(4, availableParallelism()));
+
+function deserializeWorkerError(error: { message: string; name?: string; stack?: string }) {
+  const result = new Error(error.message);
+  result.name = error.name ?? result.name;
+  result.stack = error.stack;
+  return result;
+}
+
+function encryptEthJsonV3InWorker(privateKeyHex: string, password: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const worker = new Worker(new URL('./eth_json_v3_worker.js', import.meta.url), {
+      workerData: { privateKeyHex, password },
+    });
+    let settled = false;
+
+    worker.once('message', (result: EthJsonV3WorkerResult) => {
+      settled = true;
+
+      if ('json' in result) {
+        resolve(result.json);
+      } else {
+        reject(deserializeWorkerError(result.error));
+      }
+    });
+    worker.once('error', error => {
+      settled = true;
+      reject(error);
+    });
+    worker.once('exit', code => {
+      if (!settled) {
+        reject(new Error(`ETH JSON V3 worker stopped with exit code ${code}`));
+      }
+    });
+  });
+}
+
+async function encryptEthJsonV3(privateKeyHex: string, password: string): Promise<string> {
+  if (process.env.JEST_WORKER_ID !== undefined) {
+    return await new Wallet(privateKeyHex).encrypt(password);
+  }
+  return await encryptEthJsonV3InWorker(privateKeyHex, password);
+}
+
 export type ValidatorSummary = { attesterEth?: string; attesterBls?: string; publisherEth?: string[] };
 
 export type BuildValidatorsInput = {
@@ -228,7 +277,7 @@ export async function writeBn254BlsKeystore(
 ): Promise<string> {
   mkdirSync(outDir, { recursive: true });
 
-  const keystore = createBn254Keystore(password, privateKeyHex, pubkeyHex, derivationPath);
+  const keystore = await createBn254Keystore(password, privateKeyHex, pubkeyHex, derivationPath);
 
   const safeBase = fileNameBase.replace(/[^a-zA-Z0-9_-]/g, '_');
   const outPath = join(outDir, `keystore-${safeBase}.json`);
@@ -241,28 +290,29 @@ export async function writeBlsBn254ToFile(
   validators: ValidatorKeyStore[],
   options: { outDir: string; password: string; blsPath?: string },
 ): Promise<void> {
-  for (let i = 0; i < validators.length; i++) {
-    const v = validators[i];
-    if (!v || typeof v !== 'object' || !('attester' in v)) {
-      continue;
-    }
-    const att = (v as any).attester;
+  await Promise.all(
+    validators.map(async (v, i) => {
+      if (!v || typeof v !== 'object' || !('attester' in v)) {
+        return;
+      }
+      const att = (v as any).attester;
 
-    // Shapes: { bls: <hex> } or { eth: <ethAccount>, bls?: <hex> } or plain EthAccount
-    const blsKey: string | undefined = typeof att === 'object' && 'bls' in att ? (att as any).bls : undefined;
-    if (!blsKey || typeof blsKey !== 'string') {
-      continue;
-    }
+      // Shapes: { bls: <hex> } or { eth: <ethAccount>, bls?: <hex> } or plain EthAccount
+      const blsKey: string | undefined = typeof att === 'object' && 'bls' in att ? (att as any).bls : undefined;
+      if (!blsKey || typeof blsKey !== 'string') {
+        return;
+      }
 
-    const pub = await computeBlsPublicKeyCompressed(blsKey);
-    const path = options.blsPath ?? defaultBlsPath;
-    const fileBase = `${String(i + 1)}_${pub.slice(2, 18)}`;
-    const keystorePath = await writeBn254BlsKeystore(options.outDir, fileBase, options.password, blsKey, pub, path);
+      const pub = await computeBlsPublicKeyCompressed(blsKey);
+      const path = options.blsPath ?? defaultBlsPath;
+      const fileBase = `${String(i + 1)}_${pub.slice(2, 18)}`;
+      const keystorePath = await writeBn254BlsKeystore(options.outDir, fileBase, options.password, blsKey, pub, path);
 
-    if (typeof att === 'object') {
-      (att as any).bls = { path: keystorePath, password: options.password };
-    }
-  }
+      if (typeof att === 'object') {
+        (att as any).bls = { path: keystorePath, password: options.password };
+      }
+    }),
+  );
 }
 
 /** Writes an Ethereum JSON V3 keystore using ethers, returns absolute path */
@@ -274,8 +324,7 @@ export async function writeEthJsonV3Keystore(
 ): Promise<string> {
   const safeBase = fileNameBase.replace(/[^a-zA-Z0-9_-]/g, '_');
   mkdirSync(outDir, { recursive: true });
-  const wallet = new Wallet(privateKeyHex);
-  const json = await wallet.encrypt(password);
+  const json = await encryptEthJsonV3(privateKeyHex, password);
   const outPath = join(outDir, `keystore-eth-${safeBase}.json`);
   await writeFile(outPath, json, { encoding: 'utf-8' });
   return outPath;
@@ -286,13 +335,16 @@ export async function writeEthJsonV3ToFile(
   validators: ValidatorKeyStore[],
   options: { outDir: string; password: string },
 ): Promise<void> {
-  const maybeEncryptEth = async (account: any, label: string) => {
+  const tasks: (() => Promise<void>)[] = [];
+
+  const maybeQueueEncryptEth = (account: any, label: string, setEncryptedAccount: (account: any) => void) => {
     if (typeof account === 'string' && account.startsWith('0x') && account.length === 66) {
-      const fileBase = `${label}_${account.slice(2, 10)}`;
-      const p = await writeEthJsonV3Keystore(options.outDir, fileBase, options.password, account);
-      return { path: p, password: options.password };
+      tasks.push(async () => {
+        const fileBase = `${label}_${account.slice(2, 10)}`;
+        const path = await writeEthJsonV3Keystore(options.outDir, fileBase, options.password, account);
+        setEncryptedAccount({ path, password: options.password });
+      });
     }
-    return account;
   };
 
   for (let i = 0; i < validators.length; i++) {
@@ -304,23 +356,23 @@ export async function writeEthJsonV3ToFile(
     // attester may be string (eth), object with eth, or remote signer
     const att = (v as any).attester;
     if (typeof att === 'string') {
-      (v as any).attester = await maybeEncryptEth(att, `attester_${i + 1}`);
+      maybeQueueEncryptEth(att, `attester_${i + 1}`, account => ((v as any).attester = account));
     } else if (att && typeof att === 'object' && 'eth' in att) {
-      (att as any).eth = await maybeEncryptEth((att as any).eth, `attester_${i + 1}`);
+      maybeQueueEncryptEth((att as any).eth, `attester_${i + 1}`, account => ((att as any).eth = account));
     }
 
     // publisher can be single or array
     if ('publisher' in v) {
       const pub = (v as any).publisher;
       if (Array.isArray(pub)) {
-        const out: any[] = [];
         for (let j = 0; j < pub.length; j++) {
-          out.push(await maybeEncryptEth(pub[j], `publisher_${i + 1}_${j + 1}`));
+          maybeQueueEncryptEth(pub[j], `publisher_${i + 1}_${j + 1}`, account => (pub[j] = account));
         }
-        (v as any).publisher = out;
       } else if (pub !== undefined) {
-        (v as any).publisher = await maybeEncryptEth(pub, `publisher_${i + 1}`);
+        maybeQueueEncryptEth(pub, `publisher_${i + 1}`, account => ((v as any).publisher = account));
       }
     }
   }
+
+  await asyncPool(maxEthKeystoreWorkers, tasks, task => task());
 }

package/src/config/cached_fetch.ts

@@ -1,24 +1,48 @@
 import { createLogger } from '@aztec/aztec.js/log';
 
-import { mkdir, readFile, stat, writeFile } from 'fs/promises';
+import { mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname } from 'path';
 
 export interface CachedFetchOptions {
-  /** Cache duration in milliseconds */
-  cacheDurationMs: number;
-  /** The cache file */
+  /** The cache file path for storing data. If not provided, no caching is performed. */
   cacheFile?: string;
+  /** Fallback max-age in milliseconds when server sends no Cache-Control header. Defaults to 5 minutes. */
+  defaultMaxAgeMs?: number;
+}
+
+/** Cache metadata stored in a sidecar .meta file alongside the data file. */
+interface CacheMeta {
+  etag?: string;
+  expiresAt: number;
+}
+
+const DEFAULT_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
+
+/** Extracts max-age value in milliseconds from a Response's Cache-Control header. Returns undefined if not present. */
+export function parseMaxAge(response: { headers: { get(name: string): string | null } }): number | undefined {
+  const cacheControl = response.headers.get('cache-control');
+  if (!cacheControl) {
+    return undefined;
+  }
+  const match = cacheControl.match(/max-age=(\d+)/);
+  if (!match) {
+    return undefined;
+  }
+  return parseInt(match[1], 10) * 1000;
 }
 
 /**
- * Fetches data from a URL with file-based caching support.
- * This utility can be used by both remote config and bootnodes fetching.
+ * Fetches data from a URL with file-based HTTP conditional caching.
+ *
+ * Data is stored as raw JSON in the cache file (same format as the server returns).
+ * Caching metadata (ETag, expiry) is stored in a separate sidecar `.meta` file.
+ * This keeps the data file human-readable and backward-compatible with older code.
  *
  * @param url - The URL to fetch from
- * @param networkName - Network name for cache directory structure
- * @param options - Caching and error handling options
- * @param cacheDir - Optional cache directory (defaults to no caching)
- * @returns The fetched and parsed JSON data, or undefined if fetch fails and throwOnError is false
+ * @param options - Caching options
+ * @param fetch - Fetch implementation (defaults to globalThis.fetch)
+ * @param log - Logger instance
+ * @returns The fetched and parsed JSON data, or undefined if fetch fails
  */
 export async function cachedFetch<T = any>(
   url: string,
@@ -26,42 +50,106 @@ export async function cachedFetch<T = any>(
   fetch = globalThis.fetch,
   log = createLogger('cached_fetch'),
 ): Promise<T | undefined> {
-  const { cacheDurationMs, cacheFile } = options;
+  const { cacheFile, defaultMaxAgeMs = DEFAULT_MAX_AGE_MS } = options;
+
+  // If no cacheFile, just fetch normally without caching
+  if (!cacheFile) {
+    return fetchAndParse<T>(url, fetch, log);
+  }
+
+  const metaFile = cacheFile + '.meta';
 
-  // Try to read from cache first
+  // Try to read metadata
+  let meta: CacheMeta | undefined;
   try {
-    if (cacheFile) {
-      const info = await stat(cacheFile);
-      if (info.mtimeMs + cacheDurationMs > Date.now()) {
-        const cachedData = JSON.parse(await readFile(cacheFile, 'utf-8'));
-        return cachedData;
-      }
-    }
+    meta = JSON.parse(await readFile(metaFile, 'utf-8'));
   } catch {
-    log.trace('Failed to read data from cache');
+    log.trace('No usable cache metadata found');
   }
 
+  // Try to read cached data
+  let cachedData: T | undefined;
   try {
-    const response = await fetch(url);
+    cachedData = JSON.parse(await readFile(cacheFile, 'utf-8'));
+  } catch {
+    log.trace('No usable cached data found');
+  }
+
+  // If metadata and data exist and cache is fresh, return directly
+  if (meta && cachedData !== undefined && meta.expiresAt > Date.now()) {
+    return cachedData;
+  }
+
+  // Cache is stale or missing — make a (possibly conditional) request
+  try {
+    const headers: Record<string, string> = {};
+    if (meta?.etag && cachedData !== undefined) {
+      headers['If-None-Match'] = meta.etag;
+    }
+
+    const response = await fetch(url, { headers });
+
+    if (response.status === 304 && cachedData !== undefined) {
+      // Not modified — recompute expiry from new response headers and return cached data
+      const maxAgeMs = parseMaxAge(response) ?? defaultMaxAgeMs;
+      await writeMetaFile(metaFile, { etag: meta?.etag, expiresAt: Date.now() + maxAgeMs }, log);
+      return cachedData;
+    }
+
     if (!response.ok) {
       log.warn(`Failed to fetch from ${url}: ${response.status} ${response.statusText}`);
-      return undefined;
+      return cachedData;
     }
 
-    const data = await response.json();
+    // 200 — parse new data and cache it
+    const data = (await response.json()) as T;
+    const maxAgeMs = parseMaxAge(response) ?? defaultMaxAgeMs;
+    const etag = response.headers.get('etag') ?? undefined;
 
-    try {
-      if (cacheFile) {
-        await mkdir(dirname(cacheFile), { recursive: true });
-        await writeFile(cacheFile, JSON.stringify(data), 'utf-8');
-      }
-    } catch (err) {
-      log.warn('Failed to cache data on disk: ' + cacheFile, { cacheFile, err });
-    }
+    await ensureDir(cacheFile, log);
+    await Promise.all([
+      writeFile(cacheFile, JSON.stringify(data), 'utf-8'),
+      writeFile(metaFile, JSON.stringify({ etag, expiresAt: Date.now() + maxAgeMs }), 'utf-8'),
+    ]);
 
     return data;
+  } catch (err) {
+    log.warn(`Failed to fetch from ${url}`, { err });
+    return cachedData;
+  }
+}
+
+async function fetchAndParse<T>(
+  url: string,
+  fetch: typeof globalThis.fetch,
+  log: ReturnType<typeof createLogger>,
+): Promise<T | undefined> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      log.warn(`Failed to fetch from ${url}: ${response.status} ${response.statusText}`);
+      return undefined;
+    }
+    return (await response.json()) as T;
   } catch (err) {
     log.warn(`Failed to fetch from ${url}`, { err });
     return undefined;
   }
 }
+
+async function ensureDir(filePath: string, log: ReturnType<typeof createLogger>) {
+  try {
+    await mkdir(dirname(filePath), { recursive: true });
+  } catch (err) {
+    log.warn('Failed to create cache directory for: ' + filePath, { err });
+  }
+}
+
+async function writeMetaFile(metaFile: string, meta: CacheMeta, log: ReturnType<typeof createLogger>) {
+  try {
+    await mkdir(dirname(metaFile), { recursive: true });
+    await writeFile(metaFile, JSON.stringify(meta), 'utf-8');
+  } catch (err) {
+    log.warn('Failed to write cache metadata: ' + metaFile, { err });
+  }
+}

package/src/config/chain_l2_config.ts

@@ -45,7 +45,9 @@ export function enrichEnvironmentWithChainName(networkName: NetworkNames) {
   }
 
   // Apply generated network config from defaults.yml
-  const generatedConfig = NetworkConfigs[networkName];
+  // For devnet iterations (v4-devnet-1, etc.), use the base devnet config
+  const configKey = /^v\d+-devnet-\d+$/.test(networkName) ? 'devnet' : networkName;
+  const generatedConfig = NetworkConfigs[configKey];
   if (generatedConfig) {
     enrichEnvironmentWithNetworkConfig(generatedConfig);
   }