@algorandfoundation/algokit-utils 7.0.0-beta.6 → 7.0.0-beta.8

package/types/app-client.mjs

@@ -57,10 +57,19 @@ class AppClient {
         this._boxStateMethods = this.getBoxMethods();
         this._paramsMethods = {
             ...this.getMethodCallParamsMethods(),
+            /** Get parameters to define bare (raw) transactions to the current app */
             bare: this.getBareParamsMethods(),
         };
-        this._transactionsMethods = { ...this.getMethodCallTransactionsMethods(), bare: this.getBareTransactionsMethods() };
-        this._sendMethods = { ...this.getMethodCallSendMethods(), bare: this.getBareSendMethods() };
+        this._createTransactionsMethods = {
+            ...this.getMethodCallCreateTransactionMethods(),
+            /** Get transactions for bare (raw) calls to the current app */
+            bare: this.getBareCreateTransactionMethods(),
+        };
+        this._sendMethods = {
+            ...this.getMethodCallSendMethods(),
+            /** Send bare (raw) transactions to the current app */
+            bare: this.getBareSendMethods(),
+        };
     }
     /** Start a new `AlgoKitComposer` transaction group */
     newGroup() {
@@ -136,18 +145,33 @@ class AppClient {
     get appSpec() {
         return this._appSpec;
     }
-    /** Get parameters to define transactions to the current app */
+    /** Get parameters to create transactions for the current app.
+     *
+     * A good mental model for this is that these parameters represent a deferred transaction creation.
+     * @example Create a transaction in the future using Algorand Client
+     * ```typescript
+     * const myMethodCall = appClient.params.call({method: 'my_method', args: [123, 'hello']})
+     * // ...
+     * await algorand.send.AppMethodCall(myMethodCall)
+     * ```
+     * @example Define a nested transaction as an ABI argument
+     * ```typescript
+     * const myMethodCall = appClient.params.call({method: 'my_method', args: [123, 'hello']})
+     * await appClient.send.call({method: 'my_method2', args: [myMethodCall]})
+     * ```
+     */
     get params() {
         return this._paramsMethods;
     }
-    /** Get transactions for the current app */
-    get transactions() {
-        return this._transactionsMethods;
+    /** Create transactions for the current app */
+    get createTransaction() {
+        return this._createTransactionsMethods;
     }
-    /** Send calls to the current app */
+    /** Send transactions to the current app */
     get send() {
         return this._sendMethods;
     }
+    /** Get state (local, global, box) from the current app */
     get state() {
         return {
             /**
@@ -167,6 +191,8 @@ class AppClient {
     }
     /**
      * Funds Algo into the app account for this app.
+     *
+     * An alias for `appClient.send.fundAppAccount(params)`.
      * @param params The parameters for the funding transaction
      * @returns The result of the funding
      */
@@ -279,7 +305,7 @@ class AppClient {
         this._clearSourceMap = new SourceMap(sourceMaps.clearSourceMap);
     }
     /**
-     * Returns the ABI Method for the given method name string for the app represented by this application client instance
+     * Returns the ABI Method spec for the given method string for the app represented by this application client instance
      * @param methodNameOrSignature The method name or method signature to call if an ABI call is being emitted.
      * e.g. `my_method` or `my_method(unit64,string)bytes`
      * @returns A tuple with: [ARC-56 `Method`, algosdk `ABIMethod`]
@@ -289,18 +315,37 @@ class AppClient {
     }
     /**
      * Checks for decode errors on the SendAppTransactionResult and maps the return value to the specified type
-     * on the ARC-56 method.
+     * on the ARC-56 method, replacing the `return` property with the decoded type.
      *
-     * If the return type is a struct then the struct will be returned.
+     * If the return type is an ARC-56 struct then the struct will be returned.
      *
      * @param result The SendAppTransactionResult to be mapped
      * @param method The method that was called
      * @returns The smart contract response with an updated return value
      */
-    async parseMethodCallReturn(result, method) {
+    async processMethodCallReturn(result, method) {
         const resultValue = await result;
         return { ...resultValue, return: getArc56ReturnValue(resultValue.return, method, this._appSpec.structs) };
     }
+    /**
+     * Compiles the approval and clear state programs (if TEAL templates provided),
+     * performing any provided deploy-time parameter replacement and stores
+     * the source maps.
+     *
+     * If no TEAL templates provided it will use any byte code provided in the app spec.
+     *
+     * Will store any generated source maps for later use in debugging.
+     */
+    async compile(compilation) {
+        const result = await AppClient.compile(this._appSpec, this._algorand.app, compilation);
+        if (result.approvalProgramCompilationResult) {
+            this._approvalSourceMap = result.approvalProgramCompilationResult.sourceMap;
+        }
+        if (result.clearStateProgramCompilationResult) {
+            this._clearSourceMap = result.clearStateProgramCompilationResult.sourceMap;
+        }
+        return result;
+    }
     /**
      * Takes an error that may include a logic error from a call to the current app and re-exposes the
      * error to include source code information via the source map and ARC-56 spec.
@@ -353,25 +398,25 @@ class AppClient {
             };
         }
         const approvalTemplate = Buffer.from(appSpec.source.approval, 'base64').toString('utf-8');
-        const compiledApproval = await appManager.compileTealTemplate(approvalTemplate, deployTimeParams, {
+        const approvalProgramCompilationResult = await appManager.compileTealTemplate(approvalTemplate, deployTimeParams, {
             updatable,
             deletable,
         });
         const clearTemplate = Buffer.from(appSpec.source.clear, 'base64').toString('utf-8');
-        const compiledClear = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
+        const clearStateProgramCompilationResult = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
         if (Config.debug) {
             await Config.events.emitAsync(EventType.AppCompiled, {
                 sources: [
-                    { compiledTeal: compiledApproval, appName: appSpec.name, fileName: 'approval' },
-                    { compiledTeal: compiledClear, appName: appSpec.name, fileName: 'clear' },
+                    { compiledTeal: approvalProgramCompilationResult, appName: appSpec.name, fileName: 'approval' },
+                    { compiledTeal: clearStateProgramCompilationResult, appName: appSpec.name, fileName: 'clear' },
                 ],
             });
         }
         return {
-            approvalProgram: compiledApproval.compiledBase64ToBytes,
-            compiledApproval,
-            clearStateProgram: compiledClear.compiledBase64ToBytes,
-            compiledClear,
+            approvalProgram: approvalProgramCompilationResult.compiledBase64ToBytes,
+            approvalProgramCompilationResult,
+            clearStateProgram: clearStateProgramCompilationResult.compiledBase64ToBytes,
+            clearStateProgramCompilationResult,
         };
     }
     /**
@@ -382,24 +427,53 @@ class AppClient {
      * @param methodNameOrSignature The method name or method signature to call if an ABI call is being emitted.
      * e.g. `my_method` or `my_method(unit64,string)bytes`
      * @param args The arguments to the method with `undefined` for any that should be populated with a default value
-     * @param appSpec The app spec for the app
      */
-    static getABIArgsWithDefaultValues(methodNameOrSignature, args, appSpec) {
-        const m = getArc56Method(methodNameOrSignature, appSpec);
-        return args?.map((a, i) => {
+    async getABIArgsWithDefaultValues(methodNameOrSignature, args, sender) {
+        const m = getArc56Method(methodNameOrSignature, this._appSpec);
+        return await Promise.all(args?.map(async (a, i) => {
             const arg = m.args[i];
             if (a !== undefined) {
                 // If a struct then convert to tuple for the underlying call
                 return arg.struct && typeof a === 'object' && !Array.isArray(a)
-                    ? getABITupleFromABIStruct(a, appSpec.structs[arg.struct])
+                    ? getABITupleFromABIStruct(a, this._appSpec.structs[arg.struct], this._appSpec.structs)
                     : a;
             }
-            // todo: expand this to match previous ApplicationClient implementation when ARC-56 spec is updated to support other default value options
             const defaultValue = arg.defaultValue;
-            if (defaultValue)
-                return getABIDecodedValue(Buffer.from(defaultValue, 'base64'), m.method.args[i].type, {});
+            if (defaultValue) {
+                switch (defaultValue.source) {
+                    case 'literal':
+                        if (typeof defaultValue.data === 'number')
+                            return defaultValue.data;
+                        return getABIDecodedValue(Buffer.from(defaultValue.data, 'base64'), m.method.args[i].defaultValue?.type ?? m.method.args[i].type, this._appSpec.structs);
+                    // todo: When ARC-56 supports ABI calls as default args
+                    // case 'abi': {
+                    //   const method = this.getABIMethod(defaultValue.data as string)
+                    //   const result = await this.send.call({
+                    //     method: defaultValue.data as string,
+                    //     methodArgs: method.args.map(() => undefined),
+                    //     sender,
+                    //   })
+                    //   return result.return!
+                    // }
+                    case 'local':
+                    case 'global': {
+                        const state = defaultValue.source === 'global' ? await this.getGlobalState() : await this.getLocalState(sender);
+                        const value = Object.values(state).find((s) => s.keyBase64 === defaultValue.data);
+                        if (!value) {
+                            throw new Error(`Preparing default value for argument ${arg.name ?? `arg${i + 1}`} resulted in the failure: The key '${defaultValue.data}' could not be found in ${defaultValue.source} storage`);
+                        }
+                        return 'valueRaw' in value
+                            ? getABIDecodedValue(value.valueRaw, m.method.args[i].defaultValue?.type ?? m.method.args[i].type, this._appSpec.structs)
+                            : value.value;
+                    }
+                    case 'box': {
+                        const value = await this.getBoxValue(Buffer.from(defaultValue.data, 'base64'));
+                        return getABIDecodedValue(value, m.method.args[i].defaultValue?.type ?? m.method.args[i].type, this._appSpec.structs);
+                    }
+                }
+            }
             throw new Error(`No value provided for required argument ${arg.name ?? `arg${i + 1}`} in call to method ${m.name}`);
-        });
+        }) ?? []);
     }
     getBareParamsMethods() {
         return {
@@ -432,31 +506,31 @@ class AppClient {
             },
         };
     }
-    getBareTransactionsMethods() {
+    getBareCreateTransactionMethods() {
         return {
             /** Returns a transaction for an update call, including deploy-time TEAL template replacements and compilation if provided */
             update: async (params) => {
-                return this._algorand.transactions.appUpdate(await this.params.bare.update(params));
+                return this._algorand.createTransaction.appUpdate(await this.params.bare.update(params));
             },
             /** Returns a transaction for an opt-in call */
             optIn: (params) => {
-                return this._algorand.transactions.appCall(this.params.bare.optIn(params));
+                return this._algorand.createTransaction.appCall(this.params.bare.optIn(params));
             },
             /** Returns a transaction for a delete call */
             delete: (params) => {
-                return this._algorand.transactions.appDelete(this.params.bare.delete(params));
+                return this._algorand.createTransaction.appDelete(this.params.bare.delete(params));
             },
             /** Returns a transaction for a clear state call */
             clearState: (params) => {
-                return this._algorand.transactions.appCall(this.params.bare.clearState(params));
+                return this._algorand.createTransaction.appCall(this.params.bare.clearState(params));
             },
             /** Returns a transaction for a close out call */
             closeOut: (params) => {
-                return this._algorand.transactions.appCall(this.params.bare.closeOut(params));
+                return this._algorand.createTransaction.appCall(this.params.bare.closeOut(params));
             },
             /** Returns a transaction for a call (defaults to no-op) */
             call: (params) => {
-                return this._algorand.transactions.appCall(this.params.bare.call(params));
+                return this._algorand.createTransaction.appCall(this.params.bare.call(params));
             },
         };
     }
@@ -464,7 +538,14 @@ class AppClient {
         return {
             /** Signs and sends an update call, including deploy-time TEAL template replacements and compilation if provided */
             update: async (params) => {
-                return await this.handleCallErrors(async () => this._algorand.send.appUpdate(await this.params.bare.update(params)));
+                const compiled = await this.compile(params);
+                return {
+                    ...(await this.handleCallErrors(async () => this._algorand.send.appUpdate(await this.params.bare.update(params)))),
+                    ...{
+                        compiledApproval: compiled.approvalProgramCompilationResult,
+                        compiledClear: compiled.clearStateProgramCompilationResult,
+                    },
+                };
             },
             /** Signs and sends an opt-in call */
             optIn: (params) => {
@@ -500,26 +581,26 @@ class AppClient {
             },
             /** Return params for an update ABI call, including deploy-time TEAL template replacements and compilation if provided */
             update: async (params) => {
-                return this.getABIParams({
+                return (await this.getABIParams({
                     ...params,
                     ...(await this.compile(params)),
-                }, OnApplicationComplete.UpdateApplicationOC);
+                }, OnApplicationComplete.UpdateApplicationOC));
             },
             /** Return params for an opt-in ABI call */
-            optIn: (params) => {
-                return this.getABIParams(params, OnApplicationComplete.OptInOC);
+            optIn: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.OptInOC));
             },
             /** Return params for an delete ABI call */
-            delete: (params) => {
-                return this.getABIParams(params, OnApplicationComplete.DeleteApplicationOC);
+            delete: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.DeleteApplicationOC));
             },
             /** Return params for an close out ABI call */
-            closeOut: (params) => {
-                return this.getABIParams(params, OnApplicationComplete.CloseOutOC);
+            closeOut: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.CloseOutOC));
             },
             /** Return params for an ABI call */
-            call: (params) => {
-                return this.getABIParams(params, params.onComplete ?? OnApplicationComplete.NoOpOC);
+            call: async (params) => {
+                return (await this.getABIParams(params, params.onComplete ?? OnApplicationComplete.NoOpOC));
             },
         };
     }
@@ -535,27 +616,30 @@ class AppClient {
             update: async (params) => {
                 const compiled = await this.compile(params);
                 return {
-                    ...(await this.handleCallErrors(async () => this.parseMethodCallReturn(this._algorand.send.appUpdateMethodCall(await this.params.update({ ...params })), getArc56Method(params.method, this._appSpec)))),
-                    ...compiled,
+                    ...(await this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appUpdateMethodCall(await this.params.update({ ...params })), getArc56Method(params.method, this._appSpec)))),
+                    ...{
+                        compiledApproval: compiled.approvalProgramCompilationResult,
+                        compiledClear: compiled.clearStateProgramCompilationResult,
+                    },
                 };
             },
             /**
              * Sign and send transactions for an opt-in ABI call
              */
             optIn: (params) => {
-                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.optIn(params)), getArc56Method(params.method, this._appSpec)));
+                return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.optIn(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a delete ABI call
              */
             delete: (params) => {
-                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appDeleteMethodCall(this.params.delete(params)), getArc56Method(params.method, this._appSpec)));
+                return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appDeleteMethodCall(await this.params.delete(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a close out ABI call
              */
             closeOut: (params) => {
-                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.closeOut(params)), getArc56Method(params.method, this._appSpec)));
+                return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.closeOut(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a call (defaults to no-op)
@@ -564,8 +648,13 @@ class AppClient {
                 // Read-only call - do it via simulate
                 if (params.onComplete === OnApplicationComplete.NoOpOC ||
                     (!params.onComplete && getArc56Method(params.method, this._appSpec).method.readonly)) {
-                    const result = await this._algorand.newGroup().addAppCallMethodCall(this.params.call(params)).simulate();
-                    return this.parseMethodCallReturn({
+                    const result = await this._algorand
+                        .newGroup()
+                        .addAppCallMethodCall(await this.params.call(params))
+                        .simulate({
+                        allowUnnamedResources: params.populateAppCallResources,
+                    });
+                    return this.processMethodCallReturn({
                         ...result,
                         transaction: result.transactions.at(-1),
                         confirmation: result.confirmations.at(-1),
@@ -573,67 +662,48 @@ class AppClient {
                         return: (result.returns?.length ?? 0 > 0) ? result.returns?.at(-1) : undefined,
                     }, getArc56Method(params.method, this._appSpec));
                 }
-                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.call(params)), getArc56Method(params.method, this._appSpec)));
+                return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.call(params)), getArc56Method(params.method, this._appSpec)));
             },
         };
     }
