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

package/types/application-client.d.ts

@@ -0,0 +1,229 @@
+import { ABIMethod, ABIMethodParams, ABIType, ABIValue, Algodv2, Indexer, SuggestedParams } from 'algosdk';
+import { AlgoAmount } from './amount';
+import { ABIAppCallArg, ABIAppCallArgs, AppCallArgs, AppLookup, AppMetadata, AppReference, AppState, BoxName, OnSchemaBreak, OnUpdate, RawAppCallArgs, TealTemplateParams } from './app';
+import { AppSpec } from './appspec';
+import { SendTransactionFrom, SendTransactionParams, TransactionNote } from './transaction';
+/** Configuration to resolve app by creator and name @see getCreatorAppsByName */
+export type ResolveAppByCreatorAndName = {
+    /** The address of the app creator account to resolve the app by */
+    creatorAddress: string;
+    /** The optional name to resolve the app by within the creator account (default: uses the name in the ABI contract) */
+    name?: string;
+} & ({
+    /** indexer An indexer instance to search the creator account apps */
+    indexer: Indexer;
+} | {
+    /** Optional cached value of the existing apps for the given creator, @see getCreatorAppsByName */
+    existingDeployments: AppLookup;
+});
+/** Configuration to resolve app by ID */
+export interface ResolveAppById {
+    /** The id of an existing app to call using this client, or 0 if the app hasn't been created yet */
+    id: number;
+    /** The optional name to use to mark the app when deploying @see ApplicationClient.deploy (default: uses the name in the ABI contract) */
+    name?: string;
+}
+/** The details of an ARC-0032 app spec specified app */
+export type AppSpecAppDetails = {
+    /** The ARC-0032 application spec as either:
+     *  * Parsed JSON @see {AppSpec}
+     *  * Raw JSON string
+     */
+    app: AppSpec | string;
+    /** Default sender to use for transactions issued by this application client */
+    sender?: SendTransactionFrom;
+    /** Default suggested params object to use */
+    params?: SuggestedParams;
+} & (ResolveAppById | ResolveAppByCreatorAndName);
+/** Parameters to pass into ApplicationClient.deploy */
+export interface AppClientDeployParams {
+    /** The version of the contract, uses "1.0" by default */
+    version?: string;
+    /** The optional sender to send the transaction from, will use the application client's default sender by default if specified */
+    sender?: SendTransactionFrom;
+    /** Whether or not to allow updates in the contract using the deploy-time updatability control if present in your contract.
+     * If this is not specified then it will automatically be determined based on the AppSpec definition
+     **/
+    allowUpdate?: boolean;
+    /** Whether or not to allow deletes in the contract using the deploy-time deletability control if present in your contract.
+     * If this is not specified then it will automatically be determined based on the AppSpec definition
+     **/
+    allowDelete?: boolean;
+    /** Parameters to control transaction sending */
+    sendParams?: Omit<SendTransactionParams, 'skipSending' | 'skipWaiting'>;
+    /** Any deploy-time parameters to replace in the TEAL code */
+    deployTimeParams?: TealTemplateParams;
+    /** What action to perform if a schema break is detected */
+    onSchemaBreak?: 'replace' | 'fail' | OnSchemaBreak;
+    /** What action to perform if a TEAL update is detected */
+    onUpdate?: 'update' | 'replace' | 'fail' | OnUpdate;
+    /** Any args to pass to any create transaction that is issued as part of deployment */
+    createArgs?: AppClientCallArgs;
+    /** Any args to pass to any update transaction that is issued as part of deployment */
+    updateArgs?: AppClientCallArgs;
+    /** Any args to pass to any delete transaction that is issued as part of deployment */
+    deleteArgs?: AppClientCallArgs;
+}
+/** The arguments to pass to an Application Client smart contract call */
+export type AppClientCallArgs = {
+    /** Raw argument values to pass to the smart contract call */
+    args?: RawAppCallArgs;
+} | {
+    /** If calling an ABI method then either the name of the method, or the ABI signature */
+    method: string;
+    /** Either the ABI arguments or an object with the ABI arguments and other parameters like boxes */
+    methodArgs: Omit<ABIAppCallArgs, 'method'> | ABIAppCallArg[];
+};
+/** Parameters to construct a ApplicationClient contract call */
+export type AppClientCallParams = AppClientCallArgs & {
+    /** The optional sender to send the transaction from, will use the application client's default sender by default if specified */
+    sender?: SendTransactionFrom;
+    /** The transaction note for the smart contract call */
+    note?: TransactionNote;
+    /** Parameters to control transaction sending */
+    sendParams?: SendTransactionParams;
+};
+/** Parameters for creating a contract using ApplicationClient */
+export type AppClientCreateParams = AppClientCallParams & {
+    /** Any deploy-time parameters to replace in the TEAL code */
+    deployTimeParams?: TealTemplateParams;
+    updatable?: boolean;
+    deletable?: boolean;
+};
+/** Parameters for updating a contract using ApplicationClient */
+export type AppClientUpdateParams = AppClientCreateParams;
+/** Parameters for funding an app account */
+export interface FundAppAccountParams {
+    amount: AlgoAmount;
+    /** The optional sender to send the transaction from, will use the application client's default sender by default if specified */
+    sender?: SendTransactionFrom;
+    /** The transaction note for the smart contract call */
+    note?: TransactionNote;
+    /** Parameters to control transaction sending */
+    sendParams?: SendTransactionParams;
+}
+/** Application client - a class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app */
+export declare class ApplicationClient {
+    private algod;
+    private indexer?;
+    private appSpec;
+    private sender;
+    private params;
+    private existingDeployments;
+    private _appId;
+    private _appAddress;
+    private _creator;
+    private _appName;
+    private _approvalSourceMap;
+    private _clearSourceMap;
+    /**
+     * Create a new ApplicationClient instance
+     * @param appDetails The details of the app
+     * @param algod An algod instance
+     * @param indexer An indexer instance
+     */
+    constructor(appDetails: AppSpecAppDetails, algod: Algodv2);
+    /**
+     * 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
+     *
+     * **Note:** if there is a breaking state schema change to an existing app (and `onSchemaBreak` is set to `'replace'`) the existing app will be deleted and re-created.
+     *
+     * **Note:** if there is an update (different TEAL code) to an existing app (and `onUpdate` is set to `'replace'`) the existing app will be deleted and re-created.
+     * @param deploy Deployment details
+     * @returns The metadata and transaction result(s) of the deployment, or just the metadata if it didn't need to issue transactions
+     */
+    deploy(deploy?: AppClientDeployParams): Promise<(Partial<import("./app").AppCompilationResult> & import("./transaction").ConfirmedTransactionResult & AppMetadata & {
+        operationPerformed: "update" | "create";
+    }) | (Partial<import("./app").AppCompilationResult> & import("./transaction").ConfirmedTransactionResult & AppMetadata & {
+        deleteResult: import("./transaction").ConfirmedTransactionResult;
+        operationPerformed: "replace";
+    }) | (Partial<import("./app").AppCompilationResult> & AppMetadata & {
+        operationPerformed: "nothing";
+    })>;
+    create(create?: AppClientCreateParams): Promise<Partial<import("./app").AppCompilationResult> & import("./app").AppCallTransactionResult & AppReference>;
+    update(update?: AppClientUpdateParams): Promise<Partial<import("./app").AppCompilationResult> & import("./app").AppCallTransactionResult>;
+    call(call: AppClientCallParams): Promise<import("./app").AppCallTransactionResult>;
+    optIn(call: AppClientCallParams): Promise<import("./app").AppCallTransactionResult>;
+    closeOut(call: AppClientCallParams): Promise<import("./app").AppCallTransactionResult>;
+    clearState(call: AppClientCallParams): Promise<import("./app").AppCallTransactionResult>;
+    delete(call: AppClientCallParams): Promise<import("./app").AppCallTransactionResult>;
+    private _call;
+    /**
+     * Funds ALGOs into the app account for this app.
+     * @param fund The parameters for the funding or the funding amount
+     * @returns The result of the funding
+     */
+    fundAppAccount(fund: FundAppAccountParams | AlgoAmount): Promise<import("./transaction").SendTransactionResult>;
+    /**
+     * Returns global state for the current app.
+     * @returns The global state
+     */
+    getGlobalState(): Promise<AppState>;
+    /**
+     * Returns local state for the given account / account address.
+     * @returns The global state
+     */
+    getLocalState(account: string | SendTransactionFrom): Promise<AppState>;
+    /**
+     * Returns the names of all current boxes for the current app.
+     * @returns The names of the boxes
+     */
+    getBoxNames(): Promise<BoxName[]>;
+    /**
+     * 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
+     */
+    getBoxValues(filter?: (name: BoxName) => boolean): Promise<{
+        name: BoxName;
+        value: Uint8Array;
+    }[]>;
+    /**
+     * 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
+     */
+    getBoxValuesAsABIType(type: ABIType, filter?: (name: BoxName) => boolean): Promise<{
+        name: BoxName;
+        value: ABIValue;
+    }[]>;
+    /**
+     * 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
+     * @returns The call args ready to pass into an app call
+     */
+    getCallArgs(args?: AppClientCallArgs): AppCallArgs | undefined;
+    /**
+     * 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
+     */
+    getABIMethodParams(method: string): ABIMethodParams | undefined;
+    /**
+     * Returns the ABI Method 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 for the given method
+     */
+    getABIMethod(method: string): ABIMethod | undefined;
+    /**
+     * 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
+     */
+    getAppReference(): Promise<AppMetadata | AppReference>;
+    /**
+     * Takes an error that may include a logic error from a smart contract call and re-exposes the error to include source code information via the source map.
+     * This is automatically used within @see ApplicationClient but if you pass `skipSending: true` e.g. if doing a group transaction
+     *  then you can use this in a try/catch block to get better debugging information.
+     * @param e The error to parse
+     * @param isClear Whether or not the code was running the clear state program
+     * @returns The new error, or if there was no logic error or source map then the wrapped error with source details
+     */
+    exposeLogicError(e: Error, isClear?: boolean): Error;
+}
+//# sourceMappingURL=application-client.d.ts.map

package/types/application-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-client.d.ts","sourceRoot":"","sources":["../../src/types/application-client.ts"],"names":[],"mappings":"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"}