@aztec/foundation 0.0.1-commit.3fd054f6 → 0.0.1-commit.431c48d

package/src/config/env_var.ts

@@ -1,17 +1,19 @@
 export type EnvVar =
   | 'REGISTRY_CONTRACT_ADDRESS'
   | 'FEE_ASSET_HANDLER_CONTRACT_ADDRESS'
-  | 'SLASH_FACTORY_CONTRACT_ADDRESS'
   | 'ACVM_BINARY_PATH'
   | 'ACVM_WORKING_DIRECTORY'
   | 'API_KEY'
   | 'API_PREFIX'
-  | 'ARCHIVER_MAX_LOGS'
   | 'ARCHIVER_POLLING_INTERVAL_MS'
+  | 'ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK'
   | 'ARCHIVER_URL'
   | 'ARCHIVER_VIEM_POLLING_INTERVAL_MS'
   | 'ARCHIVER_BATCH_SIZE'
+  | 'ARCHIVER_ORPHAN_PRUNE_NO_PROPOSAL_TOLERANCE'
+  | 'ARCHIVER_SKIP_ORPHAN_PROPOSED_BLOCK_PRUNING'
   | 'AZTEC_ADMIN_PORT'
+  | 'AZTEC_NODE_DEBUG'
   | 'AZTEC_ADMIN_API_KEY_HASH'
   | 'AZTEC_DISABLE_ADMIN_API_KEY'
   | 'AZTEC_RESET_ADMIN_API_KEY'
@@ -25,6 +27,7 @@ export type EnvVar =
   | 'BB_IVC_CONCURRENCY'
   | 'BB_CHONK_VERIFY_MAX_BATCH'
   | 'BB_CHONK_VERIFY_BATCH_CONCURRENCY'
+  | 'BB_DEBUG_OUTPUT_DIR'
   | 'BOOTSTRAP_NODES'
   | 'BLOB_ARCHIVE_API_URL'
   | 'BLOB_FILE_STORE_URLS'
@@ -74,11 +77,14 @@ export type EnvVar =
   | 'DEBUG'
   | 'DEBUG_P2P_DISABLE_COLOCATION_PENALTY'
   | 'ENABLE_PROVER_NODE'
+  | 'USE_AUTOMINE_SEQUENCER'
+  | 'AUTOMINE_ENABLE_PROVE_EPOCH'
   | 'ETHEREUM_HOSTS'
   | 'ETHEREUM_DEBUG_HOSTS'
   | 'ETHEREUM_ALLOW_NO_DEBUG_HOSTS'
   | 'FEE_RECIPIENT'
   | 'FORCE_COLOR'
+  | 'GOVERNANCE_PROPOSER_FORCE_PAYLOAD_VOTE'
   | 'GOVERNANCE_PROPOSER_PAYLOAD_ADDRESS'
   | 'KEY_STORE_DIRECTORY'
   | 'L1_CHAIN_ID'
@@ -94,14 +100,17 @@ export type EnvVar =
   | 'MNEMONIC'
   | 'NETWORK'
   | 'NETWORK_CONFIG_LOCATION'
-  | 'NO_PXE'
+  | 'ALLOW_OVERRIDING_NETWORK_CONFIG'
+  | 'USE_AWS_LOGGING'
   | 'USE_GCLOUD_LOGGING'
   | 'OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'
   | 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'
   | 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT'
   | 'OTEL_COLLECT_INTERVAL_MS'
+  | 'OTEL_BSP_MAX_QUEUE_SIZE'
   | 'OTEL_EXCLUDE_METRICS'
   | 'OTEL_INCLUDE_METRICS'
+  | 'OTEL_MIN_TRACE_DURATION_MS'
   | 'OTEL_EXPORT_TIMEOUT_MS'
   | 'PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'
   | 'PUBLIC_OTEL_INCLUDE_METRICS'
@@ -112,7 +121,6 @@ export type EnvVar =
   | 'P2P_BATCH_TX_REQUESTER_TX_BATCH_SIZE'
   | 'P2P_BATCH_TX_REQUESTER_BAD_PEER_THRESHOLD'
   | 'P2P_BLOCK_CHECK_INTERVAL_MS'
