@algorandfoundation/algokit-utils 7.0.0-beta.9 → 7.0.1

package/types/app-client.d.ts

@@ -3,11 +3,11 @@ import { TransactionSignerAccount } from './account';
 import { AlgorandClientInterface } from './algorand-client-interface';
 import { AlgoAmount } from './amount';
 import { ABIAppCallArgs, ABIReturn, AppCallArgs, AppCallTransactionResult, AppCallType, AppCompilationResult, AppMetadata, AppReference, AppReturn, AppState, AppStorageSchema, BoxName, AppLookup as LegacyAppLookup, OnSchemaBreak, OnUpdate, RawAppCallArgs, SendAppTransactionResult, TealTemplateParams } from './app';
-import { ABIStruct, Arc56Contract, Arc56Method } from './app-arc56';
+import { ABIStruct, Arc56Contract, Arc56Method, ProgramSourceInfo } from './app-arc56';
 import { AppLookup } from './app-deployer';
 import { AppManager, BoxIdentifier } from './app-manager';
 import { AppSpec } from './app-spec';
-import AlgoKitComposer, { AppCallMethodCall, AppCallParams, AppDeleteMethodCall, AppDeleteParams, AppMethodCall, AppMethodCallTransactionArgument, CommonAppCallParams, PaymentParams } from './composer';
+import { AppCallMethodCall, AppCallParams, AppDeleteMethodCall, AppDeleteParams, AppMethodCall, AppMethodCallTransactionArgument, CommonAppCallParams, PaymentParams } from './composer';
 import { Expand } from './expand';
 import { SendParams, SendTransactionFrom, SendTransactionParams, TransactionNote } from './transaction';
 import ABIMethod = algosdk.ABIMethod;
@@ -114,8 +114,7 @@ export interface AppClientDeployParams extends AppClientDeployCoreParams, AppCli
     /** Any overrides for the storage schema to request for the created app; by default the schema indicated by the app spec is used. */
     schema?: Partial<AppStorageSchema>;
 }
