applications.app_client

Attributes

Classes

Functions

Module Contents

algokit_utils.applications.app_client.get_constant_block_offset(program: bytes) → int

Calculate the offset after constant blocks in TEAL program.

Analyzes a compiled TEAL program to find the ending offset position after any bytecblock and intcblock operations.

• Parameters: program – The compiled TEAL program as bytes
• Returns: The maximum offset position after any constant block operations

algokit_utils.applications.app_client.CreateOnComplete

class algokit_utils.applications.app_client.AppClientCompilationResult

Result of compiling an application’s TEAL code.

Contains the compiled approval and clear state programs along with optional compilation artifacts.

approval*program *: bytes_

The compiled approval program bytes

clear*state_program *: bytes_

The compiled clear state program bytes

compiled*approval *: algokit_utils.models.application.CompiledTeal | None_ = None

Optional compilation artifacts for approval program

compiled*clear *: algokit_utils.models.application.CompiledTeal | None_ = None

Optional compilation artifacts for clear state program

class algokit_utils.applications.app_client.AppClientCompilationParams

Bases: TypedDict

Parameters for compiling an application’s TEAL code.

• Variables:
  • deploy_time_params – Optional template parameters to use during compilation
  • updatable – Optional flag indicating if app should be updatable
  • deletable – Optional flag indicating if app should be deletable

deploy_time_params : algokitutils.models.state.TealTemplateParams | None_

updatable : bool | None

deletable : bool | None

class algokit_utils.applications.app_client.CommonAppCallParams

Common configuration for app call transaction parameters

account*references *: list[str] | None_ = None

List of account addresses to reference

app*references *: list[int] | None_ = None

List of app IDs to reference

asset*references *: list[int] | None_ = None

List of asset IDs to reference

box_references : list[algokit_utils.models.state.BoxReference | algokitutils.models.state.BoxIdentifier] | None_ = None

List of box references to include

extra*fee *: algokit_utils.models.amount.AlgoAmount | None_ = None

Additional fee to add to transaction

lease : bytes | None = None

Transaction lease value

max*fee *: algokit_utils.models.amount.AlgoAmount | None_ = None

Maximum fee allowed for transaction

note : bytes | None = None

Custom note for the transaction

rekey*to *: str | None_ = None

Address to rekey account to

sender : str | None = None

Sender address override

signer : algosdk.atomic_transaction_composer.TransactionSigner | None = None

Custom transaction signer

static*fee *: algokit_utils.models.amount.AlgoAmount | None_ = None

Fixed fee for transaction

validity*window *: int | None_ = None

Number of rounds valid

first*valid_round *: int | None_ = None

First valid round number

last*valid_round *: int | None_ = None

Last valid round number

on*complete *: algosdk.transaction.OnComplete | None_ = None

Optional on complete action

class algokit_utils.applications.app_client.AppClientCreateSchema

Schema for application creation.

extra*program_pages *: int | None_ = None

Optional number of extra program pages

schema : algokit_utils.transactions.transaction_composer.AppCreateSchema | None = None

Optional application creation schema

class algokit_utils.applications.app_client.CommonAppCallCreateParams

Bases: AppClientCreateSchema, CommonAppCallParams

Common configuration for app create call transaction parameters.

on*complete *: CreateOnComplete | None_ = None

Optional on complete action

class algokit_utils.applications.app_client.FundAppAccountParams

Bases: CommonAppCallParams

Parameters for funding an application’s account.

amount : algokit_utils.models.amount.AlgoAmount

Amount to fund

close*remainder_to *: str | None_ = None

Optional address to close remainder to

class algokit_utils.applications.app_client.AppClientBareCallParams

Parameters for bare application calls.

args : list[bytes] | None = None

Optional arguments

class algokit_utils.applications.app_client.AppClientBareCallCreateParams

Bases: CommonAppCallCreateParams

Parameters for creating application with bare call.