-  | 'P2P_SLOT_CHECK_INTERVAL_MS'
   | 'P2P_BLOCK_REQUEST_BATCH_SIZE'
   | 'P2P_BOOTSTRAP_NODE_ENR_VERSION_CHECK'
   | 'P2P_BOOTSTRAP_NODES_AS_FULL_PEERS'
@@ -130,12 +138,16 @@ export type EnvVar =
   | 'P2P_GOSSIPSUB_TX_INVALID_MESSAGE_DELIVERIES_DECAY'
   | 'P2P_GOSSIPSUB_TX_INVALID_MESSAGE_DELIVERIES_WEIGHT'
   | 'P2P_GOSSIPSUB_TX_TOPIC_WEIGHT'
+  | 'P2P_HEALTH_MIN_PEERS'
   | 'P2P_L2_QUEUE_SIZE'
+  | 'P2P_MAX_GOSSIP_CLOCK_DISPARITY_MS'
   | 'P2P_MAX_PEERS'
+  | 'P2P_PEER_BAN_DURATION_SECONDS'
   | 'P2P_PEER_CHECK_INTERVAL_MS'
   | 'P2P_PEER_FAILED_BAN_TIME_MS'
   | 'P2P_PEER_PENALTY_VALUES'
   | 'P2P_QUERY_FOR_IP'
+  | 'P2P_PUBLIC_IP_SERVICES'
   | 'P2P_REQRESP_INDIVIDUAL_REQUEST_TIMEOUT_MS'
   | 'P2P_REQRESP_DIAL_TIMEOUT_MS'
   | 'P2P_REQRESP_OVERALL_REQUEST_TIMEOUT_MS'
@@ -157,7 +169,10 @@ export type EnvVar =
   | 'P2P_DROP_TX_CHANCE'
   | 'P2P_TX_POOL_DELETE_TXS_AFTER_REORG'
   | 'P2P_MIN_TX_POOL_AGE_MS'
+  | 'P2P_MISSING_TX_COLLECTION_DEADLINE_SLOTS'
   | 'P2P_RPC_PRICE_BUMP_PERCENTAGE'
+  | 'P2P_KEEP_FINALIZED_TXS_FOR_SLOTS'
+  | 'P2P_TX_VALIDATION_CACHE_SIZE'
   | 'DEBUG_P2P_INSTRUMENT_MESSAGES'
   | 'PEER_ID_PRIVATE_KEY'
   | 'PEER_ID_PRIVATE_KEY_PATH'
@@ -179,6 +194,7 @@ export type EnvVar =
   | 'PROVER_FAILED_PROOF_STORE'
   | 'PROVER_NODE_FAILED_EPOCH_STORE'
   | 'PROVER_NODE_DISABLE_PROOF_PUBLISH'
+  | 'PROVER_NODE_PROOF_SUBMISSION_TARGET_ADDRESS'
   | 'PROVER_ID'
   | 'PROVER_NODE_POLLING_INTERVAL_MS'
   | 'PROVER_NODE_MAX_PENDING_JOBS'
@@ -197,17 +213,27 @@ export type EnvVar =
   | 'PROVER_TEST_DELAY_MS'
   | 'PROVER_TEST_DELAY_TYPE'
   | 'PROVER_TEST_VERIFICATION_DELAY_MS'
+  | 'PXE_AUTO_SYNC'
+  | 'PXE_CONCURRENT_CONTRACT_SYNC_ENABLED'
   | 'PXE_L2_BLOCK_BATCH_SIZE'
   | 'PXE_PROVER_ENABLED'
   | 'PXE_SYNC_CHAIN_TIP'
   | 'RPC_MAX_BATCH_SIZE'
   | 'RPC_MAX_BODY_SIZE'
+  | 'RPC_HTTP_HEADERS_TIMEOUT_MS'
+  | 'RPC_HTTP_KEEP_ALIVE_TIMEOUT_MS'
+  | 'RPC_CORS_ALLOW_ANY_ORIGIN'
+  | 'RPC_CORS_ALLOWED_HEADERS'
+  | 'RPC_CORS_ALLOWED_ORIGINS'
   | 'RPC_SIMULATE_PUBLIC_MAX_GAS_LIMIT'
   | 'RPC_SIMULATE_PUBLIC_MAX_DEBUG_LOG_MEMORY_READS'
