@aztec/aztec.js 0.0.0-test.0

package/src/contract/batch_call.ts

@@ -0,0 +1,95 @@
+import { type FunctionCall, FunctionType, decodeFromAbi } from '@aztec/stdlib/abi';
+import type { TxExecutionRequest } from '@aztec/stdlib/tx';
+
+import type { Wallet } from '../account/index.js';
+import { BaseContractInteraction, type SendMethodOptions } from './base_contract_interaction.js';
+import type { SimulateMethodOptions } from './contract_function_interaction.js';
+
+/** A batch of function calls to be sent as a single transaction through a wallet. */
+export class BatchCall extends BaseContractInteraction {
+  constructor(wallet: Wallet, protected calls: FunctionCall[]) {
+    super(wallet);
+  }
+
+  /**
+   * Create a transaction execution request that represents this batch, encoded and authenticated by the
+   * user's wallet, ready to be simulated.
+   * @param opts - An optional object containing additional configuration for the transaction.
+   * @returns A Promise that resolves to a transaction instance.
+   */
+  public async create(opts?: SendMethodOptions): Promise<TxExecutionRequest> {
+    const calls = this.calls;
+    const capsules = this.getCapsules();
+    const fee = await this.getFeeOptions({ calls, capsules, ...opts });
+    return await this.wallet.createTxExecutionRequest({ calls, capsules, ...opts, fee });
+  }
+
+  /**
+   * Simulate a transaction and get its return values
+   * Differs from prove in a few important ways:
+   * 1. It returns the values of the function execution
+   * 2. It supports `unconstrained`, `private` and `public` functions
+   *
+   * @param options - An optional object containing additional configuration for the transaction.
+   * @returns The result of the transaction as returned by the contract function.
+   */
+  public async simulate(options: SimulateMethodOptions = {}): Promise<any> {
+    const { indexedCalls, unconstrained } = this.calls.reduce<{
+      /** Keep track of the number of private calls to retrieve the return values */
+      privateIndex: 0;
+      /** Keep track of the number of public calls to retrieve the return values */
+      publicIndex: 0;
+      /** The public and private function calls in the batch */
+      indexedCalls: [FunctionCall, number, number][];
+      /** The unconstrained function calls in the batch. */
+      unconstrained: [FunctionCall, number][];
+    }>(
+      (acc, current, index) => {
+        if (current.type === FunctionType.UNCONSTRAINED) {
+          acc.unconstrained.push([current, index]);
+        } else {
+          acc.indexedCalls.push([
+            current,
+            index,
+            current.type === FunctionType.PRIVATE ? acc.privateIndex++ : acc.publicIndex++,
+          ]);
+        }
+        return acc;
+      },
+      { indexedCalls: [], unconstrained: [], publicIndex: 0, privateIndex: 0 },
+    );
+
+    const calls = indexedCalls.map(([call]) => call);
+    const capsules = this.getCapsules();
+    const fee = await this.getFeeOptions({ calls, capsules, ...options });
+    const txRequest = await this.wallet.createTxExecutionRequest({ calls, capsules, ...options, fee });
+
+    const unconstrainedCalls = unconstrained.map(
+      async ([call, index]) =>
+        [await this.wallet.simulateUnconstrained(call.name, call.args, call.to, options?.from), index] as const,
+    );
+
+    const [unconstrainedResults, simulatedTx] = await Promise.all([
+      Promise.all(unconstrainedCalls),
+      this.wallet.simulateTx(txRequest, true, options?.from, options?.skipTxValidation),
+    ]);
+
+    const results: any[] = [];
+
+    unconstrainedResults.forEach(([result, index]) => {
+      results[index] = result;
+    });
+    indexedCalls.forEach(([call, callIndex, resultIndex]) => {
+      // As account entrypoints are private, for private functions we retrieve the return values from the first nested call
+      // since we're interested in the first set of values AFTER the account entrypoint
+      // For public functions we retrieve the first values directly from the public output.
+      const rawReturnValues =
+        call.type == FunctionType.PRIVATE
+          ? simulatedTx.getPrivateReturnValues()?.nested?.[resultIndex].values
+          : simulatedTx.getPublicReturnValues()?.[resultIndex].values;
+
+      results[callIndex] = rawReturnValues ? decodeFromAbi(call.returnTypes, rawReturnValues) : [];
+    });
+    return results;
+  }
+}

package/src/contract/checker.ts

