@aztec/stdlib 0.0.1-commit.e588bc7e5 → 0.0.1-commit.e5a3663dd

package/src/gas/README.md

@@ -84,6 +84,37 @@ 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.
 
+### Worked Example
+
+Suppose the oracle is updated at slot 10 with new L1 fees. Here is the timeline:
+
+```
+Slot  Oracle state          Active fees   Notes
+────  ────────────────────  ────────────  ──────────────────────────────────
+ 10   pre=A, post=B, soc=12   A           Update queued. slotOfChange = 10 + LAG = 12.
+ 11   (same)                  A           Still before slotOfChange → pre (A).
+ 12   (same)                  B           slot >= slotOfChange → post (B) activates.
+ 13   (same)                  B           B remains active.
+ 14   (same)                  B           B remains active.
+ 15   Update allowed again    B           Earliest next update: soc + (LIFETIME - LAG)
+                                          = 12 + 3 = 15.
+```
+ 
+Key observations:
+
+1. **Slots 10-11**: The old fees (A) are still in effect. Transactions submitted during
+   these slots see the old L1 cost. This is the **LAG** window — it gives pending
+   transactions 2 slots to land before fees change.
+
+2. **Slot 12**: The new fees (B) activate. Any checkpoint proposed at slot >= 12 uses B
+   for its sequencer/prover cost calculation.
+
+3. **Slots 12-14**: No new oracle update is accepted. The system is in a **cooldown**
+   period of `LIFETIME - LAG = 3` slots after the transition.
+
+4. **Slot 15**: A new oracle update can be queued (earliest `acceptableSlot`). If
+   triggered, the new values would activate at slot 15 + LAG = 17.
+
 ## Fee Asset Price
 
 Fees are computed in ETH internally but converted to the fee asset (Fee Juice) via

package/src/gas/fee_math.ts

