@aztec/stdlib 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/src/contract/contract_instance.ts

@@ -18,9 +18,14 @@ 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 = 1 as const;
+const VERSION = 2 as const;
 
 export type ContractInstantiationData = {
   constructorArtifact?: FunctionAbi | string;
@@ -29,6 +34,7 @@ export type ContractInstantiationData = {
   salt: Fr;
   publicKeys?: PublicKeys;
   deployer?: AztecAddress;
+  immutablesHash?: Fr;
 };
 
 export class SerializableContractInstance {
@@ -38,6 +44,7 @@ export class SerializableContractInstance {
   public readonly currentContractClassId: Fr;
   public readonly originalContractClassId: Fr;
   public readonly initializationHash: Fr;
+  public readonly immutablesHash: Fr;
   public readonly publicKeys: PublicKeys;
 
   constructor(instance: ContractInstance) {
@@ -49,6 +56,7 @@ export class SerializableContractInstance {
     this.currentContractClassId = instance.currentContractClassId;
     this.originalContractClassId = instance.originalContractClassId;
     this.initializationHash = instance.initializationHash;
+    this.immutablesHash = instance.immutablesHash;
     this.publicKeys = instance.publicKeys;
   }
 
@@ -60,6 +68,7 @@ export class SerializableContractInstance {
       this.currentContractClassId,
       this.originalContractClassId,
       this.initializationHash,
+      this.immutablesHash,
       this.publicKeys,
     );
   }
@@ -78,6 +87,7 @@ export class SerializableContractInstance {
       currentContractClassId: reader.readObject(Fr),
       originalContractClassId: reader.readObject(Fr),
       initializationHash: reader.readObject(Fr),
+      immutablesHash: reader.readObject(Fr),
       publicKeys: reader.readObject(PublicKeys),
     });
   }
@@ -90,6 +100,7 @@ export class SerializableContractInstance {
       currentContractClassId: Fr.random(),
       originalContractClassId: Fr.random(),
       initializationHash: Fr.random(),
+      immutablesHash: Fr.random(),
       publicKeys: await PublicKeys.random(),
       ...opts,
     });
@@ -103,11 +114,68 @@ export class SerializableContractInstance {
       currentContractClassId: Fr.zero(),
       originalContractClassId: Fr.zero(),
       initializationHash: Fr.zero(),
+      immutablesHash: Fr.zero(),
       publicKeys: PublicKeys.default(),
     });
   }
 }
 
+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.
@@ -130,15 +198,17 @@ export async function getContractInstanceFromInstantiationParams(
         )
       : await computeInitializationHash(constructorArtifact, args);
   const publicKeys = opts.publicKeys ?? PublicKeys.default();
+  const immutablesHash = opts.immutablesHash ?? Fr.ZERO;
 
   const instance: ContractInstance = {
     currentContractClassId: contractClass.id,
     originalContractClassId: contractClass.id,
     initializationHash,
+    immutablesHash,
     publicKeys,
     salt: opts.salt,
     deployer,
-    version: 1,
+    version: 2,
   };
 
   return { ...instance, address: await computeContractAddressFromInstance(instance) };

package/src/contract/index.ts

@@ -6,10 +6,7 @@ export * from './contract_deployment_data.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 './utility_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

@@ -42,79 +42,6 @@ const PrivateFunctionSchema = zodFor<PrivateFunction>()(
   }),
 );
 
