Skip to content

创建文章

We are looking for publications that demonstrate building dApps or smart contracts!
See the full list of Gitcoin bounties that are eligible for rewards.

types app client.ApplicationClient

@algorandfoundation/algokit-utils / types/app-client / ApplicationClient

Class: ApplicationClient

types/app-client.ApplicationClient

Application client - a class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app

Table of contents

Constructors

Properties

Methods

Constructors

constructor

new ApplicationClient(appDetails, algod): ApplicationClient

Create a new ApplicationClient instance

Parameters
Name Type Description
appDetails AppSpecAppDetails The details of the app
algod default An algod instance
Returns

ApplicationClient

Defined in

src/types/app-client.ts:291

Properties

_appAddress

Private _appAddress: string

Defined in

src/types/app-client.ts:274


_appId

Private _appId: number | bigint

Defined in

src/types/app-client.ts:273


_appName

Private _appName: string

Defined in

src/types/app-client.ts:276


_approvalSourceMap

Private _approvalSourceMap: undefined | SourceMap

Defined in

src/types/app-client.ts:278


_clearSourceMap

Private _clearSourceMap: undefined | SourceMap

Defined in

src/types/app-client.ts:279


_creator

Private _creator: undefined | string

Defined in

src/types/app-client.ts:275


algod

Private algod: default

Defined in

src/types/app-client.ts:265


appSpec

Private appSpec: AppSpec

Defined in

src/types/app-client.ts:267


deployTimeParams

Private Optional deployTimeParams: TealTemplateParams

Defined in

src/types/app-client.ts:271


existingDeployments

Private existingDeployments: undefined | AppLookup

Defined in

src/types/app-client.ts:270


indexer

Private Optional indexer: default

Defined in

src/types/app-client.ts:266


params

Private params: undefined | SuggestedParams

Defined in

src/types/app-client.ts:269


sender

Private sender: undefined | SendTransactionFrom

Defined in

src/types/app-client.ts:268

Methods

call

call(call?): Promise\<AppCallTransactionResult>

Issues a no_op (normal) call to the app.

Parameters
Name Type Description
call? AppClientCallParams The call details.
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:596


callOfType

callOfType(call?, callType): Promise\<AppCallTransactionResult>

Issues a call to the app with the given call type.

Parameters
Name Type Description
call AppClientCallParams The call details.
callType "no_op" | "opt_in" | "close_out" | "clear_state" | "delete_application" | NoOpOC | OptInOC | CloseOutOC | ClearStateOC | DeleteApplicationOC The call type
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:669


clearState

clearState(call?): Promise\<AppCallTransactionResult>

Issues a clear_state call to the app.

Parameters
Name Type Description
call? AppClientClearStateParams The call details.
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:650


closeOut

closeOut(call?): Promise\<AppCallTransactionResult>

Issues a close_out call to the app.

Parameters
Name Type Description
call? AppClientCallParams The call details.
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:641


compile

compile(compilation?): Promise\<{ approvalCompiled: CompiledTeal ; clearCompiled: CompiledTeal }>

Compiles the approval and clear programs and sets up the source map.

Parameters
Name Type Description
compilation? AppClientCompilationParams The deploy-time parameters for the compilation
Returns

Promise\<{ approvalCompiled: CompiledTeal ; clearCompiled: CompiledTeal }>

The compiled approval and clear programs

Defined in

src/types/app-client.ts:328


create

create(create?): Promise\<{ appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation?: PendingTransactionResponse ; confirmations?: PendingTransactionResponse[] ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] }>

Creates a smart contract app, returns the details of the created app.

Parameters
Name Type Description
create? AppClientCreateParams The parameters to create the app with
Returns

Promise\<{ appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation?: PendingTransactionResponse ; confirmations?: PendingTransactionResponse[] ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] }>

The details of the created app, or the transaction to create it if skipSending and the compilation result

Defined in

src/types/app-client.ts:505


delete

delete(call?): Promise\<AppCallTransactionResult>

Issues a delete_application call to the app.

Parameters
Name Type Description
call? AppClientCallParams The call details.
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:659


deploy

deploy(deploy?): Promise\<Partial\<AppCompilationResult> & AppMetadata & { operationPerformed: "nothing" } | { appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; createdMetadata: AppDeployMetadata ; createdRound: number ; deletable?: boolean ; deleted: boolean ; name: string ; operationPerformed: "update" | "create" ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] ; updatable?: boolean ; updatedRound: number ; version: string } | { appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; createdMetadata: AppDeployMetadata ; createdRound: number ; deletable?: boolean ; deleteResult: ConfirmedTransactionResult ; deleteReturn?: ABIReturn ; deleted: boolean ; name: string ; operationPerformed: "replace" ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] ; updatable?: boolean ; updatedRound: number ; version: string }>

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.

Parameters
Name Type Description
deploy? AppClientDeployParams Deployment details
Returns

Promise\<Partial\<AppCompilationResult> & AppMetadata & { operationPerformed: "nothing" } | { appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; createdMetadata: AppDeployMetadata ; createdRound: number ; deletable?: boolean ; deleted: boolean ; name: string ; operationPerformed: "update" | "create" ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] ; updatable?: boolean ; updatedRound: number ; version: string } | { appAddress: string ; appId: number | bigint ; compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; createdMetadata: AppDeployMetadata ; createdRound: number ; deletable?: boolean ; deleteResult: ConfirmedTransactionResult ; deleteReturn?: ABIReturn ; deleted: boolean ; name: string ; operationPerformed: "replace" ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] ; updatable?: boolean ; updatedRound: number ; version: string }>

The metadata and transaction result(s) of the deployment, or just the metadata if it didn't need to issue transactions

Defined in

src/types/app-client.ts:397


