@algorandfoundation/algokit-utils 7.0.0-beta.9 → 8.0.0-beta.1

package/types/app-client.mjs

@@ -1,4 +1,4 @@
-import algosdk from 'algosdk';
+import algosdk, { Address } from 'algosdk';
 import { Buffer } from 'buffer';
 import { compileTeal, createApp, updateApp, callApp, getAppGlobalState, getAppLocalState, getAppBoxNames, getAppBoxValue, getAppBoxValueFromABIType } from '../app.mjs';
 import { replaceDeployTimeControlParams, performTemplateSubstitution, deployApp, getCreatorAppsByName } from '../app-deploy.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;
@@ -17,7 +17,7 @@ var AtomicTransactionComposer = algosdk.AtomicTransactionComposer;
 var getApplicationAddress = algosdk.getApplicationAddress;
 var Indexer = algosdk.Indexer;
 var OnApplicationComplete = algosdk.OnApplicationComplete;
-var SourceMap = algosdk.SourceMap;
+var SourceMap = algosdk.ProgramSourceMap;
 /**
  * Determines deploy time control (UPDATABLE, DELETABLE) value by inspecting application specification
  * @param approval TEAL Approval program, not the base64 version found on the appSpec
@@ -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 {
@@ -49,7 +100,7 @@ class AppClient {
         this._appSpec = AppClient.normaliseAppSpec(params.appSpec);
         this._appName = params.appName ?? this._appSpec.name;
         this._algorand = params.algorand;
-        this._defaultSender = params.defaultSender;
+        this._defaultSender = typeof params.defaultSender === 'string' ? Address.fromString(params.defaultSender) : params.defaultSender;
         this._defaultSigner = params.defaultSigner;
         this._approvalSourceMap = params.approvalSourceMap;
         this._clearSourceMap = params.clearSourceMap;
@@ -72,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
@@ -138,7 +204,7 @@ class AppClient {
     get appAddress() {
         return this._appAddress;
     }
-    /** The name of the app (from the ARC-32 / ARC-56 app spec). */
+    /** The name of the app (from the ARC-32 / ARC-56 app spec or override). */
     get appName() {
         return this._appName;
     }
@@ -281,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,
         });
     }
     /**
@@ -360,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?.getLocationForPc?.(inputPc)?.line;
+            // 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];
@@ -447,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);
@@ -477,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() {
@@ -646,13 +753,13 @@ 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,
                     });
@@ -712,7 +819,7 @@ class AppClient {
         if (!sender && !this._defaultSender) {
             throw new Error(`No sender provided and no default sender present in app client for call to app ${this._appName}`);
         }
-        return sender ?? this._defaultSender;
+        return typeof sender === 'string' ? Address.fromString(sender) : (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
@@ -749,7 +856,7 @@ class AppClient {
             return await call();
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     getBoxMethods() {
@@ -917,7 +1024,7 @@ class ApplicationClient {
         }
         else {
             this._appId = 0;
-            this._creator = appIdentifier.creatorAddress;
+            this._creator = appIdentifier.creatorAddress?.toString();
             if (appIdentifier.findExistingUsing instanceof Indexer) {
                 this.indexer = appIdentifier.findExistingUsing;
             }
@@ -928,7 +1035,7 @@ class ApplicationClient {
                 this.existingDeployments = appIdentifier.findExistingUsing;
             }
         }
-        this._appAddress = algosdk.getApplicationAddress(this._appId);
+        this._appAddress = algosdk.getApplicationAddress(this._appId).toString();
         this.sender = sender;
         this.params = params;
     }
@@ -1108,12 +1215,12 @@ class ApplicationClient {
             if (result.confirmation) {
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 this._appId = result.confirmation.applicationIndex;
-                this._appAddress = getApplicationAddress(this._appId);
+                this._appAddress = getApplicationAddress(this._appId).toString();
             }
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1147,7 +1254,7 @@ class ApplicationClient {
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1473,7 +1580,7 @@ class ApplicationClient {
             if (!app) {
                 return {
                     appId: 0,
-                    appAddress: getApplicationAddress(0),
+                    appAddress: getApplicationAddress(0).toString(),
                 };
             }
             return app;
@@ -1500,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)?.getLocationForPc(pc)?.line);
         else
             return e;
     }