@aztec/aztec.js 0.0.1-commit.fcb71a6 → 0.0.1-commit.ff7989d6c

package/src/contract/deploy_method.ts

@@ -9,27 +9,46 @@ import {
   getContractInstanceFromInstantiationParams,
 } from '@aztec/stdlib/contract';
 import type { PublicKeys } from '@aztec/stdlib/keys';
-import { type Capsule, type TxProfileResult, collectOffchainEffects } from '@aztec/stdlib/tx';
+import { type Capsule, TxHash, type TxProfileResult, type TxReceipt, collectOffchainEffects } from '@aztec/stdlib/tx';
 import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
 import { publishContractClass } from '../deployment/publish_class.js';
 import { publishInstance } from '../deployment/publish_instance.js';
-import type { Wallet } from '../wallet/wallet.js';
+import type { ProfileOptions, SendOptions, SimulateOptions, Wallet } from '../wallet/wallet.js';
 import { BaseContractInteraction } from './base_contract_interaction.js';
 import type { ContractBase } from './contract_base.js';
 import { ContractFunctionInteraction } from './contract_function_interaction.js';
-import { DeploySentTx } from './deploy_sent_tx.js';
 import { getGasLimits } from './get_gas_limits.js';
 import {
+  NO_WAIT,
+  type NoWait,
   type ProfileInteractionOptions,
   type RequestInteractionOptions,
-  type SendInteractionOptions,
+  type SendInteractionOptionsWithoutWait,
   type SimulationInteractionFeeOptions,
   type SimulationReturn,
   toProfileOptions,
   toSendOptions,
   toSimulateOptions,
 } from './interaction_options.js';
+import type { WaitOpts } from './wait_opts.js';
+
+/**
+ * Wait options specific to deployment transactions.
+ * Extends WaitOpts with a flag to return the full receipt instead of just the contract.
+ */
+export type DeployWaitOptions = WaitOpts & {
+  /** If true, return the full DeployTxReceipt instead of just the contract. Defaults to false. */
+  returnReceipt?: boolean;
+};
+
+/**
+ * Type for wait options in deployment interactions.
+ * - NO_WAIT symbol: Don't wait, return TxHash immediately
+ * - DeployWaitOptions: Wait with custom options
+ * - undefined: Wait with default options
+ */
+export type DeployInteractionWaitOptions = NoWait | DeployWaitOptions | undefined;
 
 /**
  * Options for deploying a contract on the Aztec network.
@@ -55,21 +74,34 @@ export type RequestDeployOptions = RequestInteractionOptions & {
 };
 
 /**
- * Extends the deployment options with the required parameters to send the transaction
+ * Base deployment options without wait parameter.
  */
-export type DeployOptions = Omit<RequestDeployOptions, 'deployer'> & {
+export type DeployOptionsWithoutWait = Omit<RequestDeployOptions, 'deployer'> & {
   /**
    * Set to true to *not* include the sender in the address computation. This option
    * is mutually exclusive with "deployer"
    */
   universalDeploy?: boolean;
-} & Pick<SendInteractionOptions, 'from' | 'fee'>;
+} & Pick<SendInteractionOptionsWithoutWait, 'from' | 'fee' | 'additionalScopes'>;
+
+/**
+ * Extends the deployment options with the required parameters to send the transaction.
+ */
+export type DeployOptions<W extends DeployInteractionWaitOptions = undefined> = DeployOptionsWithoutWait & {
+  /**
+   * Options for waiting for the transaction to be mined.
+   * - undefined (default): wait with default options and return the contract instance
+   * - DeployWaitOptions: wait with custom options and return contract or receipt based on returnReceipt flag
+   * - NO_WAIT: return TxHash immediately without waiting
+   */
+  wait?: W;
+};
 
 /**
  * Options for simulating the deployment of a contract
  * Allows skipping certain validations and computing gas estimations
  */