@@ -0,0 +1,117 @@
+import type { AbiType, BasicType, ContractArtifact, StructType } from '@aztec/stdlib/abi';
+
+/**
+ * Represents a type derived from input type T with the 'kind' property removed.
+ * Useful when checking attributes of a specific kind and validating their types.
+ */
+type TypeWithoutKind<T> = Omit<{ [key in keyof T]: any }, 'kind'>;
+
+/**
+ * Validates the given ContractArtifact object by checking its functions and their parameters.
+ * Ensures that the ABI has at least one function, a constructor, valid bytecode, and correct parameter types.
+ * Throws an error if any inconsistency is detected during the validation process.
+ *
+ * @param artifact - The ContractArtifact object to be validated.
+ * @returns A boolean value indicating whether the artifact is valid or not.
+ */
+export function abiChecker(artifact: ContractArtifact) {
+  if (!artifact.functions || artifact.functions.length === 0) {
+    throw new Error('artifact has no functions');
+  }
+
+  artifact.functions.forEach(func => {
+    if (!('name' in func && typeof func.name === 'string' && func.name.length > 0)) {
+      throw new Error('ABI function has no name');
+    }
+
+    // TODO: implement a better check for bytecode (right now only checks if it's > 0)
+    if (!('bytecode' in func && func.bytecode.length > 0)) {
+      throw new Error('ABI function parameter has incorrect bytecode');
+    }
+
+    func.parameters.forEach(param => {
+      if (!param.type) {
+        throw new Error('ABI function parameter has no type');
+      }
+
+      abiParameterTypeChecker(param.type);
+    });
+  });
+
+  // TODO: implement a better check for constructor (right now only checks if it has it or not)
+  if (!artifact.functions.find(func => func.name === 'constructor')) {
+    throw new Error('ABI has no constructor');
+  }
+
+  return true;
+}
+
+/**
+ * Validates the ABI function parameter's type by checking its kind and attributes.
+ * Throws an error if the type has an unrecognized kind or incorrectly formed attributes.
+ * Additionally, checks nested types for array and struct kinds.
+ *
+ * @param type - The AbiType object representing the type of the ABI function parameter.
+ * @returns A boolean value indicating whether the type is valid or not.
+ */
+function abiParameterTypeChecker(type: AbiType): boolean {
+  switch (type.kind) {
+    case 'field':
+    case 'boolean':
+      return checkAttributes(type, {});
+    case 'integer':
+      return checkAttributes(type, { sign: 'string', width: 'number' });
+    case 'string':
+      return checkAttributes(type, { length: 'number' });
+    case 'array':
+      return checkAttributes(type, { length: 'number', type: 'object' }) && abiParameterTypeChecker(type.type);
+    case 'struct':
+      return checkAttributes(type, { fields: 'object', path: 'string' }) && checkStruct(type);
+    default:
+      throw new Error('ABI function parameter has an unrecognized type');
+  }
+}
+
+/**
+ * Check if the structure of the AbiType 'struct' is valid by ensuring field names are strings
+ * and their type attribute passes the abiParameterTypeChecker. Returns true on successful validation,
+ * otherwise throws an error providing insight into the incorrect formation in the struct.
+ *
+ * @param type - The StructType object containing an array of fields to validate.
+ * @returns A boolean value indicating successful validation of the struct's fields.
+ */
+function checkStruct(type: StructType) {
+  return type.fields.reduce((acc, field) => {
+    if (!('name' in field && typeof field.name === 'string')) {
+      throw new Error('ABI function parameter has an incorrectly formed struct');
+    }
+    return acc && abiParameterTypeChecker(field.type);
+  }, true);
+}
+
+/**
+ * Check if a provided ABI type has the correct attributes and their associated types.
+ * This function compares the given 'type' object's keys with the expected attribute types
+ * specified in 'incompleteAttributes', as well as the required 'kind' property.
+ * Throws an error if there are any unrecognized attributes or incorrect attribute types.
+ *
+ * @param type - The ABI type object to be checked for correct attributes.
+ * @param incompleteAttributes - An object representing the expected attribute types without the 'kind' property.
+ * @returns Returns true if the provided ABI type has the correct attributes and their associated types, otherwise throws an error.
+ */
+function checkAttributes<T extends BasicType<string>>(type: T, incompleteAttributes: TypeWithoutKind<T>) {
+  const typeKeys = Object.keys(type);
+  const attributes = { ...incompleteAttributes, kind: 'string' };
+
+  if (typeKeys.length !== Object.keys(attributes).length) {
+    throw new Error(`Unrecognized attribute on type ${type.kind}`);
+  }
+
+  typeKeys.forEach(element => {
+    if (!(element in type && typeof (type as any)[element] === (attributes as any)[element])) {
+      throw new Error(`ABI function parameter has an incorrectly formed ${type.kind}`);
+    }
+  });
+
+  return true;
+}

