@aztec-labs/aztec.js 6.0.0-nightly.20260829

package/src/authorization/call_authorization_request.ts

@@ -0,0 +1,93 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { FieldReader } from '@aztec-labs/foundation/serialize';
+import { AuthorizationSelector, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { computeInnerAuthWitHash } from '@aztec-labs/stdlib/auth-witness';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { computeVarArgsHash } from '@aztec-labs/stdlib/hash';
+
+/**
+ * An authwit request for a function call. Includes the preimage of the data
+ * to be signed, as opposed of just the inner hash.
+ */
+export class CallAuthorizationRequest {
+  private constructor(
+    /**
+     * The selector of the authwit type, used to identify it
+     * when emitted from `emit_offchain_effect`oracle.
+     * Computed as poseidon2("CallAuthwit((Field),(u32),Field)".to_bytes())
+     */
+    public selector: AuthorizationSelector,
+    /**
+     * The inner hash of the authwit, computed as
+     * poseidon2([msg_sender, selector, args_hash])
+     */
+    public innerHash: Fr,
+    /**
+     * The address on whose behalf the auth witness should be created.
+     * This is the account that must sign the authorization.
+     */
+    public onBehalfOf: AztecAddress,
+    /**
+     * The address performing the call
+     */
+    public msgSender: AztecAddress,
+    /**
+     * The selector of the function that is to be authorized
+     * */
+    public functionSelector: FunctionSelector,
+    /**
+     * The hash of the arguments to the function call,
+     */
+    public argsHash: Fr,
+    /**
+     * The arguments to the function call.
+     */
+    public args: Fr[],
+  ) {}
+
+  /** Validates that innerHash and argsHash are consistent with the provided preimage fields. */
+  private async validate(): Promise<void> {
+    const expectedArgsHash = await computeVarArgsHash(this.args);
+    if (!expectedArgsHash.equals(this.argsHash)) {
+      throw new Error(
+        `CallAuthorizationRequest argsHash mismatch: expected ${expectedArgsHash.toString()}, got ${this.argsHash.toString()}`,
+      );
+    }
+    const expectedInnerHash = await computeInnerAuthWitHash([
+      this.msgSender.toField(),
+      this.functionSelector.toField(),
+      this.argsHash,
+    ]);
+    if (!expectedInnerHash.equals(this.innerHash)) {
+      throw new Error(
+        `CallAuthorizationRequest innerHash mismatch: expected ${expectedInnerHash.toString()}, got ${this.innerHash.toString()}`,
+      );
+    }
+  }
+
+  static getSelector(): Promise<AuthorizationSelector> {
+    return AuthorizationSelector.fromSignature('CallAuthorization((Field),(u32),Field)');
+  }
+
+  static async fromFields(fields: Fr[]): Promise<CallAuthorizationRequest> {
+    const expectedSelector = await CallAuthorizationRequest.getSelector();
+    const reader = FieldReader.asReader(fields);
+    const selector = AuthorizationSelector.fromField(reader.readField());
+    if (!selector.equals(expectedSelector)) {
+      throw new Error(
+        `Invalid authorization selector for CallAuthwit: expected ${expectedSelector.toString()}, got ${selector.toString()}`,
+      );
+    }
+    const request = new CallAuthorizationRequest(
+      selector,
+      reader.readField(), // inner_hash
+      AztecAddress.fromFieldUnsafe(reader.readField()), // on_behalf_of
+      AztecAddress.fromFieldUnsafe(reader.readField()), // msg_sender
+      FunctionSelector.fromField(reader.readField()), // fn_selector
+      reader.readField(), // args_hash
+      reader.readFieldArray(reader.remainingFields()), // args
+    );
+    await request.validate();
+    return request;
+  }
+}

package/src/contract/base_contract_interaction.ts

@@ -0,0 +1,62 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import type { AuthWitness } from '@aztec-labs/stdlib/auth-witness';
+import type { Capsule, ExecutionPayload, TxReceipt } from '@aztec-labs/stdlib/tx';
+
+import type { Wallet } from '../wallet/wallet.js';
+import {
+  type InteractionWaitOptions,
+  type RequestInteractionOptions,
+  type SendInteractionOptions,
+  type SendInteractionOptionsWithoutWait,
+  type SendReturn,
+  type TxSendResultMined,
+  toSendOptions,
+} from './interaction_options.js';
+
+/**
+ * Base class for an interaction with a contract, be it a deployment, a function call, or a batch.
+ * Implements the sequence create/simulate/send.
+ */
+export abstract class BaseContractInteraction {
+  protected log = createLogger('aztecjs:contract_interaction');
+
+  constructor(
+    protected wallet: Wallet,
+    protected authWitnesses: AuthWitness[] = [],
+    protected capsules: Capsule[] = [],
+  ) {}
+
+  /**
+   * Returns an execution request that represents this operation.
+   * Can be used as a building block for constructing batch requests.
+   * @param options - An optional object containing additional configuration for the transaction.
+   * @returns An execution request wrapped in promise.
+   */
+  public abstract request(options?: RequestInteractionOptions): Promise<ExecutionPayload>;
+
+  // docs:start:send
+  /**
+   * Sends a transaction to the contract function with the specified options.
+   * By default, waits for the transaction to be mined and returns the receipt (or custom type).
+   * @param options - An object containing 'from' property representing
+   * the AztecAddress of the sender, optional fee configuration, and optional wait settings
+   * @returns TReturn (if wait is undefined/WaitOpts) or TxHash (if wait is NO_WAIT)
+   */
+  // Overload for when wait is not specified at all - returns { receipt: TReturn, offchainEffects }
+  public send<TReturn = TxReceipt>(options: SendInteractionOptionsWithoutWait): Promise<TxSendResultMined<TReturn>>;
+  // Generic overload for explicit wait values
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public send<TReturn = TxReceipt, W extends InteractionWaitOptions = undefined>(
+    options: SendInteractionOptions<W>,
+  ): Promise<SendReturn<W, TReturn>>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public async send<TReturn = TxReceipt>(
+    options: SendInteractionOptions<InteractionWaitOptions>,
+  ): Promise<SendReturn<typeof options.wait, TReturn>> {
+    // docs:end:send
+    const executionPayload = await this.request(options);
+    const sendOptions = toSendOptions(options);
+
+    return (await this.wallet.sendTx(executionPayload, sendOptions as any)) as SendReturn<typeof options.wait, TReturn>;
+  }
+}

package/src/contract/batch_call.ts

@@ -0,0 +1,188 @@
+import { type FunctionCall, FunctionType, decodeFromAbi } from '@aztec-labs/stdlib/abi';
+import { ExecutionPayload, HashedValues, UtilityExecutionResult, mergeExecutionPayloads } from '@aztec-labs/stdlib/tx';
+
+import type { TxSimulationResultWithAppOffset } from '../wallet/tx_simulation_result_with_app_offset.js';
+import type { BatchedMethod, Wallet } from '../wallet/wallet.js';
+import { BaseContractInteraction } from './base_contract_interaction.js';
+import {
+  NO_FROM,
+  type RequestInteractionOptions,
+  type SimulateInteractionOptions,
+  type SimulationResult,
+  extractOffchainOutput,
+  toSimulateOptions,
+} from './interaction_options.js';
+
+/** A batch of function calls to be sent as a single transaction through a wallet. */
+// docs:start:batch_call_class
+export class BatchCall extends BaseContractInteraction {
+  constructor(
+    wallet: Wallet,
+    protected interactions: (BaseContractInteraction | ExecutionPayload)[],
+    private extraHashedArgs: HashedValues[] = [],
+  ) {
+    super(wallet);
+  }
+  // docs:end:batch_call_class
+
+  /**
+   * Returns an execution request that represents this operation.
+   * @param options - An optional object containing additional configuration for the request generation.
+   * @returns An execution payload wrapped in promise.
+   */
+  public async request(options: RequestInteractionOptions = {}): Promise<ExecutionPayload> {
+    const requests = await this.getExecutionPayloads();
+    const feeExecutionPayload = options.fee?.paymentMethod
+      ? await options.fee.paymentMethod.getExecutionPayload()
+      : undefined;
+    const { authWitnesses, capsules } = options;
+
+    // Propagates the included authwitnesses, capsules, and extraHashedArgs potentially baked into the interaction
+    const initialExecutionPayload = new ExecutionPayload(
+      [],
+      this.authWitnesses.concat(authWitnesses ?? []),
+      this.capsules.concat(capsules ?? []),
+      this.extraHashedArgs,
+    );
+    const finalExecutionPayload = feeExecutionPayload
+      ? mergeExecutionPayloads([initialExecutionPayload, feeExecutionPayload, ...requests])
+      : mergeExecutionPayloads([initialExecutionPayload, ...requests]);
+    return finalExecutionPayload;
+  }
+
+  /**
+   * Simulates/executes the batch, supporting private, public and utility functions. Although this is a single
+   * interaction with the wallet, private and public functions will be grouped into a single ExecutionPayload
+   * that the wallet will simulate as a single transaction. Utility function calls will be executed
+   * one by one.
+   * @param options - An optional object containing additional configuration for the interaction.
+   * @returns The results of all the interactions that make up the batch
+   */
+  public async simulate(options: SimulateInteractionOptions): Promise<SimulationResult> {
+    const feeExecutionPayload = options.fee?.paymentMethod
+      ? await options.fee.paymentMethod.getExecutionPayload()
+      : undefined;
+    // A call-contributing fee payment method prepends its calls in front of the batch (see the merge below). Those
+    // calls shift the return-value indices, and the wallet-side app-call offset does not absorb them: it only counts
+    // the wallet's own fee payment method, not one supplied through options.fee. We offset each app call's result
+    // index by the number of prepended fee calls of the matching type.
+    const feePrivateCallCount = feeExecutionPayload?.calls.filter(c => c.type === FunctionType.PRIVATE).length ?? 0;
+    const feePublicCallCount = feeExecutionPayload?.calls.filter(c => c.type === FunctionType.PUBLIC).length ?? 0;
+
+    const { indexedExecutionPayloads, utility } = (await this.getExecutionPayloads()).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 execution requests in the batch */
+      indexedExecutionPayloads: [ExecutionPayload, number, number][];
+      /** The utility function calls in the batch. */
+      utility: [FunctionCall, number][];
+    }>(
+      (acc, current, index) => {
+        const call = current.calls[0];
+        if (call.type === FunctionType.UTILITY) {
+          acc.utility.push([call, index]);
+        } else {
+          acc.indexedExecutionPayloads.push([
+            current,
+            index,
+            call.type === FunctionType.PRIVATE ? acc.privateIndex++ : acc.publicIndex++,
+          ]);
+        }
+        return acc;
+      },
+      { indexedExecutionPayloads: [], utility: [], publicIndex: 0, privateIndex: 0 },
+    );
+
+    const batchRequests: BatchedMethod[] = [];
+
+    // Add utility calls to batch
+    for (const [call] of utility) {
+      batchRequests.push({
+        name: 'executeUtility' as const,
+        args: [call, { scopes: options.from === NO_FROM ? [] : [options.from], authWitnesses: options.authWitnesses }],
+      });
+    }
+
+    // Add tx simulation to batch if there are any private/public calls
+    if (indexedExecutionPayloads.length > 0) {
+      const payloads = indexedExecutionPayloads.map(([request]) => request);
+      const combinedPayload = mergeExecutionPayloads(
+        feeExecutionPayload ? [feeExecutionPayload, ...payloads] : payloads,
+      );
+      const executionPayload = new ExecutionPayload(
+        combinedPayload.calls,
+        combinedPayload.authWitnesses.concat(options.authWitnesses ?? []),
+        combinedPayload.capsules.concat(options.capsules ?? []),
+        combinedPayload.extraHashedArgs,
+        combinedPayload.feePayer,
+      );
+
+      batchRequests.push({
+        name: 'simulateTx' as const,
+        args: [executionPayload, toSimulateOptions(options)],
+      });
+    }
+
+    const batchResults = batchRequests.length > 0 ? await this.wallet.batch(batchRequests) : [];
+
+    const results: any[] = [];
+
+    // Process utility results (they come first in batch results)
+    for (let i = 0; i < utility.length; i++) {
+      const [call, resultIndex] = utility[i];
+      const wrappedResult = batchResults[i];
+      if (wrappedResult.name === 'executeUtility') {
+        const utilityResult = wrappedResult.result as UtilityExecutionResult;
+        const rawReturnValues = utilityResult.result;
+        const offchainOutput = extractOffchainOutput(utilityResult.offchainEffects, utilityResult.anchorBlockTimestamp);
+        results[resultIndex] = {
+          result: rawReturnValues ? decodeFromAbi(call.returnType, rawReturnValues) : undefined,
+          ...offchainOutput,
+        };
+      }
+    }
+
+    // Process tx simulation result (it comes last if present)
+    let simulatedTx: TxSimulationResultWithAppOffset | undefined;
+    if (indexedExecutionPayloads.length > 0) {
+      const txResultWrapper = batchResults[utility.length];
+      if (txResultWrapper.name === 'simulateTx') {
+        simulatedTx = txResultWrapper.result as TxSimulationResultWithAppOffset;
+        indexedExecutionPayloads.forEach(([request, callIndex, resultIndex]) => {
+          const call = request.calls[0];
+          // For public functions we retrieve the values directly from the public output. Both indices are offset by
+          // the fee payment method's own calls, which are prepended ahead of the batch.
+          const rawReturnValues =
+            call.type == FunctionType.PRIVATE
+              ? simulatedTx!.getPrivateReturnValuesOfAppCall(feePrivateCallCount + resultIndex)?.values
+              : simulatedTx!.getPublicReturnValues()?.[feePublicCallCount + resultIndex].values;
+
+          results[callIndex] = {
+            result: rawReturnValues ? decodeFromAbi(call.returnType, rawReturnValues) : undefined,
+            ...extractOffchainOutput(
+              simulatedTx!.offchainEffects,
+              simulatedTx!.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp,
+            ),
+          };
+        });
+      }
+    }
+
+    if (options.includeMetadata && simulatedTx) {
+      return {
+        result: results,
+        gasUsed: simulatedTx.gasUsed,
+        offchainEffects: [],
+        offchainMessages: [],
+      };
+    }
+
+    return { result: results, offchainEffects: [], offchainMessages: [] };
+  }
+
+  protected async getExecutionPayloads(): Promise<ExecutionPayload[]> {
+    return await Promise.all(this.interactions.map(i => (i instanceof ExecutionPayload ? i : i.request())));
+  }
+}

