@aztec/stdlib 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/src/gas/tx_gas_limits.ts

@@ -0,0 +1,123 @@
+import {
+  NUM_BLOCK_END_BLOB_FIELDS,
+  NUM_CHECKPOINT_END_MARKER_FIELDS,
+  NUM_FIRST_BLOCK_END_BLOB_FIELDS,
+} from '@aztec/blob-lib/encoding';
+import {
+  BLOBS_PER_CHECKPOINT,
+  DA_GAS_PER_FIELD,
+  FIELDS_PER_BLOB,
+  MAX_PROCESSABLE_L2_GAS,
+  MAX_TX_DA_GAS,
+} from '@aztec/constants';
+
+import { type ProposerTimetableConfig, buildProposerTimetable } from '../timetable/build_proposer_timetable.js';
+import type { SlotTimingConstants } from '../timetable/consensus_timetable.js';
+import { Gas } from './gas.js';
+
+/**
+ * Network-minimum per-block budget multiplier for L2 gas and tx-count allocation. A block packer must
+ * grant at least this share of the even per-block split to a single tx; operators may configure a higher
+ * multiplier (more generous), but not a lower one — enforced at sequencer startup. Also used as the default
+ * for `SequencerConfig.perBlockAllocationMultiplier`.
+ */
+export const MIN_PER_BLOCK_ALLOCATION_MULTIPLIER = 1.2;
+
+/**
+ * Network-minimum per-block budget multiplier for DA gas, applied in place of the general
+ * {@link MIN_PER_BLOCK_ALLOCATION_MULTIPLIER}. Higher than the general multiplier so the largest tx we
+ * want to support — a maximal contract class registration (~97k DA gas) — fits a single block under v5
+ * mainnet geometry (72s slots, 6s blocks → 10 blocks per checkpoint). A builder may configure a higher
+ * multiplier but never a lower one. Also used as the default for
+ * `SequencerConfig.perBlockDAAllocationMultiplier`.
+ */
+export const MIN_PER_BLOCK_DA_ALLOCATION_MULTIPLIER = 1.5;
+
+/**
+ * The DA gas budget available to tx data within a checkpoint of `maxBlocksPerCheckpoint` blocks. This is the
+ * raw blob capacity (`BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB * DA_GAS_PER_FIELD`) minus the fields the blob
+ * encoding reserves for overhead that no tx pays DA gas for:
+ *
+ * - one checkpoint-end marker field (`NUM_CHECKPOINT_END_MARKER_FIELDS`),
+ * - the first block's block-end fields (`NUM_FIRST_BLOCK_END_BLOB_FIELDS`, 7), and
+ * - `NUM_BLOCK_END_BLOB_FIELDS` (6) for each of the `blocks - 1` subsequent blocks.
+ *
+ * Subtracting the overhead for every block (not just the first) keeps the network DA admission limit at or
+ * below the builder's first-block blob-field cap at every geometry. The builder is the MOST generous for the
+ * first block — it only reserves that block's own block-end overhead — so being conservative here (assuming
+ * the checkpoint is full of blocks, each spending its share) is what guarantees admitted ⇒ buildable: a tx
+ * admitted under this budget always fits the first block's blob-field cap, regardless of how many blocks the
+ * builder ends up packing.
+ *
+ * @param maxBlocksPerCheckpoint - Number of blocks the checkpoint may contain; clamped to at least 1.
+ */
+export function getDaCheckpointBudgetForTxs(maxBlocksPerCheckpoint: number): number {
+  const blocks = Math.max(1, maxBlocksPerCheckpoint);
+  // Clamp at zero: for absurd geometries (blocks greater than ~4094) the per-block overhead alone exceeds the
+  // raw blob capacity, which would otherwise yield a negative advertised DA budget.
+  const fields = Math.max(
+    0,
+    BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB -
+      NUM_CHECKPOINT_END_MARKER_FIELDS -
+      NUM_FIRST_BLOCK_END_BLOB_FIELDS -
+      (blocks - 1) * NUM_BLOCK_END_BLOB_FIELDS,
+  );
+  return fields * DA_GAS_PER_FIELD;
+}
+
+/**
+ * Computes the maximum gas a single tx may declare on a network: the smaller of the per-tx protocol
+ * maximum and the per-block allocation a proposer grants to the first block of a checkpoint. The per-block
+ * allocation mirrors `CheckpointBuilder.capLimitsByCheckpointBudgets`
+ * (`ceil(checkpointBudget / maxBlocksPerCheckpoint * multiplier)`) using the network-minimum multipliers, so
+ * a tx declaring this much is admissible into a block under that geometry.
+ *
+ * This is a *network* limit: a function of network-wide constants only (timetable-derived
+ * blocks-per-checkpoint, checkpoint budgets, the network-minimum multipliers). It must NOT depend on a
+ * node's local restrictiveness — its multipliers configured above the network minimum, or its
+ * `maxDABlockGas` / `validateMaxDABlockGas` caps — because those make a node stricter at block-building
+ * time but cannot define what the network considers a valid tx for relay. The same value is advertised by
+ * `getNodeInfo` and enforced by the RPC/gossip/pool gas validators.
+ *
+ * The DA budget is {@link getDaCheckpointBudgetForTxs} evaluated at the clamped blocks-per-checkpoint — the
+ * raw blob capacity net of encoding overhead for every block — so the admission limit is consistent with the
+ * builder's blob-field cap.
+ *
+ * @param manaCheckpointBudget - L2 (mana) budget per checkpoint (`rollupManaLimit`).
+ */
+export function computeNetworkTxGasLimits(opts: { maxBlocksPerCheckpoint: number; manaCheckpointBudget: number }): Gas {
+  const blocks = Math.max(1, opts.maxBlocksPerCheckpoint);
+  const daBudget = getDaCheckpointBudgetForTxs(blocks);
+
+  // Clamp by the whole-checkpoint budget too: at small block counts the per-block share scaled by the
+  // multiplier can exceed the checkpoint budget itself (e.g. at blocks=1 a >1 multiplier overshoots), which
+  // would admit a tx no builder can ever pack — the builder caps each block by the remaining budget. Clamping
+  // by the budget makes "admitted ⇒ buildable" unconditional. (For DA the per-tx maximum always binds first,
+  // so the budget clamp is currently moot, but it keeps the invariant explicit.)
+  const daGas = Math.min(
+    MAX_TX_DA_GAS,
+    daBudget,
+    Math.ceil((daBudget / blocks) * MIN_PER_BLOCK_DA_ALLOCATION_MULTIPLIER),
+  );
+  const l2Gas = Math.min(
+    MAX_PROCESSABLE_L2_GAS,
+    opts.manaCheckpointBudget,
+    Math.ceil((opts.manaCheckpointBudget / blocks) * MIN_PER_BLOCK_ALLOCATION_MULTIPLIER),
+  );
+
+  return new Gas(daGas, l2Gas);
+}
+
+/**
+ * Network tx gas limits derived from a sequencer/p2p config and the L1 slot-timing + mana constants. The
+ * single source of truth shared by `getNodeInfo` (advertising) and the RPC/gossip/pool gas validators
+ * (enforcing), so a node never rejects a tx it advertised as admissible. Always uses the network-minimum
+ * multipliers, never the node's (possibly higher) configured multipliers.
+ */
+export function getNetworkTxGasLimits(
+  config: ProposerTimetableConfig,
+  l1Constants: SlotTimingConstants & { rollupManaLimit: number },
+): Gas {
+  const maxBlocksPerCheckpoint = buildProposerTimetable(config, l1Constants).getMaxBlocksPerCheckpoint();
+  return computeNetworkTxGasLimits({ maxBlocksPerCheckpoint, manaCheckpointBudget: l1Constants.rollupManaLimit });
+}

