@algorandfoundation/algokit-utils 6.3.0-beta.1 → 7.0.0-beta.10

package/types/app-client.mjs

@@ -1,19 +1,22 @@
 import algosdk from 'algosdk';
 import { Buffer } from 'buffer';
-import { compileTeal, createApp, updateApp, getABIMethodSignature, callApp, getAppGlobalState, getAppLocalState, getAppBoxNames, getAppBoxValue, getAppBoxValueFromABIType } from '../app.mjs';
+import { compileTeal, createApp, updateApp, callApp, getAppGlobalState, getAppLocalState, getAppBoxNames, getAppBoxValue, getAppBoxValueFromABIType } from '../app.mjs';
 import { replaceDeployTimeControlParams, performTemplateSubstitution, deployApp, getCreatorAppsByName } from '../app-deploy.mjs';
 import { Config } from '../config.mjs';
-import { persistSourceMaps } from '../debugging/debugging.mjs';
 import { legacySendTransactionBridge } from '../transaction/legacy-bridge.mjs';
 import { getSenderAddress, encodeTransactionNote } from '../transaction/transaction.mjs';
+import { binaryStartsWith } from '../util.mjs';
 import { UPDATABLE_TEMPLATE_NAME, DELETABLE_TEMPLATE_NAME } from './app.mjs';
-import { PersistSourceMapInput } from './debugging.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 { LogicError } from './logic-error.mjs';
 
 var ABIMethod = algosdk.ABIMethod;
 var AtomicTransactionComposer = algosdk.AtomicTransactionComposer;
 var getApplicationAddress = algosdk.getApplicationAddress;
 var Indexer = algosdk.Indexer;