+  | 'RPC_UNSEEN_BLOCK_BY_NUMBER_WAIT_MS'
+  | 'RPC_UNSEEN_BLOCK_BY_HASH_WAIT_MS'
+  | 'OFFENSE_COLLECTION_ENABLED'
   | 'SENTINEL_ENABLED'
   | 'SENTINEL_HISTORY_LENGTH_IN_EPOCHS'
-  | 'SENTINEL_HISTORIC_PROVEN_PERFORMANCE_LENGTH_IN_EPOCHS'
-  | 'SEQ_ENABLE_PROPOSER_PIPELINING'
+  | 'SENTINEL_HISTORIC_EPOCH_PERFORMANCE_LENGTH_IN_EPOCHS'
+  | 'SENTINEL_EPOCH_END_BUFFER_SLOTS'
   | 'SEQ_MAX_TX_PER_BLOCK'
   | 'SEQ_MAX_TX_PER_CHECKPOINT'
   | 'SEQ_MIN_TX_PER_BLOCK'
@@ -215,39 +241,46 @@ export type EnvVar =
   | 'SEQ_MAX_DA_BLOCK_GAS'
   | 'SEQ_MAX_L2_BLOCK_GAS'
   | 'SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER'
+  | 'SEQ_PER_BLOCK_DA_ALLOCATION_MULTIPLIER'
   | 'SEQ_REDISTRIBUTE_CHECKPOINT_BUDGET'
   | 'SEQ_PUBLISHER_PRIVATE_KEY'
   | 'SEQ_PUBLISHER_PRIVATE_KEYS'
   | 'SEQ_PUBLISHER_ADDRESSES'
   | 'SEQ_PUBLISHER_ALLOW_INVALID_STATES'
   | 'SEQ_PUBLISHER_FORWARDER_ADDRESS'
+  | 'SEQ_PUBLISHER_PREVIOUS_L1_BLOCK_WAIT_TIMEOUT_MS'
+  | 'SEQ_PUBLISHER_PREVIOUS_L1_BLOCK_WAIT_POLL_INTERVAL_MS'
   | 'PUBLISHER_FUNDING_THRESHOLD'
   | 'PUBLISHER_FUNDING_AMOUNT'
   | 'SEQ_POLLING_INTERVAL_MS'
-  | 'SEQ_ENFORCE_TIME_TABLE'
   | 'SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT'
   | 'SEQ_ATTESTATION_PROPAGATION_TIME'
+  | 'SEQ_CHECKPOINT_PROPOSAL_PREPARE_TIME'
+  | 'CHECKPOINT_PROPOSAL_SYNC_GRACE_SECONDS'
+  | 'SEQ_MIN_BLOCK_DURATION'
   | 'SEQ_BLOCK_DURATION_MS'
+  | 'SEQ_LAST_BLOCK_DURATION_MS'
   | 'SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT'
   | 'SEQ_BUILD_CHECKPOINT_IF_EMPTY'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_COMMITTEE_MEMBER'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_NON_COMMITTEE_MEMBER'
   | 'SEQ_SKIP_CHECKPOINT_PUBLISH_PERCENT'
-  | 'SLASH_MIN_PENALTY_PERCENTAGE'
-  | 'SLASH_MAX_PENALTY_PERCENTAGE'
+  | 'SEQ_MIN_PEERS_TO_PROPOSE'
   | 'SLASH_VALIDATORS_ALWAYS'
   | 'SLASH_VALIDATORS_NEVER'
-  | 'SLASH_PRUNE_PENALTY'
   | 'SLASH_DATA_WITHHOLDING_PENALTY'
+  | 'SLASH_DATA_WITHHOLDING_TOLERANCE_SLOTS'
   | 'SLASH_INACTIVITY_PENALTY'
   | 'SLASH_INACTIVITY_TARGET_PERCENTAGE'
   | 'SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD'
   | 'SLASH_INVALID_BLOCK_PENALTY'
