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

None

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(version: str | None = None, *, signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, sender: str | None = None, allow_update: bool | None = None, allow_delete: bool | None = None, on_update: algokit_utils.deploy.OnUpdate = au_deploy.OnUpdate.Fail, on_schema_break: algokit_utils.deploy.OnSchemaBreak = au_deploy.OnSchemaBreak.Fail, template_values: algokit_utils.deploy.TemplateValueMapping | None = None, create_args: algokit_utils.deploy.ABICreateCallArgs | algokit_utils.deploy.ABICreateCallArgsDict | algokit_utils.deploy.DeployCreateCallArgs | None = None, update_args: algokit_utils.deploy.ABICallArgs | algokit_utils.deploy.ABICallArgsDict | algokit_utils.deploy.DeployCallArgs | None = None, delete_args: algokit_utils.deploy.ABICallArgs | algokit_utils.deploy.ABICallArgsDict | algokit_utils.deploy.DeployCallArgs | None = None) algokit_utils.deploy.DeployResponse

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

Bases: algokit_utils.models.OnCompleteCallParameters

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

class algokit_utils.CreateCallParametersDict

Bases: typing.TypedDict, algokit_utils.models.OnCompleteCallParametersDict

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.

class algokit_utils.CreateTransactionParameters

Bases: algokit_utils.models.TransactionParameters

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

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

Bases: algokit_utils.models.TransactionParameters

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

class algokit_utils.OnCompleteCallParametersDict

Bases: typing.TypedDict, algokit_utils.models.TransactionParametersDict

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.

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