@aztec/stdlib 0.0.1-commit.e6bd8901 → 0.0.1-commit.ec7ac5448

package/src/file-store/local.ts

@@ -1,15 +1,21 @@
 import { access, mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
-import type { FileStore } from './interface.js';
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
 
 export class LocalFileStore implements FileStore {
   constructor(private readonly basePath: string) {}
 
-  public async save(path: string, data: Buffer): Promise<string> {
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
     const fullPath = this.getFullPath(path);
     await mkdir(dirname(fullPath), { recursive: true });
-    await writeFile(fullPath, data);
+    const toWrite = opts?.compress ? await gzip(data) : data;
+    await writeFile(fullPath, toWrite);
     return `file://${fullPath}`;
   }
 
@@ -18,9 +24,13 @@ export class LocalFileStore implements FileStore {
     return this.save(destPath, data);
   }
 
-  public read(pathOrUrlStr: string): Promise<Buffer> {
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
     const fullPath = this.getFullPath(pathOrUrlStr);
-    return readFile(fullPath);
+    const data = await readFile(fullPath);
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/file-store/s3.ts

@@ -13,10 +13,14 @@ import { tmpdir } from 'os';
 import { basename, dirname, join } from 'path';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { createGzip } from 'zlib';
+import { promisify } from 'util';
+import { createGzip, gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
 import type { FileStore, FileStoreSaveOptions } from './interface.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 function normalizeBasePath(path: string): string {
   return path?.replace(/^\/+|\/+$/g, '') ?? '';
 }
@@ -52,7 +56,7 @@ export class S3FileStore implements FileStore {
     const key = this.getFullPath(path);
     const shouldCompress = !!opts.compress;
 
-    const body = shouldCompress ? (await import('zlib')).gzipSync(data) : data;
+    const body = shouldCompress ? await gzip(data) : data;
     const contentLength = body.length;
     const contentType = this.detectContentType(key, shouldCompress);
     const put = new PutObjectCommand({
@@ -60,6 +64,7 @@ export class S3FileStore implements FileStore {
       Key: key,
       Body: body,
       ContentType: contentType,
+      ContentEncoding: shouldCompress ? 'gzip' : undefined,
       CacheControl: opts.metadata?.['Cache-control'],
       Metadata: this.extractUserMetadata(opts.metadata),
       ContentLength: contentLength,
@@ -134,7 +139,11 @@ export class S3FileStore implements FileStore {
     for await (const chunk of stream) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
-    return Buffer.concat(chunks);
+    const buffer = Buffer.concat(chunks);
+    if (out.ContentEncoding === 'gzip') {
+      return await gunzip(buffer);
+    }
+    return buffer;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/gas/README.md

@@ -0,0 +1,123 @@
+# Aztec Gas and Fee Model
+
+The minimum fee per mana and its components are computed on L1 in
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol`. This document describes the
+formulas, the oracle lag/lifetime mechanism, and the TypeScript types in this directory.
+
+## Mana
+
+Aztec uses **mana** as its unit of work (analogous to Ethereum gas). Transactions consume
+mana in two dimensions: **DA** (data availability) and **L2** (execution). The total fee
+is `gasUsed * feePerMana` summed across both dimensions.
+
+## Fee Components
+
+The minimum fee per mana has four components:
+
+### Sequencer Cost
+
+L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
+
+```
+sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+              + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
+              / manaTarget
+```
+
+### Prover Cost
+
+L1 cost to verify an epoch proof, amortized over epoch duration and `manaTarget`, plus a
+governance-set proving cost that compensates for off-chain proof generation:
+
+```
+proverCost = (L1_GAS_PER_EPOCH_VERIFIED * baseFee / epochDuration) / manaTarget
+           + provingCostPerMana
+```
+
+### Congestion Cost
+
+An exponential surcharge when the network is congested (inspired by EIP-1559; the
+implementation uses the `fakeExponential` Taylor series approximation from EIP-4844):
+
+```
+baseCost          = sequencerCost + proverCost
+congestionCost    = baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER - baseCost
+```
+
+When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
+and congestion cost is zero.
+
+### Congestion Multiplier
+
+```
+excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+```
+
+Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+
+### Total
+
+```
+minFeePerMana = sequencerCost + proverCost + congestionCost
+```
+
+## L1 Gas Oracle: Lag and Lifetime
+
+The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
+(`pre` / `post`) system that smooths out L1 fee volatility.
+
+- **LAG = 2 slots** — when new L1 fees are observed, they activate `LAG` slots later
+  (`slotOfChange = currentSlot + LAG`). This gives mempool transactions time to land
+  before fees change.
+- **LIFETIME = 5 slots** — after an oracle update, the next update is rejected until
+  `slotOfChange + (LIFETIME - LAG)` = 3 more slots have passed. This rate-limits how
+  frequently L1 fee data can change.
+
+Fee resolution at a given timestamp:
+
+```
+if slot < slotOfChange  →  use pre  (old fees)
+else                    →  use post (new fees)
+```
+
+**Net effect**: L1 fee changes reach L2 with a 2-slot delay and can update at most once
+every 5 slots.
+
+## Fee Asset Price
+
+Fees are computed in ETH internally but converted to the fee asset (Fee Juice) via
+`ethPerFeeAsset` (1e12 precision). The price updates at most ±1% (±100 bps) per
+checkpoint:
+
+```
+newPrice = currentPrice * (10000 + modifierBps) / 10000
+```
+
+## Maximum Fee Change Rate
+
+| Component              | Bound                                                   |
+| ---------------------- | ------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)            |
+| Fee asset price        | ±1% per checkpoint                                      |
+| Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
+| Sequencer/prover costs | Scale linearly with L1 fees                             |
+
+## Key Constants
+
+| Constant                       | Value          |
+| ------------------------------ | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000      |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000    |
+| `BLOBS_PER_CHECKPOINT`          | 3            |
+| `BLOB_GAS_PER_BLOB`             | 2^17         |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9          |
+| `LAG`                           | 2 slots      |
+| `LIFETIME`                      | 5 slots      |
+
+## TypeScript Types
+
+- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`GasFees`** — per-unit price in each dimension (`feePerDaGas`, `feePerL2Gas`).
+- **`GasSettings`** — sender-chosen fee parameters: gas limits, teardown limits, max fees, priority fees.
+- **`GasUsed`** — actual consumption after execution. Note: `billedGas` uses the teardown gas *limit*, not actual usage.

package/src/gas/gas_fees.ts

@@ -15,6 +15,17 @@ import { z } from 'zod';
 import type { UInt128 } from '../types/shared.js';
 import type { GasDimensions } from './gas.js';
 
+/**
+ * Multiplies a bigint by a non-integer scalar and returns the ceiling of the result.
+ * Avoids converting the bigint to Number (which loses precision above 2^53) by instead
+ * scaling the scalar into a bigint rational and performing ceiling division.
+ */
+function bigintMulCeil(value: bigint, scalar: number): bigint {
+  const SCALE = 1_000_000_000_000n; // 1e12
+  const scaledScalar = BigInt(Math.round(scalar * 1e12));
+  return (value * scaledScalar + SCALE - 1n) / SCALE;
+}
+
 /** Gas prices for each dimension. */
 export class GasFees {
   public readonly feePerDaGas: UInt128;
@@ -56,8 +67,11 @@ export class GasFees {
       return this.clone();
     } else if (typeof scalar === 'bigint') {
       return new GasFees(this.feePerDaGas * scalar, this.feePerL2Gas * scalar);
+    } else if (Number.isInteger(scalar)) {
+      const s = BigInt(scalar);
+      return new GasFees(this.feePerDaGas * s, this.feePerL2Gas * s);
     } else {
-      return new GasFees(Number(this.feePerDaGas) * scalar, Number(this.feePerL2Gas) * scalar);
+      return new GasFees(bigintMulCeil(this.feePerDaGas, scalar), bigintMulCeil(this.feePerL2Gas, scalar));
     }
   }
 

package/src/gas/gas_settings.ts

@@ -1,10 +1,4 @@
-import {
-  DEFAULT_DA_GAS_LIMIT,
-  DEFAULT_L2_GAS_LIMIT,
-  DEFAULT_TEARDOWN_DA_GAS_LIMIT,
-  DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-  GAS_SETTINGS_LENGTH,
-} from '@aztec/constants';
+import { GAS_SETTINGS_LENGTH, MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT, MAX_PROCESSABLE_L2_GAS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
@@ -14,6 +8,21 @@ import { z } from 'zod';
 import { Gas, GasDimensions } from './gas.js';
 import { GasFees } from './gas_fees.js';
 
+/** Approximate max DA gas limit. Arbitrary, assuming 4 blocks per checkpoint — users should use gas estimation. */
+export const APPROXIMATE_MAX_DA_GAS_PER_BLOCK = Math.floor(MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT / 4);
+/** Fallback teardown L2 gas limit. Arbitrary — users should use gas estimation. */
+export const FALLBACK_TEARDOWN_L2_GAS_LIMIT = Math.floor(MAX_PROCESSABLE_L2_GAS / 8);
+/** Fallback teardown DA gas limit. Arbitrary — users should use gas estimation. */
+export const FALLBACK_TEARDOWN_DA_GAS_LIMIT = Math.floor(APPROXIMATE_MAX_DA_GAS_PER_BLOCK / 2);
+
+// For gas estimation, we use intentionally high limits above what the network can process,
+// so the simulation runs without hitting gas caps. Since teardown gas is counted towards total,
+// the total estimation limit is teardown + max processable.
+export const GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT = MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_L2_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT + MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT = MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+export const GAS_ESTIMATION_DA_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT + MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+
 // docs:start:gas_settings_vars
 /** Gas usage and fees limits set by the transaction sender for different dimensions and phases. */
 export class GasSettings {
@@ -95,18 +104,62 @@ export class GasSettings {
     return new GasSettings(Gas.empty(), Gas.empty(), GasFees.empty(), GasFees.empty());
   }
 
-  /** Default gas settings to use when user has not provided them. Requires explicit max fees per gas. */
-  static default(overrides: {
+  /**
+   * Fills in gas limits high enough for transactions to be included in most cases.
+   * gasLimits is set to the maximum the protocol allows; since teardown gas is reserved
+   * from gasLimits during private execution (see gas_meter.nr), the effective gas available
+   * for app logic will be gasLimits - teardownGasLimits - privateOverhead.
+   * The DA gas limit is set to an approximate max per block assuming 4 blocks per checkpoint,
+   * since using the maximum per checkpoint would cause nodes to reject transactions.
+   * These values won't work if:
+   *  - Teardown consumes more than the arbitrarily assigned fallback limits
+   *  - The rest of the transaction consumes more than the remaining gas after teardown
+   *  - The DA gas limit is too low for the transaction, while still within the checkpoint limit
+   */
+  static fallback(overrides: {
+    gasLimits?: Gas;
+    teardownGasLimits?: Gas;
+    maxFeesPerGas: GasFees;
+    maxPriorityFeesPerGas?: GasFees;
+  }) {
+    return GasSettings.from({
+      gasLimits: overrides.gasLimits ?? {
+        l2Gas: MAX_PROCESSABLE_L2_GAS,
+        daGas: APPROXIMATE_MAX_DA_GAS_PER_BLOCK,
+      },
+      teardownGasLimits: overrides.teardownGasLimits ?? {
+        l2Gas: FALLBACK_TEARDOWN_L2_GAS_LIMIT,
+        daGas: FALLBACK_TEARDOWN_DA_GAS_LIMIT,
+      },
+      maxFeesPerGas: overrides.maxFeesPerGas,
+      maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
+    });
+  }
+
+  /**
+   * Gas settings for simulation/estimation only.
+   * Since teardown gas is reserved upfront from gasLimits during private execution (see gas_meter.nr),
+   * the effective gas available for app logic is gasLimits - teardownGasLimits - privateOverhead.
+   * To ensure estimation never hits gas caps, we set both limits above what the protocol allows:
+   * teardown gets MAX_PROCESSABLE and gasLimits gets teardown + MAX_PROCESSABLE, so the full
+   * processable amount remains available for each phase independently. To be used in conjunction
+   * with skipTxValidation: true during public simulation, or the node would reject the transaction
+   * outright due to gas limits being above protocol max.
+   */
+  static forEstimation(overrides: {
     gasLimits?: Gas;
     teardownGasLimits?: Gas;
     maxFeesPerGas: GasFees;
     maxPriorityFeesPerGas?: GasFees;
   }) {
     return GasSettings.from({
-      gasLimits: overrides.gasLimits ?? { l2Gas: DEFAULT_L2_GAS_LIMIT, daGas: DEFAULT_DA_GAS_LIMIT },
+      gasLimits: overrides.gasLimits ?? {
+        l2Gas: GAS_ESTIMATION_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_DA_GAS_LIMIT,
+      },
       teardownGasLimits: overrides.teardownGasLimits ?? {
-        l2Gas: DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-        daGas: DEFAULT_TEARDOWN_DA_GAS_LIMIT,
+        l2Gas: GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT,
       },
       maxFeesPerGas: overrides.maxFeesPerGas,
       maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),

package/src/ha-signing/config.ts

@@ -0,0 +1,156 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+} from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+/**
+ * Base signing protection configuration shared by both HA (Postgres) and local (LMDB) signers.
+ */
+export interface BaseSignerConfig {
+  /** L1 contract addresses (rollup address required) */
+  l1Contracts: Pick<L1ContractAddresses, 'rollupAddress'>;
+  /** Unique identifier for this node */
+  nodeId: string;
+  /** How long to wait between polls when a duty is being signed (ms) */
+  pollingIntervalMs: number;
+  /** Maximum time to wait for a duty being signed to complete (ms) */
+  signingTimeoutMs: number;
+  /** Maximum age of a stuck duty in ms (defaults to 2x hardcoded Aztec slot duration if not set) */
+  maxStuckDutiesAgeMs?: number;
+  /** Optional: clean up old duties after this many hours (disabled if not set) */
+  cleanupOldDutiesAfterHours?: number;
+}
+
+export const baseSignerConfigMappings: ConfigMappingsType<BaseSignerConfig> = {
+  l1Contracts: {
+    description: 'L1 contract addresses (rollup address required)',
+    nested: {
+      rollupAddress: {
+        description: 'The Ethereum address of the rollup contract (must be set programmatically)',
+        parseEnv: (val: string) => EthAddress.fromString(val),
+      },
+    },
+  },
+  nodeId: {
+    env: 'VALIDATOR_HA_NODE_ID',
+    description: 'The unique identifier for this node',
+    defaultValue: '',
+  },
+  pollingIntervalMs: {
+    env: 'VALIDATOR_HA_POLLING_INTERVAL_MS',
+    description: 'The number of ms to wait between polls when a duty is being signed',
+    ...numberConfigHelper(100),
+  },
+  signingTimeoutMs: {
+    env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
+    description: 'The maximum time to wait for a duty being signed to complete',
+    ...numberConfigHelper(3_000),
+  },
+  maxStuckDutiesAgeMs: {
+    env: 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS',
+    description: 'The maximum age of a stuck duty in ms (defaults to 2x Aztec slot duration)',
+    ...optionalNumberConfigHelper(),
+  },
+  cleanupOldDutiesAfterHours: {
+    env: 'VALIDATOR_HA_OLD_DUTIES_MAX_AGE_H',
+    description: 'Optional: clean up old duties after this many hours (disabled if not set)',
+    ...optionalNumberConfigHelper(),
+  },
+};
+
+export const BaseSignerConfigSchema = z.object({
+  l1Contracts: z.object({ rollupAddress: z.instanceof(EthAddress) }),
+  nodeId: z.string(),
+  pollingIntervalMs: z.number().min(0),
+  signingTimeoutMs: z.number().min(0),
+  maxStuckDutiesAgeMs: z.number().min(0).optional(),
+  cleanupOldDutiesAfterHours: z.number().min(0).optional(),
+}) satisfies ZodFor<BaseSignerConfig>;
+
+/**
+ * Configuration for the Validator HA Signer.
+ *
+ * Extends BaseSignerConfig with a flag to enable HA mode and Postgres connection settings.
+ */
+export interface ValidatorHASignerConfig extends BaseSignerConfig {
+  /** Whether HA signing / slashing protection is enabled */
+  haSigningEnabled: boolean;
+  /**
+   * PostgreSQL connection string
+   * Format: postgresql://user:password@host:port/database
+   */
+  databaseUrl?: string;
+  /** Maximum number of clients in the pool (default: 10) */
+  poolMaxCount?: number;
+  /** Minimum number of clients in the pool (default: 0) */
+  poolMinCount?: number;
+  /** Idle timeout in milliseconds (default: 10000) */
+  poolIdleTimeoutMs?: number;
+  /** Connection timeout in milliseconds (default: 0, no timeout) */
+  poolConnectionTimeoutMs?: number;
+}
+
+export const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig> = {
+  ...baseSignerConfigMappings,
+  haSigningEnabled: {
+    env: 'VALIDATOR_HA_SIGNING_ENABLED',
+    description: 'Whether HA signing / slashing protection is enabled',
+    ...booleanConfigHelper(false),
+  },
+  databaseUrl: {
+    env: 'VALIDATOR_HA_DATABASE_URL',
+    description:
+      'PostgreSQL connection string for validator HA signer (format: postgresql://user:password@host:port/database)',
+  },
+  poolMaxCount: {
+    env: 'VALIDATOR_HA_POOL_MAX',
+    description: 'Maximum number of clients in the pool',
+    ...numberConfigHelper(10),
+  },
+  poolMinCount: {
+    env: 'VALIDATOR_HA_POOL_MIN',
+    description: 'Minimum number of clients in the pool',
+    ...numberConfigHelper(0),
+  },
+  poolIdleTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS',
+    description: 'Idle timeout in milliseconds',
+    ...numberConfigHelper(10_000),
+  },
+  poolConnectionTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS',
+    description: 'Connection timeout in milliseconds (0 means no timeout)',
+    ...numberConfigHelper(0),
+  },
+};
+
+export const defaultValidatorHASignerConfig: ValidatorHASignerConfig = getDefaultConfig(
+  validatorHASignerConfigMappings,
+);
+
+/**
+ * Returns the validator HA signer configuration from environment variables.
+ * Note: If an environment variable is not set, the default value is used.
+ * @returns The validator HA signer configuration.
+ */
+export function getConfigEnvVars(): ValidatorHASignerConfig {
+  return getConfigFromMappings<ValidatorHASignerConfig>(validatorHASignerConfigMappings);
+}
+
+export const ValidatorHASignerConfigSchema = BaseSignerConfigSchema.extend({
+  haSigningEnabled: z.boolean(),
+  databaseUrl: z.string().optional(),
+  poolMaxCount: z.number().min(0).optional(),
+  poolMinCount: z.number().min(0).optional(),
+  poolIdleTimeoutMs: z.number().min(0).optional(),
+  poolConnectionTimeoutMs: z.number().min(0).optional(),
+}) satisfies ZodFor<ValidatorHASignerConfig>;

package/src/ha-signing/index.ts

@@ -0,0 +1,27 @@
+export {
+  type BaseSignerConfig,
+  BaseSignerConfigSchema,
+  baseSignerConfigMappings,
+  type ValidatorHASignerConfig,
+  ValidatorHASignerConfigSchema,
+  defaultValidatorHASignerConfig,
+  getConfigEnvVars,
+  validatorHASignerConfigMappings,
+} from './config.js';
+export {
+  type LocalSignerConfig,
+  LocalSignerConfigSchema,
+  getLocalSignerConfigEnvVars,
+  localSignerConfigMappings,
+} from './local_config.js';
+export {
+  DutyType,
+  type BlockProposalSigningContext,
+  type HAProtectedSigningContext,
+  type NoHAProtectionSigningContext,
+  type OtherSigningContext,
+  type SigningContext,
+  type VoteSigningContext,
+  getBlockNumberFromSigningContext,
+  isHAProtectedContext,
+} from './types.js';

package/src/ha-signing/local_config.ts

@@ -0,0 +1,46 @@
+import { type ConfigMappingsType, getConfigFromMappings } from '@aztec/foundation/config';
+import { zodFor } from '@aztec/foundation/schemas';
+import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
+
+import { z } from 'zod';
+
+import { type BaseSignerConfig, BaseSignerConfigSchema, baseSignerConfigMappings } from './config.js';
+
+/**
+ * Configuration for local (single-node) slashing protection.
+ *
+ * Combines the base signing protection fields (shared with HA mode) with
+ * DataStoreConfig for the local LMDB backing store, plus a per-store map-size
+ * override. Used when HA signing is disabled.
+ */
+export type LocalSignerConfig = BaseSignerConfig &
+  DataStoreConfig & {
+    /** Maximum size of the local signing-protection LMDB store in KB. Overwrites the general dataStoreMapSizeKb. */
+    signingProtectionMapSizeKb?: number;
+  };
+
+export const localSignerConfigMappings: ConfigMappingsType<LocalSignerConfig> = {
+  ...baseSignerConfigMappings,
+  ...dataConfigMappings,
+  signingProtectionMapSizeKb: {
+    env: 'SIGNING_PROTECTION_MAP_SIZE_KB',
+    description:
+      'Maximum size of the local signing-protection LMDB store in KB. Overwrites the general dataStoreMapSizeKb.',
+    parseEnv: (val: string | undefined) => (val ? +val : undefined),
+  },
+};
+
+export const LocalSignerConfigSchema = zodFor<LocalSignerConfig>()(
+  BaseSignerConfigSchema.extend({
+    dataDirectory: z.string().optional(),
+    dataStoreMapSizeKb: z.number(),
+    signingProtectionMapSizeKb: z.number().optional(),
+  }),
+);
+
+/**
+ * Returns the local signer configuration from environment variables.
+ */
+export function getLocalSignerConfigEnvVars(): LocalSignerConfig {
+  return getConfigFromMappings<LocalSignerConfig>(localSignerConfigMappings);
+}

package/src/ha-signing/types.ts

@@ -0,0 +1,112 @@
+import {
+  BlockNumber,
+  type CheckpointNumber,
+  type IndexWithinCheckpoint,
+  type SlotNumber,
+} from '@aztec/foundation/branded-types';
+
+/**
+ * Type of validator duty being performed
+ */
+export enum DutyType {
+  BLOCK_PROPOSAL = 'BLOCK_PROPOSAL',
+  CHECKPOINT_PROPOSAL = 'CHECKPOINT_PROPOSAL',
+  ATTESTATION = 'ATTESTATION',
+  ATTESTATIONS_AND_SIGNERS = 'ATTESTATIONS_AND_SIGNERS',
+  GOVERNANCE_VOTE = 'GOVERNANCE_VOTE',
+  SLASHING_VOTE = 'SLASHING_VOTE',
+  AUTH_REQUEST = 'AUTH_REQUEST',
+  TXS = 'TXS',
+}
+
+/**
+ * Base context for signing operations
+ */
+interface BaseSigningContext {
+  /** Slot number for this duty */
+  slot: SlotNumber;
+  /**
+   * Block or checkpoint number for this duty.
+   * For block proposals, this is the block number.
+   * For checkpoint proposals, this is the checkpoint number.
+   */
+  blockNumber: BlockNumber | CheckpointNumber;
+}
+
+/**
+ * Signing context for block proposals.
+ * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
+ */
+export interface BlockProposalSigningContext extends BaseSigningContext {
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Signing context for non-block-proposal duties that require HA protection.
+ * blockIndexWithinCheckpoint is not applicable (internally always -1).
+ */
+export interface OtherSigningContext extends BaseSigningContext {
+  dutyType: DutyType.CHECKPOINT_PROPOSAL | DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ * blockNumber is not applicable (internally always 0).
+ */
+export interface VoteSigningContext {
+  slot: SlotNumber;
+  dutyType: DutyType.GOVERNANCE_VOTE | DutyType.SLASHING_VOTE;
+}
+
+/**
+ * Signing context for duties which don't require slot/blockNumber
+ * as they don't need HA protection (AUTH_REQUEST, TXS).
+ */
+export interface NoHAProtectionSigningContext {
+  dutyType: DutyType.AUTH_REQUEST | DutyType.TXS;
+}
+
+/**
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext = BlockProposalSigningContext | OtherSigningContext | VoteSigningContext;
+
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ * - Vote duties only need slot (blockNumber is internally 0)
+ * - AUTH_REQUEST and TXS duties don't need slot/blockNumber (no HA protection needed)
+ */
+export type SigningContext = HAProtectedSigningContext | NoHAProtectionSigningContext;
+
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */
+export function isHAProtectedContext(context: SigningContext): context is HAProtectedSigningContext {
+  return context.dutyType !== DutyType.AUTH_REQUEST && context.dutyType !== DutyType.TXS;
+}
+
+/**
+ * Gets the block number from a signing context.
+ * - Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE): returns BlockNumber(0)
+ * - Other duties: returns the blockNumber from the context
+ */
+export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber | CheckpointNumber {
+  // Check for duty types that have blockNumber
+  if (
+    context.dutyType === DutyType.BLOCK_PROPOSAL ||
+    context.dutyType === DutyType.CHECKPOINT_PROPOSAL ||
+    context.dutyType === DutyType.ATTESTATION ||
+    context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS
+  ) {
+    return context.blockNumber;
+  }
+  // Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE) don't have blockNumber
+  return BlockNumber(0);
+}