+  | 'SLASH_INVALID_CHECKPOINT_PROPOSAL_PENALTY'
   | 'SLASH_DUPLICATE_PROPOSAL_PENALTY'
   | 'SLASH_DUPLICATE_ATTESTATION_PENALTY'
   | 'SLASH_OVERRIDE_PAYLOAD'
   | 'SLASH_PROPOSE_INVALID_ATTESTATIONS_PENALTY'
-  | 'SLASH_ATTEST_DESCENDANT_OF_INVALID_PENALTY'
+  | 'SLASH_PROPOSE_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS_PENALTY'
+  | 'SLASH_ATTEST_INVALID_CHECKPOINT_PROPOSAL_PENALTY'
   | 'SLASH_UNKNOWN_PENALTY'
   | 'SLASH_GRACE_PERIOD_L2_SLOTS'
   | 'SLASH_OFFENSE_EXPIRATION_ROUNDS'
@@ -258,28 +291,20 @@ export type EnvVar =
   | 'SYNC_SNAPSHOTS_URL'
   | 'TELEMETRY'
   | 'TEST_ACCOUNTS'
+  | 'TEST_PRELOAD_STANDARD_CONTRACTS'
   | 'SPONSORED_FPC'
   | 'PREFUND_ADDRESSES'
   | 'TX_COLLECTION_FAST_NODES_TIMEOUT_BEFORE_REQ_RESP_MS'
-  | 'TX_COLLECTION_SLOW_NODES_INTERVAL_MS'
-  | 'TX_COLLECTION_SLOW_REQ_RESP_INTERVAL_MS'
-  | 'TX_COLLECTION_SLOW_REQ_RESP_TIMEOUT_MS'
-  | 'TX_COLLECTION_RECONCILE_INTERVAL_MS'
-  | 'TX_COLLECTION_DISABLE_SLOW_DURING_FAST_REQUESTS'
   | 'TX_COLLECTION_FAST_NODE_INTERVAL_MS'
   | 'TX_COLLECTION_FAST_MAX_PARALLEL_REQUESTS_PER_NODE'
   | 'TX_COLLECTION_NODE_RPC_MAX_BATCH_SIZE'
   | 'TX_COLLECTION_NODE_RPC_URLS'
   | 'TX_COLLECTION_MISSING_TXS_COLLECTOR_TYPE'
   | 'TX_COLLECTION_FILE_STORE_URLS'
-  | 'TX_COLLECTION_FILE_STORE_SLOW_DELAY_MS'
   | 'TX_COLLECTION_FILE_STORE_FAST_DELAY_MS'
   | 'TX_COLLECTION_FILE_STORE_FAST_WORKER_COUNT'
-  | 'TX_COLLECTION_FILE_STORE_SLOW_WORKER_COUNT'
   | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_BASE_MS'
-  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_BASE_MS'
   | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_MAX_MS'
-  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_MAX_MS'
   | 'TX_FILE_STORE_URL'
   | 'TX_FILE_STORE_UPLOAD_CONCURRENCY'
   | 'TX_FILE_STORE_MAX_QUEUE_SIZE'
@@ -295,7 +320,6 @@ export type EnvVar =
   | 'VALIDATOR_MAX_TX_PER_CHECKPOINT'
   | 'VALIDATOR_PRIVATE_KEYS'
   | 'VALIDATOR_PRIVATE_KEY'
-  | 'VALIDATOR_REEXECUTE'
   | 'VALIDATOR_ADDRESSES'
   | 'ROLLUP_VERSION'
   | 'WS_BLOCK_CHECK_INTERVAL_MS'
@@ -328,7 +352,7 @@ export type EnvVar =
   | 'AZTEC_SLASH_AMOUNT_SMALL'
   | 'AZTEC_SLASH_AMOUNT_MEDIUM'
   | 'AZTEC_SLASH_AMOUNT_LARGE'
-  | 'AZTEC_SLASHER_FLAVOR'
+  | 'AZTEC_SLASHER_ENABLED'
   | 'AZTEC_GOVERNANCE_PROPOSER_QUORUM'
   | 'AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE'
   | 'AZTEC_GOVERNANCE_VOTING_DURATION'
