@aztec/stdlib 5.0.0-rc.2 → 5.0.1

package/src/contract/contract_instance.ts

@@ -18,7 +18,12 @@ import {
   computeInitializationHash,
   computeInitializationHashFromEncodedArgs,
 } from './contract_address.js';
-import type { ContractInstance, ContractInstanceWithAddress } from './interfaces/contract_instance.js';
+import type {
+  ContractInstance,
+  ContractInstancePreimage,
+  ContractInstancePreimageWithAddress,
+  ContractInstanceWithAddress,
+} from './interfaces/contract_instance.js';
 
 const VERSION = 2 as const;
 
@@ -115,6 +120,62 @@ export class SerializableContractInstance {
   }
 }
 
+export class SerializableContractInstancePreimage {
+  public readonly version = VERSION;
+  public readonly salt: Fr;
+  public readonly deployer: AztecAddress;
+  public readonly originalContractClassId: Fr;
+  public readonly initializationHash: Fr;
+  public readonly immutablesHash: Fr;
+  public readonly publicKeys: PublicKeys;
+
+  constructor(instance: ContractInstancePreimage) {
+    if (instance.version !== VERSION) {
+      throw new Error(`Unexpected contract class version ${instance.version}`);
+    }
+    this.salt = instance.salt;
+    this.deployer = instance.deployer;
+    this.originalContractClassId = instance.originalContractClassId;
+    this.initializationHash = instance.initializationHash;
+    this.immutablesHash = instance.immutablesHash;
+    this.publicKeys = instance.publicKeys;
+  }
+
+  public toBuffer() {
+    return serializeToBuffer(
+      numToUInt8(this.version),
+      this.salt,
+      this.deployer,
+      this.originalContractClassId,
+      this.initializationHash,
+      this.immutablesHash,
+      this.publicKeys,
+    );
+  }
+
+  /** Returns a copy of this object with its address included. */
+  withAddress(address: AztecAddress): ContractInstancePreimageWithAddress {
+    return { ...this, address };
+  }
+
+  static fromBuffer(bufferOrReader: Buffer | BufferReader): SerializableContractInstancePreimage {
+    const reader = BufferReader.asReader(bufferOrReader);
+    const version = reader.readUInt8();
+    if (version !== VERSION) {
+      throw new Error(`Unexpected contract instance preimage version ${version}`);
+    }
+    return new SerializableContractInstancePreimage({
+      version: VERSION,
+      salt: reader.readObject(Fr),
+      deployer: reader.readObject(AztecAddress),
+      originalContractClassId: reader.readObject(Fr),
+      initializationHash: reader.readObject(Fr),
+      immutablesHash: reader.readObject(Fr),
+      publicKeys: reader.readObject(PublicKeys),
+    });
+  }
+}
+
 /**
  * Generates a Contract Instance from some instantiation params.
  * @param artifact - The account contract build artifact.

package/src/contract/interfaces/contract_instance.ts

@@ -9,19 +9,19 @@ import { schemas, zodFor } from '../../schemas/index.js';
 const VERSION = 2 as const;
 
 /**
- * A contract instance is a concrete deployment of a contract class. It always references a contract class,
- * which dictates what code it executes when called. It has state (both private and public), as well as an
- * address that acts as its identifier. It can be called into. It may have encryption and nullifying public keys.
+ * The address preimage of a contract instance: the immutable data that hashes to its address, i.e. everything a
+ * contract deployment commits to.
+ *
+ * Note that `originaContractClassId` is not necessarily the instance's _current_ class id, in case of upgrades: that
+ * one is not part of the preimage and is instead derived from chain state.
  */