-/** Private function definition with executable bytecode. */
-export interface ExecutablePrivateFunction extends PrivateFunction {
-  /** ACIR and Brillig bytecode */
-  bytecode: Buffer;
-}
-
-const ExecutablePrivateFunctionSchema = zodFor<ExecutablePrivateFunction>()(
-  PrivateFunctionSchema.and(z.object({ bytecode: schemas.Buffer })),
-);
-
-/** Utility function definition. */
-export interface UtilityFunction {
-  /** 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 UtilityFunctionSchema = zodFor<UtilityFunction>()(
-  z.object({
-    selector: FunctionSelector.schema,
-    bytecode: schemas.Buffer,
-  }),
-);
-
-/** Sibling paths and sibling commitments for proving membership of a private function within a contract class. */
-export type PrivateFunctionMembershipProof = {
-  artifactMetadataHash: Fr;
-  functionMetadataHash: Fr;
-  utilityFunctionsTreeRoot: Fr;
-  privateFunctionTreeSiblingPath: Fr[];
-  privateFunctionTreeLeafIndex: number;
-  artifactTreeSiblingPath: Fr[];
-  artifactTreeLeafIndex: number;
-};
-
-const PrivateFunctionMembershipProofSchema = zodFor<PrivateFunctionMembershipProof>()(
-  z.object({
-    artifactMetadataHash: schemas.Fr,
-    functionMetadataHash: schemas.Fr,
-    utilityFunctionsTreeRoot: schemas.Fr,
-    privateFunctionTreeSiblingPath: z.array(schemas.Fr),
-    privateFunctionTreeLeafIndex: schemas.Integer,
-    artifactTreeSiblingPath: z.array(schemas.Fr),
-    artifactTreeLeafIndex: schemas.Integer,
-  }),
-);
-
-/** A private function with a membership proof. */
-export type ExecutablePrivateFunctionWithMembershipProof = ExecutablePrivateFunction & PrivateFunctionMembershipProof;
-
-/** Sibling paths and commitments for proving membership of a utility  function within a contract class. */
-export type UtilityFunctionMembershipProof = {
-  artifactMetadataHash: Fr;
-  functionMetadataHash: Fr;
-  privateFunctionsArtifactTreeRoot: Fr;
-  artifactTreeSiblingPath: Fr[];
-  artifactTreeLeafIndex: number;
-};
-
-const UtilityFunctionMembershipProofSchema = zodFor<UtilityFunctionMembershipProof>()(
-  z.object({
-    artifactMetadataHash: schemas.Fr,
-    functionMetadataHash: schemas.Fr,
-    privateFunctionsArtifactTreeRoot: schemas.Fr,
-    artifactTreeSiblingPath: z.array(schemas.Fr),
-    artifactTreeLeafIndex: schemas.Integer,
-  }),
-);
-
-/** A utility function with a membership proof. */
-export type UtilityFunctionWithMembershipProof = UtilityFunction & UtilityFunctionMembershipProof;
-
 export const ContractClassSchema = zodFor<ContractClass>()(
   z.object({
     version: z.literal(VERSION),
@@ -143,11 +70,8 @@ export const ContractClassWithIdSchema = zodFor<ContractClassWithId>()(
   }),
 );
 
-/** A contract class with public bytecode information, and optional private and utility functions. */
-export type ContractClassPublic = {
-  privateFunctions: ExecutablePrivateFunctionWithMembershipProof[];
-  utilityFunctions: UtilityFunctionWithMembershipProof[];
-} & Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
+/** A contract class with public bytecode information. */
+export type ContractClassPublic = Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
   Omit<ContractClass, 'privateFunctions'>;
 
 export type ContractClassPublicWithCommitment = ContractClassPublic &
@@ -158,8 +82,6 @@ export const ContractClassPublicSchema = zodFor<ContractClassPublic>()(
     .object({
       id: schemas.Fr,
       privateFunctionsRoot: schemas.Fr,
-      privateFunctions: z.array(ExecutablePrivateFunctionSchema.and(PrivateFunctionMembershipProofSchema)),
-      utilityFunctions: z.array(UtilityFunctionSchema.and(UtilityFunctionMembershipProofSchema)),
     })
     .and(ContractClassSchema.omit({ privateFunctions: true })),
 );
@@ -179,8 +101,6 @@ export function contractClassPublicFromPlainObject(obj: any): ContractClassPubli
     version: 1,
     artifactHash: Fr.fromPlainObject(obj.artifactHash),
     privateFunctionsRoot: Fr.fromPlainObject(obj.privateFunctionsRoot),
-    privateFunctions: [],
-    utilityFunctions: [],
     packedBytecode: obj.packedBytecode instanceof Buffer ? obj.packedBytecode : Buffer.from(obj.packedBytecode),
   };
 }

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

@@ -6,44 +6,65 @@ import { AztecAddress } from '../../aztec-address/index.js';
 import { PublicKeys } from '../../keys/public_keys.js';
 import { schemas, zodFor } from '../../schemas/index.js';
 
-const VERSION = 1 as const;
+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. */
   initializationHash: Fr;
+  /** Hash of Immutables Values the contract is deployed with. */
+  immutablesHash: Fr;
   /** Public keys associated with this instance. */
   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,
     publicKeys: PublicKeys.schema,
   }),
 );
 
+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 })),
 );
@@ -54,12 +75,13 @@ export const ContractInstanceWithAddressSchema = zodFor<ContractInstanceWithAddr
  */
 export function contractInstanceFromPlainObject(obj: any): ContractInstance {
   return {
-    version: 1,
+    version: 2,
     salt: Fr.fromPlainObject(obj.salt),
     deployer: AztecAddress.fromPlainObject(obj.deployer),
     currentContractClassId: Fr.fromPlainObject(obj.currentContractClassId),
     originalContractClassId: Fr.fromPlainObject(obj.originalContractClassId),
     initializationHash: Fr.fromPlainObject(obj.initializationHash),
+    immutablesHash: Fr.fromPlainObject(obj.immutablesHash),
     publicKeys: PublicKeys.fromPlainObject(obj.publicKeys),
   };
 }

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

@@ -5,6 +5,12 @@ import { z } from 'zod';
 
 import { type ProtocolContractAddresses, ProtocolContractAddressesSchema } from './protocol_contract_addresses.js';
 