@@ -357,19 +381,23 @@ export type EnvVar =
   | 'K8S_POD_NAME'
   | 'K8S_POD_UID'
   | 'K8S_NAMESPACE_NAME'
-  | 'ENABLE_VERSION_CHECK'
-  | 'VALIDATOR_REEXECUTE_DEADLINE_MS'
+  | 'ENABLE_AUTO_SHUTDOWN'
   | 'WEB3_SIGNER_URL'
   | 'SKIP_ARCHIVER_INITIAL_SYNC'
   | 'BLOB_ALLOW_EMPTY_SOURCES'
+  | 'BLOB_PREFER_FILESTORES'
+  | 'BLOB_FILE_STORE_TIMEOUT_MS'
   | 'FISHERMAN_MODE'
   | 'MAX_ALLOWED_ETH_CLIENT_DRIFT_SECONDS'
+  | 'MAX_BLOCKS_PER_CHECKPOINT'
   | 'LEGACY_BLS_CLI'
   | 'DEBUG_FORCE_TX_PROOF_VERIFICATION'
+  | 'VALIDATOR_ALLOW_EPHEMERAL_SIGNING_PROTECTION'
   | 'VALIDATOR_HA_SIGNING_ENABLED'
   | 'VALIDATOR_HA_NODE_ID'
   | 'VALIDATOR_HA_POLLING_INTERVAL_MS'
   | 'VALIDATOR_HA_SIGNING_TIMEOUT_MS'
+  | 'VALIDATOR_SIGNER_CALL_TIMEOUT_MS'
   | 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS'
   | 'VALIDATOR_HA_OLD_DUTIES_MAX_AGE_H'
   | 'VALIDATOR_HA_DATABASE_URL'

package/src/config/index.ts

@@ -10,14 +10,14 @@ export type { EnvVar, NetworkNames };
 export type { NetworkConfig, NetworkConfigMap } from './network_config.js';
 export { NetworkConfigMapSchema, NetworkConfigSchema } from './network_config.js';
 
