Skip to content

Latest commit

 

History

History
2432 lines (1452 loc) · 78.9 KB

index.md

File metadata and controls

2432 lines (1452 loc) · 78.9 KB

@algorandfoundation/algokit-utils / index

Module: index

Table of contents

Variables

Functions

Variables

Config

Const Config: UpdatableConfig

The AlgoKit config. To update it use the configure method.

Defined in

src/index.ts:16

Functions

algos

algos(algos): AlgoAmount

Returns an amount of Algos using AlgoAmount

Parameters

Name Type Description
algos number The amount in Algos

Returns

AlgoAmount

Defined in

src/amount.ts:22


callApp

callApp(call, algod): Promise<AppCallTransactionResult>

Issues a call to a given app.

Parameters

Name Type Description
call AppCallParams The call details.
algod default An algod client

Returns

Promise<AppCallTransactionResult>

The result of the call

Defined in

src/app.ts:305


capTransactionFee

capTransactionFee(transaction, maxAcceptableFee): void

Limit the acceptable fee to a defined amount of µALGOs. This also sets the transaction to be flatFee to ensure the transaction only succeeds at the estimated rate.

Parameters

Name Type Description
transaction SuggestedParams | Transaction The transaction to cap or suggested params object about to be used to create a transaction
maxAcceptableFee AlgoAmount The maximum acceptable fee to pay

Returns

void

Defined in

src/transaction.ts:426


compileTeal

compileTeal(tealCode, algod): Promise<CompiledTeal>

Compiles the given TEAL using algod and returns the result, including source map.

Parameters

Name Type Description
tealCode string The TEAL code
algod default An algod client

Returns

Promise<CompiledTeal>

The information about the compiled file

Defined in

src/app.ts:672


controlFees

controlFees<T>(transaction, feeControl): T

Allows for control of fees on a Transaction or SuggestedParams object

Type parameters

Name Type
T extends SuggestedParams | Transaction

Parameters

Name Type Description
transaction T The transaction or suggested params
feeControl Object The fee control parameters
feeControl.fee? AlgoAmount -
feeControl.maxFee? AlgoAmount -

Returns

T

Defined in

src/transaction.ts:449


createApp

createApp(create, algod): Promise<Partial<AppCompilationResult> & AppCallTransactionResult & AppReference>

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

Parameters

Name Type Description
create CreateAppParams The parameters to create the app with
algod default An algod client

Returns

Promise<Partial<AppCompilationResult> & AppCallTransactionResult & AppReference>

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

Defined in

src/app.ts:56


decodeAppState

decodeAppState(state): AppState

Converts an array of global/local state values from the algod api to a more friendly generic object keyed by the UTF-8 value of the key.

Parameters

Name Type Description
state { key: string ; value: TealValue | EvalDelta }[] A global-state, local-state, global-state-deltas or local-state-deltas

Returns

AppState

An object keyeed by the UTF-8 representation of the key with various parsings of the values

Defined in

src/app.ts:522


deployApp

deployApp(deployment, algod, indexer?): Promise<Partial<AppCompilationResult> & ConfirmedTransactionResults & AppMetadata & { operationPerformed: "create" | "update" ; return?: ABIReturn } | ConfirmedTransactionResults & AppMetadata & { deleteResult: ConfirmedTransactionResult ; deleteReturn?: ABIReturn ; operationPerformed: "replace" ; return?: ABIReturn } | AppMetadata & { operationPerformed: "nothing" }>

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: When using the return from this function be sure to check operationPerformed to get access to various return properties like transaction, confirmation and deleteResult.

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
deployment AppDeploymentParams The arguments to control the app deployment
algod default An algod client
indexer? default An indexer client, needed if existingDeployments not passed in

Returns

Promise<Partial<AppCompilationResult> & ConfirmedTransactionResults & AppMetadata & { operationPerformed: "create" | "update" ; return?: ABIReturn } | ConfirmedTransactionResults & AppMetadata & { deleteResult: ConfirmedTransactionResult ; deleteReturn?: ABIReturn ; operationPerformed: "replace" ; return?: ABIReturn } | AppMetadata & { operationPerformed: "nothing" }>

The app reference of the new/existing app

Defined in

src/app-deploy.ts:38


encodeTransactionNote

encodeTransactionNote(note?): Uint8Array | undefined

Encodes a transaction note into a byte array ready to be included in an Algorand transaction.

Parameters

Name Type Description
note? TransactionNote The transaction note

Returns

Uint8Array | undefined

the transaction note ready for inclusion in a transaction

Case on the value of data this either be:

  • null | undefined: undefined
  • string: The string value
  • Uint8Array: passthrough
  • Arc2TransactionNote object: ARC-0002 compatible transaction note
  • Else: The object/value converted into a JSON string representation

Defined in

src/transaction.ts:39


ensureFunded

ensureFunded<T>(funding, algod, kmd?): Promise<EnsureFundedReturnType | undefined>

Funds a given account using a funding source such that it has a certain amount of algos free to spend (accounting for ALGOs locked in minimum balance requirement).

https://developer.algorand.org/docs/get-details/accounts/#minimum-balance

Type parameters

Name Type
T extends EnsureFundedParams

Parameters

Name Type Description
funding T The funding configuration of type EnsureFundedParams, including the account to fund, minimum spending balance, and optional parameters. If you set useDispenserApi to true, you must also set ALGOKIT_DISPENSER_ACCESS_TOKEN in your environment variables.
algod default An instance of the Algodv2 client.
kmd? default An optional instance of the Kmd client.

Returns

Promise<EnsureFundedReturnType | undefined>

  • EnsureFundedReturnType if funds were transferred.
  • undefined if no funds were needed.

