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

package/src/api/wallet.ts

@@ -1,6 +1,7 @@
 export {
   type Aliased,
   type SimulateOptions,
+  type ExecuteUtilityOptions,
   type ProfileOptions,
   type SendOptions,
   type BatchableMethods,
@@ -11,10 +12,16 @@ export {
   type Wallet,
   type PrivateEvent,
   type PrivateEventFilter,
-  FunctionCallSchema,
+  type PublicEvent,
+  type PublicEventFilter,
+  type ContractMetadata,
+  type ContractClassMetadata,
+  AppCapabilitiesSchema,
+  WalletCapabilitiesSchema,
   ExecutionPayloadSchema,
   GasSettingsOptionSchema,
   WalletSimulationFeeOptionSchema,
+  WaitOptsSchema,
   SendOptionsSchema,
   SimulateOptionsSchema,
   ProfileOptionsSchema,
@@ -23,9 +30,49 @@ export {
   EventMetadataDefinitionSchema,
   PrivateEventSchema,
   PrivateEventFilterSchema,
+  PublicEventSchema,
+  PublicEventFilterSchema,
+  ContractClassMetadataSchema,
+  ContractMetadataSchema,
   WalletSchema,
+  ContractFunctionPatternSchema,
+  AccountsCapabilitySchema,
+  GrantedAccountsCapabilitySchema,
+  ContractsCapabilitySchema,
+  GrantedContractsCapabilitySchema,
+  ContractClassesCapabilitySchema,
+  GrantedContractClassesCapabilitySchema,
+  SimulationCapabilitySchema,
+  GrantedSimulationCapabilitySchema,
+  TransactionCapabilitySchema,
+  GrantedTransactionCapabilitySchema,
+  DataCapabilitySchema,
+  GrantedDataCapabilitySchema,
+  CapabilitySchema,
+  GrantedCapabilitySchema,
 } from '../wallet/wallet.js';
 
+export {
+  type AppCapabilities,
+  type WalletCapabilities,
+  CAPABILITY_VERSION,
+  type Capability,
+  type GrantedCapability,
+  type ContractFunctionPattern,
+  type AccountsCapability,
+  type GrantedAccountsCapability,
+  type ContractsCapability,
+  type GrantedContractsCapability,
+  type ContractClassesCapability,
+  type GrantedContractClassesCapability,
+  type SimulationCapability,
+  type GrantedSimulationCapability,
+  type TransactionCapability,
+  type GrantedTransactionCapability,
+  type DataCapability,
+  type GrantedDataCapability,
+} from '../wallet/capabilities.js';
+
 export { AccountManager } from '../wallet/account_manager.js';
 
 export { type DeployAccountOptions, DeployAccountMethod } from '../wallet/deploy_account_method.js';

package/src/contract/base_contract_interaction.ts

@@ -1,10 +1,17 @@
 import { createLogger } from '@aztec/foundation/log';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
-import type { Capsule, ExecutionPayload } from '@aztec/stdlib/tx';
+import type { Capsule, ExecutionPayload, TxReceipt } from '@aztec/stdlib/tx';
 
 import type { Wallet } from '../wallet/wallet.js';
-import { type RequestInteractionOptions, type SendInteractionOptions, toSendOptions } from './interaction_options.js';
-import { SentTx } from './sent_tx.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.
@@ -30,20 +37,26 @@ export abstract class BaseContractInteraction {
   // docs:start:send
   /**
    * Sends a transaction to the contract function with the specified options.
-   * This function throws an error if called on a utility function.
-   * It creates and signs the transaction if necessary, and returns a SentTx instance,
-   * which can be used to track the transaction status, receipt, and events.
+   * 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 and optional fee configuration
-   * @returns A SentTx instance for tracking the transaction status and information.
+   * 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)
    */
-  public send(options: SendInteractionOptions): SentTx {
+  // 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 sendTx = async () => {
-      const executionPayload = await this.request(options);
-      const sendOptions = toSendOptions(options);
-      return this.wallet.sendTx(executionPayload, sendOptions);
-    };
-    return new SentTx(this.wallet, sendTx);
+    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

@@ -1,16 +1,13 @@
 import { type FunctionCall, FunctionType, decodeFromAbi } from '@aztec/stdlib/abi';
-import {
-  ExecutionPayload,
-  TxSimulationResult,
-  UtilitySimulationResult,
-  mergeExecutionPayloads,
-} from '@aztec/stdlib/tx';
+import { ExecutionPayload, TxSimulationResult, UtilityExecutionResult, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
 import type { BatchedMethod, Wallet } from '../wallet/wallet.js';
 import { BaseContractInteraction } from './base_contract_interaction.js';
 import {
   type RequestInteractionOptions,
   type SimulateInteractionOptions,
+  emptyOffchainOutput,
+  extractOffchainOutput,
   toSimulateOptions,
 } from './interaction_options.js';
 
@@ -42,9 +39,9 @@ export class BatchCall extends BaseContractInteraction {
   }
 
   /**
-   * Simulates the batch, supporting private, public and utility functions. Although this is a single
+   * 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 simply be executed
+   * 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
@@ -81,8 +78,8 @@ export class BatchCall extends BaseContractInteraction {
     // Add utility calls to batch
     for (const [call] of utility) {
       batchRequests.push({
-        name: 'simulateUtility' as const,
-        args: [call, options?.authWitnesses],
+        name: 'executeUtility' as const,
+        args: [call, { scope: options.from, authWitnesses: options.authWitnesses }],
       });
     }
 
@@ -111,9 +108,12 @@ export class BatchCall extends BaseContractInteraction {
     for (let i = 0; i < utility.length; i++) {
       const [call, resultIndex] = utility[i];
       const wrappedResult = batchResults[i];
-      if (wrappedResult.name === 'simulateUtility') {
-        const rawReturnValues = (wrappedResult.result as UtilitySimulationResult).result;
-        results[resultIndex] = rawReturnValues ? decodeFromAbi(call.returnTypes, rawReturnValues) : [];
+      if (wrappedResult.name === 'executeUtility') {
+        const rawReturnValues = (wrappedResult.result as UtilityExecutionResult).result;
+        results[resultIndex] = {
+          result: rawReturnValues ? decodeFromAbi(call.returnTypes, rawReturnValues) : [],
+          ...emptyOffchainOutput(),
+        };
       }
     }
 
@@ -132,7 +132,10 @@ export class BatchCall extends BaseContractInteraction {
               ? simulatedTx.getPrivateReturnValues()?.nested?.[resultIndex].values
               : simulatedTx.getPublicReturnValues()?.[resultIndex].values;
 
-          results[callIndex] = rawReturnValues ? decodeFromAbi(call.returnTypes, rawReturnValues) : [];
+          results[callIndex] = {
+            result: rawReturnValues ? decodeFromAbi(call.returnTypes, rawReturnValues) : [],
+            ...extractOffchainOutput(simulatedTx.offchainEffects),
+          };
         });
       }
     }

package/src/contract/contract_function_interaction.ts

@@ -1,7 +1,18 @@
-import { type FunctionAbi, FunctionSelector, FunctionType, decodeFromAbi, encodeArguments } from '@aztec/stdlib/abi';
+import {
+  type ABIParameter,
+  type AbiType,
+  type FunctionAbi,
+  FunctionCall,
+  FunctionSelector,
+  FunctionType,
+  canBeMappedFromNullOrUndefined,
+  decodeFromAbi,
+  encodeArguments,
+  isOptionStruct,
+} from '@aztec/stdlib/abi';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { type Capsule, type HashedValues, type TxProfileResult, collectOffchainEffects } from '@aztec/stdlib/tx';
+import type { Capsule, HashedValues, TxProfileResult } from '@aztec/stdlib/tx';
 import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
 import type { Wallet } from '../wallet/wallet.js';
@@ -11,7 +22,9 @@ import {
   type ProfileInteractionOptions,
   type RequestInteractionOptions,
   type SimulateInteractionOptions,
-  type SimulationReturn,
+  type SimulationResult,
+  emptyOffchainOutput,
+  extractOffchainOutput,
   toProfileOptions,
   toSimulateOptions,
 } from './interaction_options.js';
@@ -31,11 +44,32 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
     private extraHashedArgs: HashedValues[] = [],
   ) {
     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}`);
+    // This may feel a bit ad-hoc here, so it warrants a comment. We accept Noir Option<T> parameters, and it's natural
+    // to map JS's null/undefined to Noir Option's None. One possible way to deal with null/undefined arguments at this
+    // point in the codebase is to conclude that they are accepted since at least one Noir type (ie: Option) can be
+    // encoded from them. Then we would let `encode` deal with potential mismatches. I chose not to do that because of
+    // the pervasiveness of null/undefined in JS, and how easy it is to inadvertently pass it around. Having this check
+    // here allows us to fail at a point where the boundaries and intent are clear.
+    if (this.hasInvalidNullOrUndefinedArguments(args)) {
+      const signature = formatFunctionSignature(this.functionDao.name, this.functionDao.parameters);
+      const received = args.map(formatArg).join(', ');
+      throw new Error(
+        `Null or undefined arguments are only allowed for Option<T> parameters in ${signature}. Received: (${received}).`,
+      );
     }
   }
 
+  private hasInvalidNullOrUndefinedArguments(args: any[]) {
+    return args.some((arg, index) => {
+      if (arg !== undefined && arg !== null) {
+        return false;
+      }
+
+      const parameterType = this.functionDao.parameters[index]?.type;
+      return !parameterType || !canBeMappedFromNullOrUndefined(parameterType);
+    });
+  }
+
   /**
    * Returns the encoded function call wrapped by this interaction
    * Useful when generating authwits
@@ -43,16 +77,16 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
    */
   public async getFunctionCall() {
     const args = encodeArguments(this.functionDao, this.args);
-    return {
+    return FunctionCall.from({
       name: this.functionDao.name,
-      args,
+      to: this.contractAddress,
       selector: await FunctionSelector.fromNameAndParameters(this.functionDao.name, this.functionDao.parameters),
       type: this.functionDao.functionType,
-      to: this.contractAddress,
-      isStatic: this.functionDao.isStatic,
       hideMsgSender: false /** Only set to `true` for enqueued public function calls */,
+      isStatic: this.functionDao.isStatic,
+      args,
       returnTypes: this.functionDao.returnTypes,
-    };
+    });
   }
 
   /**
@@ -90,21 +124,16 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
    * 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<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>> {
+    options: SimulateInteractionOptions = {} as SimulateInteractionOptions,
+  ): Promise<SimulationResult> {
     // docs:end:simulate
     if (this.functionDao.functionType == FunctionType.UTILITY) {
       const call = await this.getFunctionCall();
-      const utilityResult = await this.wallet.simulateUtility(call, options.authWitnesses ?? []);
+      const utilityResult = await this.wallet.executeUtility(call, {
+        scope: options.from,
+        authWitnesses: options.authWitnesses,
+      });
 
       // Decode the raw field elements to the actual return type
       const returnValue = utilityResult.result ? decodeFromAbi(this.functionDao.returnTypes, utilityResult.result) : [];
@@ -112,11 +141,11 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
       if (options.includeMetadata) {
         return {
           stats: utilityResult.stats,
+          ...emptyOffchainOutput(),
           result: returnValue,
         };
-      } else {
-        return returnValue;
       }
+      return { result: returnValue, ...emptyOffchainOutput() };
     }
 
     const executionPayload = await this.request(options);
@@ -138,6 +167,7 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
     }
 
     const returnValue = rawReturnValues ? decodeFromAbi(this.functionDao.returnTypes, rawReturnValues) : [];
+    const offchainOutput = extractOffchainOutput(simulatedTx.offchainEffects);
 
     if (options.includeMetadata || options.fee?.estimateGas) {
       const { gasLimits, teardownGasLimits } = getGasLimits(simulatedTx, options.fee?.estimatedGasPadding);
@@ -146,13 +176,12 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
       );
       return {
         stats: simulatedTx.stats,
-        offchainEffects: collectOffchainEffects(simulatedTx.privateExecutionResult),
+        ...offchainOutput,
         result: returnValue,
         estimatedGas: { gasLimits, teardownGasLimits },
       };
-    } else {
-      return returnValue;
     }
+    return { result: returnValue, ...offchainOutput };
   }
 
   /**
@@ -200,3 +229,62 @@ export class ContractFunctionInteraction extends BaseContractInteraction {
     );
   }
 }
+
+/**
+ *  Render an AbiType as a human readable string
+ * */
+function formatAbiType(abiType: AbiType): string {
+  switch (abiType.kind) {
+    case 'field':
+      return 'Field';
+    case 'boolean':
+      return 'bool';
+    case 'integer':
+      return `${abiType.sign === 'signed' ? 'i' : 'u'}${abiType.width}`;
+    case 'string':
+      return `str<${abiType.length}>`;
+    case 'array':
+      return `[${formatAbiType(abiType.type)}; ${abiType.length}]`;
+    case 'struct': {
+      if (isOptionStruct(abiType)) {
+        const innerType = abiType.fields.find(f => f.name === '_value')!.type;
+        return `Option<${formatAbiType(innerType)}>`;
+      }
+      return `(${abiType.fields.map(f => `${f.name}: ${formatAbiType(f.type)}`).join(', ')})`;
+    }
+    case 'tuple':
+      return `(${abiType.fields.map(formatAbiType).join(', ')})`;
+  }
+}
+
+/**
+ * Pretty print a function signature
+ */
+function formatFunctionSignature(name: string, parameters: ABIParameter[]): string {
+  const params = parameters.map(p => `${p.name}: ${formatAbiType(p.type)}`).join(', ');
+  return `${name}(${params})`;
+}
+
+/**
+ * Non-exhaustive pretty print of JS args to display in error messages in this module
+ */
+function formatArg(arg: unknown): string {
+  if (arg === undefined) {
+    return 'undefined';
+  }
+  if (arg === null) {
+    return 'null';
+  }
+  if (typeof arg === 'bigint') {
+    return `${arg}n`;
+  }
+  if (Array.isArray(arg)) {
+    return `[${arg.map(formatArg).join(', ')}]`;
+  }
+  if (typeof arg === 'object') {
+    const entries = Object.entries(arg).map(([k, v]) => `${k}: ${formatArg(v)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string
+  return String(arg);
+}