@aztec/stdlib 6.0.0-nightly.20260605 → 6.0.0-nightly.20260721

package/src/gas/gas_settings.ts

@@ -8,13 +8,6 @@ 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.
@@ -106,31 +99,28 @@ export class GasSettings {
 
   /**
    * 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.
+   * Callers must supply `gasLimits` — typically the most a single tx may declare on the network
+   * (`min(per-tx max, per-block allocation)`), i.e. a node's advertised `txsLimits.gas`. Since teardown gas
+   * is reserved from gasLimits during private execution (see gas_meter.nr), the effective gas available for
+   * app logic is gasLimits - teardownGasLimits - privateOverhead; the teardown default is derived from the
+   * effective total so it always stays below it.
    * 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;
+    gasLimits: Gas;
     teardownGasLimits?: Gas;
     maxFeesPerGas: GasFees;
     maxPriorityFeesPerGas?: GasFees;
   }) {
+    const gasLimits = overrides.gasLimits;
+    const teardownGasLimits =
+      overrides.teardownGasLimits ?? new Gas(Math.floor(gasLimits.daGas / 2), Math.floor(gasLimits.l2Gas / 8));
     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,
-      },
+      gasLimits,
+      teardownGasLimits,
       maxFeesPerGas: overrides.maxFeesPerGas,
       maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
     });

package/src/gas/index.ts

@@ -3,3 +3,4 @@ export * from './gas.js';
 export * from './gas_fees.js';
 export * from './gas_settings.js';
 export * from './gas_used.js';
+export * from './tx_gas_limits.js';

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

@@ -25,8 +25,20 @@ export type BaseSignerConfig = {
   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;
+  /**
+   * 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) */
@@ -44,11 +56,16 @@ export const baseSignerConfigMappings: ConfigMappingsType<BaseSignerConfig> = {
     description: 'The number of ms to wait between polls when a duty is being signed',
     ...numberConfigHelper(100),
   },
-  signingTimeoutMs: {
+  peerSigningTimeoutMs: {
     env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
-    description: 'The maximum time to wait for a duty being signed to complete',
+    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)',
@@ -65,7 +82,8 @@ export const baseSignerConfigMappings: ConfigMappingsType<BaseSignerConfig> = {
 export const BaseSignerConfigSchema = z.object({
   nodeId: z.string(),
   pollingIntervalMs: z.number().min(0),
-  signingTimeoutMs: 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'),

package/src/ha-signing/local_config.ts

@@ -1,4 +1,9 @@
-import { type ConfigMappingsType, getConfigFromMappings, optionalNumberConfigHelper } from '@aztec/foundation/config';
+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';
 
@@ -17,6 +22,12 @@ 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> = {
@@ -28,6 +39,13 @@ export const localSignerConfigMappings: ConfigMappingsType<LocalSignerConfig> =
       '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>()(
@@ -35,6 +53,7 @@ export const LocalSignerConfigSchema = zodFor<LocalSignerConfig>()(
     dataDirectory: z.string().optional(),
     dataStoreMapSizeKb: z.number(),
     signingProtectionMapSizeKb: z.number().optional(),
+    allowEphemeralSigningProtection: z.boolean().optional(),
   }),
 );
 

package/src/interfaces/archiver.ts

@@ -63,13 +63,11 @@ export type ArchiverSpecificConfig = {
   /** Skip promoting proposed checkpoints during L1 sync (for testing purposes only) */
   skipPromoteProposedCheckpointDuringL1Sync?: boolean;
 
-  /**
-   * Grace period in seconds, measured from the end of a proposed block's build slot, after which a
-   * proposed block whose enclosing checkpoint was never proposed is pruned as an orphan. Defaults
-   * from `blockDurationMs / 1000` at the node wiring layer, falling back to the timetable minimum
-   * execution time.
-   */
-  orphanProposedBlockPruneGraceSeconds?: number;
+  /** Local tolerance in seconds before pruning an orphan block when no checkpoint proposal was received. */
+  orphanPruneNoProposalTolerance?: number;
+
+  /** Skip pruning orphan proposed blocks that have no matching proposed checkpoint. */
+  skipOrphanProposedBlockPruning?: boolean;
 };
 
 export const ArchiverSpecificConfigSchema = z.object({
@@ -82,7 +80,8 @@ export const ArchiverSpecificConfigSchema = z.object({
   archiverSkipHistoricalLogsCheck: z.boolean().optional(),
   skipValidateCheckpointAttestations: z.boolean().optional(),
   skipPromoteProposedCheckpointDuringL1Sync: z.boolean().optional(),
-  orphanProposedBlockPruneGraceSeconds: schemas.Integer.optional(),
+  orphanPruneNoProposalTolerance: schemas.Integer.optional(),
+  skipOrphanProposedBlockPruning: z.boolean().optional(),
 });
 
 export type ArchiverApi = Omit<
@@ -123,7 +122,7 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getContractClass: z.function({ input: z.tuple([schemas.Fr]), output: ContractClassPublicSchema.optional() }),
   getBytecodeCommitment: z.function({ input: z.tuple([schemas.Fr]), output: schemas.Fr }),
   getContract: z.function({
-    input: z.tuple([schemas.AztecAddress, optional(schemas.BigInt)]),
+    input: z.tuple([schemas.AztecAddress, schemas.BigInt]),
     output: ContractInstanceWithAddressSchema.optional(),
   }),
   getContractClassIds: z.function({ input: z.tuple([]), output: z.array(schemas.Fr) }),

package/src/interfaces/aztec-node-admin.ts

@@ -133,7 +133,7 @@ export function createAztecNodeAdminClient(
   apiKey?: string,
 ): AztecNodeAdmin {
   return createSafeJsonRpcClient<AztecNodeAdmin>(url, AztecNodeAdminApiSchema, {
-    namespaceMethods: 'nodeAdmin',
+    namespaceMethods: 'aztecAdmin',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
     ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),

package/src/interfaces/aztec-node-debug.ts

@@ -1,10 +1,14 @@
+import { type CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
 import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
 
 import { z } from 'zod';
 
-import type { ApiSchemaFor } from '../schemas/schemas.js';
+import { type ApiSchemaFor, optional } from '../schemas/schemas.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 
+const MAX_SIGNATURES_PER_REGISTER_CALL = 100;
+const MAX_SIGNATURE_LEN = 10000;
+
 /**
  * Debug interface for Aztec node available in sandbox/local-network mode.
  */
@@ -19,10 +23,58 @@ export interface AztecNodeDebug {
    * @throws If no sequencer is running.
    */
   mineBlock(): Promise<void>;
+
+  /**
+   * Synthetically proves the L2 chain up to the given checkpoint (default: the latest checkpointed
+   * checkpoint), writing epoch out hashes into the L1 Outbox so L2-to-L1 messages become consumable
+   * and advancing the rollup's proven tip. There is no real proof — this is the local-network
+   * equivalent of an epoch proof landing on L1. The target is clamped to the latest checkpointed
+   * checkpoint and the call no-ops when it is already proven.
+   *
+   * @param upToCheckpoint - Checkpoint to prove up to; defaults to the latest checkpointed checkpoint.
+   * @returns The proven checkpoint number after the call.
+   * @throws If no automine sequencer is running (only the automine sequencer supports synthetic proving).
+   */
+  prove(upToCheckpoint?: CheckpointNumber): Promise<CheckpointNumber>;
+
+  /**
+   * Warps L1 time forward to at least `targetTimestamp` and builds an empty L2 checkpoint at the next slot boundary,
+   * advancing the L2 timestamp to at least the target. The warp is serialized with block building, so it never
+   * interleaves with an in-flight build. A no-op when `targetTimestamp` is already at or behind the current L1 time.
+   *
+   * @param targetTimestamp - Target L1 timestamp, in seconds.
+   * @throws If no automine sequencer is running (only the automine sequencer supports time warps).
+   */
+  warpL2TimeAtLeastTo(targetTimestamp: number): Promise<void>;
+
+  /**
+   * Warps L1 time forward by at least `duration` seconds from the current L1 time and builds an empty L2 checkpoint
+   * at the next slot boundary. The warp is serialized with block building, so it never interleaves with an in-flight
+   * build.
+   *
+   * @param duration - Number of seconds to advance; must be positive.
+   * @throws If no automine sequencer is running, or if `duration` is not positive.
+   */
+  warpL2TimeAtLeastBy(duration: number): Promise<void>;
+
+  /**
+   * Registers public function signatures so the node can resolve selectors to names in public-execution stack
+   * traces. The mapping lives only in unpersisted node memory, is not gossiped, and is exposed here (rather than on
+   * the main node API) because it is a debug-only, unauthenticated write that should not be reachable on prod nodes.
+   * @param functionSignatures - Decoded `name(paramTypes)` signatures to register by selector.
+   */
+  registerContractFunctionSignatures(functionSignatures: string[]): Promise<void>;
 }
 
 export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
   mineBlock: z.function({ input: z.tuple([]), output: z.void() }),
+  prove: z.function({ input: z.tuple([optional(CheckpointNumberSchema)]), output: CheckpointNumberSchema }),
+  warpL2TimeAtLeastTo: z.function({ input: z.tuple([z.number()]), output: z.void() }),
+  warpL2TimeAtLeastBy: z.function({ input: z.tuple([z.number()]), output: z.void() }),
+  registerContractFunctionSignatures: z.function({
+    input: z.tuple([z.array(z.string().max(MAX_SIGNATURE_LEN)).max(MAX_SIGNATURES_PER_REGISTER_CALL)]),
+    output: z.void(),
+  }),
 };
 
 export function createAztecNodeDebugClient(
@@ -32,7 +84,7 @@ export function createAztecNodeDebugClient(
   apiKey?: string,
 ): AztecNodeDebug {
   return createSafeJsonRpcClient<AztecNodeDebug>(url, AztecNodeDebugApiSchema, {
-    namespaceMethods: 'nodeDebug',
+    namespaceMethods: 'aztecDebug',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
     ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),