@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/contract/complete_address.ts

@@ -0,0 +1,159 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { hexSchemaFor } from '@aztec-labs/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { bufferToHex } from '@aztec-labs/foundation/string';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { computeAddress, computePreaddress, deriveKeys } from '../keys/index.js';
+import { PublicKeys } from '../keys/public_keys.js';
+import { computePartialAddress } from './contract_address.js';
+import type { PartialAddress } from './partial_address.js';
+
+/**
+ * A complete address is a combination of an Aztec address, a public key and a partial address.
+ *
+ * @remarks We have introduced this type because it is common that these 3 values are used together. They are commonly
+ *          used together because it is the information needed to send user a note.
+ * @remarks See the link below for details about how address is computed:
+ *          https://github.com/AztecProtocol/aztec-packages/blob/master/docs/docs/concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys
+ */
+export class CompleteAddress {
+  private constructor(
+    /** Contract address (typically of an account contract) */
+    public address: AztecAddress,
+    /** User public keys */
+    public publicKeys: PublicKeys,
+    /** Partial key corresponding to the public key to the address. */
+    public partialAddress: PartialAddress,
+  ) {}
+
+  static async create(
+    address: AztecAddress,
+    publicKeys: PublicKeys,
+    partialAddress: PartialAddress,
+  ): Promise<CompleteAddress> {
+    const completeAddress = new CompleteAddress(address, publicKeys, partialAddress);
+    await completeAddress.validate();
+    return completeAddress;
+  }
+
+  /** Size in bytes of an instance */
+  // address (1 Fr) + publicKeys (1 Fr hash + 1 Point + 4 Fr hashes = 7 Fr) + partialAddress (1 Fr) = 9 Fr
+  static readonly SIZE_IN_BYTES = 32 * 9;
+
+  static get schema() {
+    return hexSchemaFor(CompleteAddress);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static async random(): Promise<CompleteAddress> {
+    return await this.fromSecretKeyAndPartialAddress(Fr.random(), Fr.random());
+  }
+
+  static async fromSecretKeyAndPartialAddress(secretKey: Fr, partialAddress: Fr): Promise<CompleteAddress> {
+    const { publicKeys } = await deriveKeys(secretKey);
+    return await this.fromPublicKeysAndPartialAddress(publicKeys, partialAddress);
+  }
+
+  static async fromPublicKeysAndPartialAddress(publicKeys: PublicKeys, partialAddress: Fr): Promise<CompleteAddress> {
+    const address = await computeAddress(publicKeys, partialAddress);
+    return new CompleteAddress(address, publicKeys, partialAddress);
+  }
+
+  async getPreaddress() {
+    return computePreaddress(await this.publicKeys.hash(), this.partialAddress);
+  }
+
+  static async fromSecretKeyAndInstance(
+    secretKey: Fr,
+    instance: Parameters<typeof computePartialAddress>[0],
+  ): Promise<CompleteAddress> {
+    const partialAddress = await computePartialAddress(instance);
+    return CompleteAddress.fromSecretKeyAndPartialAddress(secretKey, partialAddress);
+  }
+
+  /** Throws if the address is not correctly derived from the public key and partial address.*/
+  public async validate() {
+    const expectedAddress = await computeAddress(this.publicKeys, this.partialAddress);
+
+    if (!expectedAddress.equals(this.address)) {
+      throw new Error(
+        `Address cannot be derived from public keys and partial address (received ${this.address.toString()}, derived ${expectedAddress.toString()})`,
+      );
+    }
+  }
+
+  /**
+   * Gets a readable string representation of the complete address.
+   * @returns A readable string representation of the complete address.
+   */
+  public toReadableString(): string {
+    return `Address: ${this.address.toString()}\nNpkM hash: ${this.publicKeys.npkMHash.toString()}\nIvpkM: ${this.publicKeys.ivpkM.toString()}\nOvpkM hash: ${this.publicKeys.ovpkMHash.toString()}\nTpkM hash: ${this.publicKeys.tpkMHash.toString()}\nMspkM hash: ${this.publicKeys.mspkMHash.toString()}\nFbpkM hash: ${this.publicKeys.fbpkMHash.toString()}\nPartial Address: ${this.partialAddress.toString()}\n`;
+  }
+
+  /**
+   * Determines if this CompleteAddress instance is equal to the given CompleteAddress instance.
+   * Equality is based on the content of their respective buffers.
+   *
+   * @param other - The CompleteAddress instance to compare against.
+   * @returns True if the buffers of both instances are equal, false otherwise.
+   */
+  equals(other: CompleteAddress): boolean {
+    return (
+      this.address.equals(other.address) &&
+      this.publicKeys.equals(other.publicKeys) &&
+      this.partialAddress.equals(other.partialAddress)
+    );
+  }
+
+  /**
+   * Converts the CompleteAddress instance into a Buffer.
+   * This method should be used when encoding the address for storage, transmission or serialization purposes.
+   *
+   * @returns A Buffer representation of the CompleteAddress instance.
+   */
+  toBuffer(): Buffer {
+    return serializeToBuffer([this.address, this.publicKeys, this.partialAddress]);
+  }
+
+  /**
+   * Creates an CompleteAddress instance from a given buffer or BufferReader.
+   * If the input is a Buffer, it wraps it in a BufferReader before processing.
+   * Throws an error if the input length is not equal to the expected size.
+   *
+   * @param buffer - The input buffer or BufferReader containing the address data.
+   * @returns - A new CompleteAddress instance with the extracted address data.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): Promise<CompleteAddress> {
+    const reader = BufferReader.asReader(buffer);
+    const address = reader.readObject(AztecAddress);
+    const publicKeys = reader.readObject(PublicKeys);
+    const partialAddress = reader.readObject(Fr);
+    return CompleteAddress.create(address, publicKeys, partialAddress);
+  }
+
+  /**
+   * Create a CompleteAddress instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 128 hex characters representing the x and y coordinates.
+   * Throws an error if the input length is invalid or coordinate values are out of range.
+   *
+   * @param address - The hex-encoded string representing the complete address.
+   * @returns A Point instance.
+   */
+  static fromString(address: string): Promise<CompleteAddress> {
+    return CompleteAddress.fromBuffer(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
+  }
+
+  /**
+   * Convert the CompleteAddress to a hexadecimal string representation, with a "0x" prefix.
+   * The resulting string will have a length of 66 characters (including the prefix).
+   *
+   * @returns A hexadecimal string representation of the CompleteAddress.
+   */
+  toString(): string {
+    return bufferToHex(this.toBuffer());
+  }
+}

package/src/contract/contract_address.ts

@@ -0,0 +1,92 @@
+import { DomainSeparator } from '@aztec-labs/constants';
+import { poseidon2HashWithSeparator } from '@aztec-labs/foundation/crypto/poseidon';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import { type FunctionAbi, FunctionSelector, encodeArguments } from '../abi/index.js';
+import type { AztecAddress } from '../aztec-address/index.js';
+import { computeVarArgsHash } from '../hash/hash.js';
+import { computeAddress } from '../keys/index.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
+
+/**
+ * Returns the deployment address for a given contract instance.
+ * ```
+ * salted_initialization_hash = poseidon2(DOM_SEP__SALTED_INITIALIZATION_HASH, [salt, initialization_hash, deployer, immutables_hash])
+ * partial_address = poseidon2(DOM_SEP__PARTIAL_ADDRESS, [contract_class_id, salted_initialization_hash])
+ * address = ((poseidon2(DOM_SEP__CONTRACT_ADDRESS_V2, [public_keys_hash, partial_address]) * G) + ivpk_m).x <- the x-coordinate of the address point
+ * ```
+ * @param instance - A contract instance for which to calculate the deployment address.
+ */
+export async function computeContractAddressFromInstance(
+  instance:
+    | ContractInstancePreimage
+    | ({ originalContractClassId: Fr; saltedInitializationHash: Fr } & Pick<ContractInstance, 'publicKeys'>),
+): Promise<AztecAddress> {
+  const partialAddress = await computePartialAddress(instance);
+  return computeAddress(instance.publicKeys, partialAddress);
+}
+
+/**
+ * Computes the partial address defined as the hash of the contract class id and salted initialization hash.
+ * @param instance - Contract instance for which to calculate the partial address.
+ */
+export async function computePartialAddress(
+  instance:
+    | Pick<ContractInstance, 'originalContractClassId' | 'initializationHash' | 'salt' | 'deployer' | 'immutablesHash'>
+    | { originalContractClassId: Fr; saltedInitializationHash: Fr },
+): Promise<PartialAddress> {
+  const saltedInitializationHash =
+    'saltedInitializationHash' in instance
+      ? instance.saltedInitializationHash
+      : await computeSaltedInitializationHash(instance);
+
+  return poseidon2HashWithSeparator(
+    [instance.originalContractClassId, saltedInitializationHash],
+    DomainSeparator.PARTIAL_ADDRESS,
+  );
+}
+
+/**
+ * Computes the salted initialization hash for an address, defined as the hash of the salt and initialization hash.
+ * @param instance - Contract instance for which to compute the salted initialization hash.
+ */
+export function computeSaltedInitializationHash(
+  instance: Pick<ContractInstance, 'initializationHash' | 'salt' | 'deployer' | 'immutablesHash'>,
+): Promise<Fr> {
+  return poseidon2HashWithSeparator(
+    [instance.salt, instance.initializationHash, instance.deployer, instance.immutablesHash],
+    DomainSeparator.SALTED_INITIALIZATION_HASH,
+  );
+}
+
+/**
+ * Computes the initialization hash for an instance given its constructor function and arguments.
+ * @param initFn - Constructor function or empty if no initialization is expected.
+ * @param args - Unencoded arguments, will be encoded as fields according to the constructor function abi.
+ * @returns The hash, or zero if no initialization function is provided.
+ */
+export async function computeInitializationHash(initFn: FunctionAbi | undefined, args: any[]): Promise<Fr> {
+  if (!initFn) {
+    return Fr.ZERO;
+  }
+  const selector = await FunctionSelector.fromNameAndParameters(initFn.name, initFn.parameters);
+  const flatArgs = encodeArguments(initFn, args);
+  return computeInitializationHashFromEncodedArgs(selector, flatArgs);
+}
+
+/**
+ * Computes the initialization hash for an instance given its constructor function selector and encoded arguments.
+ * @param initFn - Constructor function selector.
+ * @param args - Encoded arguments.
+ * @returns The hash.
+ */
+export async function computeInitializationHashFromEncodedArgs(
+  initFn: FunctionSelector,
+  encodedArgs: Fr[],
+): Promise<Fr> {
+  const argsHash = await computeVarArgsHash(encodedArgs);
+  return poseidon2HashWithSeparator([initFn, argsHash], DomainSeparator.INITIALIZER);
+}

package/src/contract/contract_class.ts

@@ -0,0 +1,66 @@
+import { CircuitKind } from '@aztec/bb.js';
+
+import { vkAsFields } from '@aztec-labs/foundation/crypto/keys';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import { type ContractArtifact, type FunctionArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
+import { hashVK } from '../hash/hash.js';
+import { computeArtifactHash } from './artifact_hash.js';
+import { type ContractClassIdPreimage, computeContractClassIdWithPreimage } from './contract_class_id.js';
+import type { ContractClass, ContractClassWithId } from './interfaces/index.js';
+
+/** Contract artifact including its artifact hash */
+export type ContractArtifactWithHash = ContractArtifact & { artifactHash: Fr };
+
+const cmpFunctionArtifacts = <T extends { selector: FunctionSelector }>(a: T, b: T) =>
+  a.selector.toField().cmp(b.selector.toField());
+
+/** Creates a ContractClass from a contract compilation artifact. */
+export async function getContractClassFromArtifact(
+  artifact: ContractArtifact | ContractArtifactWithHash,
+): Promise<ContractClassWithId & ContractClassIdPreimage> {
+  const artifactHash = 'artifactHash' in artifact ? artifact.artifactHash : await computeArtifactHash(artifact);
+
+  const publicFunctions = artifact.functions.filter(f => f.functionType === FunctionType.PUBLIC);
+  if (publicFunctions.length > 1) {
+    throw new Error(
+      `Contract should contain at most one public function artifact. Received ${publicFunctions.length}.`,
+    );
+  }
+
+  const packedBytecode = publicFunctions[0]?.bytecode ?? Buffer.alloc(0);
+
+  const privateFunctions = artifact.functions.filter(f => f.functionType === FunctionType.PRIVATE);
+  const privateArtifactFunctions: ContractClass['privateFunctions'] = await Promise.all(
+    privateFunctions.map(getContractClassPrivateFunctionFromArtifact),
+  );
+
+  privateArtifactFunctions.sort(cmpFunctionArtifacts);
+
+  const contractClass = {
+    version: 1 as const,
+    artifactHash,
+    packedBytecode,
+    privateFunctions: privateArtifactFunctions,
+  };
+  return { ...contractClass, ...(await computeContractClassIdWithPreimage(contractClass)) };
+}
+
+export async function getContractClassPrivateFunctionFromArtifact(
+  f: FunctionArtifact,
+): Promise<ContractClass['privateFunctions'][number]> {
+  return {
+    selector: await FunctionSelector.fromNameAndParameters(f.name, f.parameters),
+    vkHash: await computeVerificationKeyHash(f),
+  };
+}
+
+/**
+ * For a given private function, computes the hash of its vk.
+ */
+export async function computeVerificationKeyHash(f: FunctionArtifact) {
+  if (!f.verificationKey) {
+    throw new Error(`Private function ${f.name} must have a verification key`);
+  }
+  return hashVK(await vkAsFields(Buffer.from(f.verificationKey, 'base64'), CircuitKind.App));
+}

package/src/contract/contract_class_id.ts

@@ -0,0 +1,76 @@
+import { DomainSeparator, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS } from '@aztec-labs/constants';
+import { poseidon2HashWithSeparator } from '@aztec-labs/foundation/crypto/poseidon';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+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 => poseidon2(DOM_SEP__PRIVATE_FUNCTION_LEAF, [fn.function_selector as Field, fn.vk_hash]))
+ * private_functions_root = merkleize(private_function_leaves)
+ * bytecode_commitment = calculate_commitment(packed_bytecode)
+ * contract_class_id = poseidon2(DOM_SEP__CONTRACT_CLASS_ID, [version, artifact_hash, private_functions_root, bytecode_commitment])
+ * ```
+ * @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],
+    DomainSeparator.CONTRACT_CLASS_ID,
+  );
+  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 31 bytes each)
+  // The first element is the length of the bytecode (in bytes)
+  const [bytecodeLengthAsField, ...bytecodeAsFields] = bufferAsFields(
+    packedBytecode,
+    MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS,
+  );
+
+  const bytecodeLength = Math.ceil(bytecodeLengthAsField.toNumber() / (Fr.SIZE_IN_BYTES - 1));
+  assert(bytecodeLength < MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS, 'Bytecode exceeds maximum deployable size');
+
+  // NOTE: hash the bytecode here only up to the actual length of the bytecode.
+  // We do not hash the entire max bytecode length!
+  const sep = BigInt(DomainSeparator.PUBLIC_BYTECODE) + (bytecodeLengthAsField.toBigInt() << 32n);
+  return await poseidon2HashWithSeparator(bytecodeAsFields.slice(0, bytecodeLength), new Fr(sep).toNumber());
+}

package/src/contract/contract_deployment_data.ts

@@ -0,0 +1,124 @@
+import { ContractClassLog, PrivateLog } from '@aztec-labs/stdlib/logs';
+import type { Tx } from '@aztec-labs/stdlib/tx';
+import { z } from 'zod';
+
+/**
+ * Class containing contract class logs and private logs which are both
+ * relevant for contract registrations and deployments.
+ */
+export class ContractDeploymentData {
+  constructor(
+    public readonly contractClassLogs: ContractClassLog[],
+    public readonly privateLogs: PrivateLog[],
+  ) {}
+
+  public getContractClassLogs(): ContractClassLog[] {
+    return this.contractClassLogs;
+  }
+
+  public getPrivateLogs(): PrivateLog[] {
+    return this.privateLogs;
+  }
+
+  public static from(args: { contractClassLogs: ContractClassLog[]; privateLogs: PrivateLog[] }) {
+    return new ContractDeploymentData(args.contractClassLogs, args.privateLogs);
+  }
+
+  public static empty(): ContractDeploymentData {
+    return new ContractDeploymentData([], []);
+  }
+
+  public static get schema() {
+    return z
+      .object({
+        contractClassLogs: z.array(ContractClassLog.schema),
+        privateLogs: z.array(PrivateLog.schema),
+      })
+      .transform(ContractDeploymentData.from);
+  }
+
+  /**
+   * Creates a ContractDeploymentData from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing ContractDeploymentData fields
+   * @returns A ContractDeploymentData instance
+   */
+  public static fromPlainObject(obj: any): ContractDeploymentData {
+    if (obj instanceof ContractDeploymentData) {
+      return obj;
+    }
+    return new ContractDeploymentData(
+      obj.contractClassLogs.map((log: any) => ContractClassLog.fromPlainObject(log)),
+      obj.privateLogs.map((log: any) => PrivateLog.fromPlainObject(log)),
+    );
+  }
+}
+
+/**
+ * Class containing both revertible and non-revertible registration/deployment data.
+ */
+export class AllContractDeploymentData {
+  constructor(
+    public readonly nonRevertibleContractDeploymentData: ContractDeploymentData,
+    public readonly revertibleContractDeploymentData: ContractDeploymentData,
+  ) {}
+
+  public getNonRevertibleContractDeploymentData(): ContractDeploymentData {
+    return this.nonRevertibleContractDeploymentData;
+  }
+
+  public getRevertibleContractDeploymentData(): ContractDeploymentData {
+    return this.revertibleContractDeploymentData;
+  }
+
+  /**
+   * Extracts all contract registration/deployment data from a tx separated by revertibility.
+   * This includes contract class logs and private logs.
+   *
+   * This method handles both private-only transactions and transactions with public calls,
+   * properly splitting logs between revertible and non-revertible categories.
+   * @param tx - The transaction to extract data from
+   * @returns The extracted deployment data separated by revertibility
+   */
+  static fromTx(tx: Tx): AllContractDeploymentData {
+    const hasPublicCalls = !!tx.data.forPublic;
+
+    // Extract contract class logs from the tx
+    const allClassLogs = tx.getContractClassLogs();
+    let nonRevertibleClassLogs: ContractClassLog[];
+    let revertibleClassLogs: ContractClassLog[];
+
+    if (hasPublicCalls) {
+      // Transactions with public calls can have both revertible and non-revertible contract class logs
+      // Split the logs up here based on revertibility
+      nonRevertibleClassLogs = tx.getSplitContractClassLogs(/*revertible=*/ false);
+      revertibleClassLogs = tx.getSplitContractClassLogs(/*revertible=*/ true);
+    } else {
+      // Private-only tx: all logs are non-revertible
+      nonRevertibleClassLogs = allClassLogs;
+      revertibleClassLogs = [];
+    }
+
+    // Extract contract instance logs from the transaction's private logs
+    let nonRevertibleInstanceLogs: PrivateLog[];
+    let revertibleInstanceLogs: PrivateLog[];
+
+    if (hasPublicCalls) {
+      // Transactions with public calls can have both revertible and non-revertible contract instance logs
+      // Split the logs up here based on revertibility
+      nonRevertibleInstanceLogs = tx.data.forPublic!.nonRevertibleAccumulatedData.privateLogs.filter(l => !l.isEmpty());
+      revertibleInstanceLogs = tx.data.forPublic!.revertibleAccumulatedData.privateLogs.filter(l => !l.isEmpty());
+    } else {
+      // Private-only tx: use logs from the `forRollup` member of the tx
+      // For private-only txs, all logs are non-revertible
+      nonRevertibleInstanceLogs = tx.data.forRollup!.end.privateLogs.filter(l => !l.isEmpty());
+      revertibleInstanceLogs = [];
+    }
+
+    return new AllContractDeploymentData(
+      new ContractDeploymentData(nonRevertibleClassLogs, nonRevertibleInstanceLogs),
+      new ContractDeploymentData(revertibleClassLogs, revertibleInstanceLogs),
+    );
+  }
+}

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;
+}