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¶
- _appAddress
- _appId
- _appName
- _approvalSourceMap
- _clearSourceMap
- _creator
- algod
- appSpec
- deployTimeParams
- existingDeployments
- indexer
- params
- sender
Methods¶
- call
- callOfType
- clearState
- closeOut
- compile
- create
- delete
- deploy
- exportSourceMaps
- exposeLogicError
- fundAppAccount
- getABIMethod
- getABIMethodParams
- getAppReference
- getBoxNames
- getBoxValue
- getBoxValueFromABIType
- getBoxValues
- getBoxValuesFromABIType
- getCallArgs
- getGlobalState
- getLocalState
- importSourceMaps
- optIn
- update
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¶
Defined in¶
Properties¶
_appAddress¶
• Private _appAddress: string
Defined in¶
_appId¶
• Private _appId: number | bigint
Defined in¶
_appName¶
• Private _appName: string
Defined in¶
_approvalSourceMap¶
• Private _approvalSourceMap: undefined | SourceMap
Defined in¶
_clearSourceMap¶
• Private _clearSourceMap: undefined | SourceMap
Defined in¶
_creator¶
• Private _creator: undefined | string
Defined in¶
algod¶
• Private algod: default
Defined in¶
appSpec¶
• Private appSpec: AppSpec
Defined in¶
deployTimeParams¶
• Private Optional deployTimeParams: TealTemplateParams
Defined in¶
existingDeployments¶
• Private existingDeployments: undefined | AppLookup
Defined in¶
indexer¶
• Private Optional indexer: default
Defined in¶
params¶
• Private params: undefined | SuggestedParams
Defined in¶
sender¶
• Private sender: undefined | SendTransactionFrom
Defined in¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
exportSourceMaps¶
▸ exportSourceMaps(): AppSourceMaps
Export the current source maps for the app.
Returns¶
The source maps
Defined in¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
getGlobalState¶
▸ getGlobalState(): Promise\<AppState>
Returns global state for the current app.
Returns¶
Promise\<AppState>
The global state
Defined in¶
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¶
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¶
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¶
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