algokit_utils.applications.app_factory

algokit_utils.applications.app_factory

Classes

AppFactoryParams
AppFactoryCreateParams	Parameters for creating application with bare call.
AppFactoryCreateMethodCallParams	Parameters for creating application with method call
AppFactoryCreateMethodCallResult	Base class for transaction results.
SendAppFactoryTransactionResult	Result of an application transaction.
SendAppUpdateFactoryTransactionResult	Result of updating an application.
SendAppCreateFactoryTransactionResult	Result of creating a new application.
AppFactoryDeployResult	Result from deploying an application via AppFactory
AppFactory	ARC-56/ARC-32 app factory that, for a given app spec, allows you to create

Module Contents

class AppFactoryParams

algorand : AlgorandClient

app_spec : Arc56Contract | str

app_name : str | None = None

default_sender : str | None = None

default_signer : TransactionSigner | None = None

version : str | None = None

compilation_params : AppClientCompilationParams | None = None

class AppFactoryCreateParams

Bases: algokit_utils.applications.app_client.AppClientBareCallCreateParams

Parameters for creating application with bare call.

on_complete : CreateOnComplete | None = None

Optional on complete action

class AppFactoryCreateMethodCallParams

Bases: algokit_utils.applications.app_client.AppClientMethodCallCreateParams

Parameters for creating application with method call

class AppFactoryCreateMethodCallResult

Bases: algokit_utils.transactions.transaction_sender.SendSingleTransactionResult, Generic[ABIReturnT]

Base class for transaction results.

Represents the result of sending a single transaction.

app_id : int

app_address : str

compiled_approval : Any | None = None

compiled_clear : Any | None = None

abi_return : ABIReturnT | None = None

class SendAppFactoryTransactionResult

Bases: algokit_utils.transactions.transaction_sender.SendAppTransactionResult[algokit_utils.applications.abi.Arc56ReturnValueType]

Result of an application transaction.

Contains the ABI return value if applicable.

class SendAppUpdateFactoryTransactionResult

Bases: algokit_utils.transactions.transaction_sender.SendAppUpdateTransactionResult[algokit_utils.applications.abi.Arc56ReturnValueType]

Result of updating an application.

Contains the compiled approval and clear programs.

class SendAppCreateFactoryTransactionResult

Bases: algokit_utils.transactions.transaction_sender.SendAppCreateTransactionResult[algokit_utils.applications.abi.Arc56ReturnValueType]

Result of creating a new application.

Contains the app ID and address of the newly created application.

class AppFactoryDeployResult

Result from deploying an application via AppFactory

app : ApplicationMetaData

The application metadata

operation_performed : OperationPerformed

The operation performed

create_result : SendAppCreateFactoryTransactionResult | None = None

The create result

update_result : SendAppUpdateFactoryTransactionResult | None = None

The update result

delete_result : SendAppFactoryTransactionResult | None = None

The delete result

classmethod from_deploy_result(response: AppDeployResult, deploy_params: AppDeployParams, app_spec: Arc56Contract, app_compilation_data: AppClientCompilationResult | None = None) → Self

Construct an AppFactoryDeployResult from a deployment result.

• Parameters:
  • response – The deployment response.
  • deploy_params – The deployment parameters.
  • app_spec – The application specification.
  • app_compilation_data – Optional app compilation data.
• Returns: An instance of AppFactoryDeployResult.

class AppFactory(params: AppFactoryParams)

ARC-56/ARC-32 app factory that, for a given app spec, allows you to create and deploy one or more app instances and to create one or more app clients to interact with those (or other) app instances.

• Parameters: params – The parameters for the factory
• Example:

  factory = AppFactory(AppFactoryParams(
         algorand=AlgorandClient.mainnet(),
         app_spec=app_spec,
     )
  )

property app_name : str

The name of the app

property app_spec : Arc56Contract

The app spec

property algorand : AlgorandClient

The algorand client

property params : _MethodParamsBuilder

Get parameters to create transactions (create and deploy related calls) for the current app.

A good mental model for this is that these parameters represent a deferred transaction creation.

• Example:

  Create a transaction in the future using Algorand Client
  create_app_params = app_factory.params.create(
      AppFactoryCreateMethodCallParams(
          method=’create_method’,
          args=[123, ‘hello’]
      )
  )
  # …
  algorand.send.app_create_method_call(create_app_params)

• Example:

  Define a nested transaction as an ABI argument
  create_app_params = appFactory.params.create(
      AppFactoryCreateMethodCallParams(
          method=’create_method’,
          args=[123, ‘hello’]
      )
  )
  app_client.send.call(
      AppClientMethodCallParams(
          method=’my_method’,
          args=[create_app_params]
      )
  )

property send : _TransactionSender

Get the transaction sender.