exportSourceMaps

exportSourceMaps(): AppSourceMaps

Export the current source maps for the app.

Returns

AppSourceMaps

The source maps

Defined in

src/types/app-client.ts:364


exposeLogicError

exposeLogicError(e, isClear?): Error

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 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.

Parameters
Name Type Description
e Error The error to parse
isClear? boolean Whether or not the code was running the clear state program
Returns

Error

The new error, or if there was no logic error or source map then the wrapped error with source details

Defined in

src/types/app-client.ts:985


fundAppAccount

fundAppAccount(fund): Promise\<SendTransactionResult>

Funds ALGOs into the app account for this app.

Parameters
Name Type Description
fund AlgoAmount | FundAppAccountParams The parameters for the funding or the funding amount
Returns

Promise\<SendTransactionResult>

The result of the funding

Defined in

src/types/app-client.ts:709


getABIMethod

getABIMethod(method): undefined | ABIMethod

Returns the ABI Method for the given method name string for the app represented by this application client instance

Parameters
Name Type Description
method string Either the name of the method or the ABI method spec definition string
Returns

undefined | ABIMethod

The ABI method for the given method

Defined in

src/types/app-client.ts:944


getABIMethodParams

getABIMethodParams(method): undefined | ABIMethodParams

Returns the ABI Method parameters for the given method name string for the app represented by this application client instance

Parameters
Name Type Description
method string Either the name of the method or the ABI method spec definition string
Returns

undefined | ABIMethodParams

The ABI method params for the given method

Defined in

src/types/app-client.ts:922


getAppReference

getAppReference(): Promise\<AppReference | AppMetadata>

Gets the reference information for the current application instance. appId will be 0 if it can't find an app.

Returns

Promise\<AppReference | AppMetadata>

The app reference, or if deployed using the deploy method, the app metadata too

Defined in

src/types/app-client.ts:954


getBoxNames

getBoxNames(): Promise\<BoxName[]>

Returns the names of all current boxes for the current app.

Returns

Promise\<BoxName[]>

The names of the boxes

Defined in

src/types/app-client.ts:763


getBoxValue

getBoxValue(name): Promise\<Uint8Array>

Returns the value of the given box for the current app.

Parameters
Name Type Description
name string | Uint8Array | BoxName The name of the box to return either as a string, binary array or BoxName
Returns

Promise\<Uint8Array>

The current box value as a byte array

Defined in

src/types/app-client.ts:778


getBoxValueFromABIType

getBoxValueFromABIType(name, type): Promise\<ABIValue>

Returns the value of the given box for the current app.

Parameters
Name Type Description
name string | Uint8Array | BoxName The name of the box to return either as a string, binary array or BoxName
type ABIType
Returns

Promise\<ABIValue>

The current box value as a byte array

Defined in

src/types/app-client.ts:794


getBoxValues

getBoxValues(filter?): Promise\<{ name: BoxName ; value: Uint8Array }[]>

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.

Parameters
Name Type Description
filter? (name: BoxName) => boolean Optional filter to filter which boxes' values are returned
Returns

Promise\<{ name: BoxName ; value: Uint8Array }[]>

The (name, value) pair of the boxes with values as raw byte arrays

Defined in

src/types/app-client.ts:810


getBoxValuesFromABIType

getBoxValuesFromABIType(type, filter?): Promise\<{ name: BoxName ; value: ABIValue }[]>

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.

Parameters
Name Type Description
type ABIType The ABI type to decode the values with
filter? (name: BoxName) => boolean Optional filter to filter which boxes' values are returned
Returns

Promise\<{ name: BoxName ; value: ABIValue }[]>

The (name, value) pair of the boxes with values as the ABI Value

Defined in

src/types/app-client.ts:832


getCallArgs

getCallArgs(args, sender): Promise\<undefined | AppCallArgs>

Returns the arguments for an app call for the given ABI method or raw method specification.

Parameters
Name Type Description
args undefined | AppClientCallArgs The call args specific to this application client
sender SendTransactionFrom The sender of this call. Will be used to fetch any default argument values if applicable
Returns

Promise\<undefined | AppCallArgs>

The call args ready to pass into an app call

Defined in

src/types/app-client.ts:854


getGlobalState

getGlobalState(): Promise\<AppState>

Returns global state for the current app.

Returns

Promise\<AppState>

The global state

Defined in

src/types/app-client.ts:735


getLocalState

getLocalState(account): Promise\<AppState>

Returns local state for the given account / account address.

Parameters
Name Type
account string | SendTransactionFrom
Returns

Promise\<AppState>

The global state

Defined in

src/types/app-client.ts:749


importSourceMaps

importSourceMaps(sourceMaps): void

Import source maps for the app.

Parameters
Name Type Description
sourceMaps AppSourceMaps The source maps to import
Returns

void

Defined in

src/types/app-client.ts:381


optIn

optIn(call?): Promise\<AppCallTransactionResult>

Issues a opt_in call to the app.

Parameters
Name Type Description
call? AppClientCallParams The call details.
Returns

Promise\<AppCallTransactionResult>

The result of the call

Defined in

src/types/app-client.ts:632


update

update(update?): Promise\<{ compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation?: PendingTransactionResponse ; confirmations?: PendingTransactionResponse[] ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] }>

Updates the smart contract app.

Parameters
Name Type Description
update? AppClientUpdateParams The parameters to update the app with
Returns

Promise\<{ compiledApproval: CompiledTeal ; compiledClear: CompiledTeal ; confirmation?: PendingTransactionResponse ; confirmations?: PendingTransactionResponse[] ; return?: ABIReturn ; transaction: Transaction ; transactions: Transaction[] }>

The transaction send result and the compilation result

Defined in

src/types/app-client.ts:557