feat(config): wire startup through resolveConfig

yarn-project/archiver/src/config.ts

@@ -4,8 +4,8 @@ import { type L1ReaderConfig, l1ReaderConfigMappings } from '@aztec/ethereum/l1-
 import {
   type ConfigMappingsType,
   booleanConfigHelper,
+  buildConfigFromEnv,
   composeConfigMappings,
-  getConfigFromMappings,
   numberConfigHelper,
   optionalNumberConfigHelper,
 } from '@aztec/foundation/config';
@@ -94,7 +94,7 @@ export const archiverConfigMappings: ConfigMappingsType<ArchiverConfig> = compos
  * @returns The archiver configuration.
  */
 export function getArchiverConfigFromEnv(): ArchiverConfig {
-  return getConfigFromMappings<ArchiverConfig>(archiverConfigMappings);
+  return buildConfigFromEnv<ArchiverConfig>(archiverConfigMappings);
 }
 
 /** Extracts the archiver-specific configuration from the full ArchiverConfig */

yarn-project/aztec-node/src/aztec-node/config.ts

@@ -3,8 +3,8 @@ import type { GenesisStateConfig } from '@aztec/ethereum/config';
 import {
   type ConfigMappingsType,
   booleanConfigHelper,
+  buildConfigFromEnv,
   composeConfigMappings,
-  getConfigFromMappings,
 } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import {
@@ -97,7 +97,7 @@ export const aztecNodeConfigMappings: ConfigMappingsType<AztecNodeConfig> = comp
  * @returns A valid aztec node config.
  */
 export function getConfigEnvVars(): AztecNodeConfig {
-  return getConfigFromMappings<AztecNodeConfig>(aztecNodeConfigMappings);
+  return buildConfigFromEnv<AztecNodeConfig>(aztecNodeConfigMappings);
 }
 
 type ConfigRequiredToBuildKeyStore = SequencerClientConfig & SharedNodeConfig & ValidatorClientConfig;

yarn-project/aztec/package.json

@@ -67,6 +67,7 @@
     "commander": "^12.1.0",
     "koa": "^2.16.1",
     "koa-router": "^13.1.1",
+    "lodash.kebabcase": "^4.1.1",
     "viem": "npm:@aztec/viem@2.38.2"
   },
   "files": [
@@ -80,6 +81,7 @@
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/koa": "^2.15.0",
+    "@types/lodash.kebabcase": "^4",
     "@typescript/native-preview": "7.0.0-dev.20260113.1",
     "jest": "^30.0.0",
     "ts-node": "^10.9.1",

yarn-project/aztec/src/bin/index.ts

@@ -2,14 +2,11 @@
 //
 import { injectCommands as injectBuilderCommands } from '@aztec/builder';
 import { injectCommands as injectAztecNodeCommands } from '@aztec/cli/aztec_node';
-import { enrichEnvironmentWithChainName } from '@aztec/cli/config/chain';
-import { enrichEnvironmentWithNetworkConfig } from '@aztec/cli/config/network';
 import { injectCommands as injectContractCommands } from '@aztec/cli/contracts';
 import { injectCommands as injectInfrastructureCommands } from '@aztec/cli/infrastructure';
 import { injectCommands as injectL1Commands } from '@aztec/cli/l1';
 import { injectCommands as injectMiscCommands } from '@aztec/cli/misc';
 import { injectCommands as injectValidatorKeysCommands } from '@aztec/cli/validator_keys';
-import { getActiveNetworkName } from '@aztec/foundation/config';
 import { createConsoleLogger, createLogger } from '@aztec/foundation/log';
 import { getPackageVersion } from '@aztec/stdlib/update-checker';
 
@@ -20,8 +17,6 @@ import { injectMigrateCommand } from '../cli/cmds/migrate_ha_db.js';
 import { injectProfileCommand } from '../cli/cmds/profile.js';
 import { injectAztecCommands } from '../cli/index.js';
 
-const NETWORK_FLAG = 'network';
-
 const userLog = createConsoleLogger();
 const debugLogger = createLogger('cli');
 
@@ -33,20 +28,6 @@ async function main() {
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);
 
-  // Intercept the setting of a network and enrich the environment with defaults for that network
-  let networkValue: string | undefined;
-
-  const args = process.argv.slice(2);
-  const networkIndex = args.findIndex(arg => arg.startsWith(`--${NETWORK_FLAG}=`) || arg === `--${NETWORK_FLAG}`);
-
-  if (networkIndex !== -1) {
-    networkValue = args[networkIndex].split('=')[1] || args[networkIndex + 1];
-  }
-
-  const networkName = getActiveNetworkName(networkValue);
-  await enrichEnvironmentWithNetworkConfig(networkName);
-  enrichEnvironmentWithChainName(networkName);
-
   const cliVersion = getPackageVersion();
   let program = new Command('aztec');
   program.description('Aztec command line interface').version(cliVersion).enablePositionalOptions();

yarn-project/aztec/src/cli/api_config.ts

@@ -0,0 +1,64 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  composeConfigMappings,
+  numberConfigHelper,
+} from '@aztec/foundation/config';
+import { type NodeRPCConfig, nodeRpcConfigMappings } from '@aztec/stdlib/config';
+
+type OwnApiConfig = {
+  port: number;
+  adminPort: number;
+  adminApiKeyHash: string | undefined;
+  disableAdminApiKey: boolean;
+  resetAdminApiKey: boolean;
+  nodeDebug: boolean;
+  apiPrefix: string;
+};
+
+export type ApiConfig = OwnApiConfig & NodeRPCConfig;
+
+const ownApiConfigMappings: ConfigMappingsType<OwnApiConfig> = {
+  port: {
+    env: 'AZTEC_PORT',
+    description: 'Port to run the Aztec Services on',
+    ...numberConfigHelper(8080),
+  },
+  adminPort: {
+    env: 'AZTEC_ADMIN_PORT',
+    description: 'Port to run admin APIs of Aztec Services on',
+    ...numberConfigHelper(8880),
+  },
+  adminApiKeyHash: {
+    env: 'AZTEC_ADMIN_API_KEY_HASH',
+    description:
+      'SHA-256 hex hash of a pre-generated admin API key. When set, the node uses this hash for authentication instead of auto-generating a key.',
+  },
+  disableAdminApiKey: {
+    env: 'AZTEC_DISABLE_ADMIN_API_KEY',
+    description:
+      'Disable API key authentication on the admin RPC endpoint. By default, a key is auto-generated, displayed once, and its hash is persisted.',
+    ...booleanConfigHelper(false),
+  },
+  resetAdminApiKey: {
+    env: 'AZTEC_RESET_ADMIN_API_KEY',
+    description:
+      'Force-generate a new admin API key, replacing any previously persisted key hash. The new key is displayed once at startup.',
+    ...booleanConfigHelper(false),
+  },
+  nodeDebug: {
+    env: 'AZTEC_NODE_DEBUG',
+    description: 'Expose debug endpoints (e.g. mineBlock) on the main RPC port',
+    ...booleanConfigHelper(false),
+  },
+  apiPrefix: {
+    env: 'API_PREFIX',
+    description: 'Prefix for API routes on any service that is started',
+    defaultValue: '',
+  },
+};
+
+export const apiConfigMappings: ConfigMappingsType<ApiConfig> = composeConfigMappings(
+  ownApiConfigMappings,
+  nodeRpcConfigMappings,
+);

