@aztec/aztec.js 0.0.0-test.1 → 0.0.1-commit.5476d83

package/src/contract/contract_function_interaction.ts

@@ -1,42 +1,20 @@
-import {
-  type FunctionAbi,
-  FunctionCall,
-  FunctionSelector,
-  FunctionType,
-  decodeFromAbi,
-  encodeArguments,
-} from '@aztec/stdlib/abi';
+import { type FunctionAbi, FunctionSelector, FunctionType, decodeFromAbi, encodeArguments } from '@aztec/stdlib/abi';
+import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 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 };
+import { type Capsule, type HashedValues, type TxProfileResult, collectOffchainEffects } from '@aztec/stdlib/tx';
+import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
-/**
- * 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;
-};
+import type { Wallet } from '../wallet/wallet.js';
+import { BaseContractInteraction } from './base_contract_interaction.js';
+import { getGasLimits } from './get_gas_limits.js';
+import {
+  type ProfileInteractionOptions,
+  type RequestInteractionOptions,
+  type SimulateInteractionOptions,
+  type SimulationReturn,
+  toProfileOptions,
+  toSimulateOptions,
+} from './interaction_options.js';
 
 /**
  * This is the class that is returned when calling e.g. `contract.methods.myMethod(arg0, arg1)`.
@@ -48,40 +26,22 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
     protected contractAddress: AztecAddress,
     protected functionDao: FunctionAbi,
     protected args: any[],
+    authWitnesses: AuthWitness[] = [],
+    capsules: Capsule[] = [],
+    private extraHashedArgs: HashedValues[] = [],
   ) {
-    super(wallet);
+    super(wallet, authWitnesses, capsules);
     if (args.some(arg => arg === undefined || arg === null)) {
-      throw new Error('All function interaction arguments must be defined and not null. Received: ' + args);
+      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.
+   * Returns the encoded function call wrapped by this interaction
+   * Useful when generating authwits
+   * @returns An encoded function call
    */
-  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
+  public async getFunctionCall() {
     const args = encodeArguments(this.functionDao, this.args);
     return {
       name: this.functionDao.name,
@@ -90,35 +50,77 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
       type: this.functionDao.functionType,
       to: this.contractAddress,
       isStatic: this.functionDao.isStatic,
+      hideMsgSender: false /** Only set to `true` for enqueued public function calls */,
       returnTypes: this.functionDao.returnTypes,
     };
   }
 
+  /**
+   * Returns the execution payload that allows this operation to happen on chain.
+   * @param options - Configuration options.
+   * @returns The execution payload for this operation
+   */
+  public override async request(options: RequestInteractionOptions = {}): Promise<ExecutionPayload> {
+    const calls = [await this.getFunctionCall()];
+    const { authWitnesses, capsules } = options;
+    const feeExecutionPayload = options.fee?.paymentMethod
+      ? await options.fee.paymentMethod.getExecutionPayload()
+      : undefined;
+    const functionExecutionPayload = new ExecutionPayload(
+      calls,
+      this.authWitnesses.concat(authWitnesses ?? []),
+      this.capsules.concat(capsules ?? []),
+      this.extraHashedArgs,
+    );
+    const finalExecutionPayload = feeExecutionPayload
+      ? mergeExecutionPayloads([feeExecutionPayload, functionExecutionPayload])
+      : functionExecutionPayload;
+    return finalExecutionPayload;
+  }
+
   // docs:start:simulate
   /**
-   * Simulate a transaction and get its return values
+   * Simulate a transaction and get information from its execution.
    * 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
+   * 1. It returns the values of the function execution, plus additional metadata if requested
+   * 2. It supports `utility`, `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.
+   * @param options - An optional object containing additional configuration for the simulation.
+   * @returns Depending on the simulation options, this method directly returns the result value of the executed
+   * function or a rich object containing extra metadata, such as estimated gas costs (if requested via options),
+   * execution statistics and emitted offchain effects
    */