-export interface ConfigMapping {
+export interface ConfigMapping<T> {
   env?: EnvVar;
-  parseEnv?: (val: string) => any;
-  defaultValue?: any;
+  /** Parse an env-var string into `T`. Throws on invalid input. */
+  parseEnv?: (val: string) => T;
+  defaultValue?: T;
   printDefault?: (val: any) => string;
   description: string;
   isBoolean?: boolean;
-  nested?: Record<string, ConfigMapping>;
   fallback?: EnvVar[];
   /**
    * List of deprecated env vars that are still supported but will log a warning.
@@ -30,7 +30,9 @@ export function isBooleanConfigValue<T>(obj: T, key: keyof T): boolean {
   return typeof obj[key] === 'boolean';
 }
 
-export type ConfigMappingsType<T> = Record<keyof T, ConfigMapping>;
+export type ConfigMappingsType<T> = {
+  [K in keyof T]-?: ConfigMapping<Required<T>[K]>;
+};
 
 /**
  * Shared utility function to get a value from environment variables with fallback support.
@@ -66,8 +68,8 @@ export function getValueFromEnvWithFallback<T>(
     }
   }
 
-  // Parse the value if needed
-  if (value !== undefined) {
+  // Parse the value if needed. Empty strings are treated as "not set".
+  if (value !== undefined && value !== '') {
     return parseFunc ? parseFunc(value) : (value as unknown as T);
   }
 
@@ -79,22 +81,20 @@ export function getConfigFromMappings<T>(configMappings: ConfigMappingsType<T>):
   const config = {} as T;
 
   for (const key in configMappings) {
-    const { env, parseEnv, defaultValue, nested, fallback, deprecatedFallback } = configMappings[key];
-    if (nested) {
-      (config as any)[key] = getConfigFromMappings(nested);
-    } else {
-      // Use the shared utility function
+    const { env, parseEnv, defaultValue, fallback, deprecatedFallback } = configMappings[key];
+    try {
       (config as any)[key] = getValueFromEnvWithFallback(env, parseEnv, defaultValue, fallback);
+    } catch (e: any) {
+      throw new Error(`Failed to parse config '${key}' (env: ${env ?? 'none'}): ${e.message}`);
+    }
 
-      // Check for deprecated env vars and warn if logger is set
-      if (deprecatedFallback?.length) {
-        const userLog = createConsoleLogger('[DEPRECATED]');
-        for (const { env: deprecatedEnv, message } of deprecatedFallback) {
-          if (process.env[deprecatedEnv]) {
-            const warningMessage =
-              message ?? `Environment variable ${deprecatedEnv} is deprecated. Please use ${env} instead.`;
-            userLog(warningMessage, { deprecatedEnvVar: deprecatedEnv, newEnvVar: env });
-          }
+    if (deprecatedFallback?.length) {
+      const userLog = createConsoleLogger('[DEPRECATED]');
+      for (const { env: deprecatedEnv, message } of deprecatedFallback) {
+        if (process.env[deprecatedEnv]) {
+          const warningMessage =
+            message ?? `Environment variable ${deprecatedEnv} is deprecated. Please use ${env} instead.`;
+          userLog(warningMessage, { deprecatedEnvVar: deprecatedEnv, newEnvVar: env });
         }
       }
     }
@@ -119,29 +119,37 @@ export function omitConfigMappings<T, K extends keyof T>(
 }
 
 /**
- * Generates parseEnv and default values for a numerical config value.
- * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
- * @returns Object with parseEnv and default values for a numerical config value
+ * Generates parseEnv and default values for an integer config value.
+ *
+ * The default is used only when the environment variable is unset or empty. A set-but-invalid
+ * value (non-numeric, fractional, or outside the safe-integer range) throws rather than silently
+ * falling back to the default.
+ * @param defaultVal - The default value to use when the environment variable is unset
+ * @returns Object with parseEnv and default values for an integer config value
  */
-export function numberConfigHelper(defaultVal: number): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function numberConfigHelper(defaultVal: number): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
-    parseEnv: (val: string) => safeParseNumber(val, defaultVal),
+    parseEnv: (val: string) => parseSafeInteger(val),
     defaultValue: defaultVal,
   };
 }
 
 /**
- * Generates parseEnv and default values for a numerical config value.
- * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
- * @returns Object with parseEnv and default values for a numerical config value
+ * Generates parseEnv and default values for a floating-point config value.
+ *
+ * The default is used only when the environment variable is unset or empty. A set-but-invalid
+ * value (not a finite number) throws rather than silently falling back to the default.
+ * @param defaultVal - The default value to use when the environment variable is unset
+ * @param validationFn - Optional extra validation applied to the parsed value; should throw on invalid input
+ * @returns Object with parseEnv and default values for a floating-point config value
  */
 export function floatConfigHelper(
   defaultVal: number,
   validationFn?: (val: number) => void,
-): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string): number => {
-      const parsed = safeParseFloat(val, defaultVal);
+      const parsed = parseFiniteNumber(val);
       validationFn?.(parsed);
       return parsed;
     },
@@ -150,12 +158,17 @@ export function floatConfigHelper(
 }
 
 /**
- * Parses an environment variable to a 0-1 percentage value
+ * Generates parseEnv and default values for a 0-1 percentage config value.
+ *
+ * The default is used only when the environment variable is unset or empty. A set-but-invalid
+ * value (not a finite number, or outside the 0-1 range) throws rather than silently falling back
+ * to the default.
+ * @param defaultVal - The default value to use when the environment variable is unset
  */