yarn-project/aztec/src/cli/aztec_start_action.ts

@@ -1,3 +1,4 @@
+import { getChainConfigLayer, getNetworkConfig } from '@aztec/cli/config';
 import { getActiveNetworkName } from '@aztec/foundation/config';
 import {
   type NamespacedApiHandlers,
@@ -8,14 +9,16 @@ import {
 import type { LogFn, Logger } from '@aztec/foundation/log';
 import type { ChainConfig } from '@aztec/stdlib/config';
 import { AztecNodeAdminApiSchema, AztecNodeApiSchema, AztecNodeDebugApiSchema } from '@aztec/stdlib/interfaces/client';
+import { dataConfigMappings } from '@aztec/stdlib/kv-store';
 import { getPackageVersion } from '@aztec/stdlib/update-checker';
 import { getVersioningMiddleware } from '@aztec/stdlib/versioning';
 import { getOtelJsonRpcPropagationMiddleware } from '@aztec/telemetry-client';
 
-import { createLocalNetwork } from '../local-network/index.js';
+import { type LocalNetworkConfig, createLocalNetwork, localNetworkConfigMappings } from '../local-network/index.js';
 import { github, splash } from '../splash.js';
 import { resolveAdminApiKey } from './admin_api_key_store.js';
-import { extractNamespacedOptions, installSignalHandlers } from './util.js';
+import { apiConfigMappings } from './api_config.js';
+import { createConfigResolver, installSignalHandlers } from './util.js';
 import { getVersions } from './versioning.js';
 
 export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logger) {
@@ -26,25 +29,43 @@ export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logg
   const packageVersion = getPackageVersion();
   let config: ChainConfig | undefined = undefined;
 
+  // Resolve network name from CLI flag or env, then fetch remote config and chain defaults.
+  const networkName = getActiveNetworkName(options.network);
+  // For caching the network config fetch, use whichever data directory is explicitly available
+  // before full resolution. The full resolver isn't built yet (it needs the network config).
+  const earlyDataDir = options.dataDirectory ?? process.env.DATA_DIRECTORY;
+  const cacheDir = earlyDataDir ? `${earlyDataDir}/cache` : undefined;
+  const remoteNetworkConfig = networkName !== 'local' ? await getNetworkConfig(networkName, cacheDir) : undefined;
+  const chainConfigLayer = getChainConfigLayer(networkName);
+  const resolveConfig = createConfigResolver(options, remoteNetworkConfig, chainConfigLayer);
+  const apiConfig = resolveConfig(apiConfigMappings);
+  const { dataDirectory: resolvedDataDirectory } = resolveConfig(dataConfigMappings);
+
   if (options.localNetwork) {
-    const localNetwork = extractNamespacedOptions(options, 'localNetwork');
     userLog(`${splash}\n${github}\n\n`);
     userLog(`Setting up Aztec local network ${packageVersion}, please stand by...`);
 
-    const { node, stop } = await createLocalNetwork(
-      {
-        l1Mnemonic: localNetwork.l1Mnemonic,
-        l1RpcUrls: options.l1RpcUrls,
-        testAccounts: localNetwork.testAccounts,
-        realProofs: false,
-        // Setting the epoch duration to 2 by default for local network. This allows the epoch to be "proven" faster, so
-        // the users can consume out hash without having to wait for a long time.
-        // Note: We are not proving anything in the local network (realProofs == false). But in `createLocalNetwork`,
-        // the EpochTestSettler will set the out hash to the outbox when an epoch is complete.
-        aztecEpochDuration: 2,
-      },
-      userLog,
-    );
+    // testAccounts lives on the genesis state mapping (default: false). For local network the default
+    // should be true, so override the mapping default unless the user explicitly opted in or out via
+    // env or CLI.
+    const testAccountsExplicit =
+      options['localNetwork.testAccounts'] !== undefined ||
+      (process.env.TEST_ACCOUNTS !== undefined && process.env.TEST_ACCOUNTS !== '');
+
+    const baseLocalConfig = resolveConfig(localNetworkConfigMappings, 'localNetwork');
+    const localNetworkConfig: LocalNetworkConfig = {
+      ...baseLocalConfig,
+      testAccounts: testAccountsExplicit ? baseLocalConfig.testAccounts : true,
+      // Local network always runs without real proofs.
+      realProofs: false,
+      // Setting the epoch duration to 2 by default for local network. This allows the epoch to be "proven" faster, so
+      // the users can consume out hash without having to wait for a long time.
+      // Note: We are not proving anything in the local network (realProofs == false). But in `createLocalNetwork`,
+      // the EpochTestSettler will set the out hash to the outbox when an epoch is complete.
+      aztecEpochDuration: 2,
+    };
+
+    const { node, stop } = await createLocalNetwork(localNetworkConfig, userLog);
 
     // Start Node and PXE JSON-RPC server
     signalHandlers.push(stop);
@@ -66,23 +87,30 @@ export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logg
 
     if (options.node) {
       const { startNode } = await import('./cmds/start_node.js');
-      const networkName = getActiveNetworkName(options.network);
-      ({ config } = await startNode(options, signalHandlers, services, adminServices, userLog, networkName));
-      if (options.nodeDebug && services.node) {
+      ({ config } = await startNode(
+        options,
+        signalHandlers,
+        services,
+        adminServices,
+        userLog,
+        networkName,
+        resolveConfig,
+      ));
+      if (apiConfig.nodeDebug && services.node) {
         services.nodeDebug = [services.node[0], AztecNodeDebugApiSchema];
       }
     } else if (options.bot) {
       const { startBot } = await import('./cmds/start_bot.js');
-      await startBot(options, signalHandlers, services, userLog);
+      await startBot(options, signalHandlers, services, userLog, resolveConfig);
     } else if (options.p2pBootstrap) {
       const { startP2PBootstrap } = await import('./cmds/start_p2p_bootstrap.js');
-      ({ config } = await startP2PBootstrap(options, signalHandlers, services, userLog));
+      ({ config } = await startP2PBootstrap(signalHandlers, services, userLog, resolveConfig));
     } else if (options.proverAgent) {
       const { startProverAgent } = await import('./cmds/start_prover_agent.js');
-      await startProverAgent(options, signalHandlers, services, userLog);
+      await startProverAgent(options, signalHandlers, services, userLog, resolveConfig);
     } else if (options.proverBroker) {
       const { startProverBroker } = await import('./cmds/start_prover_broker.js');
-      await startProverBroker(options, signalHandlers, services, userLog);
+      await startProverBroker(options, signalHandlers, services, userLog, resolveConfig);
     } else if (options.txe) {
       const { startTXE } = await import('./cmds/start_txe.js');
       await startTXE(options, signalHandlers, debugLogger);
@@ -105,10 +133,10 @@ export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logg
       http200OnError: false,
       log: debugLogger,
       middlewares: [getOtelJsonRpcPropagationMiddleware(), getVersioningMiddleware(versions, versioningOpts)],
-      maxBatchSize: options.rpcMaxBatchSize,
-      maxBodySizeBytes: options.rpcMaxBodySize,
+      maxBatchSize: apiConfig.rpcMaxBatchSize,
+      maxBodySizeBytes: apiConfig.rpcMaxBodySize,
     });
-    const { port } = await startHttpRpcServer(rpcServer, { port: options.port });
+    const { port } = await startHttpRpcServer(rpcServer, { apiPrefix: apiConfig.apiPrefix, port: apiConfig.port });
     debugLogger.info(`Aztec Server listening on port ${port}`, versions);
   }
 
@@ -119,10 +147,10 @@ export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logg
     // Resolve the admin API key (auto-generated and persisted, or opt-out)
     const apiKeyResolution = await resolveAdminApiKey(
       {
-        adminApiKeyHash: options.adminApiKeyHash,
-        disableAdminApiKey: options.disableAdminApiKey,
-        resetAdminApiKey: options.resetAdminApiKey,
-        dataDirectory: options.dataDirectory,
+        adminApiKeyHash: apiConfig.adminApiKeyHash,
+        disableAdminApiKey: apiConfig.disableAdminApiKey,
+        resetAdminApiKey: apiConfig.resetAdminApiKey,
+        dataDirectory: resolvedDataDirectory,
       },
       debugLogger,
     );
@@ -136,10 +164,10 @@ export async function aztecStart(options: any, userLog: LogFn, debugLogger: Logg
       http200OnError: false,
       log: debugLogger,
       middlewares: adminMiddlewares,
-      maxBatchSize: options.rpcMaxBatchSize,
-      maxBodySizeBytes: options.rpcMaxBodySize,
+      maxBatchSize: apiConfig.rpcMaxBatchSize,
+      maxBodySizeBytes: apiConfig.rpcMaxBodySize,
     });
-    const { port } = await startHttpRpcServer(rpcServer, { port: options.adminPort });
+    const { port } = await startHttpRpcServer(rpcServer, { apiPrefix: apiConfig.apiPrefix, port: apiConfig.adminPort });
     debugLogger.info(`Aztec Server admin API listening on port ${port}`, versions);
 
     // Display the API key after the server has started