@@ -0,0 +1,120 @@
+/**
+ * TypeScript port of fee computation logic from FeeLib.sol.
+ * Used to predict worst-case min fees over a future window of L2 slots.
+ */
+
+// Constants matching FeeLib.sol
+export const MINIMUM_CONGESTION_MULTIPLIER = 1_000_000_000n;
+export const L1_GAS_PER_CHECKPOINT_PROPOSED = 300_000n;
+export const L1_GAS_PER_EPOCH_VERIFIED = 3_600_000n;
+export const BLOBS_PER_CHECKPOINT = 3n;
+export const BLOB_GAS_PER_BLOB = 2n ** 17n;
+export const MAGIC_CONGESTION_VALUE_MULTIPLIER = 854_700_854n;
+export const MAGIC_CONGESTION_VALUE_DIVISOR = 100_000_000n;
+export const ETH_PER_FEE_ASSET_PRECISION = 1_000_000_000_000n;
+export const MIN_ETH_PER_FEE_ASSET = 100n;
+
+/** Number of L2 slots of lag before new oracle values activate. Defines the prediction window. */
+export const FEE_ORACLE_LAG = 2;
+
+/** Expected mana usage per checkpoint for fee prediction. */
+export enum ManaUsageEstimate {
+  /** No usage — fees decrease as congestion drains. */
+  None = 'none',
+  /** Target usage — congestion stays roughly flat (steady state). */
+  Target = 'target',
+  /** Limit usage (2x target) — worst case, congestion grows maximally. */
+  Limit = 'limit',
+}
+
+/** Parameters for computing the mana min fee at a given point in time. */
+export type ManaMinFeeParams = {
+  l1BaseFee: bigint;
+  l1BlobFee: bigint;
+  manaTarget: bigint;
+  epochDuration: bigint;
+  provingCostPerManaEth: bigint;
+  excessMana: bigint;
+  ethPerFeeAsset: bigint;
+};
+
+/**
+ * Taylor series approximation of `factor * e^(numerator/denominator)`.
+ * Direct port of FeeLib.sol fakeExponential (EIP-4844 style).
+ */
+export function fakeExponential(factor: bigint, numerator: bigint, denominator: bigint): bigint {
+  let i = 1n;
+  let output = 0n;
+  let numeratorAccumulator = factor * denominator;
+  while (numeratorAccumulator > 0n) {
+    output += numeratorAccumulator;
+    numeratorAccumulator = (numeratorAccumulator * numerator) / (denominator * i);
+    i += 1n;
+  }
+  return output / denominator;
+}
+
+/** Computes excess mana for the next checkpoint, clamped to zero. */
+export function computeExcessMana(prevExcessMana: bigint, prevManaUsed: bigint, manaTarget: bigint): bigint {
+  const sum = prevExcessMana + prevManaUsed;
+  return sum > manaTarget ? sum - manaTarget : 0n;
+}
+
+/** Computes the congestion multiplier from excess mana (1e9 = no congestion). */
+export function computeCongestionMultiplier(excessMana: bigint, manaTarget: bigint): bigint {
+  const denominator = (manaTarget * MAGIC_CONGESTION_VALUE_MULTIPLIER) / MAGIC_CONGESTION_VALUE_DIVISOR;
+  const cappedNumerator = excessMana < denominator * 100n ? excessMana : denominator * 100n;
+  return fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, cappedNumerator, denominator);
+}
+
+/** Ceiling division for positive bigints. */
+function ceilDiv(a: bigint, b: bigint): bigint {
+  return (a + b - 1n) / b;
+}
+
+/** Converts an ETH value to fee asset value using ethPerFeeAsset (1e12 precision). */
+function toFeeAsset(ethValue: bigint, ethPerFeeAsset: bigint): bigint {
+  if (ethPerFeeAsset === 0n) {
+    return 0n;
+  }
+  return ceilDiv(ethValue * ETH_PER_FEE_ASSET_PRECISION, ethPerFeeAsset);
+}
+
+/**
+ * Computes the full mana min fee (sequencer + prover + congestion) in fee asset terms.
+ * Mirrors FeeLib.getManaMinFeeComponentsAt + summedMinFee.
+ */
+export function computeManaMinFee(params: ManaMinFeeParams): bigint {
+  const { l1BaseFee, l1BlobFee, manaTarget, epochDuration, provingCostPerManaEth, excessMana, ethPerFeeAsset } = params;
+
+  if (manaTarget === 0n) {
+    return 0n;
+  }
+
+  // Sequencer cost per mana (in ETH)
+  const ethUsed = L1_GAS_PER_CHECKPOINT_PROPOSED * l1BaseFee + BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * l1BlobFee;
+  const sequencerCostEth = ceilDiv(ethUsed, manaTarget);
+
+  // Prover cost per mana (in ETH): L1 verification gas + governance-set proving cost
+  const proverCostEth =
+    ceilDiv(ceilDiv(L1_GAS_PER_EPOCH_VERIFIED * l1BaseFee, epochDuration), manaTarget) + provingCostPerManaEth;
+
+  // Total base cost in ETH (congestion is computed on this)
+  const totalEth = sequencerCostEth + proverCostEth;
+
+  // Congestion multiplier and cost (in ETH)
+  const congestionMul = computeCongestionMultiplier(excessMana, manaTarget);
+  const congestionCostEth = (totalEth * congestionMul) / MINIMUM_CONGESTION_MULTIPLIER - totalEth;
+
+  // Convert all components to fee asset
+  const clampedEthPerFeeAsset = ethPerFeeAsset < MIN_ETH_PER_FEE_ASSET ? MIN_ETH_PER_FEE_ASSET : ethPerFeeAsset;
+  const sequencerCost = toFeeAsset(sequencerCostEth, clampedEthPerFeeAsset);
+  const proverCost = toFeeAsset(proverCostEth, clampedEthPerFeeAsset);
+  const congestionCost = toFeeAsset(congestionCostEth, clampedEthPerFeeAsset);
+
+  const total = sequencerCost + proverCost + congestionCost;
+
+  // Cap at uint128 max (matching FeeLib.summedMinFee)
+  const UINT128_MAX = (1n << 128n) - 1n;
+  return total < UINT128_MAX ? total : UINT128_MAX;
+}

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;
@@ -60,10 +71,7 @@ export class GasFees {
       const s = BigInt(scalar);
       return new GasFees(this.feePerDaGas * s, this.feePerL2Gas * s);
     } else {
-      return new GasFees(
-        BigInt(Math.ceil(Number(this.feePerDaGas) * scalar)),
-        BigInt(Math.ceil(Number(this.feePerL2Gas) * scalar)),
-      );
+      return new GasFees(bigintMulCeil(this.feePerDaGas, scalar), bigintMulCeil(this.feePerL2Gas, scalar));
     }
   }
 
