@aztec/stdlib 5.0.0-rc.1 → 5.0.0

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/file-store/factory.ts

@@ -4,6 +4,7 @@ import { GoogleCloudFileStore } from './gcs.js';
 import { HttpFileStore, type HttpFileStoreOptions } from './http.js';
 import type { FileStore, ReadOnlyFileStore } from './interface.js';
 import { LocalFileStore } from './local.js';
+import { InMemoryFileStore } from './memory.js';
 import { S3FileStore } from './s3.js';
 
 const supportedExamples = [
@@ -21,6 +22,12 @@ export async function createFileStore(
 ): Promise<FileStore | undefined> {
   if (config === undefined) {
     return undefined;
+  } else if (config.startsWith('mem://')) {
+    // In-memory store for tests (see InMemoryFileStore). The namespace is everything after the
+    // scheme, so `mem://X` and a later `mem://X` share data, like two file:// stores over one dir.
+    const namespace = config.slice('mem://'.length).replace(/\/+$/, '');
+    logger.info(`Creating in-memory file store at ${namespace}`);
+    return new InMemoryFileStore(namespace);
   } else if (config.startsWith('file://')) {
     const url = new URL(config);
     if (url.host) {

package/src/file-store/index.ts

@@ -1,3 +1,4 @@
 export * from './interface.js';
 export * from './factory.js';
 export { type HttpFileStoreOptions } from './http.js';
+export { InMemoryFileStore } from './memory.js';

package/src/file-store/memory.ts

@@ -0,0 +1,94 @@
+import { writeFile } from 'fs/promises';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+// Backing data is shared per namespace so that a store created for writing and a (read-only) store
+// created later from the same `mem://` URL observe the same files — mirroring how two `file://`
+// stores over the same directory share state on disk. Without this, `FileStoreTxSource`, which
+// builds its own store from the URL, would never see what a test wrote through a different instance.
+const namespaces = new Map<string, Map<string, Buffer>>();
+
+/**
+ * In-memory {@link FileStore}, addressed via `mem://<namespace>/...`. Reads and writes are synchronous
+ * map operations with no disk I/O, so it is deterministic — useful for tests that exercise consumers
+ * of a file store (e.g. the tx file store) rather than the on-disk store itself, where a real
+ * filesystem can introduce timing flakes.
+ */
+export class InMemoryFileStore implements FileStore {
+  private readonly files: Map<string, Buffer>;
+
+  constructor(private readonly namespace: string) {
+    let files = namespaces.get(namespace);
+    if (!files) {
+      files = new Map();
+      namespaces.set(namespace, files);
+    }
+    this.files = files;
+  }
+
+  /** Clears all in-memory file store data, or a single namespace. Intended for test isolation. */
+  static clear(namespace?: string): void {
+    if (namespace === undefined) {
+      namespaces.clear();
+    } else {
+      namespaces.delete(namespace);
+    }
+  }
+
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
+    const toStore = opts?.compress ? await gzip(data) : data;
+    const key = this.key(path);
+    this.files.set(key, Buffer.from(toStore));
+    return `mem://${this.namespace}/${key}`;
+  }
+
+  public async upload(destPath: string, srcPath: string, opts?: FileStoreSaveOptions): Promise<string> {
+    const { readFile } = await import('fs/promises');
+    return this.save(destPath, await readFile(srcPath), opts);
+  }
+
+  public async read(pathOrUrl: string): Promise<Buffer> {
+    const data = this.files.get(this.key(pathOrUrl));
+    if (data === undefined) {
+      throw new Error(`File not found in memory store: ${pathOrUrl}`);
+    }
+    // Match LocalFileStore: transparently gunzip content that was stored compressed.
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
+  }
+
+  public async download(pathOrUrl: string, destPath: string): Promise<void> {
+    await writeFile(destPath, await this.read(pathOrUrl));
+  }
+
+  public exists(pathOrUrl: string): Promise<boolean> {
+    return Promise.resolve(this.files.has(this.key(pathOrUrl)));
+  }
+
+  /** Lists stored file keys, optionally restricted to those under `prefix`. Not part of {@link FileStore}. */
+  public listFiles(prefix = ''): string[] {
+    const keys = [...this.files.keys()];
+    const normalizedPrefix = prefix.replace(/^\/+/, '');
+    return normalizedPrefix ? keys.filter(k => k.startsWith(normalizedPrefix)) : keys;
+  }
+
+  /** Resolves a relative path or a `mem://` URI (as returned by `save`) to the registry key. */
+  private key(pathOrUrl: string): string {
+    const ownPrefix = `mem://${this.namespace}/`;
+    if (pathOrUrl.startsWith(ownPrefix)) {
+      return pathOrUrl.slice(ownPrefix.length);
+    }
+    if (pathOrUrl.startsWith('mem://')) {
+      // A mem:// URI for some namespace: drop the scheme and the leading namespace segment.
+      return pathOrUrl.slice('mem://'.length).replace(/^[^/]*\//, '');
+    }
+    return pathOrUrl.replace(/^\/+/, '');
+  }
+}

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/hash/hash.ts

@@ -188,14 +188,6 @@ export function computeSecretHash(secret: Fr): Promise<Fr> {
   return poseidon2HashWithSeparator([secret], DomainSeparator.SECRET_HASH);
 }
 
-export async function computeL1ToL2MessageNullifier(contract: AztecAddress, messageHash: Fr, secret: Fr) {
-  const innerMessageNullifier = await poseidon2HashWithSeparator(
-    [messageHash, secret],
-    DomainSeparator.MESSAGE_NULLIFIER,
-  );
-  return siloNullifier(contract, innerMessageNullifier);
-}
-
 /**
  * Calculates a siloed hash of a scoped l2 to l1 message.
  * @returns Fr containing 248 bits of information of sha256 hash.

package/src/interfaces/archiver.ts

@@ -68,6 +68,13 @@ export type ArchiverSpecificConfig = {
 
   /** Skip pruning orphan proposed blocks that have no matching proposed checkpoint. */
   skipOrphanProposedBlockPruning?: boolean;
+
+  /**
+   * Preload the standard contracts (AuthRegistry, PublicChecks, HandshakeRegistry) into the contract store at block 0.
+   * For test environments only: it must only be set when genesis also seeds the matching registration/deployment
+   * nullifiers, otherwise a later on-chain publish of a preloaded class would collide with the block-0 preload.
+   */
+  testPreloadStandardContracts?: boolean;
 };
 
 export const ArchiverSpecificConfigSchema = z.object({
@@ -82,6 +89,7 @@ export const ArchiverSpecificConfigSchema = z.object({
   skipPromoteProposedCheckpointDuringL1Sync: z.boolean().optional(),
   orphanPruneNoProposalTolerance: schemas.Integer.optional(),
   skipOrphanProposedBlockPruning: z.boolean().optional(),
+  testPreloadStandardContracts: z.boolean().optional(),
 });
 
 export type ArchiverApi = Omit<
@@ -122,7 +130,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-debug.ts

@@ -6,6 +6,9 @@ import { z } from 'zod';
 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.
  */
@@ -33,11 +36,45 @@ export interface AztecNodeDebug {
    * @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(

package/src/interfaces/aztec-node.ts

@@ -23,9 +23,15 @@ import { z } from 'zod';
 import type { AztecAddress } from '../aztec-address/index.js';
 import { type BlockData, BlockDataSchema } from '../block/block_data.js';
 import { BlockHash } from '../block/block_hash.js';
-import { type BlockParameter, BlockParameterSchema } from '../block/block_parameter.js';
+import { type BlockParameter, BlockParameterSchema, BlockTagWithoutLatestSchema } from '../block/block_parameter.js';
 import { type DataInBlock, dataInBlockSchemaFor } from '../block/in_block.js';
-import { type CheckpointsQuery, CheckpointsQuerySchema } from '../block/l2_block_source.js';
+import {
+  type CheckpointsQuery,
+  CheckpointsQuerySchema,
+  type L2BlockTag,
+  type L2Tips,
+  L2TipsSchema,
+} from '../block/l2_block_source.js';
 import { type CheckpointData, CheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
 import {
   type ContractClassPublic,
@@ -80,7 +86,7 @@ import {
   type BlocksIncludeOptions,
   BlocksIncludeOptionsSchema,
 } from './block_response.js';
-import { type ChainTip, ChainTipSchema, type ChainTips, ChainTipsSchema } from './chain_tips.js';
+import { type CheckpointTag, CheckpointTagSchema } from './chain_tips.js';
 import { type CheckpointParameter, CheckpointParameterSchema } from './checkpoint_parameter.js';
 import {
   type CheckpointIncludeOptions,
@@ -232,23 +238,20 @@ export interface AztecNode {
   ): Promise<L2ToL1MembershipWitness | undefined>;
 
   /**
-   * Returns the block number at a given chain tip, or the latest proposed block number when
+   * Returns the block number at a given block tag, or the latest proposed block number when
    * `tip` is omitted.
    */
-  getBlockNumber(tip?: ChainTip): Promise<BlockNumber>;
+  getBlockNumber(tip?: L2BlockTag): Promise<BlockNumber>;
 
   /**
-   * Returns the checkpoint number at a given chain tip, or the latest checkpoint number when
-   * `tip` is omitted.
-   *
-   * @remarks **Semantic foot-gun**: block-side `'proposed'` means "latest proposed block" (chain
-   * head), but checkpoint-side `'proposed'` means "latest confirmed checkpoint" — pre-L1-confirm
-   * checkpoints are not exposed over RPC. `'checkpointed'` on the checkpoint side is equivalent.
+   * Returns the checkpoint number at a given checkpoint tag, or the latest checkpointed number when
+   * `tip` is omitted. The proposed-but-unconfirmed checkpoint frontier is archiver-internal and not
+   * exposed over RPC, so `'proposed'` is not a valid checkpoint tag (see {@link CheckpointTag}).
    */
-  getCheckpointNumber(tip?: ChainTip): Promise<CheckpointNumber>;
+  getCheckpointNumber(tip?: CheckpointTag): Promise<CheckpointNumber>;
 
   /** Returns the tips of the L2 chain. */
-  getChainTips(): Promise<ChainTips>;
+  getChainTips(): Promise<L2Tips>;
 
   /** Returns the rollup constants for the current chain. */
   getL1Constants(): Promise<L1RollupConstants>;
@@ -382,12 +385,6 @@ export interface AztecNode {
    */
   getProtocolContractAddresses(): Promise<ProtocolContractAddresses>;
 
-  /**
-   * Registers contract function signatures for debugging purposes.
-   * @param functionSignatures - An array of function signatures to register by selector.
-   */
-  registerContractFunctionSignatures(functionSignatures: string[]): Promise<void>;
-
   /**
    * Gets private logs matching the given tags. Returns one inner array per element of `query.tags`, in
    * input order. An empty inner array means no logs matched that tag. Set `query.includeEffects` to also
@@ -525,10 +522,18 @@ export interface AztecNode {
   getContractClass(id: Fr): Promise<ContractClassPublic | undefined>;
 
   /**
-   * Returns a publicly deployed contract instance given its address.
+   * Returns a publicly deployed contract instance given its address. Its current class id is resolved as of the given
+   * reference block.
+   *
+   * Returns `undefined` if the instance has not been published (i.e. `publish_for_public_execution` was never called
+   * on the `ContractInstanceRegistry`). A contract whose class has been updated will never return `undefined`:
+   * scheduling an update requires the contract's deployment nullifier, which is only emitted by publishing, so any
+   * updatable contract has necessarily been published.
    * @param address - Address of the deployed contract.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   *        Defaults to 'latest'.
    */
-  getContract(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+  getContract(address: AztecAddress, referenceBlock?: BlockParameter): Promise<ContractInstanceWithAddress | undefined>;
 
   /**
    * Returns the ENR of this node for peer discovery, if available.
@@ -566,9 +571,6 @@ export interface AztecNode {
   getProposalsForSlot(slot: SlotNumber): Promise<ProposalsForSlot>;
 }
 
-const MAX_SIGNATURES_PER_REGISTER_CALL = 100;
-const MAX_SIGNATURE_LEN = 10000;
-
 export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
   getWorldStateSyncStatus: z.function({ input: z.tuple([]), output: WorldStateSyncStatusSchema }),
 
@@ -622,11 +624,11 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     output: L2ToL1MembershipWitnessSchema.optional(),
   }),
 
-  getBlockNumber: z.function({ input: z.tuple([optional(ChainTipSchema)]), output: BlockNumberSchema }),
+  getBlockNumber: z.function({ input: z.tuple([optional(BlockTagWithoutLatestSchema)]), output: BlockNumberSchema }),
 
-  getCheckpointNumber: z.function({ input: z.tuple([optional(ChainTipSchema)]), output: CheckpointNumberSchema }),
+  getCheckpointNumber: z.function({ input: z.tuple([optional(CheckpointTagSchema)]), output: CheckpointNumberSchema }),
 
-  getChainTips: z.function({ input: z.tuple([]), output: ChainTipsSchema }),
+  getChainTips: z.function({ input: z.tuple([]), output: L2TipsSchema }),
 
   getL1Constants: z.function({ input: z.tuple([]), output: L1RollupConstantsSchema }),
 
@@ -691,11 +693,6 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getProtocolContractAddresses: z.function({ input: z.tuple([]), output: ProtocolContractAddressesSchema }),
 
-  registerContractFunctionSignatures: z.function({
-    input: z.tuple([z.array(z.string().max(MAX_SIGNATURE_LEN)).max(MAX_SIGNATURES_PER_REGISTER_CALL)]),
-    output: z.void(),
-  }),
-
   getPrivateLogsByTags: z.function({
     input: z.tuple([PrivateLogsQuerySchema]),
     output: z.array(z.array(LogResultSchema)),
@@ -769,7 +766,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
   getContractClass: z.function({ input: z.tuple([schemas.Fr]), output: ContractClassPublicSchema.optional() }),
 
   getContract: z.function({
-    input: z.tuple([schemas.AztecAddress]),
+    input: z.tuple([schemas.AztecAddress, optional(BlockParameterSchema)]),
     output: ContractInstanceWithAddressSchema.optional(),
   }),
 

package/src/interfaces/chain_tips.ts

@@ -1,24 +1,16 @@
 import { z } from 'zod';
 
-import { type L2BlockTag, type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
-
 /**
- * Public chain-tip selectors usable in RPC requests.
- * Omits internal-only tags (e.g. `proposedCheckpoint`) from {@link L2BlockTag}.
+ * Public checkpoint-tip selectors usable in RPC requests.
+ *
+ * `'proposed'` is intentionally excluded: the proposed-but-unconfirmed checkpoint frontier is an
+ * archiver-internal pipelining concept, not part of the public chain-tip surface. Select the
+ * proposed *block* tip with a block tag (`L2BlockTag`) instead.
  */
-export type ChainTip = Exclude<L2BlockTag, 'proposedCheckpoint'>;
+export type CheckpointTag = 'checkpointed' | 'proven' | 'finalized';
 
-export const ChainTipSchema = z.union([
-  z.literal('proposed'),
+export const CheckpointTagSchema = z.union([
   z.literal('checkpointed'),
   z.literal('proven'),
   z.literal('finalized'),
-]) satisfies z.ZodType<ChainTip>;
-
-/**
- * Tips of the L2 chain.
- * Omits the sequencer-internal `proposedCheckpoint` from the public RPC surface.
- */
-export type ChainTips = Omit<L2Tips, 'proposedCheckpoint'>;
-
-export const ChainTipsSchema = L2TipsSchema.omit({ proposedCheckpoint: true });
+]) satisfies z.ZodType<CheckpointTag>;