@aztec/stdlib 5.0.0-rc.1 → 5.0.0-rc.2

package/src/block/test/l2_tips_store_test_suite.ts

@@ -94,14 +94,18 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     return new PublishedCheckpoint(checkpoint, L1PublishedData.random(), []);
   };
 
-  /** Creates a chain-checkpointed event with the required block field */
-  const makeCheckpointedEvent = async (checkpoint: PublishedCheckpoint) => {
-    const lastBlock = checkpoint.checkpoint.blocks.at(-1)!;
+  /** Creates a thin chain-checkpointed event carrying the block + checkpoint ids of the checkpoint's last block. */
+  const makeCheckpointedEvent = async (published: PublishedCheckpoint) => {
+    const lastBlock = published.checkpoint.blocks.at(-1)!;
     const blockId: L2BlockId = {
       number: lastBlock.number,
       hash: (await lastBlock.hash()).toString(),
     };
-    return { type: 'chain-checkpointed' as const, checkpoint, block: blockId };
+    const checkpointId = {
+      number: published.checkpoint.number,
+      hash: published.checkpoint.hash().toString(),
+    };
+    return { type: 'chain-checkpointed' as const, checkpoint: checkpointId, block: blockId };
   };
 
   it('returns zero if no tips are stored', async () => {
@@ -123,6 +127,71 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     expect(await tipsStore.getL2BlockHash(3)).toEqual(blockHashes.get(3));
   });
 
+  it('records the proposed tip number and hash from a chain-proposed event', async () => {
+    // chain-proposed is the sole writer of proposed-tip history in tips-only mode: no preceding blocks-added.
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proposed',
+      block: { number: BlockNumber(5), hash: new Fr(500).toString() },
+    });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proposed).toEqual({ number: BlockNumber(5), hash: new Fr(500).toString() });
+    // The hash is recorded in the same index the walk-back reads, so it resolves as a sparse anchor.
+    expect(await tipsStore.getL2BlockHash(5)).toEqual(new Fr(500).toString());
+  });
+
+  it('serves sparse proposed anchors from chain-proposed events for the walk-back', async () => {
+    // Two tip-moving polls in tips-only mode, with no blocks in between (sparse history).
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proposed',
+      block: { number: BlockNumber(4), hash: new Fr(400).toString() },
+    });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proposed',
+      block: { number: BlockNumber(9), hash: new Fr(900).toString() },
+    });
+
+    // Both recorded heights resolve; the heights between them were never seen and stay undefined.
+    expect(await tipsStore.getL2BlockHash(4)).toEqual(new Fr(400).toString());
+    expect(await tipsStore.getL2BlockHash(9)).toEqual(new Fr(900).toString());
+    expect(await tipsStore.getL2BlockHash(6)).toBeUndefined();
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proposed).toEqual({ number: BlockNumber(9), hash: new Fr(900).toString() });
+  });
+
+  it('records block-hash witnesses without moving any tip cursor', async () => {
+    // Establish a proposed tip at 9 in tips-only fashion (sole writer of proposed history).
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proposed',
+      block: { number: BlockNumber(9), hash: new Fr(900).toString() },
+    });
+
+    // Record sparse witnesses at heights below the tip (e.g. a consumer materializing per-height state).
+    await tipsStore.recordBlockHashes([
+      { number: BlockNumber(4), hash: new Fr(404).toString() },
+      { number: BlockNumber(6), hash: new Fr(606).toString() },
+    ]);
+
+    // Each recorded height resolves; an unrecorded gap stays undefined.
+    expect(await tipsStore.getL2BlockHash(4)).toEqual(new Fr(404).toString());
+    expect(await tipsStore.getL2BlockHash(6)).toEqual(new Fr(606).toString());
+    expect(await tipsStore.getL2BlockHash(5)).toBeUndefined();
+
+    // No tip cursor moved: the proposed tip is still 9, and every other tier is at genesis.
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proposed).toEqual({ number: BlockNumber(9), hash: new Fr(900).toString() });
+    expect(tips.checkpointed.block).toEqual(makeTip(0));
+    expect(tips.proven.block).toEqual(makeTip(0));
+    expect(tips.finalized.block).toEqual(makeTip(0));
+  });
+
+  it('skips witnesses with no hash and tolerates an empty list', async () => {
+    await tipsStore.recordBlockHashes([]);
+    await tipsStore.recordBlockHashes([{ number: BlockNumber(3), hash: '' }]);
+    expect(await tipsStore.getL2BlockHash(3)).toBeUndefined();
+  });
+
   it('checkpoints all proposed blocks', async () => {
     // Propose blocks 1-5
     const blocks = await Promise.all(times(5, i => makeBlock(i + 1)));

package/src/checkpoint/index.ts

@@ -5,4 +5,5 @@ export * from './checkpoint_reexecution_tracker.js';
 export * from './digest.js';
 export * from './previous_checkpoint_out_hashes.js';
 export * from './published_checkpoint.js';
+export * from './simulation_overrides.js';
 export * from './validate.js';

package/src/checkpoint/simulation_overrides.ts

@@ -0,0 +1,171 @@
+import {
+  type FeeHeader,
+  RollupContract,
+  SimulationOverridesBuilder,
+  type SimulationOverridesPlan,
+} from '@aztec/ethereum/contracts';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+
+import type { CoordinationSignatureContext } from '../p2p/signature_utils.js';
+import type { ProposedCheckpointData } from './checkpoint_data.js';
+import { computeCheckpointPayloadDigest } from './digest.js';
+
+type CheckpointSimulationOverridesPlanInput = {
+  /** Target rollup contract. */
+  rollup: RollupContract;
+  /** Checkpoint number to be proposed. */
+  checkpointNumber: CheckpointNumber;
+  /** Logger instance. */
+  log: Logger;
+  /**
+   * The proposed parent checkpoint when pipelining. Its `checkpointNumber` must equal
+   * `checkpointNumber - 1`; the helper enforces this. Mutually exclusive with
+   * `invalidateToPendingCheckpointNumber`.
+   */
+  proposedCheckpointData?: ProposedCheckpointData;
+  /**
+   * The pending checkpoint number we'll end up at after invalidation lands. Mutually exclusive
+   * with `proposedCheckpointData`.
+   */
+  invalidateToPendingCheckpointNumber?: CheckpointNumber;
+  /**
+   * The real on-chain pending checkpoint number (typically `syncedTo.checkpointedCheckpointNumber`).
+   * Used as the snapshot we pin both `pending` and `proven` to avoid prunes in simulation.
+   */
+  checkpointedCheckpointNumber: CheckpointNumber;
+  /**
+   * Chain-level consensus signature context. Used to recompute the parent's `payloadDigest` for the
+   * pipelined simulation override so it matches what `propose` will write into `tempCheckpointLogs[parent]`
+   * once the parent lands.
+   */
+  signatureContext: CoordinationSignatureContext;
+};
+
+/**
+ * Builds the SimulationOverridesPlan describing the simulated L1 rollup state for a checkpoint's
+ * enqueue-time simulations: `canProposeAt` (in Sequencer.doWork) and the propose-related sims
+ * (validateBlockHeader, simulateProposeTx). The plan reflects "as if our pipelined parent
+ * checkpoint has landed and any required invalidation has executed" — the gap that needs to be
+ * bridged at enqueue time.
+ *
+ * Pipelining (`proposedCheckpointData`) and invalidation (`invalidateToPendingCheckpointNumber`)
+ * are mutually exclusive; passing both throws.
+ */
+export async function buildCheckpointSimulationOverridesPlan(
+  input: CheckpointSimulationOverridesPlanInput,
+): Promise<SimulationOverridesPlan | undefined> {
+  if (input.proposedCheckpointData && input.invalidateToPendingCheckpointNumber !== undefined) {
+    throw new Error(
+      'Error in buildCheckpointSimulationOverridesPlan: proposedCheckpointData and invalidateToPendingCheckpointNumber are mutually exclusive',
+    );
+  }
+
+  const builder = new SimulationOverridesBuilder();
+  const pendingCheckpointNumber = derivePendingCheckpointNumber(input);
+
+  // Override the latest checkpoint number when invalidating or pipelining, so our checkpoint
+  // follows from it. We also override the proven chain tip so we dont need to worry about
+  // prunes kicking in that would break out simulation if there's a prune pending. We always
+  // assume that a proof will land in time. If we don't have a pending checkpoint number to force,
+  // we still set both tips to the current checkpoint number to avoid the prune trigger.
+  const overridenChainTip = pendingCheckpointNumber ?? input.checkpointedCheckpointNumber;
+  builder.withChainTips({ pending: overridenChainTip, proven: overridenChainTip });
+
+  if (input.proposedCheckpointData) {
+    const { header, archive, checkpointOutHash, feeAssetPriceModifier } = input.proposedCheckpointData;
+    builder.withPendingArchive(archive.root);
+    // Override every locally-derivable `tempCheckpointLogs[parent]` field that L1 will eventually
+    // write. `slotNumber` is load-bearing for `STFLib.canPruneAtTime`: without it the cell reads
+    // slotNumber 0, the contract treats the pending tip as belonging to an expired epoch, and
+    // `getEffectivePendingCheckpointNumber` silently collapses pending back to proven — producing
+    // a spurious `Rollup__InvalidArchive` against the on-chain genesis archive. The other fields
+    // (headerHash, outHash, payloadDigest) are not strictly load-bearing for `canProposeAt` /
+    // `validateBlockHeader`, but mirroring the full cell keeps the simulation byte-faithful with
+    // what the actual `propose()` send will observe, which is a defense against future reads
+    // taking dependencies on them.
+    builder.withPendingTempCheckpointLogFields({
+      headerHash: header.hash(),
+      outHash: checkpointOutHash,
+      slotNumber: header.slotNumber,
+      payloadDigest: computeCheckpointPayloadDigest({
+        header,
+        archiveRoot: archive.root,
+        feeAssetPriceModifier,
+        signatureContext: input.signatureContext,
+      }),
+    });
+
+    const feeHeader = await computePipelinedParentFeeHeader({
+      checkpointNumber: input.checkpointNumber,
+      proposedCheckpointData: input.proposedCheckpointData,
+      rollup: input.rollup,
+      log: input.log,
+    });
+    if (feeHeader) {
+      builder.withPendingFeeHeader(feeHeader);
+    }
+  }
+
+  return builder.build();
+}
+
+function derivePendingCheckpointNumber(input: CheckpointSimulationOverridesPlanInput): CheckpointNumber | undefined {
+  if (input.invalidateToPendingCheckpointNumber !== undefined) {
+    return input.invalidateToPendingCheckpointNumber;
+  }
+  if (!input.proposedCheckpointData) {
+    return undefined;
+  }
+  if (input.checkpointNumber < 1) {
+    throw new Error(`Cannot build simulation override for checkpoint ${input.checkpointNumber}: no parent exists`);
+  }
+  const expectedParent = CheckpointNumber(input.checkpointNumber - 1);
+  if (input.proposedCheckpointData.checkpointNumber !== expectedParent) {
+    throw new Error(
+      `Cannot build simulation override for checkpoint ${input.checkpointNumber}: proposedCheckpointData.checkpointNumber (${input.proposedCheckpointData.checkpointNumber}) does not match expected parent ${expectedParent}`,
+    );
+  }
+  return expectedParent;
+}
+
+type PipelinedParentFeeHeaderInput = {
+  checkpointNumber: CheckpointNumber;
+  proposedCheckpointData: ProposedCheckpointData;
+  rollup: RollupContract;
+  log: Logger;
+};
+
+/**
+ * Derives the pending parent fee header used during pipelined proposal simulation. Returns
+ * `undefined` only when no grandparent exists (i.e. the proposed parent is the genesis
+ * checkpoint); all other failure modes (missing grandparent state, missing fee header, RPC
+ * errors) throw so callers don't silently desync the fee-header override.
+ */
+export async function computePipelinedParentFeeHeader(
+  input: PipelinedParentFeeHeaderInput,
+): Promise<FeeHeader | undefined> {
+  if (input.checkpointNumber < 2) {
+    return undefined;
+  }
+
+  const grandparentCheckpointNumber = CheckpointNumber(input.checkpointNumber - 2);
+
+  const [grandparentCheckpoint, manaTarget] = await Promise.all([
+    input.rollup.getCheckpoint(grandparentCheckpointNumber),
+    input.rollup.getManaTarget(),
+  ]);
+
+  if (!grandparentCheckpoint?.feeHeader) {
+    throw new Error(
+      `Grandparent checkpoint or feeHeader missing for checkpoint ${grandparentCheckpointNumber.toString()}`,
+    );
+  }
+
+  return RollupContract.computeChildFeeHeader(
+    grandparentCheckpoint.feeHeader,
+    input.proposedCheckpointData.totalManaUsed,
+    input.proposedCheckpointData.feeAssetPriceModifier,
+    manaTarget,
+  );
+}

package/src/contract/interfaces/contract_data_source.ts

@@ -25,11 +25,9 @@ export interface ContractDataSource {
   /**
    * Returns a publicly deployed contract instance given its address.
    * @param address - Address of the deployed contract.
-   * @param timestamp - Timestamp at which to retrieve the contract instance. If not provided, the latest block should
-   * be used.
-   * TODO(#15170): Fix the implementations ignoring the timestamp param and make timestamp required.
+   * @param timestamp - Timestamp at which to resolve the contract instance's current class id.
    */
-  getContract(address: AztecAddress, timestamp?: UInt64): Promise<ContractInstanceWithAddress | undefined>;
+  getContract(address: AztecAddress, timestamp: UInt64): Promise<ContractInstanceWithAddress | undefined>;
 
   /**
    * Returns the list of all class ids known.

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/interfaces/archiver.ts

@@ -122,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-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>;