on*complete *: CreateOnComplete | None_ = None

Optional on complete action

class algokit_utils.applications.app_client.BaseAppClientMethodCallParams

Bases: Generic[ArgsT, MethodT``, [CommonAppCallParams`](https://dev.algorand.co/reference/algokit-utils-py/api/applications/app_client/#algokit_utils.applications.app_client.CommonAppCallParams)

Base parameters for application method calls.

method : MethodT

Method to call

args : ArgsT | None = None

Arguments to pass to the application method call

class algokit_utils.applications.app_client.AppClientMethodCallParams

Bases: BaseAppClientMethodCallParams[collections.abc.Sequence[algokit_utils.applications.abi.ABIValue | algokit_utils.applications.abi.ABIStruct | algokit_utils.transactions.transaction_composer.AppMethodCallTransactionArgument | None], str]

Parameters for application method calls.

class algokit_utils.applications.app_client.AppClientMethodCallCreateParams

Bases: AppClientCreateSchema, AppClientMethodCallParams

Parameters for creating application with method call

on*complete *: CreateOnComplete | None_ = None

Optional on complete action

class algokit_utils.applications.app_client.AppClientParams

Full parameters for creating an app client

app*spec *: algokit_utils.applications.app_spec.arc56.Arc56Contract | algokit_utils.applications.app_spec.arc32.Arc32Contract | str_

The application specification

algorand : algokit_utils.algorand.AlgorandClient

The Algorand client

app*id *: int_

The application ID

app*name *: str | None_ = None

The application name

default*sender *: str | None_ = None

The default sender address

default_signer : algosdk.atomictransaction_composer.TransactionSigner | None_ = None

The default transaction signer

approval_source_map : algosdk.sourcemap.SourceMap | None_ = None

The approval source map

clear_source_map : algosdk.sourcemap.SourceMap | None_ = None

The clear source map

class algokit_utils.applications.app_client.AppClient(params: AppClientParams)

A client for interacting with an Algorand smart contract application.

Provides a high-level interface for interacting with Algorand smart contracts, including methods for calling application methods, managing state, and handling transactions.

• Parameters: params – Parameters for creating the app client
• Example:

params = AppClientParams(

app_spec=Arc56Contract.from_json(app_spec_json),

algorand=algorand,

app_id=1234567890,

app_name="My App",

default_sender="SENDERADDRESS",

default_signer=TransactionSigner(

account="SIGNERACCOUNT",

private_key="SIGNERPRIVATEKEY",

),

approval_source_map=SourceMap(

source="APPROVALSOURCE",

),

clear_source_map=SourceMap(

source="CLEARSOURCE",

),

)

client = AppClient(params)

property algorand : algokit_utils.algorand.AlgorandClient

Get the Algorand client instance.

• Returns: The Algorand client used by this app client

property app*id *: int_

Get the application ID.

• Returns: The ID of the Algorand application

property app*address *: str_

Get the application’s Algorand address.

• Returns: The Algorand address associated with this application

property app*name *: str_

Get the application name.

• Returns: The name of the application

property app*spec *: algokit_utils.applications.app_spec.arc56.Arc56Contract_

Get the application specification.

• Returns: The ARC-56 contract specification for this application

property state _: StateAccessor

Get the state accessor.

• Returns: The state accessor for this application

property params _: MethodParamsBuilder

Get the method parameters builder.

• Returns: The method parameters builder for this application

• Example:

# Create a transaction in the future using Algorand Client

my_method_call = app_client.params.call(AppClientMethodCallParams(

method='my_method',

args=[123, 'hello']))

# ...

await algorand.send.AppMethodCall(my_method_call)

# Define a nested transaction as an ABI argument

my_method_call = app_client.params.call(AppClientMethodCallParams(

method='my_method',

args=[123, 'hello']))

app_client.send.call(AppClientMethodCallParams(method='my_method2', args=[my_method_call]))

property send _: TransactionSender

Get the transaction sender.

• Returns: The transaction sender for this application

property create*transaction *: TransactionCreator

Get the transaction creator.

• Returns: The transaction creator for this application

static normalise_app_spec(app_spec: algokit_utils.applications.app_spec.arc56.Arc56Contract | algokit_utils.applications.app_spec.arc32.Arc32Contract | str) → algokit_utils.applications.app_spec.arc56.Arc56Contract

Normalize an application specification to ARC-56 format.

• Parameters: app_spec – The application specification to normalize. Can be raw arc32 or arc56 json, or an Arc32Contract or Arc56Contract instance
• Returns: The normalized ARC-56 contract specification
• Raises: ValueError – If the app spec format is invalid
• Example:

spec = AppClient.normalise_app_spec(app_spec_json)

static from_network(app_spec: algokit_utils.applications.app_spec.arc56.Arc56Contract | algokit_utils.applications.app_spec.arc32.Arc32Contract | str, algorand: algokit_utils.algorand.AlgorandClient, app_name: str | None = None, default_sender: str | None = None, default_signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, approval_source_map: algosdk.source_map.SourceMap | None = None, clear_source_map: algosdk.source_map.SourceMap | None = None) → AppClient

Create an AppClient instance from network information.

• Parameters:
  • app_spec – The application specification
  • algorand – The Algorand client instance
  • app_name – Optional application name
  • default_sender – Optional default sender address
  • default_signer – Optional default transaction signer
  • approval_source_map – Optional approval program source map
  • clear_source_map – Optional clear program source map
• Returns: A new AppClient instance
• Raises: Exception – If no app ID is found for the network
• Example:

client = AppClient.from_network(

app_spec=Arc56Contract.from_json(app_spec_json),

algorand=algorand,

app_name="My App",

default_sender="SENDERADDRESS",

default_signer=TransactionSigner(

account="SIGNERACCOUNT",

private_key="SIGNERPRIVATEKEY",

),

approval_source_map=SourceMap(

source="APPROVALSOURCE",

),

clear_source_map=SourceMap(

source="CLEARSOURCE",

),

)

static from_creator_and_name(creator_address: str, app_name: str, app_spec: algokit_utils.applications.app_spec.arc56.Arc56Contract | algokit_utils.applications.app_spec.arc32.Arc32Contract | str, algorand: algokit_utils.algorand.AlgorandClient, default_sender: str | None = None, default_signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, approval_source_map: algosdk.source_map.SourceMap | None = None, clear_source_map: algosdk.source_map.SourceMap | None = None, ignore_cache: bool | None = None, app_lookup_cache: algokit_utils.applications.app_deployer.ApplicationLookup | None = None) → AppClient

Create an AppClient instance from creator address and application name.

• Parameters:
  • creator_address – The address of the application creator
  • app_name – The name of the application
  • app_spec – The application specification
  • algorand – The Algorand client instance
  • default_sender – Optional default sender address
  • default_signer – Optional default transaction signer
  • approval_source_map – Optional approval program source map
  • clear_source_map – Optional clear program source map
  • ignore_cache – Optional flag to ignore cache
  • app_lookup_cache – Optional app lookup cache
• Returns: A new AppClient instance
• Raises: ValueError – If the app is not found for the creator and name
• Example:

client = AppClient.from_creator_and_name(

creator_address="CREATORADDRESS",

app_name="APPNAME",

app_spec=Arc56Contract.from_json(app_spec_json),

algorand=algorand,

)

static compile(app_spec: algokit_utils.applications.app_spec.arc56.Arc56Contract, app_manager: algokit_utils.applications.app_manager.AppManager, compilation_params: AppClientCompilationParams | None = None) → AppClientCompilationResult

Compile the application’s TEAL code.

• Parameters:
  • app_spec – The application specification
  • app_manager – The application manager instance
  • compilation_params – Optional compilation parameters
• Returns: The compilation result
• Raises: ValueError – If attempting to compile without source or byte code

compile_app(compilation_params: AppClientCompilationParams | None = None) → AppClientCompilationResult

Compile the application’s TEAL code.

• Parameters: compilation_params – Optional compilation parameters
• Returns: The compilation result

clone(app_name: str | None = _MISSING, default_sender: str | None = _MISSING, default_signer: algosdk.atomic_transaction_composer.TransactionSigner | None = _MISSING, approval_source_map: algosdk.source_map.SourceMap | None = _MISSING, clear_source_map: algosdk.source_map.SourceMap | None = _MISSING) → AppClient

Create a cloned AppClient instance with optionally overridden parameters.

• Parameters:
  • app_name – Optional new application name
  • default_sender – Optional new default sender
  • default_signer – Optional new default signer
  • approval_source_map – Optional new approval source map
  • clear_source_map – Optional new clear source map
• Returns: A new AppClient instance
• Example:

client = AppClient(params)

cloned_client = client.clone(app_name="Cloned App", default_sender="NEW_SENDER")

export_source_maps() → algokit_utils.models.application.AppSourceMaps

Export the application’s source maps.

• Returns: The application’s source maps
• Raises: ValueError – If source maps haven’t been loaded

import_source_maps(source_maps: algokit_utils.models.application.AppSourceMaps) → None

Import source maps for the application.

• Parameters: source_maps – The source maps to import
• Raises: ValueError – If source maps are invalid or missing

get_local_state(address: str) → dict[str, algokit_utils.models.application.AppState]

Get local state for an account.

• Parameters: address – The account address
• Returns: The account’s local state for this application

get_global_state() → dict[str, algokit_utils.models.application.AppState]

Get the application’s global state.

• Returns: The application’s global state
• Example:

global_state = client.get_global_state()

get_box_names() → list[algokit_utils.models.state.BoxName]

Get all box names for the application.

• Returns: List of box names
• Example:

box_names = client.get_box_names()

get_box_value(name: algokit_utils.models.state.BoxIdentifier) → bytes

Get the value of a box.

• Parameters: name – The box identifier
• Returns: The box value as bytes
• Example:

box_value = client.get_box_value(box_name)

get_box_value_from_abi_type(name: algokit_utils.models.state.BoxIdentifier, abi_type: algokit_utils.applications.abi.ABIType) → algokit_utils.applications.abi.ABIValue

Get a box value decoded according to an ABI type.

• Parameters:
  • name – The box identifier
  • abi_type – The ABI type to decode as
• Returns: The decoded box value
• Example:

box_value = client.get_box_value_from_abi_type(box_name, abi_type)

get_box_values(filter_func: collections.abc.Callable[[ algokit_utils.models.state.BoxName], bool] | None = None) → list[algokit_utils.models.state.BoxValue]

Get values for multiple boxes.

• Parameters: filter_func – Optional function to filter box names
• Returns: List of box values
• Example:

box_values = client.get_box_values()

get_box_values_from_abi_type(abi_type: algokit_utils.applications.abi.ABIType, filter_func: collections.abc.Callable[[ algokit_utils.models.state.BoxName], bool] | None = None) → list[algokit_utils.applications.abi.BoxABIValue]

Get multiple box values decoded according to an ABI type.

• Parameters:
  • abi_type – The ABI type to decode as
  • filter_func – Optional function to filter box names
• Returns: List of decoded box values
• Example:

box_values = client.get_box_values_from_abi_type(abi_type)

fund_app_account(params: FundAppAccountParams, send_params: algokit_utils.models.transaction.SendParams | None = None) → algokit_utils.transactions.transaction_sender.SendSingleTransactionResult

Fund the application’s account.

• Parameters:
  • params – The funding parameters
  • send_params – Send parameters, defaults to None
• Returns: The transaction result
• Example:

result = client.fund_app_account(params)