-export type SimulateDeployOptions = Omit<DeployOptions, 'fee'> & {
+export type SimulateDeployOptions = Omit<DeployOptionsWithoutWait, 'fee'> & {
   /** The fee options for the transaction. */
   fee?: SimulationInteractionFeeOptions;
   /** Simulate without checking for the validity of the resulting transaction,
@@ -83,6 +115,29 @@ export type SimulateDeployOptions = Omit<DeployOptions, 'fee'> & {
   includeMetadata?: boolean;
 };
 
+/** Receipt for a deployment transaction with the deployed contract instance. */
+export type DeployTxReceipt<TContract extends ContractBase = ContractBase> = TxReceipt & {
+  /** Type-safe wrapper around the deployed contract instance, linked to the deployment wallet */
+  contract: TContract;
+  /** The deployed contract instance with address and metadata. */
+  instance: ContractInstanceWithAddress;
+};
+
+/**
+ * Represents the result type of deploying a contract.
+ * - If wait is NO_WAIT, returns TxHash immediately.
+ * - If wait has returnReceipt: true, returns DeployTxReceipt after waiting.
+ * - Otherwise (undefined or DeployWaitOptions without returnReceipt), returns TContract after waiting.
+ */
+export type DeployReturn<TContract extends ContractBase, W extends DeployInteractionWaitOptions> = W extends NoWait
+  ? TxHash
+  : W extends {
+        // eslint-disable-next-line jsdoc/require-jsdoc
+        returnReceipt: true;
+      }
+    ? DeployTxReceipt<TContract>
+    : TContract;
+
 /**
  * Contract interaction for deployment.
  * Handles class publication, instance publication, and initialization of the contract.
@@ -92,8 +147,6 @@ export type SimulateDeployOptions = Omit<DeployOptions, 'fee'> & {
  * then technically the contract has already been "created", and all of the contract's
  * functions (private and utility) can be interacted-with immediately, without any
  * "deployment tx".
- *
- * Extends the BaseContractInteraction class.
  */
 export class DeployMethod<TContract extends ContractBase = ContractBase> extends BaseContractInteraction {
   /** The contract instance to be deployed. */
@@ -142,13 +195,48 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
     return finalExecutionPayload;
   }
 
-  convertDeployOptionsToRequestOptions(options: DeployOptions): RequestDeployOptions {
+  convertDeployOptionsToRequestOptions(options: DeployOptionsWithoutWait): RequestDeployOptions {
     return {
       ...options,
       deployer: !options?.universalDeploy ? options.from : undefined,
     };
   }
 
+  /**
+   * Converts DeployOptions to SendOptions, stripping out the returnReceipt flag if present.
+   * @param options - Deploy options with wait parameter
+   * @returns Send options with wait parameter
+   */
+  protected convertDeployOptionsToSendOptions<W extends DeployInteractionWaitOptions>(
+    options: DeployOptions<W>,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+  ): SendOptions<W extends { returnReceipt: true } ? WaitOpts : W> {
+    return {
+      ...toSendOptions({
+        ...options,
+        wait: options.wait as any,
+      }),
+    } as any;
+  }
+
+  /**
+   * Converts deploy simulation options into wallet-level simulate options.
+   * @param options - The deploy simulation options to convert.
+   */
+  protected convertDeployOptionsToSimulateOptions(options: SimulateDeployOptions): SimulateOptions {
+    return toSimulateOptions(options);
+  }
+
+  /**
+   * Converts deploy profile options into wallet-level profile options.
+   * @param options - The deploy profile options to convert.
+   */
+  protected convertDeployOptionsToProfileOptions(
+    options: DeployOptionsWithoutWait & ProfileInteractionOptions,
+  ): ProfileOptions {
+    return toProfileOptions(options);
+  }
+
   /**
    * Adds this contract to the wallet and returns the Contract object.
    * @param options - Deployment options.
@@ -184,16 +272,17 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
 
     // Publish the contract class if it hasn't been published already.
     if (!options?.skipClassPublication) {
-      if ((await this.wallet.getContractClassMetadata(contractClass.id)).isContractClassPubliclyRegistered) {
-        this.log.debug(
-          `Skipping publication of already-registered contract class ${contractClass.id.toString()} for ${instance.address.toString()}`,
-        );
-      } else {
+      const classMetadata = await this.wallet.getContractClassMetadata(contractClass.id);
+      if (!classMetadata.isContractClassPubliclyRegistered) {
         this.log.info(
           `Creating request for publishing contract class ${contractClass.id.toString()} as part of deployment for ${instance.address.toString()}`,
         );
         const registerContractClassInteraction = await publishContractClass(this.wallet, this.artifact);
         calls.push(await registerContractClassInteraction.request());
+      } else {
+        this.log.debug(
+          `Skipping contract class publication for ${contractClass.id.toString()} as it is already registered`,
+        );
       }
     }
 
@@ -202,7 +291,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
       // TODO(https://github.com/AztecProtocol/aztec-packages/issues/15596):
       // Read the artifact, and if there are no public functions, warn the caller that publication of the
       // contract instance is not necessary (until such time as they wish to update the instance (i.e. change its class_id)).
-      const deploymentInteraction = await publishInstance(this.wallet, instance);
+      const deploymentInteraction = publishInstance(this.wallet, instance);
       calls.push(await deploymentInteraction.request());
     }
 
@@ -231,20 +320,42 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
 
   /**
    * Send a contract deployment transaction (initialize and/or publish) using the provided options.
-   * This function extends the 'send' method from the ContractFunctionInteraction class,
-   * allowing us to send a transaction specifically for contract deployment.
+   * By default, waits for the transaction to be mined and returns the deployed contract instance.
    *
    * @param options - An object containing various deployment options such as contractAddressSalt and from.
-   * @returns A SentTx object that returns the receipt and the deployed contract instance.
+   * @returns TxHash (if wait is NO_WAIT), TContract (if wait is undefined or doesn't have returnReceipt), or DeployTxReceipt (if wait.returnReceipt is true)
    */
-  public override send(options: DeployOptions): DeploySentTx<TContract> {
-    const sendTx = async () => {
-      const executionPayload = await this.request(this.convertDeployOptionsToRequestOptions(options));
-      const sendOptions = toSendOptions(options);
-      return this.wallet.sendTx(executionPayload, sendOptions);
-    };
-    this.log.debug(`Sent deployment tx of ${this.artifact.name} contract`);
-    return new DeploySentTx(this.wallet, sendTx, this.postDeployCtor, () => this.getInstance(options));
+  // Overload for when wait is not specified at all - returns the contract
+  public override send(options: DeployOptionsWithoutWait): Promise<TContract>;
+  // Generic overload for explicit wait values
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public override send<W extends DeployInteractionWaitOptions>(
+    options: DeployOptions<W>,
+  ): Promise<DeployReturn<TContract, W>>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public override async send(options: DeployOptions<DeployInteractionWaitOptions>): Promise<any> {
+    const executionPayload = await this.request(this.convertDeployOptionsToRequestOptions(options));
+    const sendOptions = this.convertDeployOptionsToSendOptions(options);
+
+    if (options.wait === NO_WAIT) {
+      const txHash = await this.wallet.sendTx(executionPayload, sendOptions as SendOptions<NoWait>);
+      this.log.debug(`Sent deployment tx ${txHash.hash} of ${this.artifact.name} contract`);
+      return txHash;
+    }
+
+    const receipt = await this.wallet.sendTx(executionPayload, sendOptions as SendOptions<WaitOpts | undefined>);
+    this.log.debug(`Deployed ${this.artifact.name} contract in tx ${receipt.txHash}`);
+
+    // Attach contract instance
+    const instance = await this.getInstance(options);
+    const contract = this.postDeployCtor(instance, this.wallet) as TContract;
+
+    // Return full receipt if requested, otherwise just the contract
+    if (options.wait && typeof options.wait === 'object' && options.wait.returnReceipt) {
+      return { ...receipt, contract, instance };
+    }
+
+    return contract;
   }
 
   /**
@@ -275,7 +386,10 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    */
   public async simulate(options: SimulateDeployOptions): Promise<SimulationReturn<true>> {
     const executionPayload = await this.request(this.convertDeployOptionsToRequestOptions(options));
-    const simulatedTx = await this.wallet.simulateTx(executionPayload, toSimulateOptions(options));
+    const simulatedTx = await this.wallet.simulateTx(
+      executionPayload,
+      this.convertDeployOptionsToSimulateOptions(options),
+    );
 
     const { gasLimits, teardownGasLimits } = getGasLimits(simulatedTx, options.fee?.estimatedGasPadding);
     this.log.verbose(
@@ -295,13 +409,9 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    *
    * @returns An object containing the function return value and profile result.
    */
-  public async profile(options: DeployOptions & ProfileInteractionOptions): Promise<TxProfileResult> {
+  public async profile(options: DeployOptionsWithoutWait & ProfileInteractionOptions): Promise<TxProfileResult> {
     const executionPayload = await this.request(this.convertDeployOptionsToRequestOptions(options));
-    return await this.wallet.profileTx(executionPayload, {
-      ...toProfileOptions(options),
-      profileMode: options.profileMode,
-      skipProofGeneration: options.skipProofGeneration,
-    });
+    return await this.wallet.profileTx(executionPayload, this.convertDeployOptionsToProfileOptions(options));
   }
 
   /** Return this deployment address. */

package/src/contract/interaction_options.ts

@@ -2,10 +2,11 @@ import type { FieldsOf } from '@aztec/foundation/types';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { GasSettings } from '@aztec/stdlib/gas';
-import type { Capsule, OffchainEffect, SimulationStats } from '@aztec/stdlib/tx';
+import type { Capsule, OffchainEffect, SimulationStats, TxHash, TxReceipt } from '@aztec/stdlib/tx';
 
 import type { FeePaymentMethod } from '../fee/fee_payment_method.js';
 import type { ProfileOptions, SendOptions, SimulateOptions } from '../wallet/index.js';
+import type { WaitOpts } from './wait_opts.js';
 
 /**
  * Options used to tweak the simulation and add gas estimation capabilities
@@ -55,13 +56,52 @@ export type RequestInteractionOptions = {
 };
 
 /**
- * Represents options for calling a (constrained) function in a contract.
+ * Constant for explicitly not waiting for transaction confirmation.
+ * We use this instead of false to avoid confusion with falsy checks.
+ */
+export const NO_WAIT = 'NO_WAIT' as const;
+
+/**
+ * Type for the NO_WAIT constant.
+ */
+export type NoWait = typeof NO_WAIT;
+
+/**
+ * Type for wait options in interactions.
+ * - NO_WAIT symbol: Don't wait for confirmation, return TxHash immediately
+ * - WaitOpts object: Wait with custom options and return receipt/result
+ * - undefined: Wait with default options and return receipt/result
+ */
+export type InteractionWaitOptions = NoWait | WaitOpts | undefined;
+
+/**
+ * Base options for calling a (constrained) function in a contract, without wait parameter.
  */
-export type SendInteractionOptions = RequestInteractionOptions & {
+export type SendInteractionOptionsWithoutWait = RequestInteractionOptions & {
   /** The sender's Aztec address. */
   from: AztecAddress;
   /** The fee options for the transaction. */
   fee?: InteractionFeeOptions;
+  /**
+   * Additional addresses whose private state and keys should be accessible during execution,
+   * beyond the sender's. Required when the transaction needs to access private state or keys
+   * belonging to an address other than `from`, e.g. withdrawing from an escrow that holds
+   * its own private notes.
+   */
+  additionalScopes?: AztecAddress[];
+};
+
+/**
+ * Represents options for calling a (constrained) function in a contract.
+ */
+export type SendInteractionOptions<W extends InteractionWaitOptions = undefined> = SendInteractionOptionsWithoutWait & {
+  /**
+   * Whether to wait for the transaction to be mined.
+   * - undefined (default): wait with default options and return TxReceipt
+   * - WaitOpts object: wait with custom options and return TxReceipt
+   * - NO_WAIT: return txHash immediately without waiting
+   */
+  wait?: W;
 };
 
 /**
@@ -110,11 +150,22 @@ export type SimulationReturn<T extends boolean | undefined> = T extends true
     }
   : any;
 
+/**
+ * Represents the result type of sending a transaction.
+ * If `wait` is NO_WAIT, returns TxHash immediately without waiting.
+ * If `wait` is undefined or WaitOpts, returns TReturn (defaults to TxReceipt) after waiting.
+ */
+export type SendReturn<T extends InteractionWaitOptions, TReturn = TxReceipt> = T extends NoWait ? TxHash : TReturn;
+
 /**
  * Transforms and cleans up the higher level SendInteractionOptions defined by the interaction into
  * SendOptions, which are the ones that can be serialized and forwarded to the wallet
+ * @param options - The send interaction options with optional wait parameter
+ * @returns The send options to forward to the wallet
  */
-export function toSendOptions(options: SendInteractionOptions): SendOptions {
+export function toSendOptions<W extends InteractionWaitOptions = undefined>(
+  options: SendInteractionOptions<W>,
+): SendOptions<W> {
   return {
     ...options,
     fee: {
@@ -126,6 +177,7 @@ export function toSendOptions(options: SendInteractionOptions): SendOptions {
         ...options.fee?.gasSettings,
       },
     },
+    wait: options.wait, // Pass through wait option
   };
 }