package/src/contract/checker.ts

@@ -0,0 +1,122 @@
+import {
+  type AbiType,
+  type BasicType,
+  type ContractArtifact,
+  type StructType,
+  getDefaultInitializer,
+} from '@aztec-labs/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);
+    });
+  });
+
+  if (!getDefaultInitializer(artifact)) {
+    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,52 @@
+import type { ContractArtifact } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstanceWithAddress } from '@aztec-labs/stdlib/contract';
+
+import type { Wallet } from '../wallet/wallet.js';
+import { ContractBase } from './contract_base.js';
+import { type DeployInstantiationOptions, 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 onchain through the PXE, which facilitates
+ * interaction with Aztec's privacy protocol.
+ */
+export class Contract extends ContractBase {
+  /**
+   * Gets a contract instance.
+   * @param address - The address of the contract instance.
+   * @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 at(address: AztecAddress, artifact: ContractArtifact, wallet: Wallet): Contract {
+    return new Contract(address, artifact, wallet);
+  }
+
+  /**
+   * Creates a tx to deploy (initialize and/or publish) 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.
+   * @param instantiation - Other address-affecting parameters (salt, deployer / universalDeploy, publicKeys).
+   */
+  public static deploy(
+    wallet: Wallet,
+    artifact: ContractArtifact,
+    args: any[],
+    constructorName?: string,
+    instantiation?: DeployInstantiationOptions,
+  ) {
+    const postDeployCtor = (instance: ContractInstanceWithAddress, wallet: Wallet) =>
+      Contract.at(instance.address, artifact, wallet);
+    return DeployMethod.create(
+      wallet,
+      { artifact, postDeployCtor, args, constructorNameOrArtifact: constructorName },
+      instantiation,
+    );
+  }
+}

package/src/contract/contract_base.ts

@@ -0,0 +1,73 @@
+import {
+  type ContractArtifact,
+  type FieldLayout,
+  type FunctionAbi,
+  FunctionSelector,
+  getAllFunctionAbis,
+} from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+
+import type { Wallet } from '../wallet/wallet.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;
+};
+
+/**
+ * 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 contract's address. */
+    public readonly address: AztecAddress,
+    /** The Application Binary Interface for the contract. */
+    public readonly artifact: ContractArtifact,
+    /** The wallet used for interacting with this contract. */
+    public wallet: Wallet,
+  ) {
+    getAllFunctionAbis(artifact).forEach((f: FunctionAbi) => {
+      const interactionFunction = (...args: any[]) => {
+        return new ContractFunctionInteraction(this.wallet, this.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);
+        },
+      });
+    });
+  }
+
+  /**
+   * 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.address, this.artifact, wallet) as this;
+  }
+}