+var OnApplicationComplete = algosdk.OnApplicationComplete;
 var SourceMap = algosdk.SourceMap;
 /**
  * Determines deploy time control (UPDATABLE, DELETABLE) value by inspecting application specification
@@ -37,13 +40,865 @@ function getDeployTimeControl(approval, appSpec, templateVariableName, callConfi
         return !!abiCallConfig && abiCallConfig !== 'NEVER';
     });
 }
-/** Application client - a class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app */
+/** 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 {
+    constructor(params) {
+        this._appId = params.appId;
+        this._appAddress = algosdk.getApplicationAddress(this._appId);
+        this._appSpec = AppClient.normaliseAppSpec(params.appSpec);
+        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);
+        this._globalStateMethods = this.getStateMethods(() => this.getGlobalState(), () => this._appSpec.state.keys.global, () => this._appSpec.state.maps.global);
+        this._boxStateMethods = this.getBoxMethods();
+        this._paramsMethods = {
+            ...this.getMethodCallParamsMethods(),
+            /** Get parameters to define bare (raw) transactions to the current app */
+            bare: this.getBareParamsMethods(),
+        };
+        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() {
+        return this._algorand.newGroup();
+    }
+    /**
+     * 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).
+     * @param params The parameters to create the app client
+     */
+    static async fromCreatorAndName(params) {
+        const appSpec = AppClient.normaliseAppSpec(params.appSpec);
+        const appLookup = params.appLookupCache ?? (await params.algorand.appDeployer.getCreatorAppsByName(params.creatorAddress, params.ignoreCache));
+        const appMetadata = appLookup.apps[params.appName ?? appSpec.name];
+        if (!appMetadata) {
+            throw new Error(`App not found for creator ${params.creatorAddress} and name ${params.appName ?? appSpec.name}`);
+        }
+        return new AppClient({
+            ...params,
+            algorand: params.algorand,
+            appId: appMetadata.appId,
+        });
+    }
+    /**
+     * Returns an `AppClient` instance for the current network based on
+     * pre-determined network-specific app IDs specified in the ARC-56 app spec.
+     *
+     * If no IDs are in the app spec or the network isn't recognised, an error is thrown.
+     * @param params The parameters to create the app client
+     */
+    static async fromNetwork(params) {
+        const network = await params.algorand.client.network();
+        const appSpec = AppClient.normaliseAppSpec(params.appSpec);
+        const networkNames = [network.genesisHash];
+        if (network.isLocalNet)
+            networkNames.push('localnet');
+        if (network.isTestNet)
+            networkNames.push('testnet');
+        if (network.isMainNet)
+            networkNames.push('mainnet');
+        const availableAppSpecNetworks = Object.keys(appSpec.networks ?? {});
+        const networkIndex = availableAppSpecNetworks.findIndex((n) => networkNames.includes(n));
+        if (networkIndex === -1) {
+            throw new Error(`No app ID found for network ${JSON.stringify(networkNames)} in the app spec`);
+        }
+        const appId = BigInt(appSpec.networks[networkIndex].appID);
+        return new AppClient({ ...params, appId, appSpec });
+    }
+    /**
+     * Takes a string or parsed JSON object that could be ARC-32 or ARC-56 format and
+     * normalises it into a parsed ARC-56 contract object.
+     * @param spec The spec to normalise
+     * @returns The normalised ARC-56 contract object
+     */
+    static normaliseAppSpec(spec) {
+        const parsedSpec = typeof spec === 'string' ? JSON.parse(spec) : spec;
+        const appSpec = 'hints' in parsedSpec ? arc32ToArc56(parsedSpec) : parsedSpec;
+        return appSpec;
+    }
+    /** The ID of the app instance this client is linked to. */
+    get appId() {
+        return this._appId;
+    }
+    /** The app address of the app instance this client is linked to. */
+    get appAddress() {
+        return this._appAddress;
+    }
+    /** The name of the app (from the ARC-32 / ARC-56 app spec). */
+    get appName() {
+        return this._appName;
+    }
+    /** The ARC-56 app spec being used */
+    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.
+     * @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;
+    }
+    /** Create transactions for the current app */
+    get createTransaction() {
+        return this._createTransactionsMethods;
+    }
+    /** Send transactions to the current app */
+    get send() {
+        return this._sendMethods;
+    }
+    /** Get state (local, global, box) from the current app */
+    get state() {
+        return {
+            /**
+             * Methods to access local state for the current app
+             * @param address The address of the account to get the local state for
+             */
+            local: this._localStateMethods,
+            /**
+             * Methods to access global state for the current app
+             */
+            global: this._globalStateMethods,
+            /**
+             * Methods to access box storage for the current app
+             */
+            box: this._boxStateMethods,
+        };
+    }
+    /**
+     * 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
+     */
+    async fundAppAccount(params) {
+        return this.send.fundAppAccount(params);
+    }
+    /**
+     * Returns raw global state for the current app.
+     * @returns The global state
+     */
+    async getGlobalState() {
+        return await this._algorand.app.getGlobalState(this.appId);
+    }
+    /**
+     * Returns raw local state for the given account address.
+     * @param address The address of the account to get the local state for
+     * @returns The local state
+     */
+    async getLocalState(address) {
+        return await this._algorand.app.getLocalState(this.appId, address);
+    }
+    /**
+     * Returns the names of all current boxes for the current app.
+     * @returns The names of the boxes
+     */
+    async getBoxNames() {
+        return await this._algorand.app.getBoxNames(this.appId);
+    }
+    /**
+     * Returns the value of the given box for the current app.
+     * @param name The identifier of the box to return
+     * @returns The current box value as a byte array
+     */
+    async getBoxValue(name) {
+        return await this._algorand.app.getBoxValue(this.appId, name);
+    }
+    /**
+     * Returns the value of the given box for the current app.
+     * @param name The identifier of the box to return
+     * @param type
+     * @returns The current box value as a byte array
+     */
+    async getBoxValueFromABIType(name, type) {
+        return await this._algorand.app.getBoxValueFromABIType({
+            appId: this.appId,
+            boxName: name,
+            type,
+        });
+    }
+    /**
+     * Returns the values of all current boxes for the current app.
+     * Note: This will issue multiple HTTP requests (one per box) and it's not an atomic operation so values may be out of sync.
+     * @param filter Optional filter to filter which boxes' values are returned
+     * @returns The (name, value) pair of the boxes with values as raw byte arrays
+     */
+    async getBoxValues(filter) {
+        const names = (await this.getBoxNames()).filter(filter ?? ((_) => true));
+        const values = await this._algorand.app.getBoxValues(this.appId, names.map((name) => name.nameRaw));
+        return names.map((name, i) => ({ name, value: values[i] }));
+    }
+    /**
+     * Returns the values of all current boxes for the current app decoded using an ABI Type.
+     * Note: This will issue multiple HTTP requests (one per box) and it's not an atomic operation so values may be out of sync.
+     * @param type The ABI type to decode the values with
+     * @param filter Optional filter to filter which boxes' values are returned
+     * @returns The (name, value) pair of the boxes with values as the ABI Value
+     */
+    async getBoxValuesFromABIType(type, filter) {
+        const names = (await this.getBoxNames()).filter(filter ?? ((_) => true));
+        const values = await this._algorand.app.getBoxValuesFromABIType({
+            appId: this.appId,
+            boxNames: names.map((name) => name.nameRaw),
+            type,
+        });
+        return names.map((name, i) => ({ name, value: values[i] }));
+    }
+    /**
+     * 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.
+     * @param e The error to parse
+     * @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) {
+        return AppClient.exposeLogicError(e, this._appSpec, {
+            isClearStateProgram,
+            approvalSourceMap: this._approvalSourceMap,
+            clearSourceMap: this._clearSourceMap,
+        });
+    }
+    /**
+     * Export the current source maps for the app.
+     * @returns The source maps
+     */
+    exportSourceMaps() {
+        if (!this._approvalSourceMap || !this._clearSourceMap) {
+            throw new Error("Unable to export source maps; they haven't been loaded into this client - you need to call create, update, or deploy first");
+        }
+        return {
+            approvalSourceMap: this._approvalSourceMap,
+            clearSourceMap: this._clearSourceMap,
+        };
+    }
+    /**
+     * Import source maps for the app.
+     * @param sourceMaps The source maps to import
+     */
+    importSourceMaps(sourceMaps) {
+        this._approvalSourceMap = new SourceMap(sourceMaps.approvalSourceMap);
+        this._clearSourceMap = new SourceMap(sourceMaps.clearSourceMap);
+    }
+    /**
+     * 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`]
+     */
+    getABIMethod(methodNameOrSignature) {
+        return getArc56Method(methodNameOrSignature, this._appSpec);
+    }
+    /**
+     * Checks for decode errors on the SendAppTransactionResult and maps the return value to the specified type
+     * on the ARC-56 method, replacing the `return` property with the decoded type.
+     *
+     * 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 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.compiledApproval) {
+            this._approvalSourceMap = result.compiledApproval.sourceMap;
+        }
+        if (result.compiledClear) {
+            this._clearSourceMap = result.compiledClear.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.
+     * @param e The error to parse
+     * @param appSpec The app spec for the app
+     * @param details Additional information to inform the error
+     * @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 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)
+            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);
+        if (errorMessage) {
+            const appId = JSON.stringify(e).match(/(?<=app=)\d+/)?.[0] || '';
+            const txId = JSON.stringify(e).match(/(?<=transaction )\S+(?=:)/)?.[0];
+            const error = new Error(`Runtime error when executing ${appSpec.name} (appId: ${appId}) in transaction ${txId}: ${errorMessage}`);
+            error.cause = e;
+            return error;
+        }
+        return e;
+    }
+    /**
+     * Compiles the approval and clear state programs (if TEAL templates provided),
+     * performing any provided deploy-time parameter replacement and returns
+     * the compiled code and any compilation results (including 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.
+     * @param appSpec The app spec for the app
+     * @param compilation Any compilation parameters to use
+     */
+    static async compile(appSpec, appManager, compilation) {
+        const { deployTimeParams, updatable, deletable } = compilation ?? {};
+        if (!appSpec.source) {
+            if (!appSpec.byteCode?.approval || !appSpec.byteCode?.clear) {
+                throw new Error(`Attempt to compile app ${appSpec.name} without source or byteCode`);
+            }
+            return {
+                approvalProgram: Buffer.from(appSpec.byteCode.approval, 'base64'),
+                clearStateProgram: Buffer.from(appSpec.byteCode.clear, 'base64'),
+            };
+        }
+        const approvalTemplate = Buffer.from(appSpec.source.approval, 'base64').toString('utf-8');
+        const compiledApproval = 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);
+        if (Config.debug) {
+            await Config.events.emitAsync(EventType.AppCompiled, {
+                sources: [
+                    { compiledTeal: compiledApproval, appName: appSpec.name, fileName: 'approval' },
+                    { compiledTeal: compiledClear, appName: appSpec.name, fileName: 'clear' },
+                ],
+            });
+        }
+        return {
+            approvalProgram: compiledApproval.compiledBase64ToBytes,
+            compiledApproval,
+            clearStateProgram: compiledClear.compiledBase64ToBytes,
+            compiledClear,
+        };
+    }
+    /**
+     * Returns ABI method arguments ready for a method call params object with default values populated
+     * and structs replaced with tuples.
+     *
+     * It does this by replacing any `undefined` values with the equivalent default value from the given ARC-56 app spec.
+     * @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
+     */
+    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, this._appSpec.structs[arg.struct], this._appSpec.structs)
+                    : a;
+            }
+            const defaultValue = arg.defaultValue;
+            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 {
+            /** Return params for an update call, including deploy-time TEAL template replacements and compilation if provided */
+            update: async (params) => {
+                return this.getBareParams({
+                    ...params,
+                    ...(await this.compile(params)),
+                }, OnApplicationComplete.UpdateApplicationOC);
+            },
+            /** Return params for an opt-in call */
+            optIn: (params) => {
+                return this.getBareParams(params, OnApplicationComplete.OptInOC);
+            },
+            /** Return params for a delete call */
+            delete: (params) => {
+                return this.getBareParams(params, OnApplicationComplete.DeleteApplicationOC);
+            },
+            /** Return params for a clear state call */
+            clearState: (params) => {
+                return this.getBareParams(params, OnApplicationComplete.ClearStateOC);
+            },
+            /** Return params for a close out call */
+            closeOut: (params) => {
+                return this.getBareParams(params, OnApplicationComplete.CloseOutOC);
+            },
+            /** Return params for a call (defaults to no-op) */
+            call: (params) => {
+                return this.getBareParams(params, params?.onComplete ?? OnApplicationComplete.NoOpOC);
+            },
+        };
+    }
+    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.createTransaction.appUpdate(await this.params.bare.update(params));
+            },
+            /** Returns a transaction for an opt-in call */
+            optIn: (params) => {
+                return this._algorand.createTransaction.appCall(this.params.bare.optIn(params));
+            },
+            /** Returns a transaction for a delete call */
+            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.createTransaction.appCall(this.params.bare.clearState(params));
+            },
+            /** Returns a transaction for a close out call */
+            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.createTransaction.appCall(this.params.bare.call(params));
+            },
+        };
+    }
+    getBareSendMethods() {
+        return {
+            /** Signs and sends an update call, including deploy-time TEAL template replacements and compilation if provided */
+            update: async (params) => {
+                const compiled = await this.compile(params);
+                return {
+                    ...(await this.handleCallErrors(async () => this._algorand.send.appUpdate(await this.params.bare.update(params)))),
+                    ...compiled,
+                };
+            },
+            /** Signs and sends an opt-in call */
+            optIn: (params) => {
+                return this.handleCallErrors(() => this._algorand.send.appCall(this.params.bare.optIn(params)));
+            },
+            /** Signs and sends a delete call */
+            delete: (params) => {
+                return this.handleCallErrors(() => this._algorand.send.appDelete(this.params.bare.delete(params)));
+            },
+            /** Signs and sends a clear state call */
+            clearState: (params) => {
+                return this.handleCallErrors(() => this._algorand.send.appCall(this.params.bare.clearState(params)));
+            },
+            /** Signs and sends a close out call */
+            closeOut: (params) => {
+                return this.handleCallErrors(() => this._algorand.send.appCall(this.params.bare.closeOut(params)));
+            },
+            /** Signs and sends a call (defaults to no-op) */
+            call: (params) => {
+                return this.handleCallErrors(() => this._algorand.send.appCall(this.params.bare.call(params)));
+            },
+        };
+    }
+    getMethodCallParamsMethods() {
+        return {
+            /** Return params for a payment transaction to fund the app account */
+            fundAppAccount: (params) => {
+                return {
+                    ...params,
+                    sender: this.getSender(params.sender),
+                    signer: this.getSigner(params.sender, params.signer),
+                    receiver: this.appAddress,
+                };
+            },
+            /** Return params for an update ABI call, including deploy-time TEAL template replacements and compilation if provided */
+            update: async (params) => {
+                return (await this.getABIParams({
+                    ...params,
+                    ...(await this.compile(params)),
+                }, OnApplicationComplete.UpdateApplicationOC));
+            },
+            /** Return params for an opt-in ABI call */
+            optIn: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.OptInOC));
+            },
+            /** Return params for an delete ABI call */
+            delete: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.DeleteApplicationOC));
+            },
+            /** Return params for an close out ABI call */
+            closeOut: async (params) => {
+                return (await this.getABIParams(params, OnApplicationComplete.CloseOutOC));
+            },
+            /** Return params for an ABI call */
+            call: async (params) => {
+                return (await this.getABIParams(params, params.onComplete ?? OnApplicationComplete.NoOpOC));
+            },
+        };
+    }
+    getMethodCallSendMethods() {
+        return {
+            /** Sign and send transactions for a payment transaction to fund the app account */
+            fundAppAccount: (params) => {
+                return this._algorand.send.payment(this.params.fundAppAccount(params));
+            },
+            /**
+             * Sign and send transactions for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
+             */
+            update: async (params) => {
+                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)))),
+                    ...compiled,
+                };
+            },
+            /**
+             * Sign and send transactions for an opt-in ABI call
+             */
+            optIn: (params) => {
+                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(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(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)
+             */
+            call: async (params) => {
+                // 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(await this.params.call(params))
+                        .simulate({
+                        allowUnnamedResources: params.populateAppCallResources ?? true,
+                        // Simulate calls for a readonly method shouldn't invoke signing
+                        skipSignatures: true,
+                    });
+                    return this.processMethodCallReturn({
+                        ...result,
+                        transaction: result.transactions.at(-1),
+                        confirmation: result.confirmations.at(-1),
+                        // eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
+                        return: (result.returns?.length ?? 0 > 0) ? result.returns?.at(-1) : undefined,
+                    }, 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)));
+            },
+        };
+    }
+    getMethodCallCreateTransactionMethods() {
+        return {
+            /** Return transaction for a payment transaction to fund the app account */
+            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.createTransaction.appUpdateMethodCall(await this.params.update(params));
+            },
+            /**
+             * Return transactions for an opt-in ABI call
+             */
+            optIn: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.optIn(params));
+            },
+            /**
+             * Return transactions for a delete ABI call
+             */
+            delete: async (params) => {
+                return this._algorand.createTransaction.appDeleteMethodCall(await this.params.delete(params));
+            },
+            /**
+             * Return transactions for a close out ABI call
+             */
+            closeOut: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.closeOut(params));
+            },
+            /**
+             * Return transactions for an ABI call (defaults to no-op)
+             */
+            call: async (params) => {
+                return this._algorand.createTransaction.appCallMethodCall(await this.params.call(params));
+            },
+        };
+    }
+    /** 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) {
+            throw new Error(`No sender provided and no default sender present in app client 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
+     * 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,
+        };
+    }
+    async getABIParams(params, onComplete) {
+        const sender = this.getSender(params.sender);
+        const method = getArc56Method(params.method, this._appSpec);
+        const args = await this.getABIArgsWithDefaultValues(params.method, params.args, sender);
+        return {
+            ...params,
+            appId: this._appId,
+            sender: sender,
+            signer: this.getSigner(params.sender, params.signer),
+            method,
+            onComplete,
+            args,
+        };
+    }
+    /** Make the given call and catch any errors, augmenting with debugging information before re-throwing. */
+    async handleCallErrors(call) {
+        try {
+            return await call();
+        }
+        catch (e) {
+            throw this.exposeLogicError(e);
+        }
+    }
+    getBoxMethods() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const that = this;
+        const stateMethods = {
+            /**
+             * Returns all single-key state values in a record keyed by the key name and the value a decoded ABI value.
+             */
+            getAll: async () => {
+                return Object.fromEntries(await Promise.all(Object.keys(that._appSpec.state.keys.box).map(async (key) => [key, await stateMethods.getValue(key)])));
+            },
+            /**
+             * Returns a single state value for the current app with the value a decoded ABI value.
+             * @param name The name of the state value to retrieve the value for
+             * @returns
+             */
+            getValue: async (name) => {
+                const metadata = that._appSpec.state.keys.box[name];
+                const value = await that.getBoxValue(Buffer.from(metadata.key, 'base64'));
+                return getABIDecodedValue(value, metadata.valueType, that._appSpec.structs);
+            },
+            /**
+             *
+             * @param mapName The name of the map to read from
+             * @param key The key within the map (without any map prefix) as either a Buffer with the bytes or a value
+             *  that will be converted to bytes by encoding it using the specified ABI key type
+             *  in the ARC-56 spec
+             */
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            getMapValue: async (mapName, key) => {
+                const metadata = that._appSpec.state.maps.box[mapName];
+                const prefix = Buffer.from(metadata.prefix ?? '', 'base64');
+                const encodedKey = Buffer.concat([prefix, getABIEncodedValue(key, metadata.keyType, that._appSpec.structs)]);
+                const base64Key = Buffer.from(encodedKey).toString('base64');
+                const value = await that.getBoxValue(Buffer.from(base64Key, 'base64'));
+                return getABIDecodedValue(value, metadata.valueType, that._appSpec.structs);
+            },
+            /**
+             *
+             * @param mapName The name of the map to read from
+             * @param key The key within the map as either a Buffer with the bytes or a value
+             *  that will be converted to bytes by encoding it using the specified ABI key type
+             *  in the ARC-56 spec
+             * @param appState
+             */
+            getMap: async (mapName) => {
+                const metadata = that._appSpec.state.maps.box[mapName];
+                const prefix = Buffer.from(metadata.prefix ?? '', 'base64');
+                const boxNames = await that.getBoxNames();
+                return new Map(await Promise.all(boxNames
+                    .filter((b) => binaryStartsWith(b.nameRaw, prefix))
+                    .map(async (b) => {
+                    const encodedKey = Buffer.concat([prefix, b.nameRaw]);
+                    const base64Key = Buffer.from(encodedKey).toString('base64');
+                    return [
+                        getABIDecodedValue(b.nameRaw.slice(prefix.length), metadata.keyType, that._appSpec.structs),
+                        getABIDecodedValue(await that.getBoxValue(Buffer.from(base64Key, 'base64')), metadata.valueType, that._appSpec.structs),
+                    ];
+                })));
+            },
+        };
+        return stateMethods;
+    }
+    getStateMethods(stateGetter, keyGetter, mapGetter) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const that = this;
+        const stateMethods = {
+            /**
+             * Returns all single-key state values in a record keyed by the key name and the value a decoded ABI value.
+             */
+            getAll: async () => {
+                const appState = await stateGetter();
+                return Object.fromEntries(await Promise.all(Object.keys(keyGetter()).map(async (key) => [key, await stateMethods.getValue(key, appState)])));
+            },
+            /**
+             * Returns a single state value for the current app with the value a decoded ABI value.
+             * @param name The name of the state value to retrieve the value for
+             * @param appState Optional cached value of the current state
+             * @returns
+             */
+            getValue: async (name, appState) => {
+                const state = Object.values(appState ?? (await stateGetter()));
+                const metadata = keyGetter()[name];
+                const value = state.find((s) => s.keyBase64 === metadata.key);
+                if (value && 'valueRaw' in value) {
+                    return getABIDecodedValue(value.valueRaw, metadata.valueType, that._appSpec.structs);
+                }
+                return value?.value;
+            },
+            /**
+             * Returns a single value from the given map for the current app with the value a decoded ABI value.
+             * @param mapName The name of the map to read from
+             * @param key The key within the map (without any map prefix) as either a Buffer with the bytes or a value
+             *  that will be converted to bytes by encoding it using the specified ABI key type
+             *  in the ARC-56 spec
+             * @param appState Optional cached value of the current state
+             */
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            getMapValue: async (mapName, key, appState) => {
+                const state = Object.values(appState ?? (await stateGetter()));
+                const metadata = mapGetter()[mapName];
+                const prefix = Buffer.from(metadata.prefix ?? '', 'base64');
+                const encodedKey = Buffer.concat([prefix, getABIEncodedValue(key, metadata.keyType, that._appSpec.structs)]);
+                const base64Key = Buffer.from(encodedKey).toString('base64');
+                const value = state.find((s) => s.keyBase64 === base64Key);
+                if (value && 'valueRaw' in value) {
+                    return getABIDecodedValue(value.valueRaw, metadata.valueType, that._appSpec.structs);
+                }
+                return value?.value;
+            },
+            /**
+             * Returns all map values for the given map.
+             * @param mapName The name of the map to read from
+             * @param appState Optional cached value of the current state
+             * @returns A map of all key-value pairs in the map as a `Record<string, ABIValue>`
+             */
+            getMap: async (mapName) => {
+                const state = Object.values(await stateGetter());
+                const metadata = mapGetter()[mapName];
+                const prefix = Buffer.from(metadata.prefix ?? '', 'base64');
+                return new Map(state
+                    .filter((s) => binaryStartsWith(s.keyRaw, prefix))
+                    .map((s) => {
+                    const key = s.keyRaw.slice(prefix.length);
+                    return [
+                        getABIDecodedValue(key, metadata.keyType, this._appSpec.structs),
+                        getABIDecodedValue('valueRaw' in s ? s.valueRaw : s.value, metadata.valueType, this._appSpec.structs),
+                    ];
+                }));
+            },
+        };
+        return stateMethods;
+    }
+}
+/**
+ * @deprecated Use `AppClient` instead e.g. via `algorand.client.getAppClientById` or
+ * `algorand.client.getAppClientByCreatorAndName`.
+ * If you want to `create` or `deploy` then use `AppFactory` e.g. via `algorand.client.getAppFactory`,
+ * which will in turn give you an `AppClient` instance against the created/deployed app to make other calls.
+ *
+ * Application client - a class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app */
 class ApplicationClient {
-    // todo: process ABI args as needed to make them nicer to deal with like beaker-ts
-    // todo: support readonly, noop method calls
-    // todo: find create, update, delete, etc. methods from app spec and call them by default
-    // todo: intelligent version management when deploying
     /**
+     * @deprecated Use `AppClient` instead e.g. via `algorand.client.getAppClientById` or
+     * `algorand.client.getAppClientByCreatorAndName`.
+     * If you want to `create` or `deploy` then use `AppFactory` e.g. via `algorand.client.getAppFactory`,
+     * which will in turn give you an `AppClient` instance against the created/deployed app to make other calls.
+     *
      * Create a new ApplicationClient instance
      * @param appDetails The details of the app
      * @param algod An algod instance
@@ -78,9 +933,11 @@ class ApplicationClient {
         this.params = params;
     }
     /**
-     * Compiles the approval and clear programs and sets up the source map.
+     * @deprecated Use `AppClient.compile()` instead.
+     *
+     * Compiles the approval and clear state programs and sets up the source map.
      * @param compilation The deploy-time parameters for the compilation
-     * @returns The compiled approval and clear programs
+     * @returns The compiled approval and clear state programs
      */
     async compile(compilation) {
         const { deployTimeParams, updatable, deletable } = compilation ?? {};
@@ -95,15 +952,12 @@ class ApplicationClient {
         const clear = performTemplateSubstitution(clearTemplate, deployTimeParams ?? this.deployTimeParams);
         const clearCompiled = await compileTeal(clear, this.algod);
         this._clearSourceMap = clearCompiled?.sourceMap;
-        if (Config.debug && Config.projectRoot) {
-            persistSourceMaps({
+        if (Config.debug) {
+            await Config.events.emitAsync(EventType.AppCompiled, {
                 sources: [
-                    PersistSourceMapInput.fromCompiledTeal(approvalCompiled, this._appName, 'approval.teal'),
-                    PersistSourceMapInput.fromCompiledTeal(clearCompiled, this._appName, 'clear.teal'),
+                    { compiledTeal: approvalCompiled, appName: this._appName, fileName: 'approval' },
+                    { compiledTeal: clearCompiled, appName: this._appName, fileName: 'clear' },
                 ],
-                projectRoot: Config.projectRoot,
-                client: this.algod,
-                withSources: true,
             });
         }
         return { approvalCompiled, clearCompiled };
@@ -130,6 +984,8 @@ class ApplicationClient {
         this._clearSourceMap = new SourceMap(sourceMaps.clearSourceMap);
     }
     /**
+     * @deprecated Use `deploy` from an `AppFactory` instance instead.
+     *
      * Idempotently deploy (create, update/delete if changed) an app against the given name via the given creator account, including deploy-time template placeholder substitutions.
      *
      * To understand the architecture decisions behind this functionality please see https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md
@@ -215,6 +1071,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @deprecated Use `create` from an `AppFactory` instance instead.
+     *
      * Creates a smart contract app, returns the details of the created app.
      * @param create The parameters to create the app with
      * @returns The details of the created app, or the transaction to create it if `skipSending` and the compilation result
@@ -259,6 +1117,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @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
      * @returns The transaction send result and the compilation result
@@ -291,6 +1151,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @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.
      * @returns The result of the call
@@ -305,7 +1167,7 @@ class ApplicationClient {
             !call.sendParams?.atc &&
             // The method is readonly
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this.appSpec.hints[getABIMethodSignature(this.getABIMethod(call.method))].read_only) {
+            this.appSpec.hints[this.getABIMethodSignature(this.getABIMethod(call.method))].read_only) {
             const atc = new AtomicTransactionComposer();
             await this.callOfType({ ...call, sendParams: { ...call.sendParams, atc } }, 'no_op');
             const result = await atc.simulate(this.algod);
@@ -324,6 +1186,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'no_op');
     }
     /**
+     * @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.
      * @returns The result of the call
@@ -332,6 +1196,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'opt_in');
     }
     /**
+     * @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.
      * @returns The result of the call
@@ -340,6 +1206,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'close_out');
     }
     /**
+     * @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.
      * @returns The result of the call
@@ -348,6 +1216,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'clear_state');
     }
     /**
+     * @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.
      * @returns The result of the call
@@ -356,6 +1226,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'delete_application');
     }
     /**
+     * @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.
      * @param callType The call type
@@ -498,6 +1370,8 @@ class ApplicationClient {
         })));
     }
     /**
+     * @deprecated Use `appClient.params.*` from an `AppClient` instance instead.
+     *
      * Returns the arguments for an app call for the given ABI method or raw method specification.
      * @param args The call args specific to this application client
      * @param sender The sender of this call. Will be used to fetch any default argument values if applicable
@@ -512,7 +1386,7 @@ class ApplicationClient {
             if (!abiMethod) {
                 throw new Error(`Attempt to call ABI method ${args.method}, but it wasn't found`);
             }
-            const methodSignature = getABIMethodSignature(abiMethod);
+            const methodSignature = this.getABIMethodSignature(abiMethod);
             return {
                 ...args,
                 method: abiMethod,
@@ -529,7 +1403,7 @@ class ApplicationClient {
                         case 'abi-method': {
                             const method = defaultValueStrategy.data;
                             const result = await this.callOfType({
-                                method: getABIMethodSignature(method),
+                                method: this.getABIMethodSignature(method),
                                 methodArgs: method.args.map(() => undefined),
                                 sender,
                             }, 'no_op');
@@ -555,6 +1429,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @deprecated Use `appClient.getABIMethod` instead.
+     *
      * Returns the ABI Method parameters for the given method name string for the app represented by this application client instance
      * @param method Either the name of the method or the ABI method spec definition string
      * @returns The ABI method params for the given method
@@ -564,12 +1440,12 @@ class ApplicationClient {
             const methods = this.appSpec.contract.methods.filter((m) => m.name === method);
             if (methods.length > 1) {
                 throw new Error(`Received a call to method ${method} in contract ${this._appName}, but this resolved to multiple methods; please pass in an ABI signature instead: ${methods
-                    .map(getABIMethodSignature)
+                    .map(this.getABIMethodSignature)
                     .join(', ')}`);
             }
             return methods[0];
         }
-        return this.appSpec.contract.methods.find((m) => getABIMethodSignature(m) === method);
+        return this.appSpec.contract.methods.find((m) => this.getABIMethodSignature(m) === method);
     }
     /**
      * Returns the ABI Method for the given method name string for the app represented by this application client instance
@@ -581,6 +1457,8 @@ class ApplicationClient {
         return methodParams ? new ABIMethod(methodParams) : undefined;
     }
     /**
+     * @deprecated Use `appClient.appId` and `appClient.appAddress` from an `AppClient` instance instead.
+     *
      * Gets the reference information for the current application instance.
      * `appId` will be 0 if it can't find an app.
      * @returns The app reference, or if deployed using the `deploy` method, the app metadata too
@@ -626,7 +1504,10 @@ class ApplicationClient {
         else
             return e;
     }
+    getABIMethodSignature(method) {
+        return 'getSignature' in method ? method.getSignature() : new ABIMethod(method).getSignature();
+    }
 }
 
-export { ApplicationClient };
+export { AppClient, ApplicationClient };
 //# sourceMappingURL=app-client.mjs.map