package/src/ha-signing/config.ts

@@ -0,0 +1,170 @@
+import {
+  type L1ContractAddresses,
+  pickL1ContractAddressMappings,
+  pickL1ContractAddressesSchema,
+} from '@aztec/ethereum/l1-contract-addresses';
+import {
+  type ConfigMappingsType,
+  SecretValue,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+  secretStringConfigHelper,
+} from '@aztec/foundation/config';
+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 type BaseSignerConfig = {
+  /** Unique identifier for this node */
+  nodeId: string;
+  /** How long to wait between polls when a duty is being signed (ms) */
+  pollingIntervalMs: number;
+  /**
+   * How long (ms) to wait for a peer node's in-progress signing before giving up and treating the
+   * duty as already handled. This is the cross-node wait/poll timeout, distinct from
+   * signerCallTimeoutMs (the hard upper bound on this node's own signer call).
+   */
+  peerSigningTimeoutMs: number;
+  /**
+   * Hard upper bound (ms) on a single signer call made by this node. If the (possibly remote)
+   * signer does not return within this time, the call is aborted, the duty lock is released, and
+   * signing fails so it can be safely retried. The effective value is clamped to
+   * maxStuckDutiesAgeMs / 2 at construction, so a slow signer's lock is always released before
+   * stuck-duty cleanup could reclaim it. Defaults to 30_000 when unset.
+   */
+  signerCallTimeoutMs?: 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;
+} & Pick<L1ContractAddresses, 'rollupAddress'>;
+
+export const baseSignerConfigMappings: ConfigMappingsType<BaseSignerConfig> = {
+  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),
+  },
+  peerSigningTimeoutMs: {
+    env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
+    description: "How long to wait for a peer node's in-progress signing before giving up",
+    ...numberConfigHelper(3_000),
+  },
+  signerCallTimeoutMs: {
+    env: 'VALIDATOR_SIGNER_CALL_TIMEOUT_MS',
+    description: 'Hard upper bound in ms on a single signer call before it is aborted (default 30000)',
+    ...numberConfigHelper(30_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(),
+  },
+  ...pickL1ContractAddressMappings('rollupAddress'),
+};
+
+export const BaseSignerConfigSchema = z.object({
+  nodeId: z.string(),
+  pollingIntervalMs: z.number().min(0),
+  peerSigningTimeoutMs: z.number().min(0),
+  signerCallTimeoutMs: z.number().min(0).optional(),
+  maxStuckDutiesAgeMs: z.number().min(0).optional(),
+  cleanupOldDutiesAfterHours: z.number().min(0).optional(),
+  ...pickL1ContractAddressesSchema('rollupAddress'),
+}) 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?: SecretValue<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)',
+    ...secretStringConfigHelper(),
+  },
+  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: SecretValue.schema(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,29 @@
+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 AttestationSigningContext,
+  type BlockProposalSigningContext,
+  type CheckpointProposalSigningContext,
+  type HAProtectedSigningContext,
+  type NoHAProtectionSigningContext,
+  type SigningContext,
+  type VoteSigningContext,
+  getBlockNumberFromSigningContext,
+  getCheckpointNumberFromSigningContext,
+  isHAProtectedContext,
+} from './types.js';