@@ -126,3 +134,8 @@ export class GasFees {
     return `GasFees { feePerDaGas=${this.feePerDaGas} feePerL2Gas=${this.feePerL2Gas} }`;
   }
 }
+
+/** Provides projected minimum gas fees for the next block. */
+export interface BlockMinFeesProvider {
+  getCurrentMinFees(): Promise<GasFees>;
+}

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/gas/index.ts

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

package/src/ha-signing/config.ts

@@ -1,11 +1,13 @@
 import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
 import {
   type ConfigMappingsType,
+  SecretValue,
   booleanConfigHelper,
   getConfigFromMappings,
   getDefaultConfig,
   numberConfigHelper,
   optionalNumberConfigHelper,
+  secretStringConfigHelper,
 } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import type { ZodFor } from '@aztec/foundation/schemas';
@@ -88,7 +90,7 @@ export interface ValidatorHASignerConfig extends BaseSignerConfig {
    * PostgreSQL connection string
    * Format: postgresql://user:password@host:port/database
    */
-  databaseUrl?: string;
+  databaseUrl?: SecretValue<string>;
   /** Maximum number of clients in the pool (default: 10) */
   poolMaxCount?: number;
   /** Minimum number of clients in the pool (default: 0) */
@@ -110,6 +112,7 @@ export const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASign
     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',
@@ -148,7 +151,7 @@ export function getConfigEnvVars(): ValidatorHASignerConfig {
 
 export const ValidatorHASignerConfigSchema = BaseSignerConfigSchema.extend({
   haSigningEnabled: z.boolean(),
-  databaseUrl: z.string().optional(),
+  databaseUrl: SecretValue.schema(z.string()).optional(),
   poolMaxCount: z.number().min(0).optional(),
   poolMinCount: z.number().min(0).optional(),
   poolIdleTimeoutMs: z.number().min(0).optional(),

package/src/ha-signing/index.ts

@@ -16,12 +16,14 @@ export {
 } from './local_config.js';
 export {
   DutyType,
+  type AttestationSigningContext,
   type BlockProposalSigningContext,
+  type CheckpointProposalSigningContext,
   type HAProtectedSigningContext,
   type NoHAProtectionSigningContext,
-  type OtherSigningContext,
   type SigningContext,
   type VoteSigningContext,
   getBlockNumberFromSigningContext,
+  getCheckpointNumberFromSigningContext,
   isHAProtectedContext,
 } from './types.js';

package/src/ha-signing/local_config.ts

@@ -1,4 +1,4 @@
-import { type ConfigMappingsType, getConfigFromMappings } from '@aztec/foundation/config';
+import { type ConfigMappingsType, getConfigFromMappings, optionalNumberConfigHelper } from '@aztec/foundation/config';
 import { zodFor } from '@aztec/foundation/schemas';
 import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
 
@@ -26,7 +26,7 @@ export const localSignerConfigMappings: ConfigMappingsType<LocalSignerConfig> =
     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),
+    ...optionalNumberConfigHelper(),
   },
 };
 

package/src/ha-signing/types.ts

@@ -1,6 +1,6 @@
 import {
   BlockNumber,
-  type CheckpointNumber,
+  CheckpointNumber,
   type IndexWithinCheckpoint,
   type SlotNumber,
 } from '@aztec/foundation/branded-types';
@@ -20,40 +20,40 @@ export enum DutyType {
 }
 
 /**
- * Base context for signing operations
+ * Signing context for block proposals.
+ * Includes both the block number and the checkpoint number the block belongs to.
  */
-interface BaseSigningContext {
-  /** Slot number for this duty */
+export interface BlockProposalSigningContext {
   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;
+  blockNumber: BlockNumber;
+  checkpointNumber: CheckpointNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
 }
 
 /**
- * Signing context for block proposals.
- * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
+ * Signing context for checkpoint proposals.
+ * Includes the checkpoint number being proposed, but not a block number.
  */
-export interface BlockProposalSigningContext extends BaseSigningContext {
-  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
-  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
-  dutyType: DutyType.BLOCK_PROPOSAL;
+export interface CheckpointProposalSigningContext {
+  slot: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  dutyType: DutyType.CHECKPOINT_PROPOSAL;
 }
 
 /**
- * Signing context for non-block-proposal duties that require HA protection.
- * blockIndexWithinCheckpoint is not applicable (internally always -1).
+ * Signing context for attestation duties (checkpoint attestations).
+ * Includes the checkpoint number when available (from proposal validation).
  */
-export interface OtherSigningContext extends BaseSigningContext {
-  dutyType: DutyType.CHECKPOINT_PROPOSAL | DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+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.
- * blockNumber is not applicable (internally always 0).
  */
 export interface VoteSigningContext {
   slot: SlotNumber;
@@ -69,18 +69,23 @@ export interface NoHAProtectionSigningContext {
 }
 
 /**
- * Signing contexts that require HA protection (excludes AUTH_REQUEST).
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST and TXS).
  * Used by the HA signer's signWithProtection method.
  */
-export type HAProtectedSigningContext = BlockProposalSigningContext | OtherSigningContext | VoteSigningContext;
+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 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)
+ * - 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;
 
@@ -94,19 +99,28 @@ export function isHAProtectedContext(context: SigningContext): context is HAProt
 
 /**
  * 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
+ * Only BLOCK_PROPOSAL duties carry a block number; all others return BlockNumber(0).
  */
-export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber | CheckpointNumber {
-  // Check for duty types that have blockNumber
+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.blockNumber;
+    return context.checkpointNumber;
   }
-  // Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE) don't have blockNumber
-  return BlockNumber(0);
+  return CheckpointNumber(0);
 }

package/src/hash/hash.ts

@@ -6,6 +6,21 @@ import type { EthAddress } from '@aztec/foundation/eth-address';
 
 import { AztecAddress } from '../aztec-address/index.js';
 
+/** Computes a Poseidon2 merkle tree internal node hash for append-only trees (note-hash, L1->L2, archive). */
+export function computeMerkleHash(left: Fr, right: Fr): Promise<Fr> {
+  return poseidon2HashWithSeparator([left, right], DomainSeparator.MERKLE_HASH);
+}
+
+/** Merkle-node hasher for the nullifier tree's sibling paths. */
+export function computeNullifierMerkleHash(left: Fr, right: Fr): Promise<Fr> {
+  return poseidon2HashWithSeparator([left, right], DomainSeparator.NULLIFIER_MERKLE);
+}
+
+/** Merkle-node hasher for the public-data tree's sibling paths. */
+export function computePublicDataMerkleHash(left: Fr, right: Fr): Promise<Fr> {
+  return poseidon2HashWithSeparator([left, right], DomainSeparator.PUBLIC_DATA_MERKLE);
+}
+
 /**
  * Computes a hash of a given verification key.
  * @param keyAsFields - The verification key as fields.
@@ -103,6 +118,18 @@ export function computeLogTag(rawTag: number | bigint | boolean | Fr | Buffer, d
   return poseidon2HashWithSeparator([new Fr(rawTag)], domSep);
 }
 
+/**
+ * Computes the commitment of a private event from its preimage.
+ * @param randomness - Random value emitted alongside the event to prevent preimage brute-forcing.
+ * @param eventSelector - Event selector as an Fr.
+ * @param content - Serialized event content.
+ *
+ * @dev Must match the implementation in aztec-nr/aztec/src/event/event_interface.nr > compute_private_serialized_event_commitment
+ */
+export function computePrivateEventCommitment(randomness: Fr, eventSelector: Fr, content: Fr[]): Promise<Fr> {
+  return poseidon2HashWithSeparator([randomness, eventSelector, ...content], DomainSeparator.EVENT_COMMITMENT);
+}
+
 export function computeSiloedPrivateLogFirstField(contract: AztecAddress, field: Fr): Promise<Fr> {
   return poseidon2HashWithSeparator([contract, field], DomainSeparator.PRIVATE_LOG_FIRST_FIELD);
 }

package/src/interfaces/archiver.ts

@@ -4,7 +4,7 @@ import type { ApiSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
-import { BlockDataSchema } from '../block/block_data.js';
+import { BlockDataSchema, BlockDataWithCheckpointContextSchema } from '../block/block_data.js';
 import { BlockHash } from '../block/block_hash.js';
 import { CheckpointedL2Block } from '../block/checkpointed_l2_block.js';
 import { L2Block } from '../block/l2_block.js';
@@ -60,8 +60,14 @@ export type ArchiverSpecificConfig = {
   /** Whether to allow starting the archiver without debug/trace method support on Ethereum hosts */
   ethereumAllowNoDebugHosts?: boolean;
 
+  /** Skip the startup check that probes the L1 RPC for historical logs on the Rollup contract. */
+  archiverSkipHistoricalLogsCheck?: boolean;
+
   /** Skip validating checkpoint attestations (for testing purposes only) */
   skipValidateCheckpointAttestations?: boolean;
+
+  /** Skip promoting proposed checkpoints during L1 sync (for testing purposes only) */
+  skipPromoteProposedCheckpointDuringL1Sync?: boolean;
 };
 
 export const ArchiverSpecificConfigSchema = z.object({
@@ -72,7 +78,9 @@ export const ArchiverSpecificConfigSchema = z.object({
   archiverStoreMapSizeKb: schemas.Integer.optional(),
   maxAllowedEthClientDriftSeconds: schemas.Integer.optional(),
   ethereumAllowNoDebugHosts: z.boolean().optional(),
+  archiverSkipHistoricalLogsCheck: z.boolean().optional(),
   skipValidateCheckpointAttestations: z.boolean().optional(),
+  skipPromoteProposedCheckpointDuringL1Sync: z.boolean().optional(),
 });
 
 export type ArchiverApi = Omit<
@@ -109,6 +117,16 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getBlockHeaderByArchive: z.function().args(schemas.Fr).returns(BlockHeader.schema.optional()),
   getBlockData: z.function().args(BlockNumberSchema).returns(BlockDataSchema.optional()),
   getBlockDataByArchive: z.function().args(schemas.Fr).returns(BlockDataSchema.optional()),
+  getBlockDataWithCheckpointContext: z
+    .function()
+    .args(BlockNumberSchema)
+    .returns(BlockDataWithCheckpointContextSchema.optional()),
+  getCheckpointData: z.function().args(CheckpointNumberSchema).returns(CheckpointDataSchema.optional()),
+  getCheckpointDataRange: z
+    .function()
+    .args(CheckpointNumberSchema, schemas.Integer)
+    .returns(z.array(CheckpointDataSchema)),
+  getCheckpointNumberBySlot: z.function().args(schemas.SlotNumber).returns(CheckpointNumberSchema.optional()),
   getL2Block: z.function().args(BlockNumberSchema).returns(L2Block.schema.optional()),
   getL2BlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
   getL2BlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
@@ -150,8 +168,8 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .args()
     .returns(z.object({ genesisArchiveRoot: schemas.Fr })),
   getL1Timestamp: z.function().args().returns(schemas.BigInt.optional()),
-  getProposedCheckpoint: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
-  getProposedCheckpointOnly: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
+  getLastCheckpoint: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
+  getLastProposedCheckpoint: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
   syncImmediate: z.function().args().returns(z.void()),
   isPendingChainInvalid: z.function().args().returns(z.boolean()),
   getPendingChainValidationStatus: z.function().args().returns(ValidateCheckpointResultSchema),