• Returns: The _TransactionSender instance.

property create_transaction : _TransactionCreator

Get the transaction creator.

• Returns: The _TransactionCreator instance.

deploy(*, on_update: OnUpdate | None = None, on_schema_break: OnSchemaBreak | None = None, create_params: AppClientMethodCallCreateParams | AppClientBareCallCreateParams | None = None, update_params: AppClientMethodCallParams | AppClientBareCallParams | None = None, delete_params: AppClientMethodCallParams | AppClientBareCallParams | None = None, existing_deployments: ApplicationLookup | None = None, ignore_cache: bool = False, app_name: str | None = None, send_params: SendParams | None = None, compilation_params: AppClientCompilationParams | None = None) → tuple[AppClient, AppFactoryDeployResult]

Idempotently deploy (create if not exists, update if changed) an app against the given name for the given creator account, including deploy-time TEAL template placeholder substitutions (if specified).

Note: When using the return from this function be sure to check operationPerformed to get access to various return properties like transaction, confirmation and deleteResult.

Note: if there is a breaking state schema change to an existing app (and onSchemaBreak is set to ‘replace’) the existing app will be deleted and re-created.

Note: if there is an update (different TEAL code) to an existing app (and onUpdate is set to ‘replace’) the existing app will be deleted and re-created.

• Parameters:
  • on_update – The action to take if there is an update to the app
  • on_schema_break – The action to take if there is a breaking state schema change to the app
  • create_params – The arguments to create the app
  • update_params – The arguments to update the app
  • delete_params – The arguments to delete the app
  • existing_deployments – The existing deployments to use
  • ignore_cache – Whether to ignore the cache
  • app_name – The name of the app
  • send_params – The parameters for the send call
  • compilation_params – The parameters for the compilation
• Returns: The app client and the result of the deployment
• Example:

  app_client, result = factory.deploy({
    create_params=AppClientMethodCallCreateParams(
      sender='SENDER_ADDRESS',
      approval_program='APPROVAL PROGRAM',
      clear_state_program='CLEAR PROGRAM',
      schema={
        "global_byte_slices": 0,
        "global_ints": 0,
        "local_byte_slices": 0,
        "local_ints": 0
      }
    ),
    update_params=AppClientMethodCallParams(
      sender='SENDER_ADDRESS'
    ),
    delete_params=AppClientMethodCallParams(
      sender='SENDER_ADDRESS'
    ),
    compilation_params=AppClientCompilationParams(
      updatable=False,
      deletable=False
    ),
    app_name='my_app',
    on_schema_break=OnSchemaBreak.AppendApp,
    on_update=OnUpdate.AppendApp
  })

get_app_client_by_id(app_id: int, app_name: str | None = None, default_sender: str | None = None, default_signer: TransactionSigner | None = None, approval_source_map: ProgramSourceMap | None = None, clear_source_map: ProgramSourceMap | None = None) → AppClient

Returns a new AppClient client for an app instance of the given ID.

• Parameters:
  • app_id – The id of the app
  • app_name – The name of the app
  • default_sender – The default sender address
  • default_signer – The default signer
  • approval_source_map – The approval source map
  • clear_source_map – The clear source map
• Return AppClient: The app client
• Example:

  app_client = factory.get_app_client_by_id(app_id=123)

get_app_client_by_creator_and_name(creator_address: str, app_name: str, default_sender: str | None = None, default_signer: TransactionSigner | None = None, ignore_cache: bool | None = None, app_lookup_cache: ApplicationLookup | None = None, approval_source_map: ProgramSourceMap | None = None, clear_source_map: ProgramSourceMap | None = None) → AppClient

Returns a new AppClient client, resolving the app by creator address and name using AlgoKit app deployment semantics (i.e. looking for the app creation transaction note).

• Parameters:
  • creator_address – The creator address
  • app_name – The name of the app
  • default_sender – The default sender address
  • default_signer – The default signer
  • ignore_cache – Whether to ignore the cache and force a lookup
  • app_lookup_cache – Optional cache of existing app deployments to use instead of querying the indexer
  • approval_source_map – Optional source map for the approval program
  • clear_source_map – Optional source map for the clear state program
• Returns: An AppClient instance configured for the resolved application
• Example:

  app_client = factory.get_app_client_by_creator_and_name(
      creator_address='SENDER_ADDRESS',
      app_name='my_app'
  )

export_source_maps() → AppSourceMaps

import_source_maps(source_maps: AppSourceMaps) → None

Import the provided source maps into the factory.

• Parameters: source_maps – An AppSourceMaps instance containing the approval and clear source maps.

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

Compile the app’s TEAL code.

• Parameters: compilation_params – The compilation parameters
• Return AppClientCompilationResult: The compilation result
• Example:

  compilation_result = factory.compile()