package/src/contract/contract.ts

@@ -0,0 +1,69 @@
+import type { ContractArtifact } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { getContractClassFromArtifact } from '@aztec/stdlib/contract';
+import { PublicKeys } from '@aztec/stdlib/keys';
+
+import type { Wallet } from '../account/index.js';
+import { ContractBase } from './contract_base.js';
+import { DeployMethod } from './deploy_method.js';
+
+/**
+ * The Contract class represents a contract and provides utility methods for interacting with it.
+ * It enables the creation of ContractFunctionInteraction instances for each function in the contract's ABI,
+ * allowing users to call or send transactions to these functions. Additionally, the Contract class can be used
+ * to attach the contract instance to a deployed contract on-chain through the PXE, which facilitates
+ * interaction with Aztec's privacy protocol.
+ */
+export class Contract extends ContractBase {
+  /**
+   * Creates a contract instance.
+   * @param address - The deployed contract's address.
+   * @param artifact - Build artifact of the contract.
+   * @param wallet - The wallet to use when interacting with the contract.
+   * @returns A promise that resolves to a new Contract instance.
+   */
+  public static async at(address: AztecAddress, artifact: ContractArtifact, wallet: Wallet): Promise<Contract> {
+    const instance = (await wallet.getContractMetadata(address)).contractInstance;
+    if (instance === undefined) {
+      throw new Error(`Contract instance at ${address.toString()} has not been registered in the wallet's PXE`);
+    }
+    const thisContractClass = await getContractClassFromArtifact(artifact);
+    if (!thisContractClass.id.equals(instance.currentContractClassId)) {
+      // wallet holds an outdated version of this contract
+      await wallet.updateContract(address, artifact);
+      instance.currentContractClassId = thisContractClass.id;
+    }
+    return new Contract(instance, artifact, wallet);
+  }
+
+  /**
+   * Creates a tx to deploy a new instance of a contract.
+   * @param wallet - The wallet for executing the deployment.
+   * @param artifact - Build artifact of the contract to deploy
+   * @param args - Arguments for the constructor.
+   * @param constructorName - The name of the constructor function to call.
+   */
+  public static deploy(wallet: Wallet, artifact: ContractArtifact, args: any[], constructorName?: string) {
+    const postDeployCtor = (address: AztecAddress, wallet: Wallet) => Contract.at(address, artifact, wallet);
+    return new DeployMethod(PublicKeys.default(), wallet, artifact, postDeployCtor, args, constructorName);
+  }
+
+  /**
+   * Creates a tx to deploy a new instance of a contract using the specified public keys hash to derive the address.
+   * @param publicKeys - Hash of public keys to use for deriving the address.
+   * @param wallet - The wallet for executing the deployment.
+   * @param artifact - Build artifact of the contract.
+   * @param args - Arguments for the constructor.
+   * @param constructorName - The name of the constructor function to call.
+   */
+  public static deployWithPublicKeys(
+    publicKeys: PublicKeys,
+    wallet: Wallet,
+    artifact: ContractArtifact,
+    args: any[],
+    constructorName?: string,
+  ) {
+    const postDeployCtor = (address: AztecAddress, wallet: Wallet) => Contract.at(address, artifact, wallet);
+    return new DeployMethod(publicKeys, wallet, artifact, postDeployCtor, args, constructorName);
+  }
+}

package/src/contract/contract_base.ts

