@aztec/stdlib 5.0.0-rc.1 → 5.0.0

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/block/validate_block_result.ts

@@ -1,7 +1,9 @@
+import type { ViemCommitteeAttestations } from '@aztec/ethereum/contracts';
 import { EpochNumber, EpochNumberSchema } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type ZodFor, schemas } from '@aztec/foundation/schemas';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 
 import { z } from 'zod';
 
@@ -30,6 +32,14 @@ export type ValidateCheckpointNegativeResult =
       attestors: EthAddress[];
       /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
+      /**
+       * The exact packed `CommitteeAttestations` tuple as posted to L1 calldata, carried verbatim so the
+       * invalidation evidence is byte-faithful to the stored `attestationsHash`. A repack via
+       * `packAttestations` is not a round-trip inverse of `fromPacked`, so it would diverge from the hash
+       * and revert `invalidateBadAttestation`/`invalidateInsufficientAttestations`. Always populated on the
+       * calldata validation path, the only production source of invalidation evidence.
+       */
+      verbatimAttestations: ViemCommitteeAttestations;
       /** Reason for the checkpoint being invalid: not enough attestations were posted */
       reason: 'insufficient-attestations';
     }
@@ -47,6 +57,12 @@ export type ValidateCheckpointNegativeResult =
       attestors: EthAddress[];
       /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
+      /**
+       * The exact packed `CommitteeAttestations` tuple as posted to L1 calldata, carried verbatim so the
+       * invalidation evidence is byte-faithful to the stored `attestationsHash`. See the same field on the
+       * insufficient-attestations variant for why a repack cannot be used.
+       */
+      verbatimAttestations: ViemCommitteeAttestations;
       /** Reason for the checkpoint being invalid: an invalid attestation was posted */
       reason: 'invalid-attestation';
       /** Index in the attestations array of the invalid attestation posted */
@@ -56,6 +72,12 @@ export type ValidateCheckpointNegativeResult =
 /** Result type for validating checkpoint attestations */
 export type ValidateCheckpointResult = { valid: true } | ValidateCheckpointNegativeResult;
 