-export interface ContractInstance {
+export interface ContractInstancePreimage {
   /** Version identifier. Initially one, bumped for any changes to the contract instance struct. */
   version: typeof VERSION;
   /** User-generated pseudorandom value for uniqueness. */
   salt: Fr;
   /** Optional deployer address or zero if this was a universal deploy. */
   deployer: AztecAddress;
-  /** Identifier of the contract class for this instance. */
-  currentContractClassId: Fr;
   /** Identifier of the original (at deployment) contract class for this instance */
   originalContractClassId: Fr;
   /** Hash of the selector and arguments to the constructor. */
@@ -32,14 +32,24 @@ export interface ContractInstance {
   publicKeys: PublicKeys;
 }
 
+/**
+ * The address preimage plus the current contract class id, which is chain-tracked state derived from the
+ * ContractInstanceRegistry (it equals the original class id unless the contract has been upgraded).
+ */
+export interface ContractInstance extends ContractInstancePreimage {
+  /** Identifier of the contract class this instance currently runs (as of some block). */
+  currentContractClassId: Fr;
+}
+
+export type ContractInstancePreimageWithAddress = ContractInstancePreimage & { address: AztecAddress };
+
 export type ContractInstanceWithAddress = ContractInstance & { address: AztecAddress };
 
-export const ContractInstanceSchema = zodFor<ContractInstance>()(
+export const ContractInstancePreimageSchema = zodFor<ContractInstancePreimage>()(
   z.object({
     version: z.literal(VERSION),
     salt: schemas.Fr,
     deployer: schemas.AztecAddress,
-    currentContractClassId: schemas.Fr,
     originalContractClassId: schemas.Fr,
     initializationHash: schemas.Fr,
     immutablesHash: schemas.Fr,
@@ -47,6 +57,14 @@ export const ContractInstanceSchema = zodFor<ContractInstance>()(
   }),
 );
 
+export const ContractInstanceSchema = zodFor<ContractInstance>()(
+  ContractInstancePreimageSchema.and(z.object({ currentContractClassId: schemas.Fr })),
+);
+
+export const ContractInstancePreimageWithAddressSchema = zodFor<ContractInstancePreimageWithAddress>()(
+  ContractInstancePreimageSchema.and(z.object({ address: schemas.AztecAddress })),
+);
+
 export const ContractInstanceWithAddressSchema = zodFor<ContractInstanceWithAddress>()(
   ContractInstanceSchema.and(z.object({ address: schemas.AztecAddress })),
 );

package/src/contract/partial_address.ts

@@ -1,7 +1,13 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
 /**
- * A type which along with public key forms a preimage of a contract address. See the link below for more details
- * https://github.com/AztecProtocol/aztec-packages/blob/master/docs/docs/concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys
+ * The contract-side preimage of an Aztec address, i.e. the commitment to a specific contract instance.
+ *
+ * A partial address commits to a contract's code and initialization
+ * (`hash(contract_class_id, salted_initialization_hash)`) but not to its keys. Combined with an account's `PublicKeys`,
+ * it fully determines the address: `address = (hash(public_keys_hash, partial_address) * G + Ivpk_m).x`. Two accounts
+ * therefore share an address only if they share both their public keys and their partial address.
+ *
+ * See `computePartialAddress` for the derivation.
  */
 export type PartialAddress = Fr;

package/src/database-version/version_manager.ts

@@ -6,11 +6,20 @@ import { join } from 'path';
 
 import { DatabaseVersion } from './database_version.js';
 
-export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
+export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'rm' | 'mkdir' | 'rename' | 'open'>;
 
 export const DATABASE_VERSION_FILE_NAME = 'db_version';
 export type SchemaVersionMismatchPolicy = 'reset' | 'throw';
 
+/**
+ * How to react when the version file exists but cannot be read (permissions, IO error, truncation).
+ * `'reset'` (default) treats the store as unversioned and lets the reset path run — safe for stores
+ * where an empty state is legitimate. `'throw'` refuses to open, leaving data untouched — required
+ * for protection stores (e.g. signing protection) that must never be silently wiped by a transient
+ * filesystem error. A genuinely missing file (ENOENT) is a first boot and is never affected by this.
+ */
+export type VersionFileReadFailurePolicy = 'reset' | 'throw';
+
 export type DatabaseVersionManagerOptions<T> = {
   schemaVersion: number;
   rollupAddress: EthAddress;
@@ -18,6 +27,7 @@ export type DatabaseVersionManagerOptions<T> = {
   onOpen: (dataDir: string) => Promise<T>;
   onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
   schemaVersionMismatchPolicy?: SchemaVersionMismatchPolicy;
+  versionFileReadFailurePolicy?: VersionFileReadFailurePolicy;
   fileSystem?: DatabaseVersionManagerFs;
   log?: Logger;
 };
@@ -37,6 +47,7 @@ export class DatabaseVersionManager<T> {
   private onOpen: (dataDir: string) => Promise<T>;
   private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
   private schemaVersionMismatchPolicy: SchemaVersionMismatchPolicy;
+  private versionFileReadFailurePolicy: VersionFileReadFailurePolicy;
   private fileSystem: DatabaseVersionManagerFs;
   private log: Logger;
 
@@ -47,8 +58,11 @@ export class DatabaseVersionManager<T> {
    * @param rollupAddress - The rollup contract address
    * @param dataDirectory - The directory where version information will be stored
    * @param onOpen - A callback to the open the database at the given location
-   * @param onUpgrade - An optional callback to upgrade the database before opening. If not provided it will reset the database
+   * @param onUpgrade - An optional callback to upgrade the database before opening. If not provided it will reset the
+   *   database. Must be idempotent: since the version marker is written only after a successful open, a crash after
+   *   onUpgrade but before the marker is written re-runs onUpgrade on the next start.
    * @param schemaVersionMismatchPolicy - Whether schema mismatches should reset data or throw
+   * @param versionFileReadFailurePolicy - Whether an unreadable (non-missing) version file should reset data or throw
    * @param fileSystem - An interface to access the filesystem
    * @param log - Optional custom logger
    * @param options - Configuration options
@@ -60,6 +74,7 @@ export class DatabaseVersionManager<T> {
     onOpen,
     onUpgrade,
     schemaVersionMismatchPolicy = 'reset',
+    versionFileReadFailurePolicy = 'reset',
     fileSystem = fs,
     log = createLogger(`foundation:version-manager`),
   }: DatabaseVersionManagerOptions<T>) {
@@ -74,13 +89,40 @@ export class DatabaseVersionManager<T> {
     this.onOpen = onOpen;
     this.onUpgrade = onUpgrade;
     this.schemaVersionMismatchPolicy = schemaVersionMismatchPolicy;
+    this.versionFileReadFailurePolicy = versionFileReadFailurePolicy;
     this.fileSystem = fileSystem;
     this.log = log;
   }
 
   static async writeVersion(version: DatabaseVersion, dataDir: string, fileSystem: DatabaseVersionManagerFs = fs) {
     await fileSystem.mkdir(dataDir, { recursive: true });
-    return fileSystem.writeFile(join(dataDir, DatabaseVersionManager.VERSION_FILE), version.toBuffer());
+    const finalPath = join(dataDir, DatabaseVersionManager.VERSION_FILE);
+    const tmpPath = `${finalPath}.tmp`;
+
+    // Atomic durable write: fill a temp file, fsync it, then rename it into place. The marker only
+    // becomes visible under its final name once its bytes are durably on disk, so a crash mid-write
+    // can never leave a "valid" version file sitting over an empty or partially-populated data dir.
+    const handle = await fileSystem.open(tmpPath, 'w');
+    try {
+      await handle.writeFile(version.toBuffer());
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fileSystem.rename(tmpPath, finalPath);
+
+    // Best-effort fsync of the containing directory so the rename itself survives a crash. Not all
+    // filesystems support directory fsync, so a failure here is non-fatal.
+    try {
+      const dirHandle = await fileSystem.open(dataDir, 'r');
+      try {
+        await dirHandle.sync();
+      } finally {
+        await dirHandle.close();
+      }
+    } catch {
+      // directory fsync is best-effort
+    }
   }
 
   /**
@@ -105,6 +147,17 @@ export class DatabaseVersionManager<T> {
         storedVersion = DatabaseVersion.empty();
         // only turn off these logs if the data dir didn't exist before
         shouldLogDataReset = false;
+      } else if (this.versionFileReadFailurePolicy === 'throw') {
+        // The version file exists but could not be read/parsed (permissions, IO error, truncation).
+        // Treating this as "unversioned" would reset the data directory, silently wiping a store that
+        // must fail closed. Refuse to open instead, leaving the data untouched for the operator.
+        const code = (err as Error & { code?: string })?.code;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `Failed to read database version file at ${this.versionFile} (${code ?? 'unknown error'}: ${message}). ` +
+            `Refusing to open the database; data was NOT reset. Resolve the underlying filesystem error and retry.`,
+          { cause: err },
+        );
       } else {
         this.log.warn(`Failed to read stored version information: ${err}. Defaulting to empty version`);
         storedVersion = DatabaseVersion.empty();
@@ -159,10 +212,47 @@ export class DatabaseVersionManager<T> {
       await this.resetDataDirectory();
     }
 
-    // Write the current version to disk
-    await this.writeVersion();
+    // Open the database first, then record the version marker. Writing the marker only after a
+    // successful open makes it a post-commit record: if the process crashes between the reset and a
+    // durable open, no marker is left behind, so the next startup re-runs the reset instead of
+    // trusting a marker that sits over empty or partially-initialized data.
+    const instance = await this.onOpen(this.dataDirectory);
 
-    return [await this.onOpen(this.dataDirectory), needsReset];
+    // Only (re)write the marker when it would actually change — first boot, reset, or upgrade. On a
+    // normal boot it already matches, so skipping avoids an unnecessary fsync (and the directory
+    // write permission the temp-file+rename needs) and, more importantly, any window where a
+    // marker-write failure would orphan the database we just opened.
+    if (!storedVersion.equals(this.currentVersion)) {
+      try {
+        await this.writeVersion();
+      } catch (err) {
+        // The database opened but recording the marker failed; close the freshly opened instance so
+        // we do not leak its file handles / locks before propagating the failure.
+        await this.closeQuietly(instance);
+        throw err;
+      }
+    }
+
+    return [instance, needsReset];
+  }
+
+  /**
+   * Best-effort close of a just-opened database instance, used to avoid leaking handles/locks when a
+   * post-open step fails. Swallows close errors so the original failure is the one that propagates.
+   */
+  private async closeQuietly(instance: T): Promise<void> {
+    const closable = instance as
+      | { close?: () => Promise<void> | void; [Symbol.asyncDispose]?: () => Promise<void> }
+      | undefined;
+    const dispose = closable?.close ?? closable?.[Symbol.asyncDispose];
+    if (typeof dispose !== 'function') {
+      return;
+    }
+    try {
+      await dispose.call(closable);
+    } catch (err) {
+      this.log.warn(`Failed to close database after version-write failure: ${err}`);
+    }
   }
 
   /**

package/src/gas/README.md

@@ -1,47 +1,69 @@
 # 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.
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol` (`fee_math.ts` in this directory is a
+TypeScript port of those formulas, used to predict fees a few slots ahead). This document
+describes the formulas, the oracle lag/lifetime mechanism, how a transaction's fee is
+derived from them, the gas and data limits, 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.
+Aztec meters work as gas in two dimensions: **DA** (data availability, i.e. blob data
+published to L1) and **L2** (execution). The L2 dimension is called **mana** (analogous to
+Ethereum gas): block headers track `totalManaUsed`, and the fee model below prices one unit
+of mana. The total fee is `gasUsed * feePerGas` summed across both dimensions.
+
+### The DA dimension is priced at zero
+
+Only the L2 dimension currently carries a price. When building checkpoint global variables,
+the sequencer sets `feePerDaGas = 0` and sets `feePerL2Gas` to the L1-computed minimum fee
+per mana (`sequencer-client/src/global_variable_builder/global_builder.ts` and
+`fee_provider.ts` in the same directory). The cost of publishing data is still recovered:
+the blob gas a checkpoint pays on L1 is part of the *sequencer cost* component of the mana
+fee below. DA gas remains fully metered and limited (see
+[Gas and Data Limits](#gas-and-data-limits)) — it bounds how much data a tx or checkpoint
+may publish — it just contributes nothing to the fee today.
 
 ## Fee Components
 
-The minimum fee per mana has four components:
+The minimum fee per mana has four components. All are computed in ETH (wei) per mana and
+converted to the fee asset at the end (see [Fee Asset Price](#fee-asset-price)).
 
 ### Sequencer Cost
 
 L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
 
 ```
-sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+sequencerCost = ceil(((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
               + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
-              / manaTarget
+              / manaTarget)
 ```
 
+Note that `BLOBS_PER_CHECKPOINT` here is FeeLib's own constant (3), not the protocol blob
+capacity of the same name (6) — see the note under [Key Constants](#key-constants).
+
 ### 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
+proverCost = ceil(ceil((L1_GAS_PER_EPOCH_VERIFIED * baseFee) / epochDuration) / manaTarget)
            + provingCostPerMana
 ```
 
+Updates to `provingCostPerMana` are rate-limited on L1 (`FeeLib.updateProvingCostPerMana`):
+at most one update every 30 days, each moving the value by at most ×1.5 (or ÷1.5), with a
+floor of 2 wei per mana.
+
 ### 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
+baseCost       = sequencerCost + proverCost
+congestionCost = floor(baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER) - baseCost
 ```
 
 When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
@@ -50,11 +72,15 @@ and congestion cost is zero.
 ### Congestion Multiplier
 
 ```
-excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
-congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+excessMana           = max(0, prevExcessMana + prevManaUsed - manaTarget)
+denominator          = manaTarget * 854,700,854 / 1e8    ≈ 8.547 * manaTarget
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER,
+                                       min(excessMana, 100 * denominator), denominator)
 ```
 
-Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+Each additional `manaTarget` of excess mana multiplies the fee by `e^(1/8.547) ≈ 1.124`,
+i.e. ~12.5%. The exponent is capped at 100 (multiplier ≤ ~2.7e43 × the minimum) to keep
+the Taylor series from overflowing.
 
 ### Total
 
@@ -62,6 +88,11 @@ Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
 minFeePerMana = sequencerCost + proverCost + congestionCost
 ```
 
+Each component is converted from ETH to the fee asset individually (rounding up) before
+summing. The sum is capped at `type(uint128).max` (`FeeLib.summedMinFee`) so it always fits
+the proposal header's `feePerL2Gas` field — without the cap, extreme congestion could
+produce a fee no valid header can represent, halting the chain.
+
 ## L1 Gas Oracle: Lag and Lifetime
 
 The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
@@ -70,9 +101,9 @@ The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a t
 - **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.
+- **LIFETIME = 5 slots** — after an oracle update, further updates are ignored
+  (`updateL1GasFeeOracle` returns without effect) 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:
 
@@ -84,6 +115,12 @@ 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.
 
+Because queued values only activate `LAG` slots later, the min fee for the next `LAG`
+slots is fully determined by current on-chain state. `fee_math.ts` ports the FeeLib
+formulas so the sequencer can predict min fees over that window (`FeePredictor` in
+`sequencer-client/src/global_variable_builder`), under a configurable mana-usage
+assumption (`ManaUsageEstimate`: none / target / limit).
+
 ### Worked Example
 
 Suppose the oracle is updated at slot 10 with new L1 fees. Here is the timeline:
@@ -117,34 +154,68 @@ Key observations:
 
 ## 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:
+Fees are computed in ETH (wei) internally and converted to the fee asset (Fee Juice) via
+`ethPerFeeAsset` (1e12 precision), rounding up (`PriceLib.toFeeAsset` in
+`l1-contracts/src/core/libraries/compressed-data/fees/FeeConfig.sol`).
+
+Each checkpoint proposal carries a fee-asset price modifier (`OracleInput`) chosen by the
+proposer, bounded to ±1% (±100 bps) per checkpoint:
 
 ```
 newPrice = currentPrice * (10000 + modifierBps) / 10000
 ```
 
+The result is clamped to [`MIN_ETH_PER_FEE_ASSET` = 100, `MAX_ETH_PER_FEE_ASSET` = 1e14],
+i.e. 1e-10 to 100 ETH per fee asset. The floor of 100 guarantees a ±1% step always moves
+the integer price by at least 1.
+
+## Transaction Fees
+
+The checkpoint's `gasFees` (the L1-computed min fee per mana, with DA priced at zero) act
+as a base fee. Senders declare `GasSettings`: gas limits, teardown gas limits,
+`maxFeesPerGas`, and `maxPriorityFeesPerGas`. A tx is only includable if `maxFeesPerGas`
+covers the checkpoint's `gasFees` in both dimensions. The effective fee adds an
+EIP-1559-style priority fee on top of the base, capped by the max
+(`computeEffectiveGasFees` in `stdlib/src/fees/transaction_fee.ts`):
+
+```
+effectiveFeePerGas = gasFees + min(maxPriorityFeePerGas, maxFeesPerGas - gasFees)   (per dimension)
+transactionFee     = billedGas.daGas * effectiveFeePerDaGas + billedGas.l2Gas * effectiveFeePerL2Gas
+```
+
+`billedGas` is actual consumption except for the teardown phase, which is billed at the
+declared `teardownGasLimits` rather than actual usage — the fee is charged during teardown
+itself, before actual teardown consumption is known.
+
 ## 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                                      |
+| Component              | Bound                                                    |
+| ---------------------- | -------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)             |
+| Fee asset price        | ±1% per checkpoint                                       |
+| Proving cost per mana  | At most ×1.5 (or ÷1.5) per update, one update per 30 days |
 | Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
-| Sequencer/prover costs | Scale linearly with L1 fees                             |
+| 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      |
+| Constant                        | Value          |
+| ------------------------------- | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000       |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000      |
+| `BLOBS_PER_CHECKPOINT` (FeeLib) | 3              |
+| `BLOB_GAS_PER_BLOB`             | 2^17           |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9            |
+| `LAG`                           | 2 slots        |
+| `LIFETIME`                      | 5 slots        |
+| `MIN_ETH_PER_FEE_ASSET`         | 100 (1e-10 ETH) |
+| `MAX_ETH_PER_FEE_ASSET`         | 1e14 (100 ETH) |
+
+⚠️ Name clash: `FeeLib.sol` (and its port `fee_math.ts`) defines `BLOBS_PER_CHECKPOINT = 3`,
+used only to price the sequencer's blob costs. The protocol constant of the same name in
+`@aztec/constants` is **6** — the actual blob capacity of a checkpoint, used throughout the
+limits section below. The FeeLib value is a holdover from the pre-checkpoint
+`BLOBS_PER_BLOCK`, so the fee model prices half of a full checkpoint's blobs.
 
 ## Gas and Data Limits
 
@@ -196,7 +267,7 @@ advertises them in `NodeInfo.txsLimits` (a required field); wallets read it and
 `GasSettings.fallback` as the default gas limits when sending without explicit limits, and they are enforced
 by `GasLimitsValidator` (clamped to the per-tx protocol maxima) at three points: RPC tx acceptance
 (`aztec-node/src/aztec-node/server.ts`), gossip validation (`p2p/src/services/libp2p/libp2p_service.ts`),
-and pending-pool admission (`p2p/src/client/factory.ts`). They are deliberately *not* enforced at reqresp or
+and pending-pool admission (`p2p/src/client/factory.ts`). They are deliberately *not* enforced at req/resp or
 block-proposal validation — admission is relay policy, not block validity.
 
 ### Per-block builder budgets
@@ -240,7 +311,8 @@ The outermost limits, enforced as proposal validity in `validateCheckpointLimits
 
 ## TypeScript Types
 
-- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`Gas`** — gas 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.
+- **`fee_math.ts`** — TypeScript port of the FeeLib formulas, used for fee prediction over the oracle LAG window.

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'),