@aztec/cli 2.0.3 → 2.1.0-rc.2

package/dest/config/network_config.js

@@ -0,0 +1,79 @@
+import { NetworkConfigMapSchema } from '@aztec/foundation/config';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { cachedFetch } from './cached_fetch.js';
+import { enrichEthAddressVar, enrichVar } from './enrich_env.js';
+const DEFAULT_CONFIG_URL = 'https://raw.githubusercontent.com/AztecProtocol/networks/refs/heads/main/network_config.json';
+const NETWORK_CONFIG_CACHE_DURATION_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Fetches remote network configuration from GitHub with caching support.
+ * Uses the reusable cachedFetch utility.
+ *
+ * @param networkName - The network name to fetch config for
+ * @param cacheDir - Optional cache directory for storing fetched config
+ * @returns Remote configuration for the specified network, or undefined if not found/error
+ */ export async function getNetworkConfig(networkName, cacheDir) {
+    let url;
+    const configLocation = process.env.NETWORK_CONFIG_LOCATION || DEFAULT_CONFIG_URL;
+    if (!configLocation) {
+        return undefined;
+    }
+    try {
+        if (configLocation.includes('://')) {
+            url = new URL(configLocation);
+        } else {
+            url = new URL(`file://${configLocation}`);
+        }
+    } catch  {
+    /* no-op */ }
+    if (!url) {
+        return undefined;
+    }
+    try {
+        let rawConfig;
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            rawConfig = await cachedFetch(url.href, {
+                cacheDurationMs: NETWORK_CONFIG_CACHE_DURATION_MS,
+                cacheFile: cacheDir ? join(cacheDir, networkName, 'network_config.json') : undefined
+            });
+        } else if (url.protocol === 'file:') {
+            rawConfig = JSON.parse(await readFile(url.pathname, 'utf-8'));
+        } else {
+            throw new Error('Unsupported Aztec network config protocol: ' + url.href);
+        }
+        if (!rawConfig) {
+            return undefined;
+        }
+        const networkConfigMap = NetworkConfigMapSchema.parse(rawConfig);
+        if (networkName in networkConfigMap) {
+            return networkConfigMap[networkName];
+        } else {
+            return undefined;
+        }
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Enriches environment variables with remote network configuration.
+ * This function is called before node config initialization to set env vars
+ * from the remote config, following the same pattern as enrichEnvironmentWithChainConfig().
+ *
+ * @param networkName - The network name to fetch remote config for
+ */ export async function enrichEnvironmentWithNetworkConfig(networkName) {
+    if (networkName === 'local') {
+        return; // No remote config for local development
+    }
+    const cacheDir = process.env.DATA_DIRECTORY ? join(process.env.DATA_DIRECTORY, 'cache') : undefined;
+    const networkConfig = await getNetworkConfig(networkName, cacheDir);
+    if (!networkConfig) {
+        return;
+    }
+    enrichVar('BOOTSTRAP_NODES', networkConfig.bootnodes.join(','));
+    enrichVar('L1_CHAIN_ID', String(networkConfig.l1ChainId));
+    enrichVar('SYNC_SNAPSHOTS_URLS', networkConfig.snapshots.join(','));
+    enrichEthAddressVar('REGISTRY_CONTRACT_ADDRESS', networkConfig.registryAddress.toString());
+    if (networkConfig.feeAssetHandlerAddress) {
+        enrichEthAddressVar('FEE_ASSET_HANDLER_CONTRACT_ADDRESS', networkConfig.feeAssetHandlerAddress.toString());
+    }
+}

package/dest/utils/aztec.d.ts

@@ -18,7 +18,7 @@ export declare function getFunctionAbi(artifact: ContractArtifact, fnName: strin
  * @param privateKey - The private key to be used in contract deployment.
  * @param mnemonic - The mnemonic to be used in contract deployment.
  */
-export declare function deployAztecContracts(rpcUrls: string[], chainId: number, privateKey: string | undefined, mnemonic: string, mnemonicIndex: number, salt: number | undefined, initialValidators: Operator[], genesisArchiveRoot: Fr, feeJuicePortalInitialBalance: bigint, acceleratedTestDeployments: boolean, config: L1ContractsConfig, realVerifier: boolean, createVerificationJson: string | false, debugLogger: Logger): Promise<DeployL1ContractsReturnType>;
+export declare function deployAztecContracts(rpcUrls: string[], chainId: number, privateKey: string | undefined, mnemonic: string, mnemonicIndex: number, salt: number | undefined, initialValidators: Operator[], genesisArchiveRoot: Fr, feeJuicePortalInitialBalance: bigint, acceleratedTestDeployments: boolean, config: L1ContractsConfig, existingToken: EthAddress | undefined, realVerifier: boolean, createVerificationJson: string | false, debugLogger: Logger): Promise<DeployL1ContractsReturnType>;
 export declare function deployNewRollupContracts(registryAddress: EthAddress, rpcUrls: string[], chainId: number, privateKey: string | undefined, mnemonic: string, mnemonicIndex: number, salt: number | undefined, initialValidators: Operator[], genesisArchiveRoot: Fr, feeJuicePortalInitialBalance: bigint, config: L1ContractsConfig, realVerifier: boolean, logger: Logger): Promise<{
     rollup: RollupContract;
     slashFactoryAddress: EthAddress;

package/dest/utils/aztec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aztec.d.ts","sourceRoot":"","sources":["../../src/utils/aztec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAIjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAShE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAMtF;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,iBAAiB,EAAE,QAAQ,EAAE,EAC7B,kBAAkB,EAAE,EAAE,EACtB,4BAA4B,EAAE,MAAM,EACpC,0BAA0B,EAAE,OAAO,EACnC,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,OAAO,EACrB,sBAAsB,EAAE,MAAM,GAAG,KAAK,EACtC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,2BAA2B,CAAC,CAgCtC;AAED,wBAAsB,wBAAwB,CAC5C,eAAe,EAAE,UAAU,EAC3B,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,iBAAiB,EAAE,QAAQ,EAAE,EAC7B,kBAAkB,EAAE,EAAE,EACtB,4BAA4B,EAAE,MAAM,EACpC,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,OAAO,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,mBAAmB,EAAE,UAAU,CAAA;CAAE,CAAC,CA6CtE;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAKjE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,6BA4BpE;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK;;;;GAO3G;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MAK7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,KAAK,MAAM,EAKtD,CAAC;AAOF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAUtE;AAKD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,iBAyB9E"}
+{"version":3,"file":"aztec.d.ts","sourceRoot":"","sources":["../../src/utils/aztec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAIjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAShE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAMtF;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,iBAAiB,EAAE,QAAQ,EAAE,EAC7B,kBAAkB,EAAE,EAAE,EACtB,4BAA4B,EAAE,MAAM,EACpC,0BAA0B,EAAE,OAAO,EACnC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,UAAU,GAAG,SAAS,EACrC,YAAY,EAAE,OAAO,EACrB,sBAAsB,EAAE,MAAM,GAAG,KAAK,EACtC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,2BAA2B,CAAC,CAiCtC;AAED,wBAAsB,wBAAwB,CAC5C,eAAe,EAAE,UAAU,EAC3B,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,iBAAiB,EAAE,QAAQ,EAAE,EAC7B,kBAAkB,EAAE,EAAE,EACtB,4BAA4B,EAAE,MAAM,EACpC,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,OAAO,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,mBAAmB,EAAE,UAAU,CAAA;CAAE,CAAC,CA6CtE;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAKjE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,6BA4BpE;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK;;;;GAO3G;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MAK7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,KAAK,MAAM,EAKtD,CAAC;AAOF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAUtE;AAKD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,iBAyB9E"}

package/dest/utils/aztec.js

@@ -25,7 +25,7 @@ import { encodeArgs } from './encoding.js';
  * @param chainId - The chain ID of the L1 host.
  * @param privateKey - The private key to be used in contract deployment.
  * @param mnemonic - The mnemonic to be used in contract deployment.
- */ export async function deployAztecContracts(rpcUrls, chainId, privateKey, mnemonic, mnemonicIndex, salt, initialValidators, genesisArchiveRoot, feeJuicePortalInitialBalance, acceleratedTestDeployments, config, realVerifier, createVerificationJson, debugLogger) {
+ */ export async function deployAztecContracts(rpcUrls, chainId, privateKey, mnemonic, mnemonicIndex, salt, initialValidators, genesisArchiveRoot, feeJuicePortalInitialBalance, acceleratedTestDeployments, config, existingToken, realVerifier, createVerificationJson, debugLogger) {
     const { createEthereumChain, deployL1Contracts } = await import('@aztec/ethereum');
     const { mnemonicToAccount, privateKeyToAccount } = await import('viem/accounts');
     const account = !privateKey ? mnemonicToAccount(mnemonic, {
@@ -42,6 +42,7 @@ import { encodeArgs } from './encoding.js';
         acceleratedTestDeployments,
         feeJuicePortalInitialBalance,
         realVerifier,
+        existingTokenAddress: existingToken,
         ...config
     }, config, createVerificationJson);
     return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/cli",
-  "version": "2.0.3",
+  "version": "2.1.0-rc.2",
   "type": "module",
   "exports": {
     "./contracts": "./dest/cmds/contracts/index.js",
@@ -70,17 +70,17 @@
     ]
   },
   "dependencies": {
-    "@aztec/archiver": "2.0.3",
-    "@aztec/aztec.js": "2.0.3",
-    "@aztec/constants": "2.0.3",
-    "@aztec/entrypoints": "2.0.3",
-    "@aztec/ethereum": "2.0.3",
-    "@aztec/foundation": "2.0.3",
-    "@aztec/l1-artifacts": "2.0.3",
-    "@aztec/node-lib": "2.0.3",
-    "@aztec/p2p": "2.0.3",
-    "@aztec/stdlib": "2.0.3",
-    "@aztec/world-state": "2.0.3",
+    "@aztec/archiver": "2.1.0-rc.2",
+    "@aztec/aztec.js": "2.1.0-rc.2",
+    "@aztec/constants": "2.1.0-rc.2",
+    "@aztec/entrypoints": "2.1.0-rc.2",
+    "@aztec/ethereum": "2.1.0-rc.2",
+    "@aztec/foundation": "2.1.0-rc.2",
+    "@aztec/l1-artifacts": "2.1.0-rc.2",
+    "@aztec/node-lib": "2.1.0-rc.2",
+    "@aztec/p2p": "2.1.0-rc.2",
+    "@aztec/stdlib": "2.1.0-rc.2",
+    "@aztec/world-state": "2.1.0-rc.2",
     "@iarna/toml": "^2.2.5",
     "@libp2p/peer-id-factory": "^3.0.4",
     "commander": "^12.1.0",
@@ -92,8 +92,8 @@
     "viem": "2.23.7"
   },
   "devDependencies": {
-    "@aztec/accounts": "2.0.3",
-    "@aztec/protocol-contracts": "2.0.3",
+    "@aztec/accounts": "2.1.0-rc.2",
+    "@aztec/protocol-contracts": "2.1.0-rc.2",
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/lodash.chunk": "^4.2.9",
@@ -109,15 +109,15 @@
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@aztec/accounts": "2.0.3",
-    "@aztec/bb-prover": "2.0.3",
-    "@aztec/ethereum": "2.0.3",
-    "@aztec/l1-artifacts": "2.0.3",
-    "@aztec/noir-contracts.js": "2.0.3",
-    "@aztec/noir-protocol-circuits-types": "2.0.3",
-    "@aztec/noir-test-contracts.js": "2.0.3",
-    "@aztec/protocol-contracts": "2.0.3",
-    "@aztec/stdlib": "2.0.3"
+    "@aztec/accounts": "2.1.0-rc.2",
+    "@aztec/bb-prover": "2.1.0-rc.2",
+    "@aztec/ethereum": "2.1.0-rc.2",
+    "@aztec/l1-artifacts": "2.1.0-rc.2",
+    "@aztec/noir-contracts.js": "2.1.0-rc.2",
+    "@aztec/noir-protocol-circuits-types": "2.1.0-rc.2",
+    "@aztec/noir-test-contracts.js": "2.1.0-rc.2",
+    "@aztec/protocol-contracts": "2.1.0-rc.2",
+    "@aztec/stdlib": "2.1.0-rc.2"
   },
   "files": [
     "dest",

package/src/cmds/l1/deploy_l1_contracts.ts

@@ -22,6 +22,7 @@ export async function deployL1Contracts(
   createVerificationJson: string | false,
   initialValidators: EthAddress[],
   realVerifier: boolean,
+  existingToken: EthAddress | undefined,
   log: LogFn,
   debugLogger: Logger,
 ) {
@@ -50,6 +51,7 @@ export async function deployL1Contracts(
     fundingNeeded,
     acceleratedTestDeployments,
     config,
+    existingToken,
     realVerifier,
     createVerificationJson,
     debugLogger,

package/src/cmds/l1/index.ts

@@ -48,6 +48,7 @@ export function injectCommands(program: Command, log: LogFn, debugLogger: Logger
     .option('--sponsored-fpc', 'Populate genesis state with a testing sponsored FPC contract')
     .option('--accelerated-test-deployments', 'Fire and forget deployment transactions, use in testing only', false)
     .option('--real-verifier', 'Deploy the real verifier', false)
+    .option('--existing-token <address>', 'Use an existing ERC20 for both fee and staking', parseEthereumAddress)
     .option('--create-verification-json [path]', 'Create JSON file for etherscan contract verification', false)
     .action(async options => {
       const { deployL1Contracts } = await import('./deploy_l1_contracts.js');
@@ -68,6 +69,7 @@ export function injectCommands(program: Command, log: LogFn, debugLogger: Logger
         options.createVerificationJson,
         initialValidators,
         options.realVerifier,
+        options.existingToken,
         log,
         debugLogger,
       );

package/src/cmds/l1/update_l1_validators.ts

@@ -96,7 +96,7 @@ export async function addL1Validator({
 
   const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
 
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, debugLogger);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
   const proofParamsObj = ZkPassportProofParams.fromBuffer(proofParams);
   const merkleProofArray = merkleProof.map(proof => addLeadingHex(proof));
 
@@ -172,7 +172,7 @@ export async function addL1ValidatorViaRollup({
 
   const registrationTuple = await gse.makeRegistrationTuple(blsSecretKey);
 
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, debugLogger);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
 
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
     to: rollupAddress.toString(),
@@ -219,7 +219,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, debugLogger);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
 
   dualLog(`Removing validator ${validatorAddress.toString()} from rollup ${rollupAddress.toString()}`);
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
@@ -246,7 +246,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, debugLogger);
+  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client, { logger: debugLogger });
 
   dualLog(`Trying prune`);
   const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
@@ -308,7 +308,7 @@ export async function debugRollup({ rpcUrls, chainId, rollupAddress, log }: Roll
   log(`Committee: ${committee?.map(v => v.toString()).join(', ')}`);
   const archive = await rollup.archive();
   log(`Archive: ${archive}`);
-  const epochNum = await rollup.getEpochNumber();
+  const epochNum = await rollup.getCurrentEpochNumber();
   log(`Current epoch: ${epochNum}`);
   const slot = await rollup.getSlotNumber();
   log(`Current slot: ${slot}`);

package/src/config/cached_fetch.ts

@@ -0,0 +1,67 @@
+import { createLogger } from '@aztec/aztec.js';
+
+import { mkdir, readFile, stat, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+
+export interface CachedFetchOptions {
+  /** Cache duration in milliseconds */
+  cacheDurationMs: number;
+  /** The cache file */
+  cacheFile?: string;
+}
+
+/**
+ * Fetches data from a URL with file-based caching support.
+ * This utility can be used by both remote config and bootnodes fetching.
+ *
+ * @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
+ */
+export async function cachedFetch<T = any>(
+  url: string,
+  options: CachedFetchOptions,
+  fetch = globalThis.fetch,
+  log = createLogger('cached_fetch'),
+): Promise<T | undefined> {
+  const { cacheDurationMs, cacheFile } = options;
+
+  // Try to read from cache first
+  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;
+      }
+    }
+  } catch {
+    log.trace('Failed to read data from cache');
+  }
+
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      log.warn(`Failed to fetch from ${url}: ${response.status} ${response.statusText}`);
+      return undefined;
+    }
+
+    const data = await response.json();
+
+    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 });
+    }
+
+    return data;
+  } catch (err) {
+    log.warn(`Failed to fetch from ${url}`, { err });
+    return undefined;
+  }
+}