-export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string): number => {
-      const parsed = safeParseFloat(val, defaultVal);
+      const parsed = parseFiniteNumber(val);
       if (parsed < 0 || parsed > 1) {
         throw new TypeError(`Invalid percentage value: ${parsed} should be between 0 and 1`);
       }
@@ -171,12 +184,13 @@ export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping,
  * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
  * @returns Object with parseEnv and default values for a numerical config value
  */
-export function bigintConfigHelper(defaultVal?: bigint): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function bigintConfigHelper(defaultVal: bigint): Pick<ConfigMapping<bigint>, 'parseEnv' | 'defaultValue'>;
+export function bigintConfigHelper(): Pick<ConfigMapping<bigint | undefined>, 'parseEnv' | 'defaultValue'>;
+export function bigintConfigHelper(
+  defaultVal?: bigint,
+): Pick<ConfigMapping<bigint | undefined>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string) => {
-      if (val === '') {
-        return defaultVal;
-      }
       // Handle scientific notation (e.g. "1e+23", "2E23") which BigInt() doesn't accept directly.
       // We parse it losslessly using bigint arithmetic instead of going through float64.
       if (/[eE]/.test(val)) {
@@ -200,32 +214,31 @@ export function bigintConfigHelper(defaultVal?: bigint): Pick<ConfigMapping, 'pa
 
 /**
  * Generates parseEnv for an optional numerical config value.
+ * Empty strings are already handled by getValueFromEnvWithFallback.
  */
-export function optionalNumberConfigHelper(): Pick<ConfigMapping, 'parseEnv'> {
+export function optionalNumberConfigHelper(): Pick<ConfigMapping<number>, 'parseEnv'> {
   return {
-    parseEnv: (val: string | undefined) => {
-      if (val !== undefined && val.length > 0) {
-        const parsedValue = parseInt(val);
-        return Number.isSafeInteger(parsedValue) ? parsedValue : undefined;
-      }
-      return undefined;
-    },
+    parseEnv: (val: string) => parseSafeInteger(val),
   };
 }
 
 /** Generates parseEnv for an enum-like config value. */
+export function enumConfigHelper<T extends string>(
+  values: T[],
+  defaultValue: NoInfer<T>,
+): Pick<ConfigMapping<T>, 'parseEnv' | 'defaultValue'>;
+export function enumConfigHelper<T extends string>(
+  values: T[],
+): Pick<ConfigMapping<T | undefined>, 'parseEnv' | 'defaultValue'>;
 export function enumConfigHelper<T extends string>(
   values: T[],
   defaultValue?: NoInfer<T>,
-): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+): Pick<ConfigMapping<T | undefined>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string) => {
-      const sanitizedVal = (val ?? '').trim().toLowerCase();
-      if (values.includes(sanitizedVal as T)) {
-        return sanitizedVal as T;
-      }
-      if (!val && defaultValue) {
-        return defaultValue;
+      const sanitizedVal = val.trim().toLowerCase();
+      if (values.some(v => v.toLowerCase() === sanitizedVal)) {
+        return values.find(v => v.toLowerCase() === sanitizedVal)!;
       }
       throw new Error(`Invalid config value '${val}' (must be one of ${values.join(', ')})`);
     },
@@ -240,7 +253,9 @@ export function enumConfigHelper<T extends string>(
  */
 export function booleanConfigHelper(
   defaultVal = false,
-): Required<Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & { parseVal: (val: string) => boolean }> {
+): Required<
+  Pick<ConfigMapping<boolean>, 'parseEnv' | 'defaultValue' | 'isBoolean'> & { parseVal: (val: string) => boolean }
+> {
   const parse = (val: string | boolean) => (typeof val === 'boolean' ? val : parseBooleanEnv(val));
   return {
     parseEnv: parse,
@@ -250,116 +265,122 @@ export function booleanConfigHelper(
   };
 }
 
-export function secretValueConfigHelper<T>(parse: (val: string | undefined) => T): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<T>;
-  }
-> {
+export function secretValueConfigHelper<T>(parse: (val: string | undefined) => T): Pick<
+  ConfigMapping<SecretValue<T>>,
+  'parseEnv' | 'defaultValue'
+> & {
+  parseVal: (val: string) => SecretValue<T>;
+} {
   const wrap = (val: string) => new SecretValue(parse(val));
   return {
     parseEnv: wrap,
     parseVal: wrap,
     defaultValue: new SecretValue(parse(undefined)),
-    isBoolean: true,
   };
 }
 
 export { parseBooleanEnv } from './parse-env.js';
 
-export function secretStringConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string | undefined>;
-  }
->;
-export function secretStringConfigHelper(defaultValue: string): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string>;
-  }
->;
-export function secretStringConfigHelper(defaultValue?: string): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string | typeof defaultValue>;
-  }
-> {
+export function secretStringConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: undefined;
+};
+export function secretStringConfigHelper(defaultValue: string): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: SecretValue<string>;
+};
+export function secretStringConfigHelper(defaultValue?: string): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: SecretValue<string> | undefined;
+} {
   const parse = (val: string) => new SecretValue(val);
   return {
     parseEnv: parse,
     parseVal: parse,
     defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
   };
 }
 
