@algorandfoundation/algokit-utils / index
- algos
- callApp
- capTransactionFee
- compileTeal
- controlFees
- createApp
- decodeAppState
- deployApp
- encodeTransactionNote
- ensureFunded
- executePaginatedRequest
- getABIMethodSignature
- getABIReturn
- getAccount
- getAccountAddressAsString
- getAccountAddressAsUint8Array
- getAccountConfigFromEnvironment
- getAlgoClient
- getAlgoIndexerClient
- getAlgoKmdClient
- getAlgoNodeConfig
- getAlgodConfigFromEnvironment
- getAppArgsForABICall
- getAppArgsForTransaction
- getAppBoxNames
- getAppBoxValue
- getAppBoxValueFromABIType
- getAppBoxValues
- getAppBoxValuesFromABIType
- getAppById
- getAppClient
- getAppClientByCreatorAndName
- getAppClientById
- getAppDeploymentTransactionNote
- getAppGlobalState
- getAppLocalState
- getAppOnCompleteAction
- getAtomicTransactionComposerTransactions
- getBoxReference
- getConfigFromEnvOrDefaults
- getCreatorAppsByName
- getDefaultLocalNetConfig
- getDispenserAccount
- getIndexerConfigFromEnvironment
- getKmdWalletAccount
- getLocalNetDispenserAccount
- getOrCreateKmdWalletAccount
- getSenderAddress
- getSenderTransactionSigner
- getTestNetDispenserApiClient
- getTransactionParams
- getTransactionWithSigner
- isLocalNet
- isMainNet
- isSchemaIsBroken
- isTestNet
- lookupAccountByAddress
- lookupAccountCreatedApplicationByAddress
- lookupTransactionById
- microAlgos
- mnemonicAccount
- mnemonicAccountFromEnvironment
- multisigAccount
- performAtomicTransactionComposerDryrun
- performAtomicTransactionComposerSimulate
- performTemplateSubstitution
- performTemplateSubstitutionAndCompile
- randomAccount
- rekeyedAccount
- replaceDeployTimeControlParams
- searchTransactions
- sendAtomicTransactionComposer
- sendGroupOfTransactions
- sendTransaction
- signTransaction
- stripTealComments
- transactionFees
- transactionSignerAccount
- transferAlgos
- transferAsset
- updateApp
- waitForConfirmation
• Const Config: UpdatableConfig
The AlgoKit config. To update it use the configure method.
▸ algos(algos): AlgoAmount
Returns an amount of Algos using AlgoAmount
| Name | Type | Description |
|---|---|---|
algos |
number |
The amount in Algos |
▸ callApp(call, algod): Promise<AppCallTransactionResult>
Issues a call to a given app.
| Name | Type | Description |
|---|---|---|
call |
AppCallParams |
The call details. |
algod |
default |
An algod client |
Promise<AppCallTransactionResult>
The result of the call
▸ 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.
| 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 |
void
▸ compileTeal(tealCode, algod): Promise<CompiledTeal>
Compiles the given TEAL using algod and returns the result, including source map.
| Name | Type | Description |
|---|---|---|
tealCode |
string |
The TEAL code |
algod |
default |
An algod client |
Promise<CompiledTeal>
The information about the compiled file
▸ controlFees<T>(transaction, feeControl): T
Allows for control of fees on a Transaction or SuggestedParams object
| Name | Type |
|---|---|
T |
extends SuggestedParams | Transaction |
| Name | Type | Description |
|---|---|---|
transaction |
T |
The transaction or suggested params |
feeControl |
Object |
The fee control parameters |
feeControl.fee? |
AlgoAmount |
- |
feeControl.maxFee? |
AlgoAmount |
- |
T
▸ createApp(create, algod): Promise<Partial<AppCompilationResult> & AppCallTransactionResult & AppReference>
Creates a smart contract app, returns the details of the created app.
| Name | Type | Description |
|---|---|---|
create |
CreateAppParams |
The parameters to create the app with |
algod |
default |
An algod client |
Promise<Partial<AppCompilationResult> & AppCallTransactionResult & AppReference>
The details of the created app, or the transaction to create it if skipSending and the compilation result
▸ 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.
| Name | Type | Description |
|---|---|---|
state |
{ key: string ; value: TealValue | EvalDelta }[] |
A global-state, local-state, global-state-deltas or local-state-deltas |
An object keyeed by the UTF-8 representation of the key with various parsings of the values
▸ 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.
| 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 |
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
▸ encodeTransactionNote(note?): Uint8Array | undefined
Encodes a transaction note into a byte array ready to be included in an Algorand transaction.
| Name | Type | Description |
|---|---|---|
note? |
TransactionNote |
The transaction note |
Uint8Array | undefined
the transaction note ready for inclusion in a transaction
Case on the value of data this either be:
null|undefined:undefinedstring: The string value- Uint8Array: passthrough
- Arc2TransactionNote object: ARC-0002 compatible transaction note
- Else: The object/value converted into a JSON string representation
▸ 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
| Name | Type |
|---|---|
T |
extends EnsureFundedParams |
| 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. |
Promise<EnsureFundedReturnType | undefined>
EnsureFundedReturnTypeif funds were transferred.undefinedif no funds were needed.
▸ executePaginatedRequest<TResult, TRequest>(extractItems, buildRequest): Promise<TResult[]>
| Name | Type |
|---|---|
TResult |
TResult |
TRequest |
extends Object |
| Name | Type |
|---|---|
extractItems |
(response: any) => TResult[] |
buildRequest |
(nextToken?: string) => TRequest |
Promise<TResult[]>
▸ getABIMethodSignature(method): string
Returns the encoded ABI spec for a given ABI Method
| Name | Type | Description |
|---|---|---|
method |
ABIMethodParams | ABIMethod |
The method to return a signature for |
string
The encoded ABI method spec e.g. method_name(uint64,string)string
▸ getABIReturn(args?, confirmation?): ABIReturn | undefined
Returns any ABI return values for the given app call arguments and transaction confirmation.
| Name | Type | Description |
|---|---|---|
args? |
AppCallArgs |
The arguments that were used for the call |
confirmation? |
PendingTransactionResponse |
The transaction confirmation from algod |
ABIReturn | undefined
The return value for the method call
▸ getAccount(account, algod, kmdClient?): Promise<Account | SigningAccount>
| 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 |
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.
- 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.
▸ getAccount(account, algod, kmdClient?): Promise<Account | SigningAccount>
| 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 |
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.
▸ 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
| Name | Type | Description |
|---|---|---|
addressEncodedInB64 |
string |
The base64 encoded version of the underlying byte array of the address public key |
string
▸ getAccountAddressAsUint8Array(account): Uint8Array
Returns an account's address as a byte array
| Name | Type | Description |
|---|---|---|
account |
string | SendTransactionFrom |
Either an account (with private key loaded) or the string address of an account |
Uint8Array
▸ getAccountConfigFromEnvironment(accountName): AccountConfig
| Name | Type | Description |
|---|---|---|
accountName |
string |
account name |
Deprecated
Use algokit.mnemonicAccountFromEnvironment, which doesn't need this function Returns the Account configuration from environment variables
Example
environment variables
{accountName}_MNEMONIC
{accountName}_SENDER▸ getAlgoClient(config?): Algodv2
Returns an algod SDK client that automatically retries on idempotent calls
| Name | Type | Description |
|---|---|---|
config? |
AlgoClientConfig |
The config if you want to override the default (getting config from process.env) |
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()▸ getAlgoIndexerClient(config?): Indexer
Returns an indexer SDK client that automatically retries on idempotent calls
| Name | Type | Description |
|---|---|---|
config? |
AlgoClientConfig |
The config if you want to override the default (getting config from process.env) |
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()▸ 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.
| Name | Type | Description |
|---|---|---|
config? |
AlgoClientConfig |
The config if you want to override the default (getting config from process.env) |
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'})▸ getAlgoNodeConfig(network, config): AlgoClientConfig
Returns the Algorand configuration to point to the AlgoNode service
| 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 |
▸ getAlgodConfigFromEnvironment(): AlgoClientConfig
Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment not algod-side)
▸ 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
| Name | Type | Description |
|---|---|---|
args |
ABIAppCallArgs |
The ABI app call args |
from |
SendTransactionFrom |
The transaction signer |
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
▸ 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
| Name | Type | Description |
|---|---|---|
args? |
RawAppCallArgs |
The app call args |
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
▸ getAppBoxNames(appId, algod): Promise<BoxName[]>
Returns the names of the boxes for the given app.
| Name | Type | Description |
|---|---|---|
appId |
number | bigint |
The ID of the app return box names for |
algod |
default |
An algod client instance |
Promise<BoxName[]>
The current box names
▸ getAppBoxValue(appId, boxName, algod): Promise<Uint8Array>
Returns the value of the given box name for the given app.
| 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 |
Promise<Uint8Array>
The current box value as a byte array
▸ getAppBoxValueFromABIType(request, algod): Promise<ABIValue>
Returns the value of the given box name for the given app decoded based on the given ABI type.
| Name | Type | Description |
|---|---|---|
request |
BoxValueRequestParams |
The parameters for the box value request |
algod |
default |
An algod client instance |
Promise<ABIValue>
The current box value as an ABI value
▸ getAppBoxValues(appId, boxNames, algod): Promise<Uint8Array[]>
Returns the value of the given box names for the given app.
| 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 |
Promise<Uint8Array[]>
The current box values as a byte array in the same order as the passed in box names
▸ getAppBoxValuesFromABIType(request, algod): Promise<ABIValue[]>
Returns the value of the given box names for the given app decoded based on the given ABI type.
| Name | Type | Description |
|---|---|---|
request |
BoxValuesRequestParams |
The parameters for the box value request |
algod |
default |
An algod client instance |
Promise<ABIValue[]>
The current box values as an ABI value in the same order as the passed in box names
▸ getAppById(appId, algod): Promise<Application>
Gets the current data for the given app from algod.
| Name | Type | Description |
|---|---|---|
appId |
number | bigint |
The id of the app |
algod |
default |
An algod client |
Promise<Application>
The data about the app
▸ getAppClient(appDetails, algod): ApplicationClient
Create a new ApplicationClient instance
| Name | Type | Description |
|---|---|---|
appDetails |
AppSpecAppDetails |
The details of the app |
algod |
default |
An algod instance |
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,
)▸ getAppClientByCreatorAndName(appDetails, algod): ApplicationClient
Create a new ApplicationClient instance by creator and name
| Name | Type | Description |
|---|---|---|
appDetails |
AppSpecAppDetailsByCreatorAndName |
The details of the app by creator and name |
algod |
default |
An algod instance |
The application client
Example
const client = algokit.getAppClientByCreatorAndName(
{
app: {appSpec},
sender: {account},
creatorAddress: {account.addr},
findExistingUsing: {indexerClient},
},
algodClient,
)▸ getAppClientById(appDetails, algod): ApplicationClient
Create a new ApplicationClient instance by id
| Name | Type | Description |
|---|---|---|
appDetails |
AppSpecAppDetailsById |
The details of the app |
algod |
default |
An algod instance |
The application client
Example
const client = algokit.getAppClientById(
{
app: {appSpec},
sender: {account},
id: {id},
},
algodClient,
)▸ getAppDeploymentTransactionNote(metadata): Arc2TransactionNote
Return the transaction note for an app deployment.
| Name | Type | Description |
|---|---|---|
metadata |
AppDeployMetadata |
The metadata of the deployment |
The transaction note as a utf-8 string
▸ getAppGlobalState(appId, algod): Promise<AppState>
Returns the current global state values for the given app ID
| Name | Type | Description |
|---|---|---|
appId |
number | bigint |
The ID of the app return global state for |
algod |
default |
An algod client instance |
Promise<AppState>
The current global state
▸ getAppLocalState(appId, account, algod): Promise<AppState>
Returns the current global state values for the given app ID and account
| 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 |
Promise<AppState>
The current local state for the given (app, account) combination
▸ 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.
| Name | Type | Description |
|---|---|---|
onCompletionAction? |
AppCallType | OnApplicationComplete |
The on completion action |
OnApplicationComplete
The algosdk.OnApplicationComplete
▸ getAtomicTransactionComposerTransactions(atc): TransactionWithSigner[]
Returns the array of transactions currently present in the given AtomicTransactionComposer
| Name | Type | Description |
|---|---|---|
atc |
AtomicTransactionComposer |
The atomic transaction composer |
TransactionWithSigner[]
The array of transactions with signers
▸ getBoxReference(box): algosdk.BoxReference
Returns a algosdk.BoxReference given a BoxIdentifier or BoxReference.
| Name | Type | Description |
|---|---|---|
box |
BoxReference | BoxIdentifier | BoxReference |
The box to return a reference for |
algosdk.BoxReference
The box reference ready to pass into a Transaction
▸ getConfigFromEnvOrDefaults(): AlgoConfig
Retrieve configurations from environment variables when defined or get defaults (expects to be called from a Node.js environment not algod-side)
▸ 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).
| 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 |
Promise<AppLookup>
A name-based lookup of the app information (id, address)
▸ getDefaultLocalNetConfig(configOrPort): AlgoClientConfig
Returns the Algorand configuration to point to the default LocalNet
| Name | Type | Description |
|---|---|---|
configOrPort |
number | "algod" | "indexer" | "kmd" |
Which algod config to return - algod, kmd, or indexer OR a port number |
▸ 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
| 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 |
Promise<default | SigningAccount>
▸ getIndexerConfigFromEnvironment(): AlgoClientConfig
Retrieve the indexer configuration from environment variables (expects to be called from a Node.js environment not algod-side)
▸ getKmdWalletAccount(walletAccount, algod, kmdClient?): Promise<Account | undefined>
Returns an Algorand account with private key loaded from the given KMD wallet (identified by name).
| 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 |
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
)▸ 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)
| 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 |
Promise<Account>
▸ 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!
| 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 |
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
▸ getSenderAddress(sender): string
Returns the public address of the given transaction sender.
| Name | Type | Description |
|---|---|---|
sender |
SendTransactionFrom |
A transaction sender |
string
The public address
▸ 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.
| Name | Type |
|---|---|
val |
SendTransactionFrom |
TransactionSigner
A transaction signer
▸ getTestNetDispenserApiClient(params?): TestNetDispenserApiClient
Create a new TestNetDispenserApiClient instance. Refer to docs on guidance to obtain an access token.
| 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. |
An instance of the TestNetDispenserApiClient class.
Example
const client = algokit.getTestNetDispenserApiClient(
{
authToken: 'your_auth_token',
requestTimeout: 15,
}
)▸ 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.
| Name | Type | Description |
|---|---|---|
params |
undefined | SuggestedParams |
Optionally provide parameters to use |
algod |
default |
Algod algod |
Promise<SuggestedParamsWithMinFee | { fee: number ; firstRound: number ; flatFee?: boolean ; genesisHash: string ; genesisID: string ; lastRound: number }>
The suggested transaction parameters
▸ 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.
| 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. |
Promise<TransactionWithSigner>
A TransactionWithSigner object.
▸ isLocalNet(algod): Promise<boolean>
Returns true if the algod client is pointing to a LocalNet Algorand network
| Name | Type |
|---|---|
algod |
default |
Promise<boolean>
▸ isMainNet(algod): Promise<boolean>
| Name | Type |
|---|---|
algod |
default |
Promise<boolean>
▸ 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 :(
| Name | Type | Description |
|---|---|---|
before |
ApplicationStateSchema |
The existing schema |
after |
ApplicationStateSchema |
The new schema |
boolean
Whether or not there is a breaking change
▸ isTestNet(algod): Promise<boolean>
| Name | Type |
|---|---|
algod |
default |
Promise<boolean>
▸ lookupAccountByAddress(accountAddress, indexer): Promise<AccountLookupResult>
Looks up an account by address using Indexer.
| Name | Type | Description |
|---|---|---|
accountAddress |
string |
- |
indexer |
default |
An indexer client |
Promise<AccountLookupResult>
The result of the look-up
▸ lookupAccountCreatedApplicationByAddress(indexer, address, getAll?, paginationLimit?): Promise<ApplicationResult[]>
Looks up applications that were created by the given address.
| 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 |
Promise<ApplicationResult[]>
The list of application results
▸ lookupTransactionById(transactionId, indexer): Promise<TransactionLookupResult>
Looks up a transaction by ID using Indexer.
| Name | Type | Description |
|---|---|---|
transactionId |
string |
The ID of the transaction to look up |
indexer |
default |
An indexer client |
Promise<TransactionLookupResult>
The result of the look-up
▸ microAlgos(microAlgos): AlgoAmount
Returns an amount of µAlgos using AlgoAmount
| Name | Type | Description |
|---|---|---|
microAlgos |
number |
The amount in µAlgos |
▸ 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.
| 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. |
Account
▸ 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.
- 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).
| 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 |
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.
▸ multisigAccount(multisigParams, signingAccounts): MultisigAccount
Returns an account wrapper that supports partial or full multisig signing.
| Name | Type | Description |
|---|---|---|
multisigParams |
MultisigMetadata |
The parameters that define the multisig account |
signingAccounts |
(default | SigningAccount)[] |
The signers that are currently present |
A multisig account wrapper
▸ 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
| Name | Type | Description |
|---|---|---|
atc |
AtomicTransactionComposer |
- |
algod |
default |
An Algod client |
Promise<DryrunResult>
The dryrun result
▸ performAtomicTransactionComposerSimulate(atc, algod): Promise<SimulateResponse>
Performs a simulation of the transactions loaded into the given AtomicTransactionComposer.
| Name | Type | Description |
|---|---|---|
atc |
AtomicTransactionComposer |
The AtomicTransactionComposer with transaction(s) loaded. |
algod |
default |
An Algod client to perform the simulation. |
Promise<SimulateResponse>
The simulation result, which includes various details about how the transactions would be processed.
▸ performTemplateSubstitution(tealCode, templateParams?): string
Performs template substitution of a teal file.
Looks for TMPL_{parameter} for template replacements.
| Name | Type | Description |
|---|---|---|
tealCode |
string |
The TEAL logic to compile |
templateParams? |
TealTemplateParams |
Any parameters to replace in the .teal file before compiling |
string
The TEAL code with replacements
▸ 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.
| 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 |
Promise<CompiledTeal>
The information about the compiled code
▸ 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.
Account
▸ rekeyedAccount(signer, sender): SigningAccount
Returns an account wrapper that supports a rekeyed account.
| 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 |
The SigningAccount wrapper
▸ replaceDeployTimeControlParams(tealCode, params): string
Replaces deploy-time deployment control parameters within the given teal code.
TMPL_UPDATABLEfor updatability / immutability controlTMPL_DELETABLEfor 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.
| 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 |
- |
string
The replaced TEAL code
▸ searchTransactions(indexer, searchCriteria, paginationLimit?): Promise<TransactionSearchResults>
Allows transactions to be searched for the given criteria.
| 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 |
Promise<TransactionSearchResults>
The search results
▸ sendAtomicTransactionComposer(atcSend, algod): Promise<SendAtomicTransactionComposerResults>
Signs and sends transactions that have been collected by an AtomicTransactionComposer.
| 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 |
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)
▸ sendGroupOfTransactions(groupSend, algod): Promise<Omit<SendAtomicTransactionComposerResults, "returns">>
Signs and sends a group of up to 16 transactions to the chain
| 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 |
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)
▸ sendTransaction(send, algod): Promise<SendTransactionResult>
Prepares a transaction for sending and then (if instructed) signs and sends the given transaction to the chain.
| 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 |
Promise<SendTransactionResult>
An object with transaction (transaction) and (if skipWaiting is false or undefined) confirmation (confirmation)
▸ signTransaction(transaction, signer): Promise<Uint8Array>
Signs a single transaction by the given signer.
| Name | Type | Description |
|---|---|---|
transaction |
Transaction |
The transaction to sign |
signer |
SendTransactionFrom |
The signer to sign |
Promise<Uint8Array>
The signed transaction as a Uint8Array
▸ stripTealComments(tealCode): string
Remove comments from TEAL Code
| Name | Type | Description |
|---|---|---|
tealCode |
string |
The TEAL logic to compile |
string
The TEAL without comments
▸ transactionFees(numberOfTransactions): AlgoAmount
Returns an amount of µAlgos to cover standard fees for the given number of transactions using AlgoAmount
| Name | Type | Description |
|---|---|---|
numberOfTransactions |
number |
The of standard transaction fees to return the amount of ALGOs |
▸ transactionSignerAccount(signer, sender): TransactionSignerAccount
Returns an account wrapper that supports a transaction signer with associated sender address.
| Name | Type | Description |
|---|---|---|
signer |
TransactionSigner |
The transaction signer |
sender |
string |
The address of sender account |
The SigningAccount wrapper
▸ transferAlgos(transfer, algod): Promise<SendTransactionResult>
Transfer ALGOs between two accounts.
| Name | Type | Description |
|---|---|---|
transfer |
AlgoTransferParams |
The transfer definition |
algod |
default |
An algod client |
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)▸ transferAsset(transfer, algod): Promise<SendTransactionResult>
Transfer asset between two accounts.
| Name | Type | Description |
|---|---|---|
transfer |
TransferAssetParams |
The transfer definition |
algod |
default |
An algod client |
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)▸ updateApp(update, algod): Promise<Partial<AppCompilationResult> & AppCallTransactionResult>
Updates a smart contract app.
| Name | Type | Description |
|---|---|---|
update |
UpdateAppParams |
The parameters to update the app with |
algod |
default |
An algod client |
Promise<Partial<AppCompilationResult> & AppCallTransactionResult>
The transaction send result and the compilation result
▸ waitForConfirmation(transactionId, maxRoundsToWait, algod): Promise<PendingTransactionResponse>
Wait until the transaction is confirmed or rejected, or until timeout
number of rounds have passed.
| 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 |
Promise<PendingTransactionResponse>
Pending transaction information
Throws
Throws an error if the transaction is not confirmed or rejected in the next timeout rounds