@algorandfoundation/algokit-utils 7.0.0-beta.3 → 7.0.0-beta.5

package/types/app-client.mjs

@@ -6,7 +6,11 @@ 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 { getArc56Method, getArc56ReturnValue, getABITupleFromABIStruct, getABIDecodedValue, getABIEncodedValue } from './app-arc56.mjs';
+import { AppManager } from './app-manager.mjs';
+import { arc32ToArc56 } from './app-spec.mjs';
 import { PersistSourceMapInput } from './debugging.mjs';
 import { LogicError } from './logic-error.mjs';
 
@@ -14,6 +18,7 @@ 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 +42,787 @@ 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._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(),
+            bare: this.getBareParamsMethods(),
+        };
+        this._transactionsMethods = { ...this.getMethodCallTransactionsMethods(), bare: this.getBareTransactionsMethods() };
+        this._sendMethods = { ...this.getMethodCallSendMethods(), 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;
+    }
+    /** Get parameters to define transactions to the current app */
+    get params() {
+        return this._paramsMethods;
+    }
+    /** Get transactions for the current app */
+    get transactions() {
+        return this._transactionsMethods;
+    }
+    /** Send calls to the current app */
+    get send() {
+        return this._sendMethods;
+    }
+    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.
+     * @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 for the given method name 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.
+     *
+     * If the return type is a struct then the struct will be returned.
+     *
+     * @param result The SendAppTransactionResult to be mapped
+     * @param method The method that was called
+     * @returns The smart contract response with an updated return value
+     */
+    async parseMethodCallReturn(result, method) {
+        const resultValue = await result;
+        return { ...resultValue, return: getArc56ReturnValue(resultValue.return, method, this._appSpec.structs) };
+    }
+    /**
+     * 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 && Config.projectRoot) {
+            persistSourceMaps({
+                sources: [
+                    PersistSourceMapInput.fromCompiledTeal(compiledApproval, appSpec.name, 'approval.teal'),
+                    PersistSourceMapInput.fromCompiledTeal(compiledClear, appSpec.name, 'clear.teal'),
+                ],
+                projectRoot: Config.projectRoot,
+                appManager,
+                withSources: true,
+            });
+        }
+        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
+     * @param appSpec The app spec for the app
+     */
+    static getABIArgsWithDefaultValues(methodNameOrSignature, args, appSpec) {
+        const m = getArc56Method(methodNameOrSignature, appSpec);
+        return args?.map((a, i) => {
+            const arg = m.args[i];
+            if (a !== undefined) {
+                // If a struct then convert to tuple for the underlying call
+                return arg.struct && typeof a === 'object' && !Array.isArray(a)
+                    ? getABITupleFromABIStruct(a, appSpec.structs[arg.struct])
+                    : a;
+            }
+            // todo: expand this to match previous ApplicationClient implementation when ARC-56 spec is updated to support other default value options
+            const defaultValue = arg.defaultValue;
+            if (defaultValue)
+                return getABIDecodedValue(Buffer.from(defaultValue, 'base64'), m.method.args[i].type, {});
+            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);
+            },
+        };
+    }
+    getBareTransactionsMethods() {
+        return {
+            /** Returns a transaction for an update call, including deploy-time TEAL template replacements and compilation if provided */
+            update: async (params) => {
+                return this._algorand.transactions.appUpdate(await this.params.bare.update(params));
+            },
+            /** Returns a transaction for an opt-in call */
+            optIn: (params) => {
+                return this._algorand.transactions.appCall(this.params.bare.optIn(params));
+            },
+            /** Returns a transaction for a delete call */
+            delete: (params) => {
+                return this._algorand.transactions.appDelete(this.params.bare.delete(params));
+            },
+            /** Returns a transaction for a clear state call */
+            clearState: (params) => {
+                return this._algorand.transactions.appCall(this.params.bare.clearState(params));
+            },
+            /** Returns a transaction for a close out call */
+            closeOut: (params) => {
+                return this._algorand.transactions.appCall(this.params.bare.closeOut(params));
+            },
+            /** Returns a transaction for a call (defaults to no-op) */
+            call: (params) => {
+                return this._algorand.transactions.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) => {
+                return await this.handleCallErrors(async () => this._algorand.send.appUpdate(await this.params.bare.update(params)));
+            },
+            /** 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),
+                    receiver: this.appAddress,
+                };
+            },
+            /** Return params for an update ABI call, including deploy-time TEAL template replacements and compilation if provided */
+            update: async (params) => {
+                return this.getABIParams({
+                    ...params,
+                    ...(await this.compile(params)),
+                }, OnApplicationComplete.UpdateApplicationOC);
+            },
+            /** Return params for an opt-in ABI call */
+            optIn: (params) => {
+                return this.getABIParams(params, OnApplicationComplete.OptInOC);
+            },
+            /** Return params for an delete ABI call */
+            delete: (params) => {
+                return this.getABIParams(params, OnApplicationComplete.DeleteApplicationOC);
+            },
+            /** Return params for an close out ABI call */
+            closeOut: (params) => {
+                return this.getABIParams(params, OnApplicationComplete.CloseOutOC);
+            },
+            /** Return params for an ABI call */
+            call: (params) => {
+                return 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.parseMethodCallReturn(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(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.optIn(params)), getArc56Method(params.method, this._appSpec)));
+            },
+            /**
+             * Sign and send transactions for a delete ABI call
+             */
+            delete: (params) => {
+                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appDeleteMethodCall(this.params.delete(params)), getArc56Method(params.method, this._appSpec)));
+            },
+            /**
+             * Sign and send transactions for a close out ABI call
+             */
+            closeOut: (params) => {
+                return this.handleCallErrors(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.closeOut(params)), getArc56Method(params.method, this._appSpec)));
+            },
+            /**
+             * 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(this.params.call(params)).simulate();
+                    return this.parseMethodCallReturn({
+                        ...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(() => this.parseMethodCallReturn(this._algorand.send.appCallMethodCall(this.params.call(params)), getArc56Method(params.method, this._appSpec)));
+            },
+        };
+    }
+    getMethodCallTransactionsMethods() {
+        return {
+            /** Return transaction for a payment transaction to fund the app account */
+            fundAppAccount: (params) => {
+                return this._algorand.transactions.payment(this.params.fundAppAccount(params));
+            },
+            /**
+             * Return transactions for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
+             */
+            update: async (params) => {
+                return this._algorand.transactions.appUpdateMethodCall(await this.params.update(params));
+            },
+            /**
+             * Return transactions for an opt-in ABI call
+             */
+            optIn: (params) => {
+                return this._algorand.transactions.appCallMethodCall(this.params.optIn(params));
+            },
+            /**
+             * Return transactions for a delete ABI call
+             */
+            delete: (params) => {
+                return this._algorand.transactions.appDeleteMethodCall(this.params.delete(params));
+            },
+            /**
+             * Return transactions for a close out ABI call
+             */
+            closeOut: (params) => {
+                return this._algorand.transactions.appCallMethodCall(this.params.closeOut(params));
+            },
+            /**
+             * Return transactions for an ABI call (defaults to no-op)
+             */
+            call: (params) => {
+                return this._algorand.transactions.appCallMethodCall(this.params.call(params));
+            },
+        };
+    }
+    /**
+     * Compiles the approval and clear state programs (if TEAL templates provided),
+     * performing any provided deploy-time parameter replacement and stores
+     * the source maps.
+     *
+     * If no TEAL templates provided it will use any byte code provided in the app spec.
+     *
+     * Will store any generated source maps for later use in debugging.
+     */
+    async compile(compilation) {
+        const result = await AppClient.compile(this._appSpec, this._algorand.app, compilation);
+        if (result.compiledApproval) {
+            this._approvalSourceMap = result.compiledApproval.sourceMap;
+        }
+        if (result.compiledClear) {
+            this._clearSourceMap = result.compiledClear.sourceMap;
+        }
+        return result;
+    }
+    /** Returns the sender for a call, using the `defaultSender`
+     * if none provided and throws an error if neither provided */
+    getSender(sender) {
+        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;
+    }
+    getBareParams(params, onComplete) {
+        return {
+            ...params,
+            appId: this._appId,
+            sender: this.getSender(params?.sender),
+            onComplete,
+        };
+    }
+    getABIParams(params, onComplete) {
+        const method = getArc56Method(params.method, this._appSpec);
+        const args = AppClient.getABIArgsWithDefaultValues(params.method, params.args, this._appSpec);
+        return {
+            ...params,
+            appId: this._appId,
+            sender: this.getSender(params.sender),
+            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 +857,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 ?? {};
@@ -102,7 +883,7 @@ class ApplicationClient {
                     PersistSourceMapInput.fromCompiledTeal(clearCompiled, this._appName, 'clear.teal'),
                 ],
                 projectRoot: Config.projectRoot,
-                client: this.algod,
+                appManager: new AppManager(this.algod),
                 withSources: true,
             });
         }