-export function secretFrConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr | undefined>;
-  }
->;
-export function secretFrConfigHelper(defaultValue: Fr): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr>;
-  }
->;
-export function secretFrConfigHelper(defaultValue?: Fr): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr | typeof defaultValue>;
-  }
-> {
+export function secretFrConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: undefined;
+};
+export function secretFrConfigHelper(defaultValue: Fr): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: SecretValue<Fr>;
+};
+export function secretFrConfigHelper(defaultValue?: Fr): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: SecretValue<Fr> | undefined;
+} {
   const parse = (val: string) => new SecretValue(Fr.fromHexString(val));
   return {
     parseEnv: parse,
     parseVal: parse,
     defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
   };
 }
 
-export function secretFqConfigHelper(defaultValue: Fq): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq>;
-  }
->;
-export function secretFqConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq | undefined>;
-  }
->;
-export function secretFqConfigHelper(defaultValue?: Fq): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq | typeof defaultValue>;
-  }
-> {
+export function secretFqConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: undefined;
+};
+export function secretFqConfigHelper(defaultValue: Fq): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: SecretValue<Fq>;
+};
+export function secretFqConfigHelper(defaultValue?: Fq): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: SecretValue<Fq> | undefined;
+} {
   const parse = (val: string) => new SecretValue(Fq.fromHexString(val));
   return {
     parseEnv: parse,
     parseVal: parse,
-    defaultValue: typeof defaultValue !== 'undefined' ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
+    defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
   };
 }
 
 /**
- * Safely parses a number from a string.
- * If the value is not a number or is not a safe integer, the default value is returned.
+ * Parses a string into a safe integer, throwing if the value is numeric but not an integer.
+ *
+ * Unlike `parseInt`, this does not silently truncate decimals: `'0.8'` throws rather than
+ * becoming `0`. A fractional value indicates the caller intended a non-integer where only
+ * integers are supported (use `floatConfigHelper`/`percentageConfigHelper` for those).
  * @param value - The string value to parse
- * @param defaultValue - The default value to return
- * @returns Either parsed value or default value
+ * @returns The parsed integer value
  */
-function safeParseNumber(value: string, defaultValue: number): number {
-  const parsedValue = parseInt(value, 10);
-  return Number.isSafeInteger(parsedValue) ? parsedValue : defaultValue;
+function parseSafeInteger(value: string): number {
+  const parsedValue = parseFloat(value);
+  if (!Number.isSafeInteger(parsedValue)) {
+    throw new Error(`Invalid integer config value '${value}'; expected a whole number`);
+  }
+  return parsedValue;
 }
 
 /**
- * Safely parses a floating point number from a string.
- * If the value is not a number, the default value is returned.
+ * Parses a string into a finite floating-point number, throwing if the value is not a finite number.
+ *
+ * Invalid input (e.g. `'abc'`, or an overflow to `Infinity`) throws rather than being silently
+ * swallowed, so a misconfigured value fails loudly instead of falling back to the config default.
  * @param value - The string value to parse
- * @param defaultValue - The default value to return
- * @returns Either parsed value or default value
+ * @returns The parsed number
  */
-function safeParseFloat(value: string, defaultValue: number): number {
+function parseFiniteNumber(value: string): number {
   const parsedValue = parseFloat(value);
-  return Number.isNaN(parsedValue) ? defaultValue : parsedValue;
+  if (!Number.isFinite(parsedValue)) {
+    throw new Error(`Invalid number config value '${value}'`);
+  }
+  return parsedValue;
 }
 
 /**