-export interface AppClientCallRawArgs extends RawAppCallArgs {
-}
+export type AppClientCallRawArgs = RawAppCallArgs;
 export interface AppClientCallABIArgs extends Omit<ABIAppCallArgs, 'method'> {
     /** If calling an ABI method then either the name of the method, or the ABI signature */
     method: string;
@@ -215,6 +214,8 @@ export interface AppClientParams {
     /** Optional source map for the clear state program */
     clearSourceMap?: SourceMap;
 }
+/** Parameters to clone an app client */
+export type CloneAppClientParams = Expand<Partial<Omit<AppClientParams, 'algorand' | 'appSpec'>>>;
 /** onComplete parameter for a non-update app call */
 export type CallOnComplete = {
     /** On-complete of the call; defaults to no-op */
@@ -243,6 +244,7 @@ export type AppClientMethodCallParams = Expand<Omit<CommonAppCallParams, 'appId'
      * * A transaction (where the signer will be automatically assigned)
      * * An unawaited transaction (e.g. from algorand.createTransaction.transactionType())
      * * Another method call (via method call params object)
+     * * undefined (this represents a placeholder for either a default argument or a transaction argument that is fulfilled by another method call argument)
      */
     args?: (ABIValue | ABIStruct | AppMethodCallTransactionArgument | undefined)[];
 }>;
@@ -283,8 +285,13 @@ export declare class AppClient {
     private _createTransactionsMethods;
     private _sendMethods;
     constructor(params: AppClientParams);
-    /** Start a new `AlgoKitComposer` transaction group */
-    newGroup(): AlgoKitComposer;
+    /**
+     * 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: CloneAppClientParams): AppClient;
     /**
      * Returns a new `AppClient` client, resolving the app by creator address and name
      * using AlgoKit app deployment semantics (i.e. looking for the app creation transaction note).
@@ -474,7 +481,7 @@ export declare class AppClient {
                 boxReferences?: (BoxIdentifier | import("./app-manager").BoxReference)[] | undefined;
                 approvalProgram: string | Uint8Array;
                 clearStateProgram: string | Uint8Array;
-            }> | AppMethodCall<import("./composer").AppMethodCallParams>)[] | undefined;
+            }> | AppMethodCall<import("./composer").AppMethodCallParams> | undefined)[] | undefined;
         }>;
         /** Return params for an opt-in ABI call */
         optIn: (params: {
@@ -1511,7 +1518,7 @@ export declare 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: Error, isClearStateProgram?: boolean): Error;
+    exposeLogicError(e: Error, isClearStateProgram?: boolean): Promise<Error>;
     /**
      * Export the current source maps for the app.
      * @returns The source maps
@@ -1562,6 +1569,9 @@ export declare class AppClient {
         /** Whether or not the code was running the clear state program (defaults to approval program) */ isClearStateProgram?: boolean;
         /** Approval program source map */ approvalSourceMap?: SourceMap;
         /** Clear state program source map */ clearSourceMap?: SourceMap;
+        /** program bytes */ program?: Uint8Array;
+        /** ARC56 approval source info */ approvalSourceInfo?: ProgramSourceInfo;
+        /** ARC56 clear source info */ clearSourceInfo?: ProgramSourceInfo;
     }): Error;
     /**
      * Compiles the approval and clear state programs (if TEAL templates provided),
@@ -1595,7 +1605,7 @@ export declare class AppClient {
      * if none provided and throws an error if neither provided */
     private getSender;
     /** 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
+     * if no signer was provided and the sender resolves to the default sender, the call will use default signer
      * or `undefined` otherwise (so the signer is resolved from `AlgorandClient`) */
     private getSigner;
     private getBareParams;
@@ -1691,6 +1701,7 @@ export declare class ApplicationClient {
         deletable?: boolean | undefined;
         updatable?: boolean | undefined;
         return?: ABIReturn | undefined;
+        /** Configuration to resolve app by creator and name `getCreatorAppsByName` */
         operationPerformed: "update" | "create";
     } | {
         compiledApproval: import("./app").CompiledTeal;
@@ -1711,7 +1722,7 @@ export declare class ApplicationClient {
         updatable?: boolean | undefined;
         return?: ABIReturn | undefined;
         deleteReturn?: ABIReturn | undefined;
-        deleteResult: import("./transaction").ConfirmedTransactionResult; /** The optional name override to resolve the app by within the creator account (default: uses the name in the ABI contract) */
+        deleteResult: import("./transaction").ConfirmedTransactionResult;
         operationPerformed: "replace";
     }>;
     /**

package/types/app-client.js

@@ -11,7 +11,7 @@ var util = require('../util.js');
 var types_app = require('./app.js');
 var types_appArc56 = require('./app-arc56.js');
 var types_appSpec = require('./app-spec.js');
-var types_asyncEventEmitter = require('./async-event-emitter.js');
+var types_lifecycleEvents = require('./lifecycle-events.js');
 var types_logicError = require('./logic-error.js');
 
 var ABIMethod = algosdk.ABIMethod;
@@ -42,6 +42,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 {
@@ -74,9 +125,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
@@ -283,11 +349,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,
         });
     }
     /**
@@ -362,17 +436,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 = types_logicError.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 types_logicError.LogicError(errorDetails, buffer.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];
@@ -412,7 +514,7 @@ class AppClient {
         const clearTemplate = buffer.Buffer.from(appSpec.source.clear, 'base64').toString('utf-8');
         const compiledClear = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
         if (config.Config.debug) {
-            await config.Config.events.emitAsync(types_asyncEventEmitter.EventType.AppCompiled, {
+            await config.Config.events.emitAsync(types_lifecycleEvents.EventType.AppCompiled, {
                 sources: [
                     { compiledTeal: compiledApproval, appName: appSpec.name, fileName: 'approval' },
                     { compiledTeal: compiledClear, appName: appSpec.name, fileName: 'clear' },
@@ -449,19 +551,22 @@ class AppClient {
             if (defaultValue) {
                 switch (defaultValue.source) {
                     case 'literal':
-                        if (typeof defaultValue.data === 'number')
-                            return defaultValue.data;
                         return types_appArc56.getABIDecodedValue(buffer.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 types_appArc56.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);
@@ -479,7 +584,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() {
@@ -648,13 +755,13 @@ class AppClient {
              */
             call: async (params) => {
                 // Read-only call - do it via simulate
-                if (params.onComplete === OnApplicationComplete.NoOpOC ||
-                    (!params.onComplete && types_appArc56.getArc56Method(params.method, this._appSpec).method.readonly)) {
+                if ((params.onComplete === OnApplicationComplete.NoOpOC || !params.onComplete) &&
+                    types_appArc56.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,15 +819,15 @@ class AppClient {
      * if none provided and throws an error if neither provided */
     getSender(sender) {
         if (!sender && !this._defaultSender) {
-            throw new Error(`No sender provided and no default sender present in app client for call to app ${this._appName}`);
+            throw new Error(`No sender provided and no default sender present in app factory for call to app ${this._appName}`);
         }
         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
+     * if no signer was provided and the sender resolves to the default sender, the call will use default signer
      * or `undefined` otherwise (so the signer is resolved from `AlgorandClient`) */
     getSigner(sender, signer) {
-        return signer ?? (!sender ? this._defaultSigner : undefined);
+        return signer ?? (!sender || sender === this._defaultSender ? this._defaultSigner : undefined);
     }
     getBareParams(params, onComplete) {
         return {
@@ -751,7 +858,7 @@ class AppClient {
             return await call();
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     getBoxMethods() {
@@ -955,7 +1062,7 @@ class ApplicationClient {
         const clearCompiled = await app.compileTeal(clear, this.algod);
         this._clearSourceMap = clearCompiled?.sourceMap;
         if (config.Config.debug) {
-            await config.Config.events.emitAsync(types_asyncEventEmitter.EventType.AppCompiled, {
+            await config.Config.events.emitAsync(types_lifecycleEvents.EventType.AppCompiled, {
                 sources: [
                     { compiledTeal: approvalCompiled, appName: this._appName, fileName: 'approval' },
                     { compiledTeal: clearCompiled, appName: this._appName, fileName: 'clear' },
@@ -1115,7 +1222,7 @@ class ApplicationClient {
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1149,7 +1256,7 @@ class ApplicationClient {
             return { ...result, ...{ compiledApproval: approvalCompiled, compiledClear: clearCompiled } };
         }
         catch (e) {
-            throw this.exposeLogicError(e);
+            throw await this.exposeLogicError(e);
         }
     }
     /**
@@ -1502,7 +1609,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;
     }