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

package/types/app-client.mjs

@@ -9,7 +9,7 @@ import { binaryStartsWith } from '../util.mjs';
 import { UPDATABLE_TEMPLATE_NAME, DELETABLE_TEMPLATE_NAME } from './app.mjs';
 import { getArc56Method, getArc56ReturnValue, getABITupleFromABIStruct, getABIDecodedValue, getABIEncodedValue } from './app-arc56.mjs';
 import { arc32ToArc56 } from './app-spec.mjs';
-import { EventType } from './async-event-emitter.mjs';
+import { EventType } from './lifecycle-events.mjs';
 import { LogicError } from './logic-error.mjs';
 
 var ABIMethod = algosdk.ABIMethod;
@@ -40,6 +40,57 @@ function getDeployTimeControl(approval, appSpec, templateVariableName, callConfi
         return !!abiCallConfig && abiCallConfig !== 'NEVER';
     });
 }
+const BYTE_CBLOCK = 38;
+const INT_CBLOCK = 32;
+/**
+ * Get the offset of the last constant block at the beginning of the program
+ * This value is used to calculate the program counter for an ARC56 program that has a pcOffsetMethod of "cblocks"
+ *
+ * @param program The program to parse
+ * @returns The PC value of the opcode after the last constant block
+ */
+function getConstantBlockOffset(program) {
+    const bytes = [...program];
+    const programSize = bytes.length;
+    bytes.shift(); // remove version
+    /** The PC of the opcode after the bytecblock */
+    let bytecblockOffset;
+    /** The PC of the opcode after the intcblock */
+    let intcblockOffset;
+    while (bytes.length > 0) {
+        /** The current byte from the beginning of the byte array */
+        const byte = bytes.shift();
+        // If the byte is a constant block...
+        if (byte === BYTE_CBLOCK || byte === INT_CBLOCK) {
+            const isBytecblock = byte === BYTE_CBLOCK;
+            /** The byte following the opcode is the number of values in the constant block */
+            const valuesRemaining = bytes.shift();
+            // Iterate over all the values in the constant block
+            for (let i = 0; i < valuesRemaining; i++) {
+                if (isBytecblock) {
+                    /** The byte following the opcode is the length of the next element */
+                    const length = bytes.shift();
+                    bytes.splice(0, length);
+                }
+                else {
+                    // intcblock is a uvarint, so we need to keep reading until we find the end (MSB is not set)
+                    while ((bytes.shift() & 0x80) !== 0) {
+                        // Do nothing...
+                    }
+                }
+            }
+            if (isBytecblock)
+                bytecblockOffset = programSize - bytes.length - 1;
+            else
+                intcblockOffset = programSize - bytes.length - 1;
+            if (bytes[0] !== BYTE_CBLOCK && bytes[0] !== INT_CBLOCK) {
+                // if the next opcode isn't a constant block, we're done
+                break;
+            }
+        }
+    }
+    return Math.max(bytecblockOffset ?? 0, intcblockOffset ?? 0);
+}
 /** ARC-56/ARC-32 application client that allows you to manage calls and
  * state for a specific deployed instance of an app (with a known app ID). */
 class AppClient {
@@ -50,6 +101,7 @@ class AppClient {
         this._appName = params.appName ?? this._appSpec.name;
         this._algorand = params.algorand;
         this._defaultSender = params.defaultSender;
+        this._defaultSigner = params.defaultSigner;
         this._approvalSourceMap = params.approvalSourceMap;
         this._clearSourceMap = params.clearSourceMap;
         this._localStateMethods = (address) => this.getStateMethods(() => this.getLocalState(address), () => this._appSpec.state.keys.local, () => this._appSpec.state.maps.local);
@@ -71,9 +123,24 @@ class AppClient {
             bare: this.getBareSendMethods(),
         };
     }
-    /** Start a new `AlgoKitComposer` transaction group */
-    newGroup() {
-        return this._algorand.newGroup();
+    /**
+     * Clone this app client with different params
+     *
+     * @param params The params to use for the the cloned app client. Omit a param to keep the original value. Set a param to override the original value. Setting to undefined will clear the original value.
+     * @returns A new app client with the altered params
+     */
+    clone(params) {
+        return new AppClient({
+            appId: this._appId,
+            appSpec: this._appSpec,
+            algorand: this._algorand,
+            appName: this._appName,
+            defaultSender: this._defaultSender,
+            defaultSigner: this._defaultSigner,
+            approvalSourceMap: this._approvalSourceMap,
+            clearSourceMap: this._clearSourceMap,
+            ...params,
+        });
     }
     /**
      * Returns a new `AppClient` client, resolving the app by creator address and name
@@ -145,6 +212,10 @@ class AppClient {
     get appSpec() {
         return this._appSpec;
     }
+    /** A reference to the underlying `AlgorandClient` this app client is using. */
+    get algorand() {
+        return this._algorand;
+    }
     /** Get parameters to create transactions for the current app.
      *
      * A good mental model for this is that these parameters represent a deferred transaction creation.
@@ -276,11 +347,19 @@ class AppClient {
      * @param isClearStateProgram Whether or not the code was running the clear state program (defaults to approval program)
      * @returns The new error, or if there was no logic error or source map then the wrapped error with source details
      */
-    exposeLogicError(e, isClearStateProgram) {
+    async exposeLogicError(e, isClearStateProgram) {
+        const pcOffsetMethod = this._appSpec.sourceInfo?.[isClearStateProgram ? 'clear' : 'approval']?.pcOffsetMethod;
+        let program;
+        if (pcOffsetMethod === 'cblocks') {
+            // TODO: Cache this if we deploy the app and it's not updateable
+            const appInfo = await this._algorand.app.getById(this.appId);
+            program = isClearStateProgram ? appInfo.clearStateProgram : appInfo.approvalProgram;
+        }
         return AppClient.exposeLogicError(e, this._appSpec, {
             isClearStateProgram,
             approvalSourceMap: this._approvalSourceMap,
             clearSourceMap: this._clearSourceMap,
+            program,
         });
     }
     /**
@@ -338,11 +417,11 @@ class AppClient {
      */
     async compile(compilation) {
         const result = await AppClient.compile(this._appSpec, this._algorand.app, compilation);
-        if (result.approvalProgramCompilationResult) {
-            this._approvalSourceMap = result.approvalProgramCompilationResult.sourceMap;
+        if (result.compiledApproval) {
+            this._approvalSourceMap = result.compiledApproval.sourceMap;
         }
-        if (result.clearStateProgramCompilationResult) {
-            this._clearSourceMap = result.clearStateProgramCompilationResult.sourceMap;
+        if (result.compiledClear) {
+            this._clearSourceMap = result.compiledClear.sourceMap;
         }
         return result;
     }
@@ -355,17 +434,45 @@ class AppClient {
      * @returns The new error, or if there was no logic error or source map then the wrapped error with source details
      */
     static exposeLogicError(e, appSpec, details) {
-        const { isClearStateProgram, approvalSourceMap, clearSourceMap } = details;
-        if ((!isClearStateProgram && approvalSourceMap == undefined) || (isClearStateProgram && clearSourceMap == undefined))
-            return e;
+        const { isClearStateProgram, approvalSourceMap, clearSourceMap, program } = details;
+        const sourceMap = isClearStateProgram ? clearSourceMap : approvalSourceMap;
         const errorDetails = LogicError.parseLogicError(e);
-        const errorMessage = (isClearStateProgram ? appSpec.sourceInfo?.clear : appSpec.sourceInfo?.approval)?.find((s) => s?.pc?.includes(errorDetails?.pc ?? -1))?.errorMessage;
-        if (errorDetails !== undefined && appSpec.source)
+        // Return the error if we don't have a PC
+        if (errorDetails === undefined || errorDetails?.pc === undefined)
+            return e;
+        /** The PC value to find in the ARC56 SourceInfo */
+        let arc56Pc = errorDetails?.pc;
+        const programSourceInfo = isClearStateProgram ? appSpec.sourceInfo?.clear : appSpec.sourceInfo?.approval;
+        /** The offset to apply to the PC if using the cblocks pc offset method */
+        let cblocksOffset = 0;
+        // If the program uses cblocks offset, then we need to adjust the PC accordingly
+        if (programSourceInfo?.pcOffsetMethod === 'cblocks') {
+            if (program === undefined)
+                throw new Error('Program bytes are required to calculate the ARC56 cblocks PC offset');
+            cblocksOffset = getConstantBlockOffset(program);
+            arc56Pc = errorDetails.pc - cblocksOffset;
+        }
+        // Find the source info for this PC and get the error message
+        const sourceInfo = programSourceInfo?.sourceInfo.find((s) => s.pc.includes(arc56Pc));
+        const errorMessage = sourceInfo?.errorMessage;
+        // If we have the source we can display the TEAL in the error message
+        if (appSpec.source) {
+            let getLineForPc = (inputPc) => sourceMap?.getLineForPc?.(inputPc);
+            // If the SourceMap is not defined, we need to provide our own function for going from a PC to TEAL based on ARC56 SourceInfo[]
+            if (sourceMap === undefined) {
+                getLineForPc = (inputPc) => {
+                    const teal = programSourceInfo?.sourceInfo.find((s) => s.pc.includes(inputPc - cblocksOffset))?.teal;
+                    if (teal === undefined)
+                        return undefined;
+                    return teal - 1;
+                };
+            }
             e = new LogicError(errorDetails, Buffer.from(isClearStateProgram ? appSpec.source.clear : appSpec.source.approval, 'base64')
                 .toString()
                 .split('\n'), 
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            isClearStateProgram ? clearSourceMap : approvalSourceMap);
+            getLineForPc);
+        }
         if (errorMessage) {
             const appId = JSON.stringify(e).match(/(?<=app=)\d+/)?.[0] || '';
             const txId = JSON.stringify(e).match(/(?<=transaction )\S+(?=:)/)?.[0];
@@ -398,25 +505,25 @@ class AppClient {
             };
         }
         const approvalTemplate = Buffer.from(appSpec.source.approval, 'base64').toString('utf-8');
-        const approvalProgramCompilationResult = await appManager.compileTealTemplate(approvalTemplate, deployTimeParams, {
+        const compiledApproval = await appManager.compileTealTemplate(approvalTemplate, deployTimeParams, {
             updatable,
             deletable,
         });
         const clearTemplate = Buffer.from(appSpec.source.clear, 'base64').toString('utf-8');
-        const clearStateProgramCompilationResult = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
+        const compiledClear = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
         if (Config.debug) {
             await Config.events.emitAsync(EventType.AppCompiled, {
                 sources: [
-                    { compiledTeal: approvalProgramCompilationResult, appName: appSpec.name, fileName: 'approval' },
-                    { compiledTeal: clearStateProgramCompilationResult, appName: appSpec.name, fileName: 'clear' },
+                    { compiledTeal: compiledApproval, appName: appSpec.name, fileName: 'approval' },
+                    { compiledTeal: compiledClear, appName: appSpec.name, fileName: 'clear' },
                 ],
             });
         }
         return {
-            approvalProgram: approvalProgramCompilationResult.compiledBase64ToBytes,
-            approvalProgramCompilationResult,
-            clearStateProgram: clearStateProgramCompilationResult.compiledBase64ToBytes,
-            clearStateProgramCompilationResult,
+            approvalProgram: compiledApproval.compiledBase64ToBytes,
+            compiledApproval,
+            clearStateProgram: compiledClear.compiledBase64ToBytes,
+            compiledClear,
         };
     }
     /**
@@ -442,19 +549,22 @@ class AppClient {
             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 'method': {
+                        const method = this.getABIMethod(defaultValue.data);
+                        const result = await this.send.call({
+                            method: defaultValue.data,
+                            args: method.args.map(() => undefined),
+                            sender,
+                        });
+                        if (result.return === undefined) {
+                            throw new Error('Default value method call did not return a value');
+                        }
+                        if (typeof result.return === 'object' && !(result.return instanceof Uint8Array) && !Array.isArray(result.return)) {
+                            return getABITupleFromABIStruct(result.return, this._appSpec.structs[method.returns.struct], this._appSpec.structs);
+                        }
+                        return result.return;
+                    }
                     case 'local':
                     case 'global': {
                         const state = defaultValue.source === 'global' ? await this.getGlobalState() : await this.getLocalState(sender);
@@ -472,7 +582,9 @@ class AppClient {
                     }
                 }
             }
-            throw new Error(`No value provided for required argument ${arg.name ?? `arg${i + 1}`} in call to method ${m.name}`);
+            if (!algosdk.abiTypeIsTransaction(arg.type)) {
+                throw new Error(`No value provided for required argument ${arg.name ?? `arg${i + 1}`} in call to method ${m.name}`);
+            }
         }) ?? []);
     }
     getBareParamsMethods() {
@@ -541,10 +653,7 @@ class AppClient {
                 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,
-                    },
+                    ...compiled,
                 };
             },
             /** Signs and sends an opt-in call */
@@ -576,6 +685,7 @@ class AppClient {
                 return {
                     ...params,
                     sender: this.getSender(params.sender),
+                    signer: this.getSigner(params.sender, params.signer),
                     receiver: this.appAddress,
                 };
             },
@@ -617,10 +727,7 @@ class AppClient {
                 const compiled = await this.compile(params);
                 return {
                     ...(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,
-                    },
+                    ...compiled,
                 };
             },
             /**
@@ -646,13 +753,15 @@ class AppClient {
              */
             call: async (params) => {
                 // Read-only call - do it via simulate
-                if (params.onComplete === OnApplicationComplete.NoOpOC ||
-                    (!params.onComplete && getArc56Method(params.method, this._appSpec).method.readonly)) {
+                if ((params.onComplete === OnApplicationComplete.NoOpOC || !params.onComplete) &&
+                    getArc56Method(params.method, this._appSpec).method.readonly) {
                     const result = await this._algorand
                         .newGroup()
                         .addAppCallMethodCall(await this.params.call(params))
                         .simulate({
-                        allowUnnamedResources: params.populateAppCallResources,
+                        allowUnnamedResources: params.populateAppCallResources ?? true,
+                        // Simulate calls for a readonly method shouldn't invoke signing
+                        skipSignatures: true,
                     });
                     return this.processMethodCallReturn({
                         ...result,
@@ -704,7 +813,7 @@ class AppClient {
             },
         };
     }
-    /** Returns the sender for a call, using the `defaultSender`
+    /** Returns the sender for a call, using the provided sender or using the `defaultSender`
      * if none provided and throws an error if neither provided */
     getSender(sender) {
         if (!sender && !this._defaultSender) {
@@ -712,11 +821,18 @@ class AppClient {
         }
         return sender ?? this._defaultSender;
     }
+    /** Returns the signer for a call, using the provided signer or the `defaultSigner`
+     * if no signer was provided and the call will use default sender
+     * or `undefined` otherwise (so the signer is resolved from `AlgorandClient`) */
+    getSigner(sender, signer) {
+        return signer ?? (!sender ? this._defaultSigner : undefined);
+    }
     getBareParams(params, onComplete) {
         return {
             ...params,
             appId: this._appId,
             sender: this.getSender(params?.sender),
+            signer: this.getSigner(params?.sender, params?.signer),
             onComplete,
         };
     }
@@ -728,6 +844,7 @@ class AppClient {
             ...params,
             appId: this._appId,
             sender: sender,
+            signer: this.getSigner(params.sender, params.signer),
             method,
             onComplete,
             args,
@@ -739,7 +856,7 @@ class AppClient {
             return await call();
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     getBoxMethods() {
@@ -1103,7 +1220,7 @@ class ApplicationClient {
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1137,7 +1254,7 @@ class ApplicationClient {
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1490,7 +1607,7 @@ class ApplicationClient {
                 .toString()
                 .split('\n'), 
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            isClear ? this._clearSourceMap : this._approvalSourceMap);
+            (pc) => (isClear ? this._clearSourceMap : this._approvalSourceMap).getLineForPc(pc));
         else
             return e;
     }