algokit_utils.applications.app_client ===================================== .. py:module:: algokit_utils.applications.app_client Attributes ---------- .. autoapisummary:: algokit_utils.applications.app_client.CreateOnComplete Classes ------- .. autoapisummary:: algokit_utils.applications.app_client.AppClientCompilationResult algokit_utils.applications.app_client.AppClientCompilationParams algokit_utils.applications.app_client.CommonAppCallParams algokit_utils.applications.app_client.AppClientCreateSchema algokit_utils.applications.app_client.CommonAppCallCreateParams algokit_utils.applications.app_client.FundAppAccountParams algokit_utils.applications.app_client.AppClientBareCallParams algokit_utils.applications.app_client.AppClientBareCallCreateParams algokit_utils.applications.app_client.BaseAppClientMethodCallParams algokit_utils.applications.app_client.AppClientMethodCallParams algokit_utils.applications.app_client.AppClientMethodCallCreateParams algokit_utils.applications.app_client.AppClientParams algokit_utils.applications.app_client.AppClient Functions --------- .. autoapisummary:: algokit_utils.applications.app_client.get_constant_block_offset Module Contents --------------- .. py:function:: 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. :param program: The compiled TEAL program as bytes :return: The maximum offset position after any constant block operations .. py:data:: CreateOnComplete .. py:class:: AppClientCompilationResult Result of compiling an application's TEAL code. Contains the compiled approval and clear state programs along with optional compilation artifacts. .. py:attribute:: approval_program :type: bytes The compiled approval program bytes .. py:attribute:: clear_state_program :type: bytes The compiled clear state program bytes .. py:attribute:: compiled_approval :type: algokit_utils.models.application.CompiledTeal | None :value: None Optional compilation artifacts for approval program .. py:attribute:: compiled_clear :type: algokit_utils.models.application.CompiledTeal | None :value: None Optional compilation artifacts for clear state program .. py:class:: AppClientCompilationParams Bases: :py:obj:`TypedDict` Parameters for compiling an application's TEAL code. :ivar deploy_time_params: Optional template parameters to use during compilation :ivar updatable: Optional flag indicating if app should be updatable :ivar deletable: Optional flag indicating if app should be deletable .. py:attribute:: deploy_time_params :type: algokit_utils.models.state.TealTemplateParams | None .. py:attribute:: updatable :type: bool | None .. py:attribute:: deletable :type: bool | None .. py:class:: CommonAppCallParams Common configuration for app call transaction parameters .. py:attribute:: account_references :type: list[str] | None :value: None List of account addresses to reference .. py:attribute:: app_references :type: list[int] | None :value: None List of app IDs to reference .. py:attribute:: asset_references :type: list[int] | None :value: None List of asset IDs to reference .. py:attribute:: box_references :type: list[algokit_utils.models.state.BoxReference | algokit_utils.models.state.BoxIdentifier] | None :value: None List of box references to include .. py:attribute:: extra_fee :type: algokit_utils.models.amount.AlgoAmount | None :value: None Additional fee to add to transaction .. py:attribute:: lease :type: bytes | None :value: None Transaction lease value .. py:attribute:: max_fee :type: algokit_utils.models.amount.AlgoAmount | None :value: None Maximum fee allowed for transaction .. py:attribute:: note :type: bytes | None :value: None Custom note for the transaction .. py:attribute:: rekey_to :type: str | None :value: None Address to rekey account to .. py:attribute:: sender :type: str | None :value: None Sender address override .. py:attribute:: signer :type: algosdk.atomic_transaction_composer.TransactionSigner | None :value: None Custom transaction signer .. py:attribute:: static_fee :type: algokit_utils.models.amount.AlgoAmount | None :value: None Fixed fee for transaction .. py:attribute:: validity_window :type: int | None :value: None Number of rounds valid .. py:attribute:: first_valid_round :type: int | None :value: None First valid round number .. py:attribute:: last_valid_round :type: int | None :value: None Last valid round number .. py:attribute:: on_complete :type: algosdk.transaction.OnComplete | None :value: None Optional on complete action .. py:class:: AppClientCreateSchema Schema for application creation. .. py:attribute:: extra_program_pages :type: int | None :value: None Optional number of extra program pages .. py:attribute:: schema :type: algokit_utils.transactions.transaction_composer.AppCreateSchema | None :value: None Optional application creation schema .. py:class:: CommonAppCallCreateParams Bases: :py:obj:`AppClientCreateSchema`, :py:obj:`CommonAppCallParams` Common configuration for app create call transaction parameters. .. py:attribute:: on_complete :type: CreateOnComplete | None :value: None Optional on complete action .. py:class:: FundAppAccountParams Bases: :py:obj:`CommonAppCallParams` Parameters for funding an application's account. .. py:attribute:: amount :type: algokit_utils.models.amount.AlgoAmount Amount to fund .. py:attribute:: close_remainder_to :type: str | None :value: None Optional address to close remainder to .. py:class:: AppClientBareCallParams Bases: :py:obj:`CommonAppCallParams` Parameters for bare application calls. .. py:attribute:: args :type: list[bytes] | None :value: None Optional arguments .. py:class:: AppClientBareCallCreateParams Bases: :py:obj:`CommonAppCallCreateParams` Parameters for creating application with bare call. .. py:attribute:: on_complete :type: CreateOnComplete | None :value: None Optional on complete action .. py:class:: BaseAppClientMethodCallParams Bases: :py:obj:`Generic`\ [\ :py:obj:`ArgsT`\ , :py:obj:`MethodT`\ ], :py:obj:`CommonAppCallParams` Base parameters for application method calls. .. py:attribute:: method :type: MethodT Method to call .. py:attribute:: args :type: ArgsT | None :value: None Arguments to pass to the application method call .. py:class:: AppClientMethodCallParams Bases: :py:obj:`BaseAppClientMethodCallParams`\ [\ :py:obj:`collections.abc.Sequence`\ [\ :py:obj:`algokit_utils.applications.abi.ABIValue | algokit_utils.applications.abi.ABIStruct | algokit_utils.transactions.transaction_composer.AppMethodCallTransactionArgument | None`\ ]\ , :py:obj:`str`\ ] Parameters for application method calls. .. py:class:: AppClientMethodCallCreateParams Bases: :py:obj:`AppClientCreateSchema`, :py:obj:`AppClientMethodCallParams` Parameters for creating application with method call .. py:attribute:: on_complete :type: CreateOnComplete | None :value: None Optional on complete action .. py:class:: AppClientParams Full parameters for creating an app client .. py:attribute:: app_spec :type: algokit_utils.applications.app_spec.arc56.Arc56Contract | algokit_utils.applications.app_spec.arc32.Arc32Contract | str The application specification .. py:attribute:: algorand :type: algokit_utils.algorand.AlgorandClient The Algorand client .. py:attribute:: app_id :type: int The application ID .. py:attribute:: app_name :type: str | None :value: None The application name .. py:attribute:: default_sender :type: str | None :value: None The default sender address .. py:attribute:: default_signer :type: algosdk.atomic_transaction_composer.TransactionSigner | None :value: None The default transaction signer .. py:attribute:: approval_source_map :type: algosdk.source_map.SourceMap | None :value: None The approval source map .. py:attribute:: clear_source_map :type: algosdk.source_map.SourceMap | None :value: None The clear source map .. py:class:: 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. :param 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) .. py:property:: algorand :type: algokit_utils.algorand.AlgorandClient Get the Algorand client instance. :return: The Algorand client used by this app client .. py:property:: app_id :type: int Get the application ID. :return: The ID of the Algorand application .. py:property:: app_address :type: str Get the application's Algorand address. :return: The Algorand address associated with this application .. py:property:: app_name :type: str Get the application name. :return: The name of the application .. py:property:: app_spec :type: algokit_utils.applications.app_spec.arc56.Arc56Contract Get the application specification. :return: The ARC-56 contract specification for this application .. py:property:: state :type: _StateAccessor Get the state accessor. :return: The state accessor for this application .. py:property:: params :type: _MethodParamsBuilder Get the method parameters builder. :return: 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])) .. py:property:: send :type: _TransactionSender Get the transaction sender. :return: The transaction sender for this application .. py:property:: create_transaction :type: _TransactionCreator Get the transaction creator. :return: The transaction creator for this application .. py:method:: 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 :staticmethod: Normalize an application specification to ARC-56 format. :param app_spec: The application specification to normalize. Can be raw arc32 or arc56 json, or an Arc32Contract or Arc56Contract instance :return: The normalized ARC-56 contract specification :raises ValueError: If the app spec format is invalid :example: >>> spec = AppClient.normalise_app_spec(app_spec_json) .. py:method:: 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 :staticmethod: Create an AppClient instance from network information. :param app_spec: The application specification :param algorand: The Algorand client instance :param app_name: Optional application name :param default_sender: Optional default sender address :param default_signer: Optional default transaction signer :param approval_source_map: Optional approval program source map :param clear_source_map: Optional clear program source map :return: 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", ... ), ... ) .. py:method:: 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 :staticmethod: Create an AppClient instance from creator address and application name. :param creator_address: The address of the application creator :param app_name: The name of the application :param app_spec: The application specification :param algorand: The Algorand client instance :param default_sender: Optional default sender address :param default_signer: Optional default transaction signer :param approval_source_map: Optional approval program source map :param clear_source_map: Optional clear program source map :param ignore_cache: Optional flag to ignore cache :param app_lookup_cache: Optional app lookup cache :return: 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, ... ) .. py:method:: compile(app_spec: algokit_utils.applications.app_spec.arc56.Arc56Contract, app_manager: algokit_utils.applications.app_manager.AppManager, compilation_params: AppClientCompilationParams | None = None) -> AppClientCompilationResult :staticmethod: Compile the application's TEAL code. :param app_spec: The application specification :param app_manager: The application manager instance :param compilation_params: Optional compilation parameters :return: The compilation result :raises ValueError: If attempting to compile without source or byte code .. py:method:: compile_app(compilation_params: AppClientCompilationParams | None = None) -> AppClientCompilationResult Compile the application's TEAL code. :param compilation_params: Optional compilation parameters :return: The compilation result .. py:method:: 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. :param app_name: Optional new application name :param default_sender: Optional new default sender :param default_signer: Optional new default signer :param approval_source_map: Optional new approval source map :param clear_source_map: Optional new clear source map :return: A new AppClient instance :example: >>> client = AppClient(params) >>> cloned_client = client.clone(app_name="Cloned App", default_sender="NEW_SENDER") .. py:method:: export_source_maps() -> algokit_utils.models.application.AppSourceMaps Export the application's source maps. :return: The application's source maps :raises ValueError: If source maps haven't been loaded .. py:method:: import_source_maps(source_maps: algokit_utils.models.application.AppSourceMaps) -> None Import source maps for the application. :param source_maps: The source maps to import :raises ValueError: If source maps are invalid or missing .. py:method:: get_local_state(address: str) -> dict[str, algokit_utils.models.application.AppState] Get local state for an account. :param address: The account address :return: The account's local state for this application .. py:method:: get_global_state() -> dict[str, algokit_utils.models.application.AppState] Get the application's global state. :return: The application's global state :example: >>> global_state = client.get_global_state() .. py:method:: get_box_names() -> list[algokit_utils.models.state.BoxName] Get all box names for the application. :return: List of box names :example: >>> box_names = client.get_box_names() .. py:method:: get_box_value(name: algokit_utils.models.state.BoxIdentifier) -> bytes Get the value of a box. :param name: The box identifier :return: The box value as bytes :example: >>> box_value = client.get_box_value(box_name) .. py:method:: 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. :param name: The box identifier :param abi_type: The ABI type to decode as :return: The decoded box value :example: >>> box_value = client.get_box_value_from_abi_type(box_name, abi_type) .. py:method:: 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. :param filter_func: Optional function to filter box names :return: List of box values :example: >>> box_values = client.get_box_values() .. py:method:: 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. :param abi_type: The ABI type to decode as :param filter_func: Optional function to filter box names :return: List of decoded box values :example: >>> box_values = client.get_box_values_from_abi_type(abi_type) .. py:method:: 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. :param params: The funding parameters :param send_params: Send parameters, defaults to None :return: The transaction result :example: >>> result = client.fund_app_account(params)