+/** Limits a single transaction may declare on a network. */
+export interface TxsLimits {
+  /** Maximum gas limits a single tx may declare: the smaller of the per-tx maximum and the per-block allocation. */
+  gas: { daGas: number; l2Gas: number };
+}
+
 /** Provides basic information about the running node. */
 export interface NodeInfo {
   /** Version as tracked in the aztec-packages repository. */
@@ -19,6 +25,10 @@ export interface NodeInfo {
   l1ContractAddresses: L1ContractAddresses;
   /** Protocol contract addresses */
   protocolContractAddresses: ProtocolContractAddresses;
+  /** Whether the node requires real proofs for transaction submission. */
+  realProofs: boolean;
+  /** Limits a single tx may declare on this network. Clients rely on this to set fallback gas limits. */
+  txsLimits: TxsLimits;
 }
 
 export const NodeInfoSchema: ZodFor<NodeInfo> = z
@@ -29,5 +39,9 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,
+    realProofs: z.boolean(),
+    txsLimits: z.object({
+      gas: z.object({ daGas: z.number().int().nonnegative(), l2Gas: z.number().int().nonnegative() }),
+    }),
   })
   .transform(obj => ({ enr: undefined, ...obj }));

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;

package/src/contract/private_function.ts

@@ -1,9 +1,9 @@
-import { FUNCTION_TREE_HEIGHT, GeneratorIndex } from '@aztec/constants';
-import { pedersenHash } from '@aztec/foundation/crypto/pedersen';
+import { DomainSeparator, FUNCTION_TREE_HEIGHT } from '@aztec/constants';
 import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
 
+import { computeMerkleHash } from '../hash/hash.js';
 import type { PrivateFunction } from './interfaces/contract_class.js';
 
 // Memoize the merkle tree calculators to avoid re-computing the zero-hash for each level in each call
@@ -32,18 +32,19 @@ function computePrivateFunctionLeaves(fns: PrivateFunction[]): Promise<Buffer[]>
 
 /** Returns the leaf for a given private function. */
 export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<Buffer> {
-  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], GeneratorIndex.FUNCTION_LEAF)).toBuffer();
+  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], DomainSeparator.PRIVATE_FUNCTION_LEAF)).toBuffer();
 }
 
 async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {
   if (!privateFunctionTreeCalculator) {
     const functionTreeZeroLeaf = (
-      await pedersenHash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))
+      await poseidon2Hash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))
     ).toBuffer() as Buffer<ArrayBuffer>;
     privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
       FUNCTION_TREE_HEIGHT,
       functionTreeZeroLeaf,
-      async (left, right) => (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
+      async (left, right) =>
+        (await computeMerkleHash(Fr.fromBuffer(left), Fr.fromBuffer(right))).toBuffer() as Buffer<ArrayBuffer>,
     );
   }
   return privateFunctionTreeCalculator;

package/src/database-version/database_version.ts

@@ -0,0 +1,87 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
+
+import { z } from 'zod';
+
+/**
+ * Symbol for Node.js custom inspect. Using Symbol.for() is the documented way to
+ * reference this without importing node:util. In browsers, objects with this symbol
+ * simply won't have custom inspect behavior (which is fine).
+ * @see https://nodejs.org/api/util.html#utilinspectcustom
+ */
+const inspectCustomSymbol = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Represents a version record for storing in a version file.
+ */
+export class DatabaseVersion {
+  constructor(
+    /** The version of the data on disk. Used to perform upgrades */
+    public readonly schemaVersion: number,
+    /** The rollup the data pertains to */
+    public readonly rollupAddress: EthAddress,
+  ) {}
+
+  public toBuffer(): Buffer {
+    return Buffer.from(jsonStringify(this));
+  }
+
+  public static fromBuffer(buf: Buffer): DatabaseVersion {
+    try {
+      return jsonParseWithSchema(buf.toString('utf-8'), DatabaseVersion.schema);
+    } catch (err) {
+      throw new Error(`Failed to deserialize version information: ${err}`, { cause: err });
+    }
+  }
+
+  /**
+   * Compares two versions. If the rollups addresses are different then it returns undefined
+   */
+  public cmp(other: DatabaseVersion): undefined | -1 | 0 | 1 {
+    if (this.rollupAddress.equals(other.rollupAddress)) {
+      if (this.schemaVersion < other.schemaVersion) {
+        return -1;
+      } else if (this.schemaVersion > other.schemaVersion) {
+        return 1;
+      } else {
+        return 0;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Checks if two versions exactly match
+   */
+  public equals(other: DatabaseVersion): boolean {
+    return this.cmp(other) === 0;
+  }
+
+  /**
+   * Returns the schema for this class
+   */
+  static get schema() {
+    return z
+      .object({
+        schemaVersion: z.number(),
+        rollupAddress: EthAddress.schema,
+      })
+      .transform(({ schemaVersion, rollupAddress }) => new DatabaseVersion(schemaVersion, rollupAddress));
+  }
+
+  /** Allows for better introspection in Node.js console. Ignored in browser envs. */
+  public [inspectCustomSymbol](): string {
+    return this.toString();
+  }
+
+  public toString(): string {
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
+  }
+
+  /**
+   * Returns an empty instance
+   */
+  static empty() {
+    return new DatabaseVersion(0, EthAddress.ZERO);
+  }
+}