@@ -0,0 +1,90 @@
+import {
+  type ContractArtifact,
+  type ContractNote,
+  type FieldLayout,
+  type FunctionArtifact,
+  FunctionSelector,
+} from '@aztec/stdlib/abi';
+import { type ContractInstanceWithAddress, computePartialAddress } from '@aztec/stdlib/contract';
+
+import type { Wallet } from '../account/index.js';
+import { ContractFunctionInteraction } from './contract_function_interaction.js';
+
+/**
+ * Type representing a contract method that returns a ContractFunctionInteraction instance
+ * and has a readonly 'selector' property of type Buffer. Takes any number of arguments.
+ */
+export type ContractMethod = ((...args: any[]) => ContractFunctionInteraction) & {
+  /**
+   * The unique identifier for a contract function in bytecode.
+   */
+  selector: () => Promise<FunctionSelector>;
+};
+
+/**
+ * Type representing the storage layout of a contract.
+ */
+export type ContractStorageLayout<T extends string> = {
+  [K in T]: FieldLayout;
+};
+
+/**
+ * Type representing the notes used in a contract.
+ */
+export type ContractNotes<T extends string> = {
+  [K in T]: ContractNote;
+};
+
+/**
+ * Abstract implementation of a contract extended by the Contract class and generated contract types.
+ */
+export class ContractBase {
+  /**
+   * An object containing contract methods mapped to their respective names.
+   */
+  public methods: { [name: string]: ContractMethod } = {};
+
+  protected constructor(
+    /** The deployed contract instance definition. */
+    public readonly instance: ContractInstanceWithAddress,
+    /** The Application Binary Interface for the contract. */
+    public readonly artifact: ContractArtifact,
+    /** The wallet used for interacting with this contract. */
+    public wallet: Wallet,
+  ) {
+    artifact.functions.forEach((f: FunctionArtifact) => {
+      const interactionFunction = (...args: any[]) => {
+        return new ContractFunctionInteraction(this.wallet, this.instance.address, f, args);
+      };
+
+      this.methods[f.name] = Object.assign(interactionFunction, {
+        /**
+         * A getter for users to fetch the function selector.
+         * @returns Selector of the function.
+         */
+        selector() {
+          return FunctionSelector.fromNameAndParameters(f.name, f.parameters);
+        },
+      });
+    });
+  }
+
+  /** Address of the contract. */
+  public get address() {
+    return this.instance.address;
+  }
+
+  /** Partial address of the contract. */
+  public get partialAddress() {
+    return computePartialAddress(this.instance);
+  }
+
+  /**
+   * Creates a new instance of the contract wrapper attached to a different wallet.
+   * @param wallet - Wallet to use for sending txs.
+   * @returns A new contract instance.
+   */
+  public withWallet(wallet: Wallet): this {
+    return new ContractBase(this.instance, this.artifact, wallet) as this;
+  }
+}

package/src/contract/contract_function_interaction.ts