package/src/ha-signing/local_config.ts

@@ -0,0 +1,65 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  optionalNumberConfigHelper,
+} 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;
+    /**
+     * Allow local signing protection to run against an ephemeral store when no data directory is set.
+     * Without this, a missing data directory fails startup, since ephemeral protection does not survive
+     * restarts. Intended for dev/test networks only; production validators must persist to disk.
+     */
+    allowEphemeralSigningProtection?: boolean;
+  };
+
+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.',
+    ...optionalNumberConfigHelper(),
+  },
+  allowEphemeralSigningProtection: {
+    env: 'VALIDATOR_ALLOW_EPHEMERAL_SIGNING_PROTECTION',
+    description:
+      'Allow local signing protection to run against an ephemeral store when no data directory is set (dev/test only). ' +
+      'Ephemeral protection does not survive restarts, so this is unsafe for production validators.',
+    ...booleanConfigHelper(false),
+  },
+};
+
+export const LocalSignerConfigSchema = zodFor<LocalSignerConfig>()(
+  BaseSignerConfigSchema.extend({
+    dataDirectory: z.string().optional(),
+    dataStoreMapSizeKb: z.number(),
+    signingProtectionMapSizeKb: z.number().optional(),
+    allowEphemeralSigningProtection: z.boolean().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,126 @@
+import {
+  BlockNumber,
+  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',
+}
+
+/**
+ * Signing context for block proposals.
+ * Includes both the block number and the checkpoint number the block belongs to.
+ */
+export interface BlockProposalSigningContext {
+  slot: SlotNumber;
+  blockNumber: BlockNumber;
+  checkpointNumber: CheckpointNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Signing context for checkpoint proposals.
+ * Includes the checkpoint number being proposed, but not a block number.
+ */
+export interface CheckpointProposalSigningContext {
+  slot: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  dutyType: DutyType.CHECKPOINT_PROPOSAL;
+}
+
+/**
+ * Signing context for attestation duties (checkpoint attestations).
+ * Includes the checkpoint number when available (from proposal validation).
+ */
+export interface AttestationSigningContext {
+  slot: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  dutyType: DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ */
+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 and TXS).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext =
+  | BlockProposalSigningContext
+  | CheckpointProposalSigningContext
+  | AttestationSigningContext
+  | VoteSigningContext;
+
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties have blockNumber, checkpointNumber, and blockIndexWithinCheckpoint
+ * - CHECKPOINT_PROPOSAL duties have checkpointNumber
+ * - ATTESTATION/ATTESTATIONS_AND_SIGNERS duties have only slot
+ * - Vote duties have only slot
+ * - AUTH_REQUEST and TXS duties don't need HA protection
+ */
+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.
+ * Only BLOCK_PROPOSAL duties carry a block number; all others return BlockNumber(0).
+ */
+export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber {
+  if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+    return context.blockNumber;
+  }
+  return BlockNumber(0);
+}
+
+/**
+ * Gets the checkpoint number from a signing context.
+ * BLOCK_PROPOSAL, CHECKPOINT_PROPOSAL, ATTESTATION, and ATTESTATIONS_AND_SIGNERS duties carry a checkpoint number;
+ * vote duties return CheckpointNumber(0).
+ */
+export function getCheckpointNumberFromSigningContext(context: HAProtectedSigningContext): CheckpointNumber {
+  if (
+    context.dutyType === DutyType.BLOCK_PROPOSAL ||
+    context.dutyType === DutyType.CHECKPOINT_PROPOSAL ||
+    context.dutyType === DutyType.ATTESTATION ||
+    context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS
+  ) {
+    return context.checkpointNumber;
+  }
+  return CheckpointNumber(0);
+}