-  public async simulate(options: SimulateMethodOptions = {}): Promise<any> {
+  public async simulate<T extends SimulateInteractionOptions>(
+    options: T,
+  ): Promise<SimulationReturn<Exclude<T['fee'], undefined>['estimateGas']>>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public async simulate<T extends SimulateInteractionOptions>(
+    options: T,
+  ): Promise<SimulationReturn<T['includeMetadata']>>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public async simulate(
+    options: SimulateInteractionOptions,
+  ): Promise<SimulationReturn<typeof options.includeMetadata>> {
     // docs:end:simulate
-    if (this.functionDao.functionType == FunctionType.UNCONSTRAINED) {
-      return this.wallet.simulateUnconstrained(this.functionDao.name, this.args, this.contractAddress, options?.from);
+    if (this.functionDao.functionType == FunctionType.UTILITY) {
+      const call = await this.getFunctionCall();
+      const utilityResult = await this.wallet.simulateUtility(call, options.authWitnesses ?? []);
+
+      // Decode the raw field elements to the actual return type
+      const returnValue = utilityResult.result ? decodeFromAbi(this.functionDao.returnTypes, utilityResult.result) : [];
+
+      if (options.includeMetadata) {
+        return {
+          stats: utilityResult.stats,
+          result: returnValue,
+        };
+      } else {
+        return returnValue;
+      }
     }
 
-    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,
-    );
+    const executionPayload = await this.request(options);
+    const simulatedTx = await this.wallet.simulateTx(executionPayload, toSimulateOptions(options));
 
     let rawReturnValues;
     if (this.functionDao.functionType == FunctionType.PRIVATE) {
@@ -132,42 +134,69 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
       }
     } else {
       // For public functions we retrieve the first values directly from the public output.
-      rawReturnValues = simulatedTx.getPublicReturnValues()?.[0].values;
+      rawReturnValues = simulatedTx.getPublicReturnValues()?.[0]?.values;
     }
 
-    return rawReturnValues ? decodeFromAbi(this.functionDao.returnTypes, rawReturnValues) : [];
+    const returnValue = rawReturnValues ? decodeFromAbi(this.functionDao.returnTypes, rawReturnValues) : [];
+
+    if (options.includeMetadata || options.fee?.estimateGas) {
+      const { gasLimits, teardownGasLimits } = getGasLimits(simulatedTx, options.fee?.estimatedGasPadding);
+      this.log.verbose(
+        `Estimated gas limits for tx: DA=${gasLimits.daGas} L2=${gasLimits.l2Gas} teardownDA=${teardownGasLimits.daGas} teardownL2=${teardownGasLimits.l2Gas}`,
+      );
+      return {
+        stats: simulatedTx.stats,
+        offchainEffects: collectOffchainEffects(simulatedTx.privateExecutionResult),
+        result: returnValue,
+        estimatedGas: { gasLimits, teardownGasLimits },
+      };
+    } else {
+      return returnValue;
+    }
   }
 
   /**
    * Simulate a transaction and profile the gate count for each function in the transaction.
-   * @param options - Same options as `simulate`.
+   * @param options - Same options as `simulate`, plus profiling method
    *
    * @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.");
+  public async profile(options: ProfileInteractionOptions): Promise<TxProfileResult> {
+    if (this.functionDao.functionType == FunctionType.UTILITY) {
+      throw new Error("Can't profile a utility 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) : [];
+    const executionPayload = await this.request(options);
+    return await this.wallet.profileTx(executionPayload, toProfileOptions(options));
+  }
 
-    return {
-      returnValues: rawReturnValuesDecoded,
-      gateCounts: simulatedTx.profileResult!.gateCounts,
-    };
+  /**
+   * Augments this ContractFunctionInteraction with additional metadata, such as authWitnesses, capsules, and extraHashedArgs.
+   * This is useful when creating a "batteries included" interaction, such as registering a contract class with its associated
+   * capsule instead of having the user provide them externally.
+   * @param options - An object containing the metadata to add to the interaction
+   * @returns A new ContractFunctionInteraction with the added metadata, but calling the same original function in the same manner
+   */
+  public with({
+    authWitnesses = [],
+    capsules = [],
+    extraHashedArgs = [],
+  }: {
+    /** The authWitnesses to add to the interaction */
+    authWitnesses?: AuthWitness[];
+    /** The capsules to add to the interaction */
+    capsules?: Capsule[];
+    /** The extra hashed args to add to the interaction */
+    extraHashedArgs?: HashedValues[];
+  }): ContractFunctionInteraction {
+    return new ContractFunctionInteraction(
+      this.wallet,
+      this.contractAddress,
+      this.functionDao,
+      this.args,
+      this.authWitnesses.concat(authWitnesses),
+      this.capsules.concat(capsules),
+      this.extraHashedArgs.concat(extraHashedArgs),
+    );
   }
 }