Defined in

src/transfer.ts:114


executePaginatedRequest

executePaginatedRequest<TResult, TRequest>(extractItems, buildRequest): Promise<TResult[]>

Type parameters

Name Type
TResult TResult
TRequest extends Object

Parameters

Name Type
extractItems (response: any) => TResult[]
buildRequest (nextToken?: string) => TRequest

Returns

Promise<TResult[]>

Defined in

src/indexer-lookup.ts:108


getABIMethodSignature

getABIMethodSignature(method): string

Returns the encoded ABI spec for a given ABI Method

Parameters

Name Type Description
method ABIMethodParams | ABIMethod The method to return a signature for

Returns

string

The encoded ABI method spec e.g. method_name(uint64,string)string

Defined in

src/app.ts:688


getABIReturn

getABIReturn(args?, confirmation?): ABIReturn | undefined

Returns any ABI return values for the given app call arguments and transaction confirmation.

Parameters

Name Type Description
args? AppCallArgs The arguments that were used for the call
confirmation? PendingTransactionResponse The transaction confirmation from algod

Returns

ABIReturn | undefined

The return value for the method call

Defined in

src/app.ts:386


getAccount

getAccount(account, algod, kmdClient?): Promise<Account | SigningAccount>

Parameters

Name Type Description
account string | { fundWith?: AlgoAmount ; name: string } The details of the account to get, either the name identifier (string) or an object with: * name: The name identifier of the account * fundWith: The amount to fund the account with when it gets created (when targeting LocalNet), if not specified then 1000 Algos will be funded from the dispenser account
algod default An algod client
kmdClient? default An optional KMD client to use to create an account (when targeting LocalNet), if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account | SigningAccount>

The requested account with private key loaded from the environment variables or when targeting LocalNet from KMD (idempotently creating and funding the account)

Deprecated

use mnemonicAccountFromEnvironment instead

Returns an Algorand account with private key loaded by convention based on the given name identifier.

Note: This function expects to run in a Node.js environment.

Convention:

  • Non-LocalNet: will load process.env['{NAME}_MNEMONIC'] as a mnemonic secret; Note: Be careful how the mnemonic is handled, never commit it into source control and ideally load it via a secret storage service rather than the file system. If process.env['{NAME}_SENDER'] is defined then it will use that for the sender address (i.e. to support rekeyed accounts)
  • LocalNet: will load the account from a KMD wallet called {NAME} and if that wallet doesn't exist it will create it and fund the account for you

This allows you to write code that will work seamlessly in production and local development (LocalNet) without manual config locally (including when you reset the LocalNet).

Example

Default

If you have a mnemonic secret loaded into process.env.ACCOUNT_MNEMONIC then you can call the following to get that private key loaded into an account object:

const account = await getAccount('ACCOUNT', algod)

If that code runs against LocalNet then a wallet called ACCOUNT will automatically be created with an account that is automatically funded with 1000 (default) ALGOs from the default LocalNet dispenser.

Defined in

src/account.ts:92

getAccount(account, algod, kmdClient?): Promise<Account | SigningAccount>

Parameters

Name Type Description
account Object The details of the account to get, an object with: * config: Account configuration. To get from environment use getAccountConfigFromEnvironment(accountName) * fundWith: The amount to fund the account with when it gets created (when targeting LocalNet), if not specified then 1000 Algos will be funded from the dispenser account
account.config AccountConfig -
account.fundWith? AlgoAmount -
algod default An algod client
kmdClient? default An optional KMD client to use to create an account (when targeting LocalNet), if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account | SigningAccount>

The requested account with private key loaded from the environment variables or when targeting LocalNet from KMD (idempotently creating and funding the account)

Deprecated

use mnemonicAccountFromEnvironment instead Returns an Algorand account with private key loaded by convention based on the given name identifier.

Note: This function expects to run in a Node.js environment.

Example

Default

If you have a mnemonic secret loaded into process.env.ACCOUNT_MNEMONIC then you can call the following to get that private key loaded into an account object:

const account = await getAccount({config: getAccountConfigFromEnvironment('ACCOUNT')}, algod)

If that code runs against LocalNet then a wallet called ACCOUNT will automatically be created with an account that is automatically funded with 1000 (default) ALGOs from the default LocalNet dispenser.

Defined in

src/account.ts:119


getAccountAddressAsString

getAccountAddressAsString(addressEncodedInB64): string

Returns the string address of an Algorand account from a base64 encoded version of the underlying byte array of the address public key

Parameters

Name Type Description
addressEncodedInB64 string The base64 encoded version of the underlying byte array of the address public key

Returns

string

Defined in

src/account.ts:270


getAccountAddressAsUint8Array

getAccountAddressAsUint8Array(account): Uint8Array

Returns an account's address as a byte array

Parameters

Name Type Description
account string | SendTransactionFrom Either an account (with private key loaded) or the string address of an account

Returns

Uint8Array

Defined in

src/account.ts:262


getAccountConfigFromEnvironment

getAccountConfigFromEnvironment(accountName): AccountConfig

Parameters

Name Type Description
accountName string account name

Returns

AccountConfig

Deprecated

Use algokit.mnemonicAccountFromEnvironment, which doesn't need this function Returns the Account configuration from environment variables

Example

environment variables
{accountName}_MNEMONIC
{accountName}_SENDER

Defined in

src/account.ts:298


getAlgoClient

getAlgoClient(config?): Algodv2

Returns an algod SDK client that automatically retries on idempotent calls

Parameters

Name Type Description
config? AlgoClientConfig The config if you want to override the default (getting config from process.env)