@@ -0,0 +1,173 @@
+import {
+  type FunctionAbi,
+  FunctionCall,
+  FunctionSelector,
+  FunctionType,
+  decodeFromAbi,
+  encodeArguments,
+} from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { PrivateKernelProverProfileResult } from '@aztec/stdlib/kernel';
+import type { TxExecutionRequest } from '@aztec/stdlib/tx';
+
+import type { Wallet } from '../account/wallet.js';
+import { FeeJuicePaymentMethod } from '../fee/fee_juice_payment_method.js';
+import { BaseContractInteraction, type SendMethodOptions } from './base_contract_interaction.js';
+
+export type { SendMethodOptions };
+
+/**
+ * Represents the options for simulating a contract function interaction.
+ * Allows specifying the address from which the view method should be called.
+ * Disregarded for simulation of public functions
+ */
+export type SimulateMethodOptions = Pick<SendMethodOptions, 'fee'> & {
+  /** The sender's Aztec address. */
+  from?: AztecAddress;
+  /** Simulate without checking for the validity of the resulting transaction, e.g. whether it emits any existing nullifiers. */
+  skipTxValidation?: boolean;
+  /** Whether to ensure the fee payer is not empty and has enough balance to pay for the fee. */
+  skipFeeEnforcement?: boolean;
+};
+
+/**
+ * The result of a profile() call.
+ */
+export type ProfileResult = PrivateKernelProverProfileResult & {
+  /** The result of the transaction as returned by the contract function. */
+  returnValues: any;
+};
+
+/**
+ * This is the class that is returned when calling e.g. `contract.methods.myMethod(arg0, arg1)`.
+ * It contains available interactions one can call on a method, including view.
+ */
+export class ContractFunctionInteraction extends BaseContractInteraction {
+  constructor(
+    wallet: Wallet,
+    protected contractAddress: AztecAddress,
+    protected functionDao: FunctionAbi,
+    protected args: any[],
+  ) {
+    super(wallet);
+    if (args.some(arg => arg === undefined || arg === null)) {
+      throw new Error('All function interaction arguments must be defined and not null. Received: ' + args);
+    }
+  }
+
+  // docs:start:create
+  /**
+   * Create a transaction execution request that represents this call, encoded and authenticated by the
+   * user's wallet, ready to be simulated.
+   * @param opts - An optional object containing additional configuration for the transaction.
+   * @returns A Promise that resolves to a transaction instance.
+   */
+  public async create(opts: SendMethodOptions = {}): Promise<TxExecutionRequest> {
+    // docs:end:create
+    if (this.functionDao.functionType === FunctionType.UNCONSTRAINED) {
+      throw new Error("Can't call `create` on an unconstrained function.");
+    }
+    const calls = [await this.request()];
+    const capsules = this.getCapsules();
+    const fee = await this.getFeeOptions({ calls, capsules, ...opts });
+    const { nonce, cancellable } = opts;
+    return await this.wallet.createTxExecutionRequest({ calls, fee, nonce, cancellable, capsules });
+  }
+
+  // docs:start:request
+  /**
+   * Returns an execution request that represents this operation. Useful as a building
+   * block for constructing batch requests.
+   * @returns An execution request wrapped in promise.
+   */
+  public async request(): Promise<FunctionCall> {
+    // docs:end:request
+    const args = encodeArguments(this.functionDao, this.args);
+    return {
+      name: this.functionDao.name,
+      args,
+      selector: await FunctionSelector.fromNameAndParameters(this.functionDao.name, this.functionDao.parameters),
+      type: this.functionDao.functionType,
+      to: this.contractAddress,
+      isStatic: this.functionDao.isStatic,
+      returnTypes: this.functionDao.returnTypes,
+    };
+  }
+
+  // docs:start:simulate
+  /**
+   * Simulate a transaction and get its return values
+   * Differs from prove in a few important ways:
+   * 1. It returns the values of the function execution
+   * 2. It supports `unconstrained`, `private` and `public` functions
+   *
+   * @param options - An optional object containing additional configuration for the transaction.
+   * @returns The result of the transaction as returned by the contract function.
+   */
+  public async simulate(options: SimulateMethodOptions = {}): Promise<any> {
+    // docs:end:simulate
+    if (this.functionDao.functionType == FunctionType.UNCONSTRAINED) {
+      return this.wallet.simulateUnconstrained(this.functionDao.name, this.args, this.contractAddress, options?.from);
+    }
+
+    const fee = options.fee ?? { paymentMethod: new FeeJuicePaymentMethod(AztecAddress.ZERO) };
+    const txRequest = await this.create({ fee });
+    const simulatedTx = await this.wallet.simulateTx(
+      txRequest,
+      true /* simulatePublic */,
+      options.from,
+      options.skipTxValidation,
+      options.skipFeeEnforcement ?? true,
+    );
+
+    let rawReturnValues;
+    if (this.functionDao.functionType == FunctionType.PRIVATE) {
+      if (simulatedTx.getPrivateReturnValues().nested.length > 0) {
+        // The function invoked is private and it was called via an account contract
+        // TODO(#10631): There is a bug here: this branch might be triggered when there is no-account contract as well
+        rawReturnValues = simulatedTx.getPrivateReturnValues().nested[0].values;
+      } else {
+        // The function invoked is private and it was called directly (without account contract)
+        rawReturnValues = simulatedTx.getPrivateReturnValues().values;
+      }
+    } else {
+      // For public functions we retrieve the first values directly from the public output.
+      rawReturnValues = simulatedTx.getPublicReturnValues()?.[0].values;
+    }
+
+    return rawReturnValues ? decodeFromAbi(this.functionDao.returnTypes, rawReturnValues) : [];
+  }
+
+  /**
+   * Simulate a transaction and profile the gate count for each function in the transaction.
+   * @param options - Same options as `simulate`.
+   *
+   * @returns An object containing the function return value and profile result.
+   */
+  public async simulateWithProfile(options: SimulateMethodOptions = {}): Promise<ProfileResult> {
+    if (this.functionDao.functionType == FunctionType.UNCONSTRAINED) {
+      throw new Error("Can't profile an unconstrained function.");
+    }
+
+    const txRequest = await this.create({ fee: options.fee });
+    const simulatedTx = await this.wallet.simulateTx(
+      txRequest,
+      true,
+      options?.from,
+      options?.skipTxValidation,
+      undefined,
+      true,
+    );
+
+    const rawReturnValues =
+      this.functionDao.functionType == FunctionType.PRIVATE
+        ? simulatedTx.getPrivateReturnValues().nested?.[0].values
+        : simulatedTx.getPublicReturnValues()?.[0].values;
+    const rawReturnValuesDecoded = rawReturnValues ? decodeFromAbi(this.functionDao.returnTypes, rawReturnValues) : [];
+
+    return {
+      returnValues: rawReturnValuesDecoded,
+      gateCounts: simulatedTx.profileResult!.gateCounts,
+    };
+  }
+}