+/** Zod schema for the raw packed `CommitteeAttestations` viem tuple (two 0x-prefixed hex strings). */
+const ViemCommitteeAttestationsSchema: ZodFor<ViemCommitteeAttestations> = z.object({
+  signatureIndices: schemas.HexStringWith0x,
+  signaturesOrAddresses: schemas.HexStringWith0x,
+});
+
 export const ValidateCheckpointResultSchema: ZodFor<ValidateCheckpointResult> = z.union([
   z.object({ valid: z.literal(true) }),
   z.object({
@@ -66,6 +88,7 @@ export const ValidateCheckpointResultSchema: ZodFor<ValidateCheckpointResult> =
     seed: schemas.BigInt,
     attestors: z.array(schemas.EthAddress),
     attestations: z.array(CommitteeAttestation.schema),
+    verbatimAttestations: ViemCommitteeAttestationsSchema,
     reason: z.literal('insufficient-attestations'),
   }),
   z.object({
@@ -76,6 +99,7 @@ export const ValidateCheckpointResultSchema: ZodFor<ValidateCheckpointResult> =
     seed: schemas.BigInt,
     attestors: z.array(schemas.EthAddress),
     attestations: z.array(CommitteeAttestation.schema),
+    verbatimAttestations: ViemCommitteeAttestationsSchema,
     reason: z.literal('invalid-attestation'),
     invalidIndex: z.number(),
   }),
@@ -87,6 +111,8 @@ export function serializeValidateCheckpointResult(result: ValidateCheckpointResu
   }
 
   const checkpointBuffer = serializeCheckpointInfo(result.checkpoint);
+  const signatureIndices = hexToBuffer(result.verbatimAttestations.signatureIndices);
+  const signaturesOrAddresses = hexToBuffer(result.verbatimAttestations.signaturesOrAddresses);
   return serializeToBuffer(
     result.valid,
     result.reason,
@@ -101,6 +127,10 @@ export function serializeValidateCheckpointResult(result: ValidateCheckpointResu
     result.attestations.length,
     result.attestations,
     result.reason === 'invalid-attestation' ? result.invalidIndex : 0,
+    signatureIndices.length,
+    signatureIndices,
+    signaturesOrAddresses.length,
+    signaturesOrAddresses,
   );
 }
 
@@ -118,10 +148,26 @@ export function deserializeValidateCheckpointResult(bufferOrReader: Buffer | Buf
   const attestors = reader.readVector(EthAddress, MAX_COMMITTEE_SIZE);
   const attestations = reader.readVector(CommitteeAttestation, MAX_COMMITTEE_SIZE);
   const invalidIndex = reader.readNumber();
+  const verbatimAttestations: ViemCommitteeAttestations = {
+    signatureIndices: bufferToHex(reader.readBuffer()),
+    signaturesOrAddresses: bufferToHex(reader.readBuffer()),
+  };
+
   if (reason === 'insufficient-attestations') {
-    return { valid, reason, checkpoint, committee, epoch, seed, attestors, attestations };
+    return { valid, reason, checkpoint, committee, epoch, seed, attestors, attestations, verbatimAttestations };
   } else if (reason === 'invalid-attestation') {
-    return { valid, reason, checkpoint, committee, epoch, seed, attestors, invalidIndex, attestations };
+    return {
+      valid,
+      reason,
+      checkpoint,
+      committee,
+      epoch,
+      seed,
+      attestors,
+      invalidIndex,
+      attestations,
+      verbatimAttestations,
+    };
   } else {
     const _: never = reason;
     throw new Error(`Unknown reason: ${reason}`);

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/config/network-consensus-config.ts

@@ -1,4 +1,4 @@
-import { type L1ContractsConfig, l1ContractsConfigMappings } from '@aztec/ethereum/config';
+import { type L1ContractsConfig, l1ContractsConfigMappings, validateSlotDurations } from '@aztec/ethereum/config';
 import { type EnvVar, pickConfigMappings } from '@aztec/foundation/config';
 
 import type { SequencerConfig } from '../interfaces/configs.js';
@@ -156,21 +156,10 @@ export function validateNetworkConsensusConfig(config: NetworkConsensusConfig):
     return errors;
   }
 
-  if (config.ethereumSlotDuration <= 0) {
-    errors.push(`ethereumSlotDuration must be positive (got ${config.ethereumSlotDuration})`);
-  }
+  errors.push(...validateSlotDurations(config));
   if (config.blockDurationMs <= 0) {
     errors.push(`blockDurationMs must be positive (got ${config.blockDurationMs})`);
   }
-  if (config.aztecSlotDuration <= 0) {
-    errors.push(`aztecSlotDuration must be positive (got ${config.aztecSlotDuration})`);
-  }
-  if (config.ethereumSlotDuration > 0 && config.aztecSlotDuration % config.ethereumSlotDuration !== 0) {
-    errors.push(
-      `aztecSlotDuration (${config.aztecSlotDuration}s) must be a multiple of ethereumSlotDuration ` +
-        `(${config.ethereumSlotDuration}s)`,
-    );
-  }
   if (config.blockDurationMs / 1000 > config.aztecSlotDuration) {
     errors.push(
       `blockDurationMs (${config.blockDurationMs}ms) exceeds aztecSlotDuration (${config.aztecSlotDuration}s)`,

package/src/contract/contract_address.ts

@@ -6,7 +6,8 @@ import { type FunctionAbi, FunctionSelector, encodeArguments } from '../abi/inde
 import type { AztecAddress } from '../aztec-address/index.js';
 import { computeVarArgsHash } from '../hash/hash.js';
 import { computeAddress } from '../keys/index.js';
-import type { ContractInstance } from './interfaces/contract_instance.js';
+import type { ContractInstance, ContractInstancePreimage } from './interfaces/contract_instance.js';
+import type { PartialAddress } from './partial_address.js';
 
 // TODO(@spalladino): Review all generator indices in this file
 
@@ -21,7 +22,7 @@ import type { ContractInstance } from './interfaces/contract_instance.js';
  */
 export async function computeContractAddressFromInstance(
   instance:
-    | ContractInstance
+    | ContractInstancePreimage
     | ({ originalContractClassId: Fr; saltedInitializationHash: Fr } & Pick<ContractInstance, 'publicKeys'>),
 ): Promise<AztecAddress> {
   const partialAddress = await computePartialAddress(instance);
@@ -36,7 +37,7 @@ export async function computePartialAddress(
   instance:
     | Pick<ContractInstance, 'originalContractClassId' | 'initializationHash' | 'salt' | 'deployer' | 'immutablesHash'>
     | { originalContractClassId: Fr; saltedInitializationHash: Fr },
-): Promise<Fr> {
+): Promise<PartialAddress> {
   const saltedInitializationHash =
     'saltedInitializationHash' in instance
       ? instance.saltedInitializationHash

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_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/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;