@aztec/stdlib 0.0.0-test.0

package/src/contract/contract_class_id.ts

@@ -0,0 +1,70 @@
+import { GeneratorIndex, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS } from '@aztec/constants';
+import { poseidon2HashAccumulate, poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+
+import { strict as assert } from 'assert';
+
+import { bufferAsFields } from '../abi/index.js';
+import type { ContractClass } from './interfaces/contract_class.js';
+import { computePrivateFunctionsRoot } from './private_function.js';
+
+/**
+ * Returns the id of a contract class computed as its hash.
+ *
+ * ```
+ * version = 1
+ * private_function_leaves = private_functions.map(fn => pedersen([fn.function_selector as Field, fn.vk_hash], GENERATOR__FUNCTION_LEAF))
+ * private_functions_root = merkleize(private_function_leaves)
+ * bytecode_commitment = calculate_commitment(packed_bytecode)
+ * contract_class_id = pedersen([version, artifact_hash, private_functions_root, bytecode_commitment], GENERATOR__CLASS_IDENTIFIER)
+ * ```
+ * @param contractClass - Contract class.
+ * @returns The identifier.
+ */
+export async function computeContractClassId(contractClass: ContractClass | ContractClassIdPreimage): Promise<Fr> {
+  return (await computeContractClassIdWithPreimage(contractClass)).id;
+}
+
+/** Computes a contract class id and returns it along with its preimage. */
+export async function computeContractClassIdWithPreimage(
+  contractClass: ContractClass | ContractClassIdPreimage,
+): Promise<ContractClassIdPreimage & { id: Fr }> {
+  const artifactHash = contractClass.artifactHash;
+  const privateFunctionsRoot =
+    'privateFunctionsRoot' in contractClass
+      ? contractClass.privateFunctionsRoot
+      : await computePrivateFunctionsRoot(contractClass.privateFunctions);
+  const publicBytecodeCommitment =
+    'publicBytecodeCommitment' in contractClass
+      ? contractClass.publicBytecodeCommitment
+      : await computePublicBytecodeCommitment(contractClass.packedBytecode);
+  const id = await poseidon2HashWithSeparator(
+    [artifactHash, privateFunctionsRoot, publicBytecodeCommitment],
+    GeneratorIndex.CONTRACT_LEAF, // TODO(@spalladino): Review all generator indices in this file
+  );
+  return { id, artifactHash, privateFunctionsRoot, publicBytecodeCommitment };
+}
+
+/** Returns the preimage of a contract class id given a contract class. */
+export async function computeContractClassIdPreimage(contractClass: ContractClass): Promise<ContractClassIdPreimage> {
+  const privateFunctionsRoot = await computePrivateFunctionsRoot(contractClass.privateFunctions);
+  const publicBytecodeCommitment = await computePublicBytecodeCommitment(contractClass.packedBytecode);
+  return { artifactHash: contractClass.artifactHash, privateFunctionsRoot, publicBytecodeCommitment };
+}
+
+/** Preimage of a contract class id. */
+export type ContractClassIdPreimage = {
+  artifactHash: Fr;
+  privateFunctionsRoot: Fr;
+  publicBytecodeCommitment: Fr;
+};
+
+export async function computePublicBytecodeCommitment(packedBytecode: Buffer) {
+  // Encode the buffer into field elements (chunked into 32 bytes each)
+  const encodedBytecode: Fr[] = bufferAsFields(packedBytecode, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS);
+  // The first element is the length of the bytecode (in bytes)
+  const bytecodeLength = Math.ceil(encodedBytecode[0].toNumber() / (Fr.SIZE_IN_BYTES - 1));
+  assert(bytecodeLength < MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS, 'Bytecode exceeds maximum deployable size');
+
+  return bytecodeLength == 0 ? new Fr(0) : await poseidon2HashAccumulate(encodedBytecode.slice(0, bytecodeLength + 1));
+}

package/src/contract/contract_function_dao.ts

@@ -0,0 +1,13 @@
+import type { FunctionArtifact, FunctionSelector } from '../abi/index.js';
+
+/**
+ * A contract function Data Access Object (DAO).
+ * Extends the FunctionArtifact interface, adding a 'selector' property.
+ * The 'selector' is a unique identifier for the function within the contract.
+ */
+export interface ContractFunctionDao extends FunctionArtifact {
+  /**
+   * Unique identifier for a contract function.
+   */
+  selector: FunctionSelector;
+}

package/src/contract/contract_instance.ts

@@ -0,0 +1,151 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { type ContractArtifact, type FunctionArtifact, FunctionSelector, getDefaultInitializer } from '../abi/index.js';
+import { AztecAddress } from '../aztec-address/index.js';
+import { getContractClassFromArtifact } from '../contract/contract_class.js';
+import { PublicKeys } from '../keys/public_keys.js';
+import {
+  computeContractAddressFromInstance,
+  computeInitializationHash,
+  computeInitializationHashFromEncodedArgs,
+} from './contract_address.js';
+import type { ContractInstance, ContractInstanceWithAddress } from './interfaces/contract_instance.js';
+
+const VERSION = 1 as const;
+
+export class SerializableContractInstance {
+  public readonly version = VERSION;
+  public readonly salt: Fr;
+  public readonly deployer: AztecAddress;
+  public readonly currentContractClassId: Fr;
+  public readonly originalContractClassId: Fr;
+  public readonly initializationHash: Fr;
+  public readonly publicKeys: PublicKeys;
+
+  constructor(instance: ContractInstance) {
+    if (instance.version !== VERSION) {
+      throw new Error(`Unexpected contract class version ${instance.version}`);
+    }
+    this.salt = instance.salt;
+    this.deployer = instance.deployer;
+    this.currentContractClassId = instance.currentContractClassId;
+    this.originalContractClassId = instance.originalContractClassId;
+    this.initializationHash = instance.initializationHash;
+    this.publicKeys = instance.publicKeys;
+  }
+
+  public toBuffer() {
+    return serializeToBuffer(
+      numToUInt8(this.version),
+      this.salt,
+      this.deployer,
+      this.currentContractClassId,
+      this.originalContractClassId,
+      this.initializationHash,
+      this.publicKeys,
+    );
+  }
+
+  /** Returns a copy of this object with its address included. */
+  withAddress(address: AztecAddress): ContractInstanceWithAddress {
+    return { ...this, address };
+  }
+
+  static fromBuffer(bufferOrReader: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(bufferOrReader);
+    return new SerializableContractInstance({
+      version: reader.readUInt8() as typeof VERSION,
+      salt: reader.readObject(Fr),
+      deployer: reader.readObject(AztecAddress),
+      currentContractClassId: reader.readObject(Fr),
+      originalContractClassId: reader.readObject(Fr),
+      initializationHash: reader.readObject(Fr),
+      publicKeys: reader.readObject(PublicKeys),
+    });
+  }
+
+  static async random(opts: Partial<FieldsOf<ContractInstance>> = {}) {
+    return new SerializableContractInstance({
+      version: VERSION,
+      salt: Fr.random(),
+      deployer: await AztecAddress.random(),
+      currentContractClassId: Fr.random(),
+      originalContractClassId: Fr.random(),
+      initializationHash: Fr.random(),
+      publicKeys: await PublicKeys.random(),
+      ...opts,
+    });
+  }
+
+  static default() {
+    return new SerializableContractInstance({
+      version: VERSION,
+      salt: Fr.zero(),
+      deployer: AztecAddress.zero(),
+      currentContractClassId: Fr.zero(),
+      originalContractClassId: Fr.zero(),
+      initializationHash: Fr.zero(),
+      publicKeys: PublicKeys.default(),
+    });
+  }
+}
+
+/**
+ * Generates a Contract Instance from the deployment params.
+ * @param artifact - The account contract build artifact.
+ * @param opts - Options for the deployment.
+ * @returns - The contract instance
+ */
+export async function getContractInstanceFromDeployParams(
+  artifact: ContractArtifact,
+  opts: {
+    constructorArtifact?: FunctionArtifact | string;
+    constructorArgs?: any[];
+    skipArgsDecoding?: boolean;
+    salt?: Fr;
+    publicKeys?: PublicKeys;
+    deployer?: AztecAddress;
+  },
+): Promise<ContractInstanceWithAddress> {
+  const args = opts.constructorArgs ?? [];
+  const salt = opts.salt ?? Fr.random();
+  const constructorArtifact = getConstructorArtifact(artifact, opts.constructorArtifact);
+  const deployer = opts.deployer ?? AztecAddress.ZERO;
+  const contractClass = await getContractClassFromArtifact(artifact);
+  const initializationHash =
+    constructorArtifact && opts?.skipArgsDecoding
+      ? await computeInitializationHashFromEncodedArgs(
+          await FunctionSelector.fromNameAndParameters(constructorArtifact?.name, constructorArtifact?.parameters),
+          args,
+        )
+      : await computeInitializationHash(constructorArtifact, args);
+  const publicKeys = opts.publicKeys ?? PublicKeys.default();
+
+  const instance: ContractInstance = {
+    currentContractClassId: contractClass.id,
+    originalContractClassId: contractClass.id,
+    initializationHash,
+    publicKeys,
+    salt,
+    deployer,
+    version: 1,
+  };
+
+  return { ...instance, address: await computeContractAddressFromInstance(instance) };
+}
+
+function getConstructorArtifact(
+  artifact: ContractArtifact,
+  requestedConstructorArtifact: FunctionArtifact | string | undefined,
+): FunctionArtifact | undefined {
+  if (typeof requestedConstructorArtifact === 'string') {
+    const found = artifact.functions.find(fn => fn.name === requestedConstructorArtifact);
+    if (!found) {
+      throw new Error(`No constructor found with name ${requestedConstructorArtifact}`);
+    }
+    return found;
+  }
+  return requestedConstructorArtifact ?? getDefaultInitializer(artifact);
+}

package/src/contract/contract_instance_update.ts

@@ -0,0 +1,47 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import type { ContractInstanceUpdate } from './interfaces/contract_instance_update.js';
+
+export class SerializableContractInstanceUpdate {
+  prevContractClassId: Fr;
+  newContractClassId: Fr;
+  blockOfChange: number;
+
+  constructor(instance: ContractInstanceUpdate) {
+    this.prevContractClassId = instance.prevContractClassId;
+    this.newContractClassId = instance.newContractClassId;
+    this.blockOfChange = instance.blockOfChange;
+  }
+
+  public toBuffer() {
+    return serializeToBuffer(this.prevContractClassId, this.newContractClassId, this.blockOfChange);
+  }
+
+  static fromBuffer(bufferOrReader: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(bufferOrReader);
+    return new SerializableContractInstanceUpdate({
+      prevContractClassId: reader.readObject(Fr),
+      newContractClassId: reader.readObject(Fr),
+      blockOfChange: reader.readNumber(),
+    });
+  }
+
+  static random(opts: Partial<FieldsOf<ContractInstanceUpdate>> = {}) {
+    return new SerializableContractInstanceUpdate({
+      prevContractClassId: Fr.random(),
+      newContractClassId: Fr.random(),
+      blockOfChange: Math.floor(Math.random() * 1000),
+      ...opts,
+    });
+  }
+
+  static default() {
+    return new SerializableContractInstanceUpdate({
+      prevContractClassId: Fr.zero(),
+      newContractClassId: Fr.zero(),
+      blockOfChange: 0,
+    });
+  }
+}

package/src/contract/deployment_info.ts

@@ -0,0 +1,25 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import type { CompleteAddress } from './complete_address.js';
+
+/**
+ * Represents the data generated as part of contract deployment.
+ */
+export type DeploymentInfo = {
+  /**
+   * The complete address of the deployed contract.
+   */
+  completeAddress: CompleteAddress;
+  /**
+   * The contract's constructor verification key hash.
+   */
+  constructorVkHash: Fr;
+  /**
+   * The contract's constructor hash.
+   */
+  constructorHash: Fr;
+  /**
+   * The root of the contract's function tree.
+   */
+  functionTreeRoot: Fr;
+};

package/src/contract/index.ts

@@ -0,0 +1,14 @@
+export * from './artifact_hash.js';
+export * from './contract_address.js';
+export * from './contract_class.js';
+export * from './contract_class_id.js';
+export * from './contract_instance.js';
+export * from './contract_instance_update.js';
+export * from './private_function.js';
+export * from './private_function_membership_proof.js';
+export * from './unconstrained_function_membership_proof.js';
+export * from './interfaces/index.js';
+export * from './contract_function_dao.js';
+export * from './partial_address.js';
+export * from './deployment_info.js';
+export * from './complete_address.js';

package/src/contract/interfaces/contract_class.ts

@@ -0,0 +1,167 @@
+import type { Fr } from '@aztec/foundation/fields';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { FunctionSelector } from '../../abi/index.js';
+
+const VERSION = 1 as const;
+
+/**
+ * A Contract Class in the protocol. Aztec differentiates contracts classes and instances, where a
+ * contract class represents the code of the contract, but holds no state. Classes are identified by
+ * an id that is a commitment to all its data.
+ */
+export interface ContractClass {
+  /** Version of the contract class. */
+  version: typeof VERSION;
+  /** Hash of the contract artifact. The specification of this hash is not enforced by the protocol. Should include commitments to unconstrained code and compilation metadata. Intended to be used by clients to verify that an off-chain fetched artifact matches a registered class. */
+  artifactHash: Fr;
+  /** List of individual private functions, constructors included. */
+  privateFunctions: PrivateFunction[];
+  // TODO(https://github.com/AztecProtocol/aztec-packages/issues/8985): Remove public functions.
+  /** Contains the public_dispatch function (and only that) if there's any public code in the contract. */
+  publicFunctions: PublicFunction[];
+  /** Bytecode for the public_dispatch function, or empty. */
+  packedBytecode: Buffer;
+}
+
+/** Private function definition within a contract class. */
+export interface PrivateFunction {
+  /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
+  selector: FunctionSelector;
+  /** Hash of the verification key associated to this private function. */
+  vkHash: Fr;
+}
+
+const PrivateFunctionSchema = z.object({
+  selector: FunctionSelector.schema,
+  vkHash: schemas.Fr,
+}) satisfies ZodFor<PrivateFunction>;
+
+/** Private function definition with executable bytecode. */
+export interface ExecutablePrivateFunction extends PrivateFunction {
+  /** ACIR and Brillig bytecode */
+  bytecode: Buffer;
+}
+
+const ExecutablePrivateFunctionSchema = PrivateFunctionSchema.and(
+  z.object({ bytecode: schemas.Buffer }),
+) satisfies ZodFor<ExecutablePrivateFunction>;
+
+/** Public function definition within a contract class. */
+export interface PublicFunction {
+  /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
+  selector: FunctionSelector;
+  /** Public bytecode. */
+  bytecode: Buffer;
+}
+
+export const PublicFunctionSchema = z.object({
+  selector: FunctionSelector.schema,
+  bytecode: schemas.Buffer,
+}) satisfies ZodFor<PublicFunction>;
+
+/** Unconstrained function definition. */
+export interface UnconstrainedFunction {
+  /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
+  selector: FunctionSelector;
+  /** Brillig. */
+  bytecode: Buffer;
+}
+
+const UnconstrainedFunctionSchema = z.object({
+  /** lala */
+  selector: FunctionSelector.schema,
+  bytecode: schemas.Buffer,
+}) satisfies ZodFor<UnconstrainedFunction>;
+
+/** Sibling paths and sibling commitments for proving membership of a private function within a contract class. */
+export type PrivateFunctionMembershipProof = {
+  artifactMetadataHash: Fr;
+  functionMetadataHash: Fr;
+  unconstrainedFunctionsArtifactTreeRoot: Fr;
+  privateFunctionTreeSiblingPath: Fr[];
+  privateFunctionTreeLeafIndex: number;
+  artifactTreeSiblingPath: Fr[];
+  artifactTreeLeafIndex: number;
+};
+
+const PrivateFunctionMembershipProofSchema = z.object({
+  artifactMetadataHash: schemas.Fr,
+  functionMetadataHash: schemas.Fr,
+  unconstrainedFunctionsArtifactTreeRoot: schemas.Fr,
+  privateFunctionTreeSiblingPath: z.array(schemas.Fr),
+  privateFunctionTreeLeafIndex: schemas.Integer,
+  artifactTreeSiblingPath: z.array(schemas.Fr),
+  artifactTreeLeafIndex: schemas.Integer,
+}) satisfies ZodFor<PrivateFunctionMembershipProof>;
+
+/** A private function with a memebership proof. */
+export type ExecutablePrivateFunctionWithMembershipProof = ExecutablePrivateFunction & PrivateFunctionMembershipProof;
+
+/** Sibling paths and commitments for proving membership of an unconstrained function within a contract class. */
+export type UnconstrainedFunctionMembershipProof = {
+  artifactMetadataHash: Fr;
+  functionMetadataHash: Fr;
+  privateFunctionsArtifactTreeRoot: Fr;
+  artifactTreeSiblingPath: Fr[];
+  artifactTreeLeafIndex: number;
+};
+
+const UnconstrainedFunctionMembershipProofSchema = z.object({
+  artifactMetadataHash: schemas.Fr,
+  functionMetadataHash: schemas.Fr,
+  privateFunctionsArtifactTreeRoot: schemas.Fr,
+  artifactTreeSiblingPath: z.array(schemas.Fr),
+  artifactTreeLeafIndex: schemas.Integer,
+}) satisfies ZodFor<UnconstrainedFunctionMembershipProof>;
+
+/** An unconstrained function with a membership proof. */
+export type UnconstrainedFunctionWithMembershipProof = UnconstrainedFunction & UnconstrainedFunctionMembershipProof;
+
+export const ContractClassSchema = z.object({
+  version: z.literal(VERSION),
+  artifactHash: schemas.Fr,
+  privateFunctions: z.array(PrivateFunctionSchema),
+  publicFunctions: z.array(PublicFunctionSchema),
+  packedBytecode: schemas.Buffer,
+}) satisfies ZodFor<ContractClass>;
+
+/** Commitments to fields of a contract class. */
+interface ContractClassCommitments {
+  /** Identifier of the contract class. */
+  id: Fr;
+  /** Commitment to the public bytecode. */
+  publicBytecodeCommitment: Fr;
+  /** Root of the private functions tree  */
+  privateFunctionsRoot: Fr;
+}
+
+/** A contract class with its precomputed id. */
+export type ContractClassWithId = ContractClass & Pick<ContractClassCommitments, 'id'>;
+
+export const ContractClassWithIdSchema = ContractClassSchema.extend({
+  id: schemas.Fr,
+}) satisfies ZodFor<ContractClassWithId>;
+
+/** A contract class with public bytecode information, and optional private and unconstrained. */
+export type ContractClassPublic = {
+  privateFunctions: ExecutablePrivateFunctionWithMembershipProof[];
+  unconstrainedFunctions: UnconstrainedFunctionWithMembershipProof[];
+} & Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
+  Omit<ContractClass, 'privateFunctions'>;
+export type ContractClassWithCommitment = ContractClassPublic &
+  Pick<ContractClassCommitments, 'publicBytecodeCommitment'>;
+
+export const ContractClassPublicSchema = z
+  .object({
+    id: schemas.Fr,
+    privateFunctionsRoot: schemas.Fr,
+    privateFunctions: z.array(ExecutablePrivateFunctionSchema.and(PrivateFunctionMembershipProofSchema)),
+    unconstrainedFunctions: z.array(UnconstrainedFunctionSchema.and(UnconstrainedFunctionMembershipProofSchema)),
+  })
+  .and(ContractClassSchema.omit({ privateFunctions: true })) satisfies ZodFor<ContractClassPublic>;
+
+/** The contract class with the block it was initially deployed at */
+export type ContractClassPublicWithBlockNumber = { l2BlockNumber: number } & ContractClassPublic;

package/src/contract/interfaces/contract_data_source.ts

@@ -0,0 +1,52 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { FunctionSelector } from '../../abi/index.js';
+import type { AztecAddress } from '../../aztec-address/index.js';
+import type { ContractClassPublic, PublicFunction } from './contract_class.js';
+import type { ContractInstanceWithAddress } from './contract_instance.js';
+
+export interface ContractDataSource {
+  /**
+   * Returns a contract's encoded public function, given its function selector.
+   * @param address - The contract aztec address.
+   * @param selector - The function's selector.
+   * @returns The function's data.
+   */
+  getPublicFunction(address: AztecAddress, selector: FunctionSelector): Promise<PublicFunction | undefined>;
+
+  /**
+   * Gets the number of the latest L2 block processed by the implementation.
+   * @returns The number of the latest L2 block processed by the implementation.
+   */
+  getBlockNumber(): Promise<number>;
+
+  /**
+   * Returns the contract class for a given contract class id, or undefined if not found.
+   * @param id - Contract class id.
+   */
+  getContractClass(id: Fr): Promise<ContractClassPublic | undefined>;
+
+  getBytecodeCommitment(id: Fr): Promise<Fr | undefined>;
+
+  /**
+   * Adds a contract class to the database.
+   * TODO(#10007): Remove this method
+   */
+  addContractClass(contractClass: ContractClassPublic): Promise<void>;
+
+  /**
+   * Returns a publicly deployed contract instance given its address.
+   * @param address - Address of the deployed contract.
+   */
+  getContract(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+
+  /**
+   * Returns the list of all class ids known.
+   */
+  getContractClassIds(): Promise<Fr[]>;
+
+  /** Returns a function's name */
+  getContractFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+  /** Registers a function names. Useful for debugging. */
+  registerContractFunctionSignatures(address: AztecAddress, signatures: string[]): Promise<void>;
+}

package/src/contract/interfaces/contract_instance.ts

@@ -0,0 +1,47 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import { PublicKeys } from '../../keys/public_keys.js';
+import { type ZodFor, schemas } from '../../schemas/index.js';
+
+const VERSION = 1 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.
+ */
+export interface ContractInstance {
+  /** 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. */
+  initializationHash: Fr;
+  /** Public keys associated with this instance. */
+  publicKeys: PublicKeys;
+}
+
+export type ContractInstanceWithAddress = ContractInstance & { address: AztecAddress };
+
+export const ContractInstanceSchema = z.object({
+  version: z.literal(VERSION),
+  salt: schemas.Fr,
+  deployer: schemas.AztecAddress,
+  currentContractClassId: schemas.Fr,
+  originalContractClassId: schemas.Fr,
+  initializationHash: schemas.Fr,
+  publicKeys: PublicKeys.schema,
+}) satisfies ZodFor<ContractInstance>;
+
+export const ContractInstanceWithAddressSchema = ContractInstanceSchema.and(
+  z.object({ address: schemas.AztecAddress }),
+) satisfies ZodFor<ContractInstanceWithAddress>;

package/src/contract/interfaces/contract_instance_update.ts

@@ -0,0 +1,30 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import { type ZodFor, schemas } from '../../schemas/index.js';
+
+/**
+ * An update to a contract instance, changing its contract class.
+ */
+export interface ContractInstanceUpdate {
+  /** Identifier of the previous contract class for this instance */
+  prevContractClassId: Fr;
+  /** Identifier of the new contract class for this instance. */
+  newContractClassId: Fr;
+  /** The block number where the contract class in use will be the new one */
+  blockOfChange: number;
+}
+
+export type ContractInstanceUpdateWithAddress = ContractInstanceUpdate & { address: AztecAddress };
+
+export const ContractInstanceUpdateSchema = z.object({
+  prevContractClassId: schemas.Fr,
+  newContractClassId: schemas.Fr,
+  blockOfChange: z.number().int().nonnegative(),
+}) satisfies ZodFor<ContractInstanceUpdate>;
+
+export const ContractInstanceUpdateWithAddressSchema = ContractInstanceUpdateSchema.and(
+  z.object({ address: schemas.AztecAddress }),
+) satisfies ZodFor<ContractInstanceUpdateWithAddress>;

package/src/contract/interfaces/index.ts

@@ -0,0 +1,6 @@
+export * from './contract_class.js';
+export * from './contract_data_source.js';
+export * from './contract_instance.js';
+export * from './contract_instance_update.js';
+export * from './node-info.js';
+export * from './protocol_contract_addresses.js';

package/src/contract/interfaces/node-info.ts

@@ -0,0 +1,33 @@
+import { type L1ContractAddresses, L1ContractAddressesSchema } from '@aztec/ethereum/l1-contract-addresses';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { type ProtocolContractAddresses, ProtocolContractAddressesSchema } from './protocol_contract_addresses.js';
+
+/** Provides basic information about the running node. */
+export interface NodeInfo {
+  /** Version as tracked in the aztec-packages repository. */
+  nodeVersion: string;
+  /** L1 chain id. */
+  l1ChainId: number;
+  /** Protocol version. */
+  protocolVersion: number;
+  /** The node's ENR. */
+  enr: string | undefined;
+  /** The deployed l1 contract addresses */
+  l1ContractAddresses: L1ContractAddresses;
+  /** Protocol contract addresses */
+  protocolContractAddresses: ProtocolContractAddresses;
+}
+
+export const NodeInfoSchema: ZodFor<NodeInfo> = z
+  .object({
+    nodeVersion: z.string(),
+    l1ChainId: z.number().int().nonnegative(),
+    protocolVersion: z.number().int().nonnegative(),
+    enr: z.string().optional(),
+    l1ContractAddresses: L1ContractAddressesSchema,
+    protocolContractAddresses: ProtocolContractAddressesSchema,
+  })
+  .transform(obj => ({ enr: undefined, ...obj }));