@aztec/aztec.js 0.0.1-commit.d6f2b3f94 → 0.0.1-commit.db765a8

package/src/contract/deploy_method.ts

@@ -9,12 +9,12 @@ import {
   getContractInstanceFromInstantiationParams,
 } from '@aztec/stdlib/contract';
 import type { PublicKeys } from '@aztec/stdlib/keys';
-import { type Capsule, TxHash, type TxProfileResult, type TxReceipt, collectOffchainEffects } from '@aztec/stdlib/tx';
+import { type Capsule, HashedValues, type TxProfileResult, type TxReceipt } 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 { SendOptions, 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';
@@ -22,11 +22,15 @@ import { getGasLimits } from './get_gas_limits.js';
 import {
   NO_WAIT,
   type NoWait,
+  type OffchainOutput,
   type ProfileInteractionOptions,
   type RequestInteractionOptions,
   type SendInteractionOptionsWithoutWait,
   type SimulationInteractionFeeOptions,
-  type SimulationReturn,
+  type SimulationResult,
+  type TxSendResultImmediate,
+  type TxSendResultMined,
+  extractOffchainOutput,
   toProfileOptions,
   toSendOptions,
   toSimulateOptions,
@@ -82,7 +86,7 @@ export type DeployOptionsWithoutWait = Omit<RequestDeployOptions, 'deployer'> &
    * is mutually exclusive with "deployer"
    */
   universalDeploy?: boolean;
-} & Pick<SendInteractionOptionsWithoutWait, 'from' | 'fee'>;
+} & Pick<SendInteractionOptionsWithoutWait, 'from' | 'fee' | 'additionalScopes'>;
 
 /**
  * Extends the deployment options with the required parameters to send the transaction.
@@ -123,20 +127,32 @@ export type DeployTxReceipt<TContract extends ContractBase = ContractBase> = TxR
   instance: ContractInstanceWithAddress;
 };
 
+/** Wait options that request a full receipt instead of just the contract instance. */
+type WaitWithReturnReceipt = {
+  /** Request the full receipt instead of just the contract instance. */
+  returnReceipt: true;
+};
+
 /**
  * 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.
  */
+/** Result of deploying a contract when waiting for mining (default case). */
+export type DeployResultMined<TContract extends ContractBase> = {
+  /** The deployed contract instance. */
+  contract: TContract;
+  /** The deploy transaction receipt. */
+  receipt: DeployTxReceipt<TContract>;
+} & OffchainOutput;
+
+/** Conditional return type for deploy based on wait options. */
 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;
+  ? TxSendResultImmediate
+  : W extends WaitWithReturnReceipt
+    ? TxSendResultMined<DeployTxReceipt<TContract>>
+    : DeployResultMined<TContract>;
 
 /**
  * Contract interaction for deployment.
@@ -164,6 +180,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
     constructorNameOrArtifact?: string | FunctionArtifact,
     authWitnesses: AuthWitness[] = [],
     capsules: Capsule[] = [],
+    private extraHashedArgs: HashedValues[] = [],
   ) {
     super(wallet, authWitnesses, capsules);
     this.constructorArtifact = getInitializer(artifact, constructorNameOrArtifact);
@@ -174,20 +191,29 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    * @param options - Configuration options.
    * @returns The execution payload for this operation
    */