-    getMethodCallTransactionsMethods() {
+    getMethodCallCreateTransactionMethods() {
         return {
             /** Return transaction for a payment transaction to fund the app account */
             fundAppAccount: (params) => {
-                return this._algorand.transactions.payment(this.params.fundAppAccount(params));
+                return this._algorand.createTransaction.payment(this.params.fundAppAccount(params));
             },
             /**
              * Return transactions for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
              */
             update: async (params) => {
-                return this._algorand.transactions.appUpdateMethodCall(await this.params.update(params));
+                return this._algorand.createTransaction.appUpdateMethodCall(await this.params.update(params));
             },
             /**
              * Return transactions for an opt-in ABI call
              */
-            optIn: (params) => {
-                return this._algorand.transactions.appCallMethodCall(this.params.optIn(params));
+            optIn: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.optIn(params));
             },
             /**
              * Return transactions for a delete ABI call
              */
-            delete: (params) => {
-                return this._algorand.transactions.appDeleteMethodCall(this.params.delete(params));
+            delete: async (params) => {
+                return this._algorand.createTransaction.appDeleteMethodCall(await this.params.delete(params));
             },
             /**
              * Return transactions for a close out ABI call
              */
-            closeOut: (params) => {
-                return this._algorand.transactions.appCallMethodCall(this.params.closeOut(params));
+            closeOut: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.closeOut(params));
             },
             /**
              * Return transactions for an ABI call (defaults to no-op)
              */
-            call: (params) => {
-                return this._algorand.transactions.appCallMethodCall(this.params.call(params));
+            call: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.call(params));
             },
         };
     }
