@aztec/aztec.js 0.0.1-commit.03f7ef2 → 0.0.1-commit.04852196a

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,11 +1,20 @@
+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 } 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';
+import type { WaitOpts } from './wait_opts.js';
 
 /**
  * Options used to tweak the simulation and add gas estimation capabilities
@@ -55,13 +64,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;
 };
 
 /**
@@ -76,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;
 };
 
@@ -91,30 +139,99 @@ 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 TxSendResultImmediate.
+ * Otherwise returns TxSendResultMined.
+ */
+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
  * 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 +243,7 @@ export function toSendOptions(options: SendInteractionOptions): SendOptions {
         ...options.fee?.gasSettings,
       },
     },
+    wait: options.wait, // Pass through wait option
   };
 }