`algokit_utils`

Package Contents

Classes

`ABICallArgs`	ABI Parameters used to update or delete an application when calling `deploy()`
`ABICallArgsDict`	ABI Parameters used to update or delete an application when calling `deploy()`
`ABICreateCallArgs`	ABI Parameters used to create an application when calling `deploy()`
`ABICreateCallArgsDict`	ABI Parameters used to create an application when calling `deploy()`
`ABITransactionResponse`	Response for an ABI call
`Account`	Holds the private_key and address for an account
`AlgoClientConfig`	Connection details for connecting to an `algosdk.v2client.algod.AlgodClient` or `algosdk.v2client.indexer.IndexerClient`
`AppDeployMetaData`	Metadata about an application stored in a transaction note during creation.
`AppLookup`	Cache of `AppMetaData` for a specific `creator`
`AppMetaData`	Metadata about a deployed app
`AppReference`	Information about an Algorand app
`ApplicationClient`	A class that wraps an ARC-0032 app spec and provides high productivity methods to deploy and call the app
`ApplicationSpecification`	ARC-0032 application specification
`CallConfig`	Describes the type of calls a method can be used for based on `algosdk.transaction.OnComplete` type
`CreateCallParameters`	Additional parameters that can be included in a transaction when using the ApplicationClient.create/compose_create methods
`CreateCallParametersDict`	Additional parameters that can be included in a transaction when using the ApplicationClient.create/compose_create methods
`CreateTransactionParameters`	Additional parameters that can be included in a transaction when calling a create method
`DefaultArgumentDict`	DefaultArgument is a container for any arguments that may be resolved prior to calling some target method
`DeployCallArgs`	Parameters used to update or delete an application when calling `deploy()`
`DeployCallArgsDict`	Parameters used to update or delete an application when calling `deploy()`
`DeployCreateCallArgs`	Parameters used to create an application when calling `deploy()`
`DeployCreateCallArgsDict`	Parameters used to create an application when calling `deploy()`
`DeployResponse`	Describes the action taken during deployment, related transactions and the `AppMetaData`
`EnsureBalanceParameters`	Parameters for ensuring an account has a minimum number of µALGOs
`EnsureFundedResponse`	Response for ensuring an account has a minimum number of µALGOs
`MethodHints`	MethodHints provides hints to the caller about how to call the method
`OnCompleteCallParameters`	Additional parameters that can be included in a transaction when using the ApplicationClient.call/compose_call methods
`OnCompleteCallParametersDict`	Additional parameters that can be included in a transaction when using the ApplicationClient.call/compose_call methods
`OnSchemaBreak`	Action to take if an Application’s schema has breaking changes
`OnUpdate`	Action to take if an Application has been updated
`OperationPerformed`	Describes the actions taken during deployment
`Program`	A compiled TEAL program
`TestNetDispenserApiClient`	Client for interacting with the AlgoKit TestNet Dispenser API. To get started create a new access token via `algokit dispenser login --ci` and pass it to the client constructor as `auth_token`. Alternatively set the access token as environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN`, and it will be auto loaded. If both are set, the constructor argument takes precedence.
`TransactionParameters`	Additional parameters that can be included in a transaction
`TransactionParametersDict`	Additional parameters that can be included in a transaction
`TransactionResponse`	Response for a non ABI call
`TransferAssetParameters`	Parameters for transferring assets between accounts
`TransferParameters`	Parameters for transferring µALGOs between accounts

Functions

`create_kmd_wallet_account`	Creates a wallet with specified name
`ensure_funded`	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) see https://developer.algorand.org/docs/get-details/accounts/#minimum-balance
`execute_atc_with_logic_error`	Calls `AtomicTransactionComposer.execute()` on provided `atc`, but will parse any errors and raise a `LogicError` if possible
`get_account`	Returns an Algorand account with private key loaded by convention based on the given name identifier.
`get_account_from_mnemonic`	Convert a mnemonic (25 word passphrase) into an Account
`get_algod_client`	Returns an `algosdk.v2client.algod.AlgodClient` from `config` or environment
`get_app_id_from_tx_id`	Finds the app_id for provided transaction id
`get_creator_apps`	Returns a mapping of Application names to `AppMetaData` for all Applications created by specified creator that have a transaction note containing `AppDeployMetaData`
`get_default_localnet_config`	Returns the client configuration to point to the default LocalNet
`get_dispenser_account`	Returns an Account based on DISPENSER_MNENOMIC environment variable or the default account on LocalNet
`get_indexer_client`	Returns an `algosdk.v2client.indexer.IndexerClient` from `config` or environment.
`get_kmd_client_from_algod_client`	Returns an `algosdk.kmd.KMDClient` from supplied `client`
`get_kmd_wallet_account`	Returns wallet matching specified name and predicate or None if not found
`get_localnet_default_account`	Returns the default Account in a LocalNet instance
`get_next_version`	Calculates the next version from `current_version`
`get_or_create_kmd_wallet_account`	Returns a wallet with specified name, or creates one if not found
`get_sender_from_signer`	Returns the associated address of a signer, return None if no address found
`is_localnet`	Returns True if client genesis is `devnet-v1` or `sandnet-v1`
`is_mainnet`	Returns True if client genesis is `mainnet-v1`
`is_testnet`	Returns True if client genesis is `testnet-v1`
`num_extra_program_pages`	Calculate minimum number of extra_pages required for provided approval and clear programs
`opt_in`	Opt-in to a list of assets on the Algorand blockchain. Before an account can receive a specific asset, it must `opt-in` to receive it. An opt-in transaction places an asset holding of 0 into the account and increases its minimum balance by 100,000 microAlgos.
`opt_out`	Opt out from a list of Algorand Standard Assets (ASAs) by transferring them back to their creators. The account also recovers the Minimum Balance Requirement for the asset (100,000 microAlgos) The `optOut` function manages the opt-out process, permitting the account to discontinue holding a group of assets.
`persist_sourcemaps`	Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts. Args: sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects. project_root (Path): The root directory of the project. client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain. with_sources (bool): If True, it will dump teal source files along with sourcemaps. Default is True, as needed by an AlgoKit AVM debugger.
`replace_template_variables`	Replaces `TMPL_*` variables in `program` with `template_values`
`simulate_and_persist_response`	Simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object, and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.
`transfer`	Transfer µALGOs between accounts
`transfer_asset`	Transfer assets between accounts

Data

`AppSpecStateDict`	Type defining Application Specification state entries
`DELETABLE_TEMPLATE_NAME`	Template variable name used to control if a smart contract is deletable or not at deployment
`DefaultArgumentType`	Literal values describing the types of default argument sources
`MethodConfigDict`	Dictionary of `dict[OnCompletionActionName, CallConfig]` representing allowed actions for each on completion type
`NOTE_PREFIX`	ARC-0002 compliant note prefix for algokit_utils deployed applications
`OnCompleteActionName`	String literals representing on completion transaction types
`TemplateValueDict`	Dictionary of `dict[str, int \| str \| bytes]` representing template variable names and values
`TemplateValueMapping`	Mapping of `str` to `int \| str \| bytes` representing template variable names and values
`UPDATABLE_TEMPLATE_NAME`	Template variable name used to control if a smart contract is updatable or not at deployment

API

class algokit_utils.ABICallArgs

Bases: algokit_utils.deploy.DeployCallArgs, algokit_utils.deploy.ABICall

ABI Parameters used to update or delete an application when calling deploy()

class algokit_utils.ABICallArgsDict

Bases: algokit_utils.deploy.DeployCallArgsDict, typing.TypedDict

ABI Parameters used to update or delete an application when calling deploy()

Initialization

Initialize self. See help(type(self)) for accurate signature.

class algokit_utils.ABICreateCallArgs

Bases: algokit_utils.deploy.DeployCreateCallArgs, algokit_utils.deploy.ABICall

ABI Parameters used to create an application when calling deploy()

class algokit_utils.ABICreateCallArgsDict

Bases: algokit_utils.deploy.DeployCreateCallArgsDict, typing.TypedDict

ABI Parameters used to create an application when calling deploy()

Initialization

Initialize self. See help(type(self)) for accurate signature.

class algokit_utils.ABITransactionResponse

Bases: algokit_utils.models.TransactionResponse, typing.Generic[algokit_utils.models.ReturnType]

Response for an ABI call

decode_error: Exception | None

None

Details of error that occurred when attempting to decode raw_value

method: algosdk.abi.Method

None

ABI method used to make call

raw_value: bytes

None

The raw response before ABI decoding

return_value: algokit_utils.models.ReturnType

None

Decoded ABI result

tx_info: dict

None

Details of transaction

class algokit_utils.Account

Holds the private_key and address for an account

address: str

‘field(…)’

Address for this account

private_key: str

None

Base64 encoded private key

property public_key: bytes: The public key for this account

property signer: algosdk.atomic_transaction_composer.AccountTransactionSigner: An AccountTransactionSigner for this account

class algokit_utils.AlgoClientConfig

Connection details for connecting to an algosdk.v2client.algod.AlgodClient or algosdk.v2client.indexer.IndexerClient

server: str

None

URL for the service e.g. http://localhost:4001 or https://testnet-api.algonode.cloud

token: str

None

API Token to authenticate with the service

class algokit_utils.AppDeployMetaData

Metadata about an application stored in a transaction note during creation.

The note is serialized as JSON and prefixed with NOTE_PREFIX and stored in the transaction note field as part of ApplicationClient.deploy()

class algokit_utils.AppLookup

Cache of AppMetaData for a specific creator

Can be used as an argument to ApplicationClient to reduce the number of calls when deploying multiple apps or discovering multiple app_ids

class algokit_utils.AppMetaData

Bases: algokit_utils.deploy.AppReference, algokit_utils.deploy.AppDeployMetaData

Metadata about a deployed app

class algokit_utils.AppReference: Information about an Algorand app

algokit_utils.AppSpecStateDict: TypeAlias

None

Type defining Application Specification state entries

class algokit_utils.ApplicationClient(algod_client: algosdk.v2client.algod.AlgodClient, app_spec: algokit_utils.application_specification.ApplicationSpecification | pathlib.Path, *, app_id: int = 0, creator: str | algokit_utils.models.Account | None = None, indexer_client: IndexerClient | None = None, existing_deployments: algokit_utils.deploy.AppLookup | None = None, signer: algosdk.atomic_transaction_composer.TransactionSigner | algokit_utils.models.Account | None = None, sender: str | None = None, suggested_params: algosdk.transaction.SuggestedParams | None = None, template_values: algokit_utils.deploy.TemplateValueMapping | None = None, app_name: str | None = None)

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

Initialization

ApplicationClient can be created with an app_id to interact with an existing application, alternatively it can be created with a creator and indexer_client specified to find existing applications by name and creator.

Parameters:

algod_client (AlgodClient) – AlgoSDK algod client
app_spec (ApplicationSpecification | Path) – An Application Specification or the path to one
app_id (int) – The app_id of an existing application, to instead find the application by creator and name use the creator and indexer_client parameters
creator (str | Account) – The address or Account of the app creator to resolve the app_id
indexer_client (IndexerClient) – AlgoSDK indexer client, only required if deploying or finding app_id by creator and app name
existing_deployments (AppLookup) –
signer (TransactionSigner | Account) – Account or signer to use to sign transactions, if not specified and creator was passed as an Account will use that.
sender (str) – Address to use as the sender for all transactions, will use the address associated with the signer if not specified.
template_values (TemplateValueMapping) – Values to use for TMPL_* template variables, dictionary keys should NOT include the TMPL_ prefix
app_name (str | None) – Name of application to use when deploying, defaults to name defined on the Application Specification

add_method_call(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, abi_method: algokit_utils.models.ABIMethod | bool | None = None, *, abi_args: algokit_utils.models.ABIArgsDict | None = None, app_id: int | None = None, parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, on_complete: algosdk.transaction.OnComplete = transaction.OnComplete.NoOpOC, local_schema: algosdk.transaction.StateSchema | None = None, global_schema: algosdk.transaction.StateSchema | None = None, approval_program: bytes | None = None, clear_program: bytes | None = None, extra_pages: int | None = None, app_args: list[bytes] | None = None, call_config: algokit_utils.application_specification.CallConfig = au_spec.CallConfig.CALL) → None: Adds a transaction to the AtomicTransactionComposer passed

call(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.OnCompleteCallParameters | algokit_utils.models.OnCompleteCallParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with specified parameters

clear_state(transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, app_args: list[bytes] | None = None) → algokit_utils.models.TransactionResponse: Submits a signed transaction with on_complete=ClearState

close_out(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with on_complete=CloseOut

compose_call(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.OnCompleteCallParameters | algokit_utils.models.OnCompleteCallParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with specified parameters to atc

compose_clear_state(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, app_args: list[bytes] | None = None) → None: Adds a signed transaction with on_complete=ClearState to atc

compose_close_out(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with on_complete=CloseOut to ac

compose_create(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.CreateCallParameters | algokit_utils.models.CreateCallParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with application id == 0 and the schema and source of client’s app_spec to atc

compose_delete(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with on_complete=DeleteApplication to atc

compose_opt_in(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with on_complete=OptIn to atc

compose_update(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, /, call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → None: Adds a signed transaction with on_complete=UpdateApplication to atc

create(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.CreateCallParameters | algokit_utils.models.CreateCallParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with application id == 0 and the schema and source of client’s app_spec

delete(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with on_complete=DeleteApplication

Deploy an application and update client to reference it.

Idempotently deploy (create, update/delete if changed) an app against the given name via the given creator account, including deploy-time template placeholder substitutions. To understand the architecture decisions behind this functionality please see https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md

Note

If there is a breaking state schema change to an existing app (and on_schema_break is set to ‘ReplaceApp’ the existing app will be deleted and re-created.

Note

If there is an update (different TEAL code) to an existing app (and on_update is set to ‘ReplaceApp’) the existing app will be deleted and re-created.

Parameters:

version (str) – version to use when creating or updating app, if None version will be auto incremented
signer (algosdk.atomic_transaction_composer.TransactionSigner) – signer to use when deploying app , if None uses self.signer
sender (str) – sender address to use when deploying app, if None uses self.sender
allow_delete (bool) – Used to set the TMPL_DELETABLE template variable to conditionally control if an app can be deleted
allow_update (bool) – Used to set the TMPL_UPDATABLE template variable to conditionally control if an app can be updated
on_update (OnUpdate) – Determines what action to take if an application update is required
on_schema_break (OnSchemaBreak) – Determines what action to take if an application schema requirements has increased beyond the current allocation
template_values (dict[str, int|str|bytes]) – Values to use for TMPL_* template variables, dictionary keys should NOT include the TMPL_ prefix
create_args (ABICreateCallArgs) – Arguments used when creating an application
update_args (ABICallArgs | ABICallArgsDict) – Arguments used when updating an application
delete_args (ABICallArgs | ABICallArgsDict) – Arguments used when deleting an application

Return DeployResponse:

details action taken and relevant transactions

Raises:

DeploymentError – If the deployment failed

export_source_map() → str | None: Export approval source map to JSON, can be later re-imported with import_source_map

get_global_state(*, raw: bool = False) → dict[bytes | str, bytes | str | int]: Gets the global state info associated with app_id

get_local_state(account: str | None = None, *, raw: bool = False) → dict[bytes | str, bytes | str | int]: Gets the local state info for associated app_id and account/sender

get_signer_sender(signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, sender: str | None = None) → tuple[algosdk.atomic_transaction_composer.TransactionSigner | None, str | None]

Return signer and sender, using default values on client if not specified

Will use provided values if given, otherwise will fall back to values defined on client. If no sender is specified then will attempt to obtain sender from signer

import_source_map(source_map_json: str) → None: Import approval source from JSON exported by export_source_map

opt_in(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with on_complete=OptIn

prepare(signer: algosdk.atomic_transaction_composer.TransactionSigner | algokit_utils.models.Account | None = None, sender: str | None = None, app_id: int | None = None, template_values: algokit_utils.deploy.TemplateValueDict | None = None) → algokit_utils.application_client.ApplicationClient: Creates a copy of this ApplicationClient, using the new signer, sender and app_id values if provided. Will also substitute provided template_values into the associated app_spec in the copy

resolve(to_resolve: algokit_utils.application_specification.DefaultArgumentDict) → int | str | bytes: Resolves the default value for an ABI method, based on app_spec

resolve_signer_sender(signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, sender: str | None = None) → tuple[algosdk.atomic_transaction_composer.TransactionSigner, str]

Return signer and sender, using default values on client if not specified

Will use provided values if given, otherwise will fall back to values defined on client. If no sender is specified then will attempt to obtain sender from signer

Raises:: ValueError – Raised if a signer or sender is not provided. See get_signer_sender for variant with no exception

update(call_abi_method: algokit_utils.models.ABIMethod | bool | None = None, transaction_parameters: algokit_utils.models.TransactionParameters | algokit_utils.models.TransactionParametersDict | None = None, **abi_kwargs: algokit_utils.models.ABIArgType) → algokit_utils.models.TransactionResponse | algokit_utils.models.ABITransactionResponse: Submits a signed transaction with on_complete=UpdateApplication

class algokit_utils.ApplicationSpecification

ARC-0032 application specification

See https://github.com/algorandfoundation/ARCs/pull/150

export(directory: pathlib.Path | str | None = None) → None

write out the artifacts generated by the application to disk

Args: directory(optional): path to the directory where the artifacts should be written

class algokit_utils.CallConfig

Bases: enum.IntFlag

Describes the type of calls a method can be used for based on algosdk.transaction.OnComplete type

Initialization

Initialize self. See help(type(self)) for accurate signature.

ALL

3

Handle the specified on completion type for both create and normal application calls

CALL

1

Only handle the specified on completion type for application calls

CREATE

2

Only handle the specified on completion type for application create calls

NEVER

0

Never handle the specified on completion type

class algokit_utils.CreateCallParameters

Additional parameters that can be included in a transaction when using the ApplicationClient.create/compose_create methods

accounts: list[str] | None

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]] | None

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int] | None

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int] | None

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str | None

None

Lease value for this transaction

note: bytes | str | None

None

Note for this transaction

rekey_to: str | None

None

Address to rekey to

sender: str | None

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner | None

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams | None

None

SuggestedParams to use for this transaction

class algokit_utils.CreateCallParametersDict

Bases: typing.TypedDict

Additional parameters that can be included in a transaction when using the ApplicationClient.create/compose_create methods

Initialization

Initialize self. See help(type(self)) for accurate signature.

accounts: list[str]

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]]

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int]

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int]

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str

None

Lease value for this transaction

note: bytes | str

None

Note for this transaction

rekey_to: str

None

Address to rekey to

sender: str

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams

None

SuggestedParams to use for this transaction

class algokit_utils.CreateTransactionParameters

Additional parameters that can be included in a transaction when calling a create method

accounts: list[str] | None

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]] | None

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int] | None

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int] | None

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str | None

None

Lease value for this transaction

note: bytes | str | None

None

Note for this transaction

rekey_to: str | None

None

Address to rekey to

sender: str | None

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner | None

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams | None

None

SuggestedParams to use for this transaction

algokit_utils.DELETABLE_TEMPLATE_NAME

None

Template variable name used to control if a smart contract is deletable or not at deployment

class algokit_utils.DefaultArgumentDict

Bases: typing.TypedDict

DefaultArgument is a container for any arguments that may be resolved prior to calling some target method

Initialization

Initialize self. See help(type(self)) for accurate signature.

algokit_utils.DefaultArgumentType: TypeAlias

None

Literal values describing the types of default argument sources

class algokit_utils.DeployCallArgs: Parameters used to update or delete an application when calling deploy()

class algokit_utils.DeployCallArgsDict

Bases: typing.TypedDict

Parameters used to update or delete an application when calling deploy()

Initialization

Initialize self. See help(type(self)) for accurate signature.

class algokit_utils.DeployCreateCallArgs

Bases: algokit_utils.deploy.DeployCallArgs

Parameters used to create an application when calling deploy()

class algokit_utils.DeployCreateCallArgsDict

Bases: algokit_utils.deploy.DeployCallArgsDict, typing.TypedDict

Parameters used to create an application when calling deploy()

Initialization

Initialize self. See help(type(self)) for accurate signature.

class algokit_utils.DeployResponse: Describes the action taken during deployment, related transactions and the AppMetaData

exception algokit_utils.DeploymentFailedError: Bases: Exception

class algokit_utils.EnsureBalanceParameters

Parameters for ensuring an account has a minimum number of µALGOs

account_to_fund: algokit_utils.models.Account | algosdk.atomic_transaction_composer.AccountTransactionSigner | str

None

The account address that will receive the µALGOs

fee_micro_algos: int | None

None

(optional) The flat fee you want to pay, useful for covering extra fees in a transaction group or app call

funding_source: algokit_utils.models.Account | algosdk.atomic_transaction_composer.AccountTransactionSigner | algokit_utils.dispenser_api.TestNetDispenserApiClient | None

None

The account (with private key) or signer that will send the µALGOs, will use get_dispenser_account by default. Alternatively you can pass an instance of TestNetDispenserApiClient which will allow you to interact with AlgoKit TestNet Dispenser API.

max_fee_micro_algos: int | None

None

(optional)The maximum fee that you are happy to pay (default: unbounded) - if this is set it’s possible the transaction could get rejected during network congestion

min_funding_increment_micro_algos: int

0

When issuing a funding amount, the minimum amount to transfer (avoids many small transfers if this gets called often on an active account)

min_spending_balance_micro_algos: int

None

The minimum balance of ALGOs that the account should have available to spend (i.e. on top of minimum balance requirement)

note: str | bytes | None

None

The (optional) transaction note, default: “Funding account to meet minimum requirement

suggested_params: algosdk.transaction.SuggestedParams | None

None

(optional) transaction parameters

class algokit_utils.EnsureFundedResponse

Response for ensuring an account has a minimum number of µALGOs

transaction_id: str

None

The amount of µALGOs that were funded

exception algokit_utils.LogicError(*, logic_error_str: str, program: str, source_map: AlgoSourceMap | None, transaction_id: str, message: str, pc: int, logic_error: Exception | None = None, traces: list | None = None): Bases: Exception

algokit_utils.MethodConfigDict: TypeAlias

None

Dictionary of dict[OnCompletionActionName, CallConfig] representing allowed actions for each on completion type

class algokit_utils.MethodHints: MethodHints provides hints to the caller about how to call the method

algokit_utils.NOTE_PREFIX

‘ALGOKIT_DEPLOYER:j’

ARC-0002 compliant note prefix for algokit_utils deployed applications

algokit_utils.OnCompleteActionName: TypeAlias

None

String literals representing on completion transaction types

class algokit_utils.OnCompleteCallParameters

Additional parameters that can be included in a transaction when using the ApplicationClient.call/compose_call methods

accounts: list[str] | None

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]] | None

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int] | None

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int] | None

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str | None

None

Lease value for this transaction

note: bytes | str | None

None

Note for this transaction

rekey_to: str | None

None

Address to rekey to

sender: str | None

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner | None

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams | None

None

SuggestedParams to use for this transaction

class algokit_utils.OnCompleteCallParametersDict

Bases: typing.TypedDict

Additional parameters that can be included in a transaction when using the ApplicationClient.call/compose_call methods

Initialization

Initialize self. See help(type(self)) for accurate signature.

accounts: list[str]

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]]

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int]

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int]

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str

None

Lease value for this transaction

note: bytes | str

None

Note for this transaction

rekey_to: str

None

Address to rekey to

sender: str

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams

None

SuggestedParams to use for this transaction

class algokit_utils.OnSchemaBreak(*args, **kwds)

Bases: enum.Enum

Action to take if an Application’s schema has breaking changes

Initialization

AppendApp

3

Create a new Application

Fail

0

Fail the deployment

ReplaceApp

2

Create a new Application and delete the old Application in a single transaction

class algokit_utils.OnUpdate(*args, **kwds)

Bases: enum.Enum

Action to take if an Application has been updated

Initialization

AppendApp

3

Create a new application

Fail

0

Fail the deployment

ReplaceApp

2

Create a new Application and delete the old Application in a single transaction

UpdateApp

1

Update the Application with the new approval and clear programs

class algokit_utils.OperationPerformed(*args, **kwds)

Bases: enum.Enum

Describes the actions taken during deployment

Initialization

Create

1

No existing Application was found, created a new Application

Nothing

0

An existing Application was found

Replace

3

An existing Application was found, but was out of date, created a new Application and deleted the original

Update

2

An existing Application was found, but was out of date, updated to latest version

class algokit_utils.Program(program: str, client: algosdk.v2client.algod.AlgodClient)

A compiled TEAL program

Initialization

Fully compile the program source to binary and generate a source map for matching pc to line number

algokit_utils.TemplateValueDict: TypeAlias

None

Dictionary of dict[str, int | str | bytes] representing template variable names and values

algokit_utils.TemplateValueMapping: TypeAlias

None

Mapping of str to int | str | bytes representing template variable names and values

class algokit_utils.TestNetDispenserApiClient(auth_token: str | None = None, request_timeout: int = DISPENSER_REQUEST_TIMEOUT)

Client for interacting with the AlgoKit TestNet Dispenser API. To get started create a new access token via algokit dispenser login --ci and pass it to the client constructor as auth_token. Alternatively set the access token as environment variable ALGOKIT_DISPENSER_ACCESS_TOKEN, and it will be auto loaded. If both are set, the constructor argument takes precedence.

Default request timeout is 15 seconds. Modify by passing request_timeout to the constructor.

Initialization

fund(address: str, amount: int, asset_id: int) → algokit_utils.dispenser_api.DispenserFundResponse: Fund an account with Algos from the dispenser API

get_limit(address: str) → algokit_utils.dispenser_api.DispenserLimitResponse: Get current limit for an account with Algos from the dispenser API

refund(refund_txn_id: str) → None: Register a refund for a transaction with the dispenser API

class algokit_utils.TransactionParameters

Additional parameters that can be included in a transaction

accounts: list[str] | None

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]] | None

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int] | None

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int] | None

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str | None

None

Lease value for this transaction

note: bytes | str | None

None

Note for this transaction

rekey_to: str | None

None

Address to rekey to

sender: str | None

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner | None

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams | None

None

SuggestedParams to use for this transaction

class algokit_utils.TransactionParametersDict

Bases: typing.TypedDict

Additional parameters that can be included in a transaction

Initialization

Initialize self. See help(type(self)) for accurate signature.

accounts: list[str]

None

Accounts to include in transaction

boxes: collections.abc.Sequence[tuple[int, bytes | bytearray | str | int]]

None

Box references to include in transaction. A sequence of (app id, box key) tuples

foreign_apps: list[int]

None

List of foreign apps (by app id) to include in transaction

foreign_assets: list[int]

None

List of foreign assets (by asset id) to include in transaction

lease: bytes | str

None

Lease value for this transaction

note: bytes | str

None

Note for this transaction

rekey_to: str

None

Address to rekey to

sender: str

None

Sender of this transaction

signer: algosdk.atomic_transaction_composer.TransactionSigner

None

Signer to use when signing this transaction

suggested_params: algosdk.transaction.SuggestedParams

None

SuggestedParams to use for this transaction

class algokit_utils.TransactionResponse

Response for a non ABI call

confirmed_round: int | None

None

Round transaction was confirmed, None if call was a from a dry-run

static from_atr(result: algosdk.atomic_transaction_composer.AtomicTransactionResponse | algosdk.atomic_transaction_composer.SimulateAtomicTransactionResponse, transaction_index: int = -1) → algokit_utils.models.TransactionResponse

Returns either an ABITransactionResponse or a TransactionResponse based on the type of the transaction referred to by transaction_index

Parameters:

result (AtomicTransactionResponse) – Result containing one or more transactions
transaction_index (int) – Which transaction in the result to return, defaults to -1 (the last transaction)

tx_id: str

None

Transaction Id

class algokit_utils.TransferAssetParameters

Bases: algokit_utils._transfer.TransferParametersBase

Parameters for transferring assets between accounts

Args: asset_id (int): The asset id that will be transfered amount (int): The amount to send clawback_from (str | None): An address of a target account from which to perform a clawback operation. Please note, in such cases senderAccount must be equal to clawback field on ASA metadata.

class algokit_utils.TransferParameters

Bases: algokit_utils._transfer.TransferParametersBase

Parameters for transferring µALGOs between accounts

algokit_utils.UPDATABLE_TEMPLATE_NAME

None

Template variable name used to control if a smart contract is updatable or not at deployment

algokit_utils.create_kmd_wallet_account(kmd_client: algosdk.kmd.KMDClient, name: str) → algokit_utils.models.Account: Creates a wallet with specified name

algokit_utils.ensure_funded(client: algosdk.v2client.algod.AlgodClient, parameters: algokit_utils._ensure_funded.EnsureBalanceParameters) → algokit_utils._ensure_funded.EnsureFundedResponse | None

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) see https://developer.algorand.org/docs/get-details/accounts/#minimum-balance

Args: client (AlgodClient): An instance of the AlgodClient class from the AlgoSDK library. parameters (EnsureBalanceParameters): An instance of the EnsureBalanceParameters class that specifies the account to fund and the minimum spending balance.

Returns: PaymentTxn | str | None: If funds are needed, the function returns a payment transaction or a string indicating that the dispenser API was used. If no funds are needed, the function returns None.

algokit_utils.execute_atc_with_logic_error(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, algod_client: algosdk.v2client.algod.AlgodClient, approval_program: str, wait_rounds: int = 4, approval_source_map: algosdk.source_map.SourceMap | Callable[[], algosdk.source_map.SourceMap | None] | None = None) → algosdk.atomic_transaction_composer.AtomicTransactionResponse: Calls AtomicTransactionComposer.execute() on provided atc, but will parse any errors and raise a LogicError if possible

Note

approval_program and approval_source_map are required to be able to parse any errors into a LogicError

algokit_utils.get_account(client: algosdk.v2client.algod.AlgodClient, name: str, fund_with_algos: float = 1000, kmd_client: KMDClient | None = None) → algokit_utils.models.Account

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

Convention

Non-LocalNet: will load os.environ[f"{name}_MNEMONIC"] as a mnemonic secret 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.

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

If you have a mnemonic secret loaded into os.environ["ACCOUNT_MNEMONIC"] then you can call the following to get that private key loaded into an account object:

account = get_account('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.

algokit_utils.get_account_from_mnemonic(mnemonic: str) → algokit_utils.models.Account: Convert a mnemonic (25 word passphrase) into an Account

algokit_utils.get_algod_client(config: algokit_utils.network_clients.AlgoClientConfig | None = None) → algosdk.v2client.algod.AlgodClient

Returns an algosdk.v2client.algod.AlgodClient from config or environment

If no configuration provided will use environment variables ALGOD_SERVER, ALGOD_PORT and ALGOD_TOKEN

algokit_utils.get_app_id_from_tx_id(algod_client: algosdk.v2client.algod.AlgodClient, tx_id: str) → int: Finds the app_id for provided transaction id

algokit_utils.get_creator_apps(indexer: algosdk.v2client.indexer.IndexerClient, creator_account: algokit_utils.models.Account | str) → algokit_utils.deploy.AppLookup: Returns a mapping of Application names to AppMetaData for all Applications created by specified creator that have a transaction note containing AppDeployMetaData

algokit_utils.get_default_localnet_config(config: Literal[algod, indexer, kmd]) → algokit_utils.network_clients.AlgoClientConfig: Returns the client configuration to point to the default LocalNet

algokit_utils.get_dispenser_account(client: algosdk.v2client.algod.AlgodClient) → algokit_utils.models.Account: Returns an Account based on DISPENSER_MNENOMIC environment variable or the default account on LocalNet

algokit_utils.get_indexer_client(config: algokit_utils.network_clients.AlgoClientConfig | None = None) → algosdk.v2client.indexer.IndexerClient

Returns an algosdk.v2client.indexer.IndexerClient from config or environment.

If no configuration provided will use environment variables INDEXER_SERVER, INDEXER_PORT and INDEXER_TOKEN

algokit_utils.get_kmd_client_from_algod_client(client: algosdk.v2client.algod.AlgodClient) → algosdk.kmd.KMDClient

Returns an algosdk.kmd.KMDClient from supplied client

Will use the same address as provided client but on port specified by KMD_PORT environment variable, or 4002 by default

algokit_utils.get_kmd_wallet_account(client: algosdk.v2client.algod.AlgodClient, kmd_client: algosdk.kmd.KMDClient, name: str, predicate: Callable[[dict[str, Any]], bool] | None = None) → algokit_utils.models.Account | None: Returns wallet matching specified name and predicate or None if not found

algokit_utils.get_localnet_default_account(client: algosdk.v2client.algod.AlgodClient) → algokit_utils.models.Account: Returns the default Account in a LocalNet instance

algokit_utils.get_next_version(current_version: str) → str

Calculates the next version from current_version

Next version is calculated by finding a semver like version string and incrementing the lower. This function is used by ApplicationClient.deploy() when a version is not specified, and is intended mostly for convenience during local development.

Params str current_version:: An existing version string with a semver like version contained within it, some valid inputs and incremented outputs: 1 -> 2 1.0 -> 1.1 v1.1 -> v1.2 v1.1-beta1 -> v1.2-beta1 v1.2.3.4567 -> v1.2.3.4568 v1.2.3.4567-alpha -> v1.2.3.4568-alpha
Raises:: DeploymentFailedError – If current_version cannot be parsed

algokit_utils.get_or_create_kmd_wallet_account(client: algosdk.v2client.algod.AlgodClient, name: str, fund_with_algos: float = 1000, kmd_client: KMDClient | None = None) → algokit_utils.models.Account: Returns a wallet with specified name, or creates one if not found

algokit_utils.get_sender_from_signer(signer: algosdk.atomic_transaction_composer.TransactionSigner | None) → str | None: Returns the associated address of a signer, return None if no address found

algokit_utils.is_localnet(client: algosdk.v2client.algod.AlgodClient) → bool: Returns True if client genesis is devnet-v1 or sandnet-v1

algokit_utils.is_mainnet(client: algosdk.v2client.algod.AlgodClient) → bool: Returns True if client genesis is mainnet-v1

algokit_utils.is_testnet(client: algosdk.v2client.algod.AlgodClient) → bool: Returns True if client genesis is testnet-v1

algokit_utils.num_extra_program_pages(approval: bytes, clear: bytes) → int: Calculate minimum number of extra_pages required for provided approval and clear programs

algokit_utils.opt_in(algod_client: algosdk.v2client.algod.AlgodClient, account: algokit_utils.models.Account, asset_ids: list[int]) → dict[int, str]

Opt-in to a list of assets on the Algorand blockchain. Before an account can receive a specific asset, it must opt-in to receive it. An opt-in transaction places an asset holding of 0 into the account and increases its minimum balance by 100,000 microAlgos.

Args: algod_client (AlgodClient): An instance of the AlgodClient class from the algosdk library. account (Account): An instance of the Account class representing the account that wants to opt-in to the assets. asset_ids (list[int]): A list of integers representing the asset IDs to opt-in to. Returns: dict[int, str]: A dictionary where the keys are the asset IDs and the values are the transaction IDs for opting-in to each asset.

algokit_utils.opt_out(algod_client: algosdk.v2client.algod.AlgodClient, account: algokit_utils.models.Account, asset_ids: list[int]) → dict[int, str]

Opt out from a list of Algorand Standard Assets (ASAs) by transferring them back to their creators. The account also recovers the Minimum Balance Requirement for the asset (100,000 microAlgos) The optOut function manages the opt-out process, permitting the account to discontinue holding a group of assets.

It’s essential to note that an account can only opt_out of an asset if its balance of that asset is zero.

Args: algod_client (AlgodClient): An instance of the AlgodClient class from the algosdk library. account (Account): An instance of the Account class that holds the private key and address for an account. asset_ids (list[int]): A list of integers representing the asset IDs of the ASAs to opt out from. Returns: dict[int, str]: A dictionary where the keys are the asset IDs and the values are the transaction IDs of the executed transactions.

algokit_utils.persist_sourcemaps(*, sources: list[algokit_utils._debugging.PersistSourceMapInput], project_root: pathlib.Path, client: algosdk.v2client.algod.AlgodClient, with_sources: bool = True) → None: Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts. Args: sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects. project_root (Path): The root directory of the project. client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain. with_sources (bool): If True, it will dump teal source files along with sourcemaps. Default is True, as needed by an AlgoKit AVM debugger.

algokit_utils.replace_template_variables(program: str, template_values: algokit_utils.deploy.TemplateValueMapping) → str: Replaces TMPL_* variables in program with template_values

Note

template_values keys should NOT be prefixed with TMPL_

algokit_utils.simulate_and_persist_response(atc: algosdk.atomic_transaction_composer.AtomicTransactionComposer, project_root: pathlib.Path, algod_client: algosdk.v2client.algod.AlgodClient, buffer_size_mb: float = 256) → algosdk.atomic_transaction_composer.SimulateAtomicTransactionResponse

Simulates the atomic transactions using the provided AtomicTransactionComposer object and AlgodClient object, and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.

Parameters:

atc – An AtomicTransactionComposer object representing the atomic transactions to be simulated and persisted.
project_root – A Path object representing the root directory of the project.
algod_client – An AlgodClient object representing the Algorand client.
buffer_size_mb – The size of the trace buffer in megabytes. Defaults to 256mb.

Returns:

None

Returns: SimulateAtomicTransactionResponse: The simulated response after persisting it for AlgoKit AVM Debugger consumption.

algokit_utils.transfer(client: algosdk.v2client.algod.AlgodClient, parameters: algokit_utils._transfer.TransferParameters) → algosdk.transaction.PaymentTxn: Transfer µALGOs between accounts

algokit_utils.transfer_asset(client: algosdk.v2client.algod.AlgodClient, parameters: algokit_utils._transfer.TransferAssetParameters) → algosdk.transaction.AssetTransferTxn: Transfer assets between accounts

algokit_utils

Package Contents

Classes

Functions

Data

API

Convention

Example

`algokit_utils`