@aztec-labs/aztec.js 6.0.0-nightly.20260829

package/dest/contract/contract_function_interaction.js

@@ -0,0 +1,218 @@
+import { FunctionCall, FunctionSelector, FunctionType, canBeMappedFromNullOrUndefined, decodeFromAbi, encodeArguments, getFunctionReturnType, isOptionStruct } from '@aztec-labs/stdlib/abi';
+import { ExecutionPayload, mergeExecutionPayloads } from '@aztec-labs/stdlib/tx';
+import { BaseContractInteraction } from './base_contract_interaction.js';
+import { NO_FROM, extractOffchainOutput, toProfileOptions, toSimulateOptions } from './interaction_options.js';
+/**
+ * This is the class that is returned when calling e.g. `contract.methods.myMethod(arg0, arg1)`.
+ * It contains available interactions one can call on a method, including view.
+ */ export class ContractFunctionInteraction extends BaseContractInteraction {
+    contractAddress;
+    functionDao;
+    args;
+    extraHashedArgs;
+    constructor(wallet, contractAddress, functionDao, args, authWitnesses = [], capsules = [], extraHashedArgs = []){
+        super(wallet, authWitnesses, capsules), this.contractAddress = contractAddress, this.functionDao = functionDao, this.args = args, this.extraHashedArgs = extraHashedArgs;
+        // 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}).`);
+        }
+    }
+    hasInvalidNullOrUndefinedArguments(args) {
+        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
+   * @returns An encoded function call
+   */ async getFunctionCall() {
+        const args = encodeArguments(this.functionDao, this.args);
+        return FunctionCall.from({
+            name: this.functionDao.name,
+            to: this.contractAddress,
+            selector: await FunctionSelector.fromNameAndParameters(this.functionDao.name, this.functionDao.parameters),
+            type: this.functionDao.functionType,
+            hideMsgSender: false,
+            isStatic: this.functionDao.isStatic,
+            args,
+            returnType: getFunctionReturnType(this.functionDao)
+        });
+    }
+    /**
+   * Returns the execution payload that allows this operation to happen on chain.
+   * @param options - Configuration options.
+   * @returns The execution payload for this operation
+   */ async request(options = {}) {
+        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 information from its execution.
+   * Differs from prove in a few important ways:
+   * 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 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
+   */ async simulate(options = {}) {
+        // docs:end:simulate
+        if (this.functionDao.functionType == FunctionType.UTILITY) {
+            if (options.overrides?.publicStorage?.length || options.overrides?.contracts) {
+                throw new Error('overrides are not supported for utility function simulation.');
+            }
+            const call = await this.getFunctionCall();
+            const scopes = [
+                ...options.additionalScopes ?? []
+            ];
+            const utilityResult = await this.wallet.executeUtility(call, {
+                scopes: options.from === NO_FROM ? scopes : [
+                    options.from,
+                    ...scopes
+                ],
+                authWitnesses: options.authWitnesses
+            });
+            // Decode the raw field elements to the actual return type
+            const returnValue = utilityResult.result ? decodeFromAbi(getFunctionReturnType(this.functionDao), utilityResult.result) : undefined;
+            const offchainOutput = extractOffchainOutput(utilityResult.offchainEffects, utilityResult.anchorBlockTimestamp);
+            if (options.includeMetadata) {
+                return {
+                    stats: utilityResult.stats,
+                    ...offchainOutput,
+                    result: returnValue
+                };
+            }
+            return {
+                result: returnValue,
+                ...offchainOutput
+            };
+        }
+        const executionPayload = await this.request(options);
+        const simulatedTx = await this.wallet.simulateTx(executionPayload, toSimulateOptions(options));
+        let rawReturnValues;
+        if (this.functionDao.functionType == FunctionType.PRIVATE) {
+            // request() prepends the fee payment method's calls (if any) before this interaction's single call, so the app
+            // call is the last call of its type in the payload. Its position among the private return values is the number
+            // of private calls that precede it.
+            const appCallIndex = executionPayload.calls.filter((c)=>c.type === FunctionType.PRIVATE).length - 1;
+            rawReturnValues = simulatedTx.getPrivateReturnValuesOfAppCall(appCallIndex)?.values;
+        } else {
+            // For public functions we retrieve the values directly from the public output, offset by any public fee calls
+            // that request() prepended ahead of the app call.
+            const appCallIndex = executionPayload.calls.filter((c)=>c.type === FunctionType.PUBLIC).length - 1;
+            rawReturnValues = simulatedTx.getPublicReturnValues()?.[appCallIndex]?.values;
+        }
+        const returnValue = rawReturnValues ? decodeFromAbi(getFunctionReturnType(this.functionDao), rawReturnValues) : undefined;
+        const offchainOutput = extractOffchainOutput(simulatedTx.offchainEffects, simulatedTx.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp);
+        if (options.includeMetadata) {
+            return {
+                stats: simulatedTx.stats,
+                ...offchainOutput,
+                result: returnValue,
+                gasUsed: simulatedTx.gasUsed
+            };
+        }
+        return {
+            result: returnValue,
+            ...offchainOutput
+        };
+    }
+    /**
+   * Simulate a transaction and profile the gate count for each function in the transaction.
+   * @param options - Same options as `simulate`, plus profiling method
+   *
+   * @returns An object containing the function return value and profile result.
+   */ async profile(options) {
+        if (this.functionDao.functionType == FunctionType.UTILITY) {
+            throw new Error("Can't profile a utility function.");
+        }
+        const executionPayload = await this.request(options);
+        return await this.wallet.profileTx(executionPayload, toProfileOptions(options));
+    }
+    /**
+   * 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
+   */ with({ authWitnesses = [], capsules = [], extraHashedArgs = [] }) {
+        return new ContractFunctionInteraction(this.wallet, this.contractAddress, this.functionDao, this.args, this.authWitnesses.concat(authWitnesses), this.capsules.concat(capsules), this.extraHashedArgs.concat(extraHashedArgs));
+    }
+}
+/**
+ *  Render an AbiType as a human readable string
+ * */ function formatAbiType(abiType) {
+    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, parameters) {
+    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) {
+    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);
+}