@@ -130,6 +911,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 +998,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 +1044,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @deprecated Use `appClient.send.update` or `appClient.transactions.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 +1078,8 @@ class ApplicationClient {
         }
     }
     /**
+     * @deprecated Use `appClient.send.call` or `appClient.transactions.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
@@ -324,6 +1113,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'no_op');
     }
     /**
+     * @deprecated Use `appClient.send.optIn` or `appClient.transactions.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 +1123,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'opt_in');
     }
     /**
+     * @deprecated Use `appClient.send.closeOut` or `appClient.transactions.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 +1133,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'close_out');
     }
     /**
+     * @deprecated Use `appClient.send.clearState` or `appClient.transactions.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 +1143,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'clear_state');
     }
     /**
+     * @deprecated Use `appClient.send.delete` or `appClient.transactions.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 +1153,8 @@ class ApplicationClient {
         return await this.callOfType(call, 'delete_application');
     }
     /**
+     * @deprecated Use `appClient.send.call` or `appClient.transactions.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 +1297,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
@@ -555,6 +1356,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
@@ -581,6 +1384,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
@@ -631,5 +1436,5 @@ class ApplicationClient {
     }
 }
 
-export { ApplicationClient };
+export { AppClient, ApplicationClient };
 //# sourceMappingURL=app-client.mjs.map