algokit_utils.application_client

Classes

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

Functions

execute_atc_with_logic_error	Calls AtomicTransactionComposer.execute() on provided atc, but will parse any errors and raise a LogicError if possible
get_next_version	Calculates the next version from current_version
get_sender_from_signer	Returns the associated address of a signer, return None if no address found
num_extra_program_pages	Calculate minimum number of extra_pages required for provided approval and clear programs
substitute_template_and_compile	Substitutes the provided template_values into app_spec and compiles

Data

__all__	Alias for pyteal.ABIReturnSubroutine, algosdk.abi.method.Method or a str representing an ABI method name or signature
logger	A dictionary dict[str, Any] representing ABI argument names and values

API

class algokit_utils.application_client.ApplicationClient

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.

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

add_method_call

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

export_source_map

export_source_map() → str | None

Export approval source map to JSON, can be later re-imported with import_source_map

get_global_state

get_global_state(*, raw: bool = False) → dict[bytes | str, bytes | str | int]

Gets the global state info associated with app_id

get_local_state

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

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

import_source_map(source_map_json: str) → None

Import approval source from JSON exported by export_source_map

opt_in

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

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

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

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

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

algokit_utils.application_client.__all__

all

[‘ApplicationClient’, ‘execute_atc_with_logic_error’, ‘get_next_version’, ‘get_sender_from_signer’, …

Alias for pyteal.ABIReturnSubroutine, algosdk.abi.method.Method or a str representing an ABI method name or signature

algokit_utils.application_client.execute_atc_with_logic_error

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.application_client.get_next_version

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.application_client.get_sender_from_signer

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.application_client.logger

logger

‘getLogger(…)’

A dictionary dict[str, Any] representing ABI argument names and values

algokit_utils.application_client.num_extra_program_pages

num_extra_program_pages(approval: bytes, clear: bytes) → int

Calculate minimum number of extra_pages required for provided approval and clear programs

algokit_utils.application_client.substitute_template_and_compile

substitute_template_and_compile(algod_client: algosdk.v2client.algod.AlgodClient, app_spec: algokit_utils.application_specification.ApplicationSpecification, template_values: algokit_utils.deploy.TemplateValueMapping) → tuple[algokit_utils.common.Program, algokit_utils.common.Program]

Substitutes the provided template_values into app_spec and compiles