-  public async request(options?: RequestDeployOptions): Promise<ExecutionPayload> {
+  public async request(options: RequestDeployOptions = {}): Promise<ExecutionPayload> {
     const publication = await this.getPublicationExecutionPayload(options);
 
     if (!options?.skipRegistration) {
       await this.wallet.registerContract(await this.getInstance(options), this.artifact);
     }
-
+    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 initialization = await this.getInitializationExecutionPayload(options);
     const feeExecutionPayload = options?.fee?.paymentMethod
       ? await options.fee.paymentMethod.getExecutionPayload()
       : undefined;
     const finalExecutionPayload = feeExecutionPayload
-      ? mergeExecutionPayloads([feeExecutionPayload, publication, initialization])
-      : mergeExecutionPayloads([publication, initialization]);
+      ? mergeExecutionPayloads([initialExecutionPayload, feeExecutionPayload, publication, initialization])
+      : mergeExecutionPayloads([initialExecutionPayload, publication, initialization]);
     if (!finalExecutionPayload.calls.length) {
       throw new Error(`No transactions are needed to publish or initialize contract ${this.artifact.name}`);
     }
@@ -207,7 +233,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    * @param options - Deploy options with wait parameter
    * @returns Send options with wait parameter
    */
-  private convertDeployOptionsToSendOptions<W extends DeployInteractionWaitOptions>(
+  protected convertDeployOptionsToSendOptions<W extends DeployInteractionWaitOptions>(
     options: DeployOptions<W>,
     // eslint-disable-next-line jsdoc/require-jsdoc
   ): SendOptions<W extends { returnReceipt: true } ? WaitOpts : W> {
@@ -219,6 +245,24 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
     } 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.
@@ -308,8 +352,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    * @returns TxHash (if wait is NO_WAIT), TContract (if wait is undefined or doesn't have returnReceipt), or DeployTxReceipt (if wait.returnReceipt is true)
    */
   // 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
+  public override send(options: DeployOptionsWithoutWait): Promise<DeployResultMined<TContract>>;
   // eslint-disable-next-line jsdoc/require-jsdoc
   public override send<W extends DeployInteractionWaitOptions>(
     options: DeployOptions<W>,
@@ -320,12 +363,15 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
     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 result = await this.wallet.sendTx(executionPayload, sendOptions as SendOptions<NoWait>);
+      this.log.debug(`Sent deployment tx ${result.txHash.hash} of ${this.artifact.name} contract`);
+      return result;
     }
 
-    const receipt = await this.wallet.sendTx(executionPayload, sendOptions as SendOptions<WaitOpts | undefined>);
+    const { receipt, ...offchainOutput } = 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
@@ -334,10 +380,10 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
 
     // Return full receipt if requested, otherwise just the contract
     if (options.wait && typeof options.wait === 'object' && options.wait.returnReceipt) {
-      return { ...receipt, contract, instance };
+      return { receipt: { ...receipt, contract, instance }, ...offchainOutput };
     }
 
-    return contract;
+    return { contract, receipt, ...offchainOutput };
   }
 
   /**
@@ -366,9 +412,12 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    * @returns A simulation result object containing metadata of the execution, including gas
    * estimations (if requested via options), execution statistics and emitted offchain effects
    */
-  public async simulate(options: SimulateDeployOptions): Promise<SimulationReturn<true>> {
+  public async simulate(options: SimulateDeployOptions): Promise<SimulationResult> {
     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(
@@ -376,7 +425,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
     );
     return {
       stats: simulatedTx.stats!,
-      offchainEffects: collectOffchainEffects(simulatedTx.privateExecutionResult),
+      ...extractOffchainOutput(simulatedTx.offchainEffects),
       result: undefined,
       estimatedGas: { gasLimits, teardownGasLimits },
     };
@@ -390,11 +439,7 @@ export class DeployMethod<TContract extends ContractBase = ContractBase> extends
    */
   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/get_gas_limits.ts

@@ -1,4 +1,4 @@
-import { AVM_MAX_PROCESSABLE_L2_GAS } from '@aztec/constants';
+import { MAX_PROCESSABLE_L2_GAS } from '@aztec/constants';
 import { Gas } from '@aztec/stdlib/gas';
 import type { TxSimulationResult } from '@aztec/stdlib/tx';
 
@@ -23,8 +23,8 @@ export function getGasLimits(
   const gasLimits = simulationResult.gasUsed.totalGas.mul(1 + pad);
   const teardownGasLimits = simulationResult.gasUsed.teardownGas.mul(1 + pad);
 
-  if (gasLimits.l2Gas > AVM_MAX_PROCESSABLE_L2_GAS) {
-    throw new Error('Transaction consumes more gas than the AVM maximum processable gas');
+  if (gasLimits.l2Gas > MAX_PROCESSABLE_L2_GAS) {
+    throw new Error('Transaction consumes more l2 gas than the maximum processable gas');
   }
   return {
     gasLimits,

package/src/contract/interaction_options.ts

@@ -1,8 +1,16 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { FieldsOf } from '@aztec/foundation/types';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { GasSettings } from '@aztec/stdlib/gas';
-import type { Capsule, OffchainEffect, SimulationStats, TxHash, TxReceipt } from '@aztec/stdlib/tx';
+import {
+  type Capsule,
+  OFFCHAIN_MESSAGE_IDENTIFIER,
+  type OffchainEffect,
+  type SimulationStats,
+  type TxHash,
+  type TxReceipt,
+} from '@aztec/stdlib/tx';
 
 import type { FeePaymentMethod } from '../fee/fee_payment_method.js';
 import type { ProfileOptions, SendOptions, SimulateOptions } from '../wallet/index.js';
@@ -82,6 +90,13 @@ export type SendInteractionOptionsWithoutWait = RequestInteractionOptions & {
   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[];
 };
 
 /**
@@ -109,8 +124,8 @@ export type SimulateInteractionOptions = Omit<SendInteractionOptions, 'fee'> & {
   skipTxValidation?: boolean;
   /** Whether to ensure the fee payer is not empty and has enough balance to pay for the fee. */
   skipFeeEnforcement?: boolean;
-  /** Whether to include metadata such as offchain effects and performance statistics (e.g. timing information of the different circuits and oracles) in
-   * the simulation result, instead of just the return value of the function */
+  /** Whether to include metadata such as performance statistics (e.g. timing information of the different circuits and oracles) and gas estimation
+   * in the simulation result, in addition to the return value and offchain effects */
   includeMetadata?: boolean;
 };
 
@@ -124,31 +139,89 @@ export type ProfileInteractionOptions = SimulateInteractionOptions & {
   skipProofGeneration?: boolean;
 };
 
+/** A message emitted during execution or proving, to be delivered offchain. */
+export type OffchainMessage = {
+  /** The intended recipient of the message. */
+  recipient: AztecAddress;
+  /** The message payload (typically encrypted). */
+  payload: Fr[];
+  /** The contract that emitted the message. */
+  contractAddress: AztecAddress;
+};
+
+/** Groups all unproven outputs from private execution that are returned to the client. */
+export type OffchainOutput = {
+  /** Raw offchain effects emitted during execution. */
+  offchainEffects: OffchainEffect[];
+  /** Messages emitted during execution, to be delivered offchain. */
+  offchainMessages: OffchainMessage[];
+};
+
 /**
- * Represents the result type of a simulation.
- * By default, it will just be the return value of the simulated function
- * If `includeMetadata` is set to true in `SimulateInteractionOptions` on the input of `simulate(...)`,
- * it will provide extra information.
- */
-export type SimulationReturn<T extends boolean | undefined> = T extends true
-  ? {
-      /** Additional stats about the simulation */
-      stats: SimulationStats;
-      /** Offchain effects generated during the simulation */
-      offchainEffects: OffchainEffect[];
-      /**  Return value of the function */
-      result: any;
-      /** Gas estimation results */
-      estimatedGas: Pick<GasSettings, 'gasLimits' | 'teardownGasLimits'>;
+ * Splits an array of offchain effects into decoded offchain messages and remaining effects.
+ * Effects whose data starts with `OFFCHAIN_MESSAGE_IDENTIFIER` are parsed as messages and removed
+ * from the effects array.
+ */
+export function extractOffchainOutput(effects: OffchainEffect[]): OffchainOutput {
+  const offchainEffects: OffchainEffect[] = [];
+  const offchainMessages: OffchainMessage[] = [];
+
+  for (const effect of effects) {
+    if (effect.data.length >= 2 && effect.data[0].equals(OFFCHAIN_MESSAGE_IDENTIFIER)) {
+      offchainMessages.push({
+        recipient: AztecAddress.fromField(effect.data[1]),
+        payload: effect.data.slice(2),
+        contractAddress: effect.contractAddress,
+      });
+    } else {
+      offchainEffects.push(effect);
     }
-  : any;
+  }
+
+  return { offchainEffects, offchainMessages };
+}
+
+/**
+ * Returns an empty `OffchainOutput` (no effects, no messages).
+ */
+export function emptyOffchainOutput(): OffchainOutput {
+  return { offchainEffects: [], offchainMessages: [] };
+}
+
+/**
+ * Represents the result of a simulation.
+ * Always includes the return value and offchain output.
+ * When `includeMetadata` or `fee.estimateGas` is set, also includes stats and gas estimation.
+ */
+export type SimulationResult = {
+  /** Return value of the function */
+  result: any;
+  /** Additional stats about the simulation. Present when `includeMetadata` is set. */
+  stats?: SimulationStats;
+  /** Gas estimation results. Present when `includeMetadata` or `fee.estimateGas` is set. */
+  estimatedGas?: Pick<GasSettings, 'gasLimits' | 'teardownGasLimits'>;
+} & OffchainOutput;
+
+/** Result of sendTx when not waiting for mining. */
+export type TxSendResultImmediate = {
+  /** The hash of the sent transaction. */
+  txHash: TxHash;
+} & OffchainOutput;
+
+/** Result of sendTx when waiting for mining. */
+export type TxSendResultMined<TReturn = TxReceipt> = {
+  /** The transaction receipt. */
+  receipt: TReturn;
+} & OffchainOutput;
 
 /**
  * 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.
+ * If `wait` is NO_WAIT, returns TxSendResultImmediate.
+ * Otherwise returns TxSendResultMined.
  */
-export type SendReturn<T extends InteractionWaitOptions, TReturn = TxReceipt> = T extends NoWait ? TxHash : TReturn;
+export type SendReturn<T extends InteractionWaitOptions, TReturn = TxReceipt> = T extends NoWait
+  ? TxSendResultImmediate
+  : TxSendResultMined<TReturn>;
 
 /**
  * Transforms and cleans up the higher level SendInteractionOptions defined by the interaction into