Returns

Algodv2

Example

Default (load from environment variables)

// Uses process.env.ALGOD_SERVER, process.env.ALGOD_PORT and process.env.ALGOD_TOKEN
// Automatically detects if you are using PureStake to switch in the right header name for ALGOD_TOKEN
const algod = getAlgoClient()
await algod.healthCheck().do()

Example

AlgoNode (testnet)

 const algod = getAlgoClient(getAlgoNodeConfig('testnet', 'algod'))
 await algod.healthCheck().do()

Example

AlgoNode (mainnet)

 const algod = getAlgoClient(getAlgoNodeConfig('mainnet', 'algod'))
 await algod.healthCheck().do()

Example

Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)

 const algod = getAlgoClient({server: 'http://localhost', port: '4001', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
 await algod.healthCheck().do()

Defined in

src/network-client.ts:126


getAlgoIndexerClient

getAlgoIndexerClient(config?): Indexer

Returns an indexer SDK client that automatically retries on idempotent calls

Parameters

Name Type Description
config? AlgoClientConfig The config if you want to override the default (getting config from process.env)

Returns

Indexer

Example

Default (load from environment variables)

// Uses process.env.INDEXER_SERVER, process.env.INDEXER_PORT and process.env.INDEXER_TOKEN
// Automatically detects if you are using PureStake to switch in the right header name for INDEXER_TOKEN
const indexer = getAlgoIndexerClient()
await indexer.makeHealthCheck().do()

Example

AlgoNode (testnet)

 const indexer = getAlgoIndexerClient(getAlgoNodeConfig('testnet', 'indexer'))
 await indexer.makeHealthCheck().do()

Example

AlgoNode (mainnet)

 const indexer = getAlgoIndexerClient(getAlgoNodeConfig('mainnet', 'indexer'))
 await indexer.makeHealthCheck().do()

Example

Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)

 const indexer = getAlgoIndexerClient({server: 'http://localhost', port: '8980', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
 await indexer.makeHealthCheck().do()

Defined in

src/network-client.ts:159


getAlgoKmdClient

getAlgoKmdClient(config?): Kmd

Returns a KMD SDK client that automatically retries on idempotent calls

KMD client allows you to export private keys, which is useful to get the default account in a LocalNet network.

Parameters

Name Type Description
config? AlgoClientConfig The config if you want to override the default (getting config from process.env)

Returns

Kmd

Example

Default (load from environment variables)

// Uses process.env.ALGOD_SERVER, process.env.KMD_PORT (or if not specified: port 4002) and process.env.ALGOD_TOKEN
const kmd = getAlgoKmdClient()

Example

Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)

 const kmd = getAlgoKmdClient({server: 'http://localhost', port: '4002', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})

Defined in

src/network-client.ts:182


getAlgoNodeConfig

getAlgoNodeConfig(network, config): AlgoClientConfig

Returns the Algorand configuration to point to the AlgoNode service

Parameters

Name Type Description
network "testnet" | "mainnet" Which network to connect to - TestNet or MainNet
config "algod" | "indexer" Which algod config to return - Algod or Indexer

Returns

AlgoClientConfig

Defined in

src/network-client.ts:72


getAlgodConfigFromEnvironment

getAlgodConfigFromEnvironment(): AlgoClientConfig

Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment not algod-side)

Returns

AlgoClientConfig

Defined in

src/network-client.ts:34


getAppArgsForABICall

getAppArgsForABICall(args, from): Promise<{ appAccounts: undefined | string[] ; appForeignApps: undefined | number[] = args.apps; appForeignAssets: undefined | number[] = args.assets; boxes: undefined | BoxReference[] ; lease: undefined | Uint8Array ; method: ABIMethod ; methodArgs: (string | number | bigint | boolean | Uint8Array | ABIValue[] | TransactionWithSigner)[] = methodArgs; rekeyTo: undefined = undefined; sender: string ; signer: TransactionSigner = signer }>

Returns the app args ready to load onto an ABI method call in AtomicTransactionComposer

Parameters

Name Type Description
args ABIAppCallArgs The ABI app call args
from SendTransactionFrom The transaction signer

Returns

Promise<{ appAccounts: undefined | string[] ; appForeignApps: undefined | number[] = args.apps; appForeignAssets: undefined | number[] = args.assets; boxes: undefined | BoxReference[] ; lease: undefined | Uint8Array ; method: ABIMethod ; methodArgs: (string | number | bigint | boolean | Uint8Array | ABIValue[] | TransactionWithSigner)[] = methodArgs; rekeyTo: undefined = undefined; sender: string ; signer: TransactionSigner = signer }>

The parameters ready to pass into addMethodCall within AtomicTransactionComposer

Defined in

src/app.ts:589


getAppArgsForTransaction

getAppArgsForTransaction(args?): undefined | { accounts: undefined | string[] ; appArgs: undefined | Uint8Array[] ; boxes: undefined | BoxReference[] ; foreignApps: undefined | number[] = args.apps; foreignAssets: undefined | number[] = args.assets; lease: undefined | Uint8Array }

Returns the app args ready to load onto an app Transaction object

Parameters

Name Type Description
args? RawAppCallArgs The app call args

Returns

undefined | { accounts: undefined | string[] ; appArgs: undefined | Uint8Array[] ; boxes: undefined | BoxReference[] ; foreignApps: undefined | number[] = args.apps; foreignAssets: undefined | number[] = args.assets; lease: undefined | Uint8Array }

The args ready to load into a Transaction

Defined in

src/app.ts:569


getAppBoxNames

getAppBoxNames(appId, algod): Promise<BoxName[]>

Returns the names of the boxes for the given app.

Parameters

Name Type Description
appId number | bigint The ID of the app return box names for
algod default An algod client instance

Returns

Promise<BoxName[]>

The current box names

Defined in

src/app.ts:458


getAppBoxValue

getAppBoxValue(appId, boxName, algod): Promise<Uint8Array>

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

Parameters

Name Type Description
appId number | bigint The ID of the app return box names for
boxName string | Uint8Array | BoxName The name of the box to return either as a string, binary array or BoxName
algod default An algod client instance

Returns

Promise<Uint8Array>

The current box value as a byte array

Defined in

src/app.ts:476


getAppBoxValueFromABIType

getAppBoxValueFromABIType(request, algod): Promise<ABIValue>

Returns the value of the given box name for the given app decoded based on the given ABI type.

Parameters

Name Type Description
request BoxValueRequestParams The parameters for the box value request
algod default An algod client instance

Returns

Promise<ABIValue>

The current box value as an ABI value

Defined in

src/app.ts:499


getAppBoxValues

getAppBoxValues(appId, boxNames, algod): Promise<Uint8Array[]>

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

Parameters

Name Type Description
appId number The ID of the app return box names for
boxNames (string | Uint8Array | BoxName)[] The names of the boxes to return either as a string, binary array or BoxName
algod default An algod client instance

Returns

Promise<Uint8Array[]>

The current box values as a byte array in the same order as the passed in box names

Defined in

src/app.ts:489


getAppBoxValuesFromABIType

getAppBoxValuesFromABIType(request, algod): Promise<ABIValue[]>

Returns the value of the given box names for the given app decoded based on the given ABI type.

Parameters

Name Type Description
request BoxValuesRequestParams The parameters for the box value request
algod default An algod client instance

Returns

Promise<ABIValue[]>

The current box values as an ABI value in the same order as the passed in box names

Defined in

src/app.ts:511


getAppById

getAppById(appId, algod): Promise<Application>

Gets the current data for the given app from algod.

Parameters

Name Type Description
appId number | bigint The id of the app
algod default An algod client

Returns

Promise<Application>

The data about the app

Defined in

src/app.ts:661


getAppClient

getAppClient(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

The application client

Example

Resolve by creator and name
const client = algokit.getAppClient(
    {
      resolveBy: 'creatorAndName',
      app: {appSpec},
      sender: {account},
      creatorAddress: {creator},
      findExistingUsing: indexerClient,
    },
    algodClient,
  )

Example

Resolve by id:
const client = algokit.getAppClient(
    {
      resolveBy: 'id',
      app: {appSpec},
      sender: {account},
      id: {id},
    },
   algodClient,
)

Defined in

src/app-client.ts:34


getAppClientByCreatorAndName

getAppClientByCreatorAndName(appDetails, algod): ApplicationClient

Create a new ApplicationClient instance by creator and name

Parameters

Name Type Description
appDetails AppSpecAppDetailsByCreatorAndName The details of the app by creator and name
algod default An algod instance

Returns

ApplicationClient

The application client

Example

const client = algokit.getAppClientByCreatorAndName(
    {
      app: {appSpec},
      sender: {account},
      creatorAddress: {account.addr},
      findExistingUsing: {indexerClient},
    },
    algodClient,
  )

Defined in

src/app-client.ts:77


getAppClientById

getAppClientById(appDetails, algod): ApplicationClient

Create a new ApplicationClient instance by id

Parameters

Name Type Description
appDetails AppSpecAppDetailsById The details of the app
algod default An algod instance

Returns

ApplicationClient

The application client

Example

const client = algokit.getAppClientById(
    {
      app: {appSpec},
      sender: {account},
      id: {id},
    },
    algodClient,
  )

Defined in

src/app-client.ts:55


getAppDeploymentTransactionNote

getAppDeploymentTransactionNote(metadata): Arc2TransactionNote

Return the transaction note for an app deployment.

Parameters

Name Type Description
metadata AppDeployMetadata The metadata of the deployment

Returns

Arc2TransactionNote

The transaction note as a utf-8 string

Defined in

src/app-deploy.ts:528


getAppGlobalState

getAppGlobalState(appId, algod): Promise<AppState>

Returns the current global state values for the given app ID

Parameters

Name Type Description
appId number | bigint The ID of the app return global state for
algod default An algod client instance

Returns

Promise<AppState>

The current global state

Defined in

src/app.ts:422


getAppLocalState

getAppLocalState(appId, account, algod): Promise<AppState>

Returns the current global state values for the given app ID and account

Parameters

Name Type Description
appId number | bigint The ID of the app return global state for
account string | SendTransactionFrom Either the string address of an account or an account object for the account to get local state for the given app
algod default An algod client instance

Returns

Promise<AppState>

The current local state for the given (app, account) combination

Defined in

src/app.ts:439


getAppOnCompleteAction

getAppOnCompleteAction(onCompletionAction?): OnApplicationComplete

Returns an algosdk.OnApplicationComplete for the given onCompleteAction.

If given undefined will return OnApplicationComplete.NoOpOC.

If given an AppCallType will convert the string enum to the correct underlying algosdk.OnApplicationComplete.

Parameters

Name Type Description
onCompletionAction? AppCallType | OnApplicationComplete The on completion action

Returns

OnApplicationComplete

The algosdk.OnApplicationComplete

Defined in

src/app.ts:275


getAtomicTransactionComposerTransactions

getAtomicTransactionComposerTransactions(atc): TransactionWithSigner[]

Returns the array of transactions currently present in the given AtomicTransactionComposer

Parameters

Name Type Description
atc AtomicTransactionComposer The atomic transaction composer

Returns

TransactionWithSigner[]

The array of transactions with signers

Defined in

src/transaction.ts:481


getBoxReference

getBoxReference(box): algosdk.BoxReference

Returns a algosdk.BoxReference given a BoxIdentifier or BoxReference.

Parameters

Name Type Description
box BoxReference | BoxIdentifier | BoxReference The box to return a reference for

Returns

algosdk.BoxReference

The box reference ready to pass into a Transaction

Defined in

src/app.ts:631


getConfigFromEnvOrDefaults

getConfigFromEnvOrDefaults(): AlgoConfig

Retrieve configurations from environment variables when defined or get defaults (expects to be called from a Node.js environment not algod-side)

Returns

AlgoConfig

Defined in

src/network-client.ts:7


getCreatorAppsByName

getCreatorAppsByName(creatorAccount, indexer): Promise<AppLookup>

Returns a lookup of name => app metadata (id, address, ...metadata) for all apps created by the given account that have an AppDeployNote in the transaction note of the creation transaction.

Note: It's recommended this is only called once and then stored since it's a somewhat expensive operation (multiple indexer calls).

Parameters

Name Type Description
creatorAccount string | SendTransactionFrom The account (with private key loaded) or string address of an account that is the creator of the apps you want to search for
indexer default An indexer client

Returns

Promise<AppLookup>

A name-based lookup of the app information (id, address)

Defined in

src/app-deploy.ts:421


getDefaultLocalNetConfig

getDefaultLocalNetConfig(configOrPort): AlgoClientConfig

Returns the Algorand configuration to point to the default LocalNet

Parameters

Name Type Description
configOrPort number | "algod" | "indexer" | "kmd" Which algod config to return - algod, kmd, or indexer OR a port number

Returns

AlgoClientConfig

Defined in

src/network-client.ts:83


getDispenserAccount

getDispenserAccount(algod, kmd?): Promise<default | SigningAccount>

Returns an account (with private key loaded) that can act as a dispenser

If running on LocalNet then it will return the default dispenser account automatically, otherwise it will load the account mnemonic stored in process.env.DISPENSER_MNEMONIC

Parameters

Name Type Description
algod default An algod client
kmd? default A KMD client, if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<default | SigningAccount>

Defined in

src/account.ts:282


getIndexerConfigFromEnvironment

getIndexerConfigFromEnvironment(): AlgoClientConfig

Retrieve the indexer configuration from environment variables (expects to be called from a Node.js environment not algod-side)

Returns

AlgoClientConfig

Defined in

src/network-client.ts:51


getKmdWalletAccount

getKmdWalletAccount(walletAccount, algod, kmdClient?): Promise<Account | undefined>

Returns an Algorand account with private key loaded from the given KMD wallet (identified by name).

Parameters

Name Type Description
walletAccount Object The details of the wallet, with: * name: The name of the wallet to retrieve an account from * predicate: An optional filter to use to find the account (otherwise it will return a random account from the wallet)
walletAccount.name string -
walletAccount.predicate? (account: Record<string, any>) => boolean -
algod default An algod client
kmdClient? default A KMD client, if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account | undefined>

Example

Get default funded account in a LocalNet

const defaultDispenserAccount = await getKmdWalletAccount(algod,
  'unencrypted-default-wallet',
  a => a.status !== 'Offline' && a.amount > 1_000_000_000
)

Defined in

src/localnet.ts:90


getLocalNetDispenserAccount

getLocalNetDispenserAccount(algod, kmd?): Promise<Account>

Returns an Algorand account with private key loaded for the default LocalNet dispenser account (that can be used to fund other accounts)

Parameters

Name Type Description
algod default An algod client
kmd? default A KMD client, if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account>

Defined in

src/localnet.ts:141


getOrCreateKmdWalletAccount

getOrCreateKmdWalletAccount(walletAccount, algod, kmdClient?): Promise<Account>

Gets an account with private key loaded from a KMD wallet of the given name, or alternatively creates one with funds in it via a KMD wallet of the given name.

This is useful to get idempotent accounts from LocalNet without having to specify the private key (which will change when resetting the LocalNet).

This significantly speeds up local dev time and improves experience since you can write code that just works first go without manual config in a fresh LocalNet.

If this is used via mnemonicAccountFromEnvironment, then you can even use the same code that runs on production without changes for local development!

Parameters

Name Type Description
walletAccount Object The wallet details with: * name: The name of the wallet to retrieve / create * fundWith: The number of Algos to fund the account with when it gets created, if not specified then 1000 Algos will be funded from the dispenser account
walletAccount.fundWith? AlgoAmount -
walletAccount.name string -
algod default An algod client
kmdClient? default A KMD client, if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account>

An Algorand account with private key loaded - either one that already existed in the given KMD wallet, or a new one that is funded for you

Defined in

src/localnet.ts:32


getSenderAddress

getSenderAddress(sender): string

Returns the public address of the given transaction sender.

Parameters

Name Type Description
sender SendTransactionFrom A transaction sender

Returns

string

The public address

Defined in

src/transaction.ts:60


getSenderTransactionSigner

getSenderTransactionSigner(val): TransactionSigner

Returns a TransactionSigner for the given transaction sender. This function has memoization, so will return the same transaction signer for a given sender.

Parameters

Name Type
val SendTransactionFrom

Returns

TransactionSigner

A transaction signer

Defined in

src/transaction.ts:70


getTestNetDispenserApiClient

getTestNetDispenserApiClient(params?): TestNetDispenserApiClient

Create a new TestNetDispenserApiClient instance. Refer to docs on guidance to obtain an access token.

Parameters

Name Type Default value Description
params null | TestNetDispenserApiClientParams null An object containing parameters for the TestNetDispenserApiClient class. Or null if you want the client to load the access token from the environment variable ALGOKIT_DISPENSER_ACCESS_TOKEN.

Returns

TestNetDispenserApiClient

An instance of the TestNetDispenserApiClient class.

Example

const client = algokit.getTestNetDispenserApiClient(
    {
      authToken: 'your_auth_token',
      requestTimeout: 15,
    }
)

Defined in

src/dispenser-client.ts:19


getTransactionParams

getTransactionParams(params, algod): Promise<SuggestedParamsWithMinFee | { fee: number ; firstRound: number ; flatFee?: boolean ; genesisHash: string ; genesisID: string ; lastRound: number }>

Returns suggested transaction parameters from algod unless some are already provided.

Parameters

Name Type Description
params undefined | SuggestedParams Optionally provide parameters to use
algod default Algod algod

Returns

Promise<SuggestedParamsWithMinFee | { fee: number ; firstRound: number ; flatFee?: boolean ; genesisHash: string ; genesisID: string ; lastRound: number }>

The suggested transaction parameters

Defined in

src/transaction.ts:472


getTransactionWithSigner

getTransactionWithSigner(transaction, defaultSender?): Promise<TransactionWithSigner>

Given a transaction in a variety of supported formats, returns a TransactionWithSigner object ready to be passed to an AtomicTransactionComposer's addTransaction method.

Parameters

Name Type Description
transaction Transaction | TransactionToSign | Promise<SendTransactionResult> | TransactionWithSigner One of: A TransactionWithSigner object (returned as is), a TransactionToSign object (signer is obtained from the signer property), a Transaction object (signer is extracted from the defaultSender parameter), an async SendTransactionResult returned by one of algokit utils' helpers (signer is obtained from the defaultSender parameter)
defaultSender? SendTransactionFrom The default sender to be used to obtain a signer where the object provided to the transaction parameter does not include a signer.

Returns

Promise<TransactionWithSigner>

A TransactionWithSigner object.

Defined in

src/transaction.ts:83


isLocalNet

isLocalNet(algod): Promise<boolean>

Returns true if the algod client is pointing to a LocalNet Algorand network

Parameters

Name Type
algod default

Returns

Promise<boolean>

Defined in

src/localnet.ts:9


isMainNet

isMainNet(algod): Promise<boolean>

Parameters

Name Type
algod default

Returns

Promise<boolean>

Defined in

src/network-client.ts:194


isSchemaIsBroken

isSchemaIsBroken(before, after): boolean

Returns true is there is a breaking change in the application state schema from before to after. i.e. if the schema becomes larger, since applications can't ask for more schema after creation. Otherwise, there is no error, the app just doesn't store data in the extra schema :(

Parameters

Name Type Description
before ApplicationStateSchema The existing schema
after ApplicationStateSchema The new schema

Returns

boolean

Whether or not there is a breaking change

Defined in

src/app-deploy.ts:408


isTestNet

isTestNet(algod): Promise<boolean>

Parameters

Name Type
algod default

Returns

Promise<boolean>

Defined in

src/network-client.ts:189


lookupAccountByAddress

lookupAccountByAddress(accountAddress, indexer): Promise<AccountLookupResult>

Looks up an account by address using Indexer.

Parameters

Name Type Description
accountAddress string -
indexer default An indexer client

Returns

Promise<AccountLookupResult>

The result of the look-up

Defined in

src/indexer-lookup.ts:29


lookupAccountCreatedApplicationByAddress

lookupAccountCreatedApplicationByAddress(indexer, address, getAll?, paginationLimit?): Promise<ApplicationResult[]>

Looks up applications that were created by the given address.

Parameters

Name Type Default value Description
indexer default undefined An indexer instance
address string undefined The address of the creator to look up
getAll undefined | boolean undefined Whether or not to include deleted applications
paginationLimit? number undefined The number of records to return per paginated request, default 1000

Returns

Promise<ApplicationResult[]>

The list of application results

Defined in

src/indexer-lookup.ts:41


lookupTransactionById

lookupTransactionById(transactionId, indexer): Promise<TransactionLookupResult>

Looks up a transaction by ID using Indexer.

Parameters

Name Type Description
transactionId string The ID of the transaction to look up
indexer default An indexer client

Returns

Promise<TransactionLookupResult>

The result of the look-up

Defined in

src/indexer-lookup.ts:19


microAlgos

microAlgos(microAlgos): AlgoAmount

Returns an amount of µAlgos using AlgoAmount

Parameters

Name Type Description
microAlgos number The amount in µAlgos

Returns

AlgoAmount

Defined in

src/amount.ts:29


mnemonicAccount

mnemonicAccount(mnemonicSecret): Account

Returns an Algorand account with secret key loaded (i.e. that can sign transactions) by taking the mnemonic secret.

This is a wrapper around algosdk.mnemonicToSecretKey to provide a more friendly/obvious name.

Parameters

Name Type Description
mnemonicSecret string The mnemonic secret representing the private key of an account; Note: Be careful how the mnemonic is handled, never commit it into source control and ideally load it from the environment (ideally via a secret storage service) rather than the file system.

Returns

Account

Defined in

src/account.ts:47


mnemonicAccountFromEnvironment

mnemonicAccountFromEnvironment(account, algod, kmdClient?): Promise<Account | SigningAccount>

Returns an Algorand account with private key loaded by convention from environment variables based on the given name identifier.

Note: This function expects to run in a Node.js environment.

Convention:

  • Non-LocalNet: will load process.env['{NAME}_MNEMONIC'] as a mnemonic secret; Note: Be careful how the mnemonic is handled, never commit it into source control and ideally load it via a secret storage service rather than the file system. If process.env['{NAME}_SENDER'] is defined then it will use that for the sender address (i.e. to support rekeyed accounts)
  • LocalNet: will load the account from a KMD wallet called {NAME} and if that wallet doesn't exist it will create it and fund the account for you

This allows you to write code that will work seamlessly in production and local development (LocalNet) without manual config locally (including when you reset the LocalNet).

Parameters

Name Type Description
account string | { fundWith?: AlgoAmount ; name: string } The details of the account to get, either the name identifier (string) or an object with: * name: string: The name identifier of the account * fundWith: The amount to fund the account with when it gets created (when targeting LocalNet), if not specified then 1000 Algos will be funded from the dispenser account
algod default An algod client
kmdClient? default An optional KMD client to use to create an account (when targeting LocalNet), if not specified then a default KMD client will be loaded from environment variables

Returns

Promise<Account | SigningAccount>

The requested account with private key loaded from the environment variables or when targeting LocalNet from KMD (idempotently creating and funding the account)

Example

Default

If you have a mnemonic secret loaded into process.env.MY_ACCOUNT_MNEMONIC then you can call the following to get that private key loaded into an account object:

const account = await mnemonicAccountFromEnvironment('MY_ACCOUNT', algod)

If that code runs against LocalNet then a wallet called MY_ACCOUNT will automatically be created with an account that is automatically funded with 1000 (default) ALGOs from the default LocalNet dispenser. If not running against LocalNet then it will use proces.env.MY_ACCOUNT_MNEMONIC as the private key and (if present) process.env.MY_ACCOUNT_SENDER as the sender address.

Defined in

src/account.ts:230


multisigAccount

multisigAccount(multisigParams, signingAccounts): MultisigAccount

Returns an account wrapper that supports partial or full multisig signing.

Parameters

Name Type Description
multisigParams MultisigMetadata The parameters that define the multisig account
signingAccounts (default | SigningAccount)[] The signers that are currently present

Returns

MultisigAccount

A multisig account wrapper

Defined in

src/account.ts:16


performAtomicTransactionComposerDryrun

performAtomicTransactionComposerDryrun(atc, algod): Promise<DryrunResult>

Performs a dry run of the transactions loaded into the given AtomicTransactionComposer @param atc The AtomicTransactionComposer with transaction(s) loaded

Parameters

Name Type Description
atc AtomicTransactionComposer -
algod default An Algod client

Returns

Promise<DryrunResult>

The dryrun result

Defined in

src/transaction.ts:278


performAtomicTransactionComposerSimulate

performAtomicTransactionComposerSimulate(atc, algod): Promise<SimulateResponse>

Performs a simulation of the transactions loaded into the given AtomicTransactionComposer.

Parameters

Name Type Description
atc AtomicTransactionComposer The AtomicTransactionComposer with transaction(s) loaded.
algod default An Algod client to perform the simulation.

Returns

Promise<SimulateResponse>

The simulation result, which includes various details about how the transactions would be processed.

Defined in

src/transaction.ts:293


performTemplateSubstitution

performTemplateSubstitution(tealCode, templateParams?): string

Performs template substitution of a teal file.

Looks for TMPL_{parameter} for template replacements.

Parameters

Name Type Description
tealCode string The TEAL logic to compile
templateParams? TealTemplateParams Any parameters to replace in the .teal file before compiling

Returns

string

The TEAL code with replacements

Defined in

src/app-deploy.ts:580


performTemplateSubstitutionAndCompile

performTemplateSubstitutionAndCompile(tealCode, algod, templateParams?, deploymentMetadata?): Promise<CompiledTeal>

Performs template substitution of a teal file and compiles it, returning the compiled result.

Looks for TMPL_{parameter} for template replacements.

Parameters

Name Type Description
tealCode string The TEAL logic to compile
algod default An algod client
templateParams? TealTemplateParams Any parameters to replace in the .teal file before compiling
deploymentMetadata? AppDeployMetadata The deployment metadata the app will be deployed with

Returns

Promise<CompiledTeal>

The information about the compiled code

Defined in

src/app-deploy.ts:610


randomAccount

randomAccount(): Account

Returns a new, random Algorand account with secret key loaded.

This is a wrapper around algosdk.generateAccount to provide a more friendly/obvious name.

Returns

Account

Defined in

src/account.ts:57


rekeyedAccount

rekeyedAccount(signer, sender): SigningAccount

Returns an account wrapper that supports a rekeyed account.

Parameters

Name Type Description
signer default The account, with private key loaded, that is signing
sender string The address of the rekeyed account that will act as a sender

Returns

SigningAccount

The SigningAccount wrapper

Defined in

src/account.ts:26


replaceDeployTimeControlParams

replaceDeployTimeControlParams(tealCode, params): string

Replaces deploy-time deployment control parameters within the given teal code.

  • TMPL_UPDATABLE for updatability / immutability control
  • TMPL_DELETABLE for deletability / permanence control

Note: If these values are not undefined, but the corresponding TMPL_* value isn't in the teal code it will throw an exception.

Parameters

Name Type Description
tealCode string The TEAL code to substitute
params Object The deploy-time deployment control parameter value to replace
params.deletable? boolean -
params.updatable? boolean -

Returns

string

The replaced TEAL code

Defined in

src/app-deploy.ts:549


searchTransactions

searchTransactions(indexer, searchCriteria, paginationLimit?): Promise<TransactionSearchResults>

Allows transactions to be searched for the given criteria.

Parameters

Name Type Description
indexer default An indexer client
searchCriteria (s: default) => default The criteria to search for
paginationLimit? number The number of records to return per paginated request, default 1000

Returns

Promise<TransactionSearchResults>

The search results

Defined in

src/indexer-lookup.ts:74


sendAtomicTransactionComposer

sendAtomicTransactionComposer(atcSend, algod): Promise<SendAtomicTransactionComposerResults>

Signs and sends transactions that have been collected by an AtomicTransactionComposer.

Parameters

Name Type Description
atcSend AtomicTransactionComposerToSend The parameters controlling the send, including: * atc The AtomicTransactionComposer * sendParams The parameters to control the send behaviour
algod default An algod client

Returns

Promise<SendAtomicTransactionComposerResults>

An object with transaction IDs, transactions, group transaction ID (groupTransactionId) if more than 1 transaction sent, and (if skipWaiting is false or unset) confirmation (confirmation)

Defined in

src/transaction.ts:190


sendGroupOfTransactions

sendGroupOfTransactions(groupSend, algod): Promise<Omit<SendAtomicTransactionComposerResults, "returns">>

Signs and sends a group of up to 16 transactions to the chain

Parameters

Name Type Description
groupSend TransactionGroupToSend The group details to send, with: * transactions: The array of transactions to send along with their signing account * sendParams: The parameters to dictate how the group is sent
algod default An algod client

Returns

Promise<Omit<SendAtomicTransactionComposerResults, "returns">>

An object with transaction IDs, transactions, group transaction ID (groupTransactionId) if more than 1 transaction sent, and (if skipWaiting is false or unset) confirmation (confirmation)

Defined in

src/transaction.ts:324


sendTransaction

sendTransaction(send, algod): Promise<SendTransactionResult>

Prepares a transaction for sending and then (if instructed) signs and sends the given transaction to the chain.

Parameters

Name Type Description
send Object The details for the transaction to prepare/send, including: * transaction: The unsigned transaction * from: The account to sign the transaction with: either an account with private key loaded or a logic signature account * config: The sending configuration for this transaction
send.from SendTransactionFrom -
send.sendParams? SendTransactionParams -
send.transaction Transaction -
algod default An algod client

Returns

Promise<SendTransactionResult>

An object with transaction (transaction) and (if skipWaiting is false or undefined) confirmation (confirmation)

Defined in

src/transaction.ts:146


signTransaction

signTransaction(transaction, signer): Promise<Uint8Array>

Signs a single transaction by the given signer.

Parameters

Name Type Description
transaction Transaction The transaction to sign
signer SendTransactionFrom The signer to sign

Returns

Promise<Uint8Array>

The signed transaction as a Uint8Array

Defined in

src/transaction.ts:126


stripTealComments

stripTealComments(tealCode): string

Remove comments from TEAL Code

Parameters

Name Type Description
tealCode string The TEAL logic to compile

Returns

string

The TEAL without comments

Defined in

src/app-deploy.ts:633


transactionFees

transactionFees(numberOfTransactions): AlgoAmount

Returns an amount of µAlgos to cover standard fees for the given number of transactions using AlgoAmount

Parameters

Name Type Description
numberOfTransactions number The of standard transaction fees to return the amount of ALGOs

Returns

AlgoAmount

Defined in

src/amount.ts:36


transactionSignerAccount

transactionSignerAccount(signer, sender): TransactionSignerAccount

Returns an account wrapper that supports a transaction signer with associated sender address.

Parameters

Name Type Description
signer TransactionSigner The transaction signer
sender string The address of sender account

Returns

TransactionSignerAccount

The SigningAccount wrapper

Defined in

src/account.ts:36


transferAlgos

transferAlgos(transfer, algod): Promise<SendTransactionResult>

Transfer ALGOs between two accounts.

Parameters

Name Type Description
transfer AlgoTransferParams The transfer definition
algod default An algod client

Returns

Promise<SendTransactionResult>

The transaction object and optionally the confirmation if it was sent to the chain (skipSending is false or unset)

Example

Usage example

await algokit.transferAlgos({ from, to, amount: algokit.algos(1) }, algod)

Defined in

src/transfer.ts:82


transferAsset

transferAsset(transfer, algod): Promise<SendTransactionResult>

Transfer asset between two accounts.

Parameters

Name Type Description
transfer TransferAssetParams The transfer definition
algod default An algod client

Returns

Promise<SendTransactionResult>

The transaction object and optionally the confirmation if it was sent to the chain (skipSending is false or unset)

Example

Usage example

await algokit.transferAsset({ from, to, assetId, amount }, algod)

Defined in

src/transfer.ts:165


updateApp

updateApp(update, algod): Promise<Partial<AppCompilationResult> & AppCallTransactionResult>

Updates a smart contract app.

Parameters

Name Type Description
update UpdateAppParams The parameters to update the app with
algod default An algod client

Returns

Promise<Partial<AppCompilationResult> & AppCallTransactionResult>

The transaction send result and the compilation result

Defined in

src/app.ts:188


waitForConfirmation

waitForConfirmation(transactionId, maxRoundsToWait, algod): Promise<PendingTransactionResponse>

Wait until the transaction is confirmed or rejected, or until timeout number of rounds have passed.

Parameters

Name Type Description
transactionId string The transaction ID to wait for
maxRoundsToWait number | bigint Maximum number of rounds to wait
algod default An algod client

Returns

Promise<PendingTransactionResponse>

Pending transaction information

Throws

Throws an error if the transaction is not confirmed or rejected in the next timeout rounds

Defined in

src/transaction.ts:369