-    /**
-     * Compiles the approval and clear state programs (if TEAL templates provided),
-     * performing any provided deploy-time parameter replacement and stores
-     * the source maps.
-     *
-     * If no TEAL templates provided it will use any byte code provided in the app spec.
-     *
-     * Will store any generated source maps for later use in debugging.
-     */
-    async compile(compilation) {
-        const result = await AppClient.compile(this._appSpec, this._algorand.app, compilation);
-        if (result.compiledApproval) {
-            this._approvalSourceMap = result.compiledApproval.sourceMap;
-        }
-        if (result.compiledClear) {
-            this._clearSourceMap = result.compiledClear.sourceMap;
-        }
-        return result;
-    }
     /** Returns the sender for a call, using the `defaultSender`
      * if none provided and throws an error if neither provided */
     getSender(sender) {
@@ -650,13 +720,14 @@ class AppClient {
             onComplete,
         };
     }
-    getABIParams(params, onComplete) {
+    async getABIParams(params, onComplete) {
+        const sender = this.getSender(params.sender);
         const method = getArc56Method(params.method, this._appSpec);
-        const args = AppClient.getABIArgsWithDefaultValues(params.method, params.args, this._appSpec);
+        const args = await this.getABIArgsWithDefaultValues(params.method, params.args, sender);
         return {
             ...params,
             appId: this._appId,
-            sender: this.getSender(params.sender),
+            sender: sender,
             method,
             onComplete,
             args,
@@ -1036,7 +1107,7 @@ class ApplicationClient {
         }
     }
     /**
-     * @deprecated Use `appClient.send.update` or `appClient.transactions.update` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.update` or `appClient.createTransaction.update` from an `AppClient` instance instead.
      *
      * Updates the smart contract app.
      * @param update The parameters to update the app with
@@ -1070,7 +1141,7 @@ class ApplicationClient {
         }
     }
     /**
-     * @deprecated Use `appClient.send.call` or `appClient.transactions.call` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.call` or `appClient.createTransaction.call` from an `AppClient` instance instead.
      *
      * Issues a no_op (normal) call to the app.
      * @param call The call details.
@@ -1105,7 +1176,7 @@ class ApplicationClient {
         return await this.callOfType(call, 'no_op');
     }
     /**
-     * @deprecated Use `appClient.send.optIn` or `appClient.transactions.optIn` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.optIn` or `appClient.createTransaction.optIn` from an `AppClient` instance instead.
      *
      * Issues a opt_in call to the app.
      * @param call The call details.
@@ -1115,7 +1186,7 @@ class ApplicationClient {
         return await this.callOfType(call, 'opt_in');
     }
     /**
-     * @deprecated Use `appClient.send.closeOut` or `appClient.transactions.closeOut` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.closeOut` or `appClient.createTransaction.closeOut` from an `AppClient` instance instead.
      *
      * Issues a close_out call to the app.
      * @param call The call details.
@@ -1125,7 +1196,7 @@ class ApplicationClient {
         return await this.callOfType(call, 'close_out');
     }
     /**
-     * @deprecated Use `appClient.send.clearState` or `appClient.transactions.clearState` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.clearState` or `appClient.createTransaction.clearState` from an `AppClient` instance instead.
      *
      * Issues a clear_state call to the app.
      * @param call The call details.
@@ -1135,7 +1206,7 @@ class ApplicationClient {
         return await this.callOfType(call, 'clear_state');
     }
     /**
-     * @deprecated Use `appClient.send.delete` or `appClient.transactions.delete` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.delete` or `appClient.createTransaction.delete` from an `AppClient` instance instead.
      *
      * Issues a delete_application call to the app.
      * @param call The call details.
@@ -1145,7 +1216,7 @@ class ApplicationClient {
         return await this.callOfType(call, 'delete_application');
     }
     /**
-     * @deprecated Use `appClient.send.call` or `appClient.transactions.call` from an `AppClient` instance instead.
+     * @deprecated Use `appClient.send.call` or `appClient.createTransaction.call` from an `AppClient` instance instead.
      *
      * Issues a call to the app with the given call type.
      * @param call The call details.