App client and App factory | Algorand Developer Portal

App client and App factory

[!NOTE] This page covers the untyped app client, but we recommend using typed clients (coming soon), which will give you a better developer experience with strong typing specific to the app itself.

App client and App factory are higher-order use case capabilities provided by AlgoKit Utils that builds on top of the core capabilities, particularly App deployment and App management. They allow you to access high productivity application clients that work with ARC-56 and ARC-32 application spec defined smart contracts, which you can use to create, update, delete, deploy and call a smart contract and access state data for it.

[!NOTE] If you are confused about when to use the factory vs client the mental model is: use the client if you know the app ID, use the factory if you don’t know the app ID (deferred knowledge or the instance doesn’t exist yet on the blockchain) or you have multiple app IDs

AppFactory

The AppFactory is a class 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.

To get an instance of AppFactory you can use AlgorandClient via algorand.get_app_factory:

# Minimal example

factory = algorand.get_app_factory(

app_spec="{/* ARC-56 or ARC-32 compatible JSON */}",

)

# Advanced example

factory = algorand.get_app_factory(

app_spec=parsed_arc32_or_arc56_app_spec,

default_sender="SENDERADDRESS",

app_name="OverriddenAppName",

version="2.0.0",

compilation_params={

"updatable": True,

"deletable": False,

"deploy_time_params": { "ONE": 1, "TWO": "value" },

}

)

AppClient

The AppClient is a class that, for a given app spec, allows you to manage calls and state for a specific deployed instance of an app (with a known app ID).

To get an instance of AppClient you can use either AlgorandClient or instantiate it directly:

# Minimal examples

app_client = AppClient.from_creator_and_name(

app_spec="{/* ARC-56 or ARC-32 compatible JSON */}",

creator_address="CREATORADDRESS",

algorand=algorand,

)

app_client = AppClient(

AppClientParams(

app_spec="{/* ARC-56 or ARC-32 compatible JSON */}",

app_id=12345,

algorand=algorand,

)

)

app_client = AppClient.from_network(

app_spec="{/* ARC-56 or ARC-32 compatible JSON */}",

algorand=algorand,

)

# Advanced example

app_client = AppClient(

AppClientParams(

app_spec=parsed_app_spec,

app_id=12345,

algorand=algorand,

app_name="OverriddenAppName",

default_sender="SENDERADDRESS",

approval_source_map=approval_teal_source_map,

clear_source_map=clear_teal_source_map,

)

)

You can access app_id, app_address, app_name and app_spec as properties on the AppClient.

Dynamically creating clients for a given app spec

The AppFactory allows you to conveniently create multiple AppClient instances on-the-fly with information pre-populated.

This is possible via two methods on the app factory:

app_client1 = factory.get_app_client_by_id(app_id=12345)

app_client2 = factory.get_app_client_by_id(app_id=12346)

app_client3 = factory.get_app_client_by_id(

app_id=12345,

default_sender="SENDER2ADDRESS"
)

app_client4 = factory.get_app_client_by_creator_and_name(

creator_address="CREATORADDRESS"
)

app_client5 = factory.get_app_client_by_creator_and_name(

creator_address="CREATORADDRESS",

app_name="NonDefaultAppName"
)

app_client6 = factory.get_app_client_by_creator_and_name(

creator_address="CREATORADDRESS",

app_name="NonDefaultAppName",

ignore_cache=True,  # Perform fresh indexer lookups
    default_sender="SENDER2ADDRESS"
)

Creating and deploying an app

Once you have an app factory you can perform the following actions:

Create

The create method is a wrapper over the app_create (bare calls) and app_create_method_call (ABI method calls) methods, with the following differences:

# Use no-argument bare-call

result, app_client = factory.send.bare.create()

# Specify parameters for bare-call and override other parameters

result, app_client = factory.send.bare.create(

params=AppClientBareCallParams(

args=[bytes([1, 2, 3, 4])],

static_fee=AlgoAmount.from_microalgos(3000),

on_complete=OnComplete.OptIn,

),

compilation_params={

"deploy_time_params": {

"ONE": 1,

"TWO": "two",

},

"updatable": True,

"deletable": False,

}

)

# Specify parameters for ABI method call

result, app_client = factory.send.create(

AppClientMethodCallParams(

method="create_application",

args=[1, "something"]

)
)

Updating and deleting an app

Deploy method aside, the ability to make update and delete calls happens after there is an instance of an app created via AppClient. The semantics of this are no different than other calls, with the caveat that the update call is a bit different since the code will be compiled when constructing the update params and the update calls thus optionally takes compilation parameters (compilation_params) for deploy-time parameter replacements and deploy-time immutability and permanence control.

Calling the app

You can construct a params object, transaction(s) and sign and send a transaction to call the app that a given AppClient instance is pointing to.

This is done via the following properties:

Where {method} is one of:

call1 = app_client.send.update(

AppClientMethodCallParams(

method="update_abi",

args=["string_io"],

),

compilation_params={"deploy_time_params": deploy_time_params}
)

call2 = app_client.send.delete(

AppClientMethodCallParams(

method="delete_abi",

args=["string_io"]
    )
)

call3 = app_client.send.opt_in(

AppClientMethodCallParams(method="opt_in")
)

call4 = app_client.send.bare.clear_state()

transaction = app_client.create_transaction.bare.close_out(

AppClientBareCallParams(

args=[bytes([1, 2, 3])]
    )
)

params = app_client.params.opt_in(

AppClientMethodCallParams(method="optin")
)

Funding the app account

Often there is a need to fund an app account to cover minimum balance requirements for boxes and other scenarios. There is an app client method that will do this for you via fund_app_account(params).

The input parameters are:

Note: If you are passing the funding payment in as an ABI argument so it can be validated by the ABI method then you’ll want to get the funding call as a transaction, e.g.:

result = app_client.send.call(

AppClientMethodCallParams(

method="bootstrap",

args=[\
\
            app_client.create_transaction.fund_app_account(\
\
                FundAppAccountParams(\
\
                    amount=AlgoAmount.from_microalgos(200_000)\
\
                )\
\
            )\
\
        ],

box_references=["Box1"]
    )
)

You can also get the funding call as a params object via app_client.params.fund_app_account(params).

Reading state

AppClient has a number of mechanisms to read state (global, local and box storage) from the app instance.

App spec methods

The ARC-56 app spec can specify detailed information about the encoding format of state values and as such allows for a more advanced ability to automatically read state values and decode them as their high-level language types rather than the limited int / bytes / str ability that the generic methods give you.

You can access this functionality via:

Where {method} is one of:

values = app_client.state.global_state.get_all()

value = app_client.state.local_state("ADDRESS").get_value("value1")

map_value = app_client.state.box.get_map_value("map1", "mapKey")

map_dict = app_client.state.global_state.get_map("myMap")

Generic methods

There are various methods defined that let you read state from the smart contract app:

global_state = app_client.get_global_state()

local_state = app_client.get_local_state("ACCOUNTADDRESS")

box_name: BoxReference = BoxReference(app_id=app_client.app_id, name="my-box")

box_name2: BoxReference = BoxReference(app_id=app_client.app_id, name="my-box2")

box_names = app_client.get_box_names()

box_value = app_client.get_box_value(box_name)

box_values = app_client.get_box_values([box_name, box_name2])

box_abi_value = app_client.get_box_value_from_abi_type(

box_name,

algosdk.ABIStringType
)

box_abi_values = app_client.get_box_values_from_abi_type(

[box_name, box_name2],

algosdk.ABIStringType
)

Handling logic errors and diagnosing errors

Often when calling a smart contract during development you will get logic errors that cause an exception to throw. This may be because of a failing assertion, a lack of fees, exhaustion of opcode budget, or any number of other reasons.

When this occurs, you will generally get an error that looks something like: TransactionPool.Remember: transaction {TRANSACTION_ID}: logic eval error: {ERROR_MESSAGE}. Details: pc={PROGRAM_COUNTER_VALUE}, opcodes={LIST_OF_OP_CODES}.

The information in that error message can be parsed and when combined with the source map from compilation you can expose debugging information that makes it much easier to understand what’s happening. The ARC-56 app spec, if provided, can also specify human-readable error messages against certain program counter values and further augment the error message.

The app client and app factory automatically provide this functionality for all smart contract calls through an automatically registered error transformer. This error transformer:

They also expose a function that can be used for any custom calls you manually construct and need to add into your own try/catch expose_logic_error(e: Error, is_clear: bool = False).

For more information about error transformers and how to create custom ones, see the Transaction Composer Error Transformers documentation.

When an error is thrown then the resulting error that is re-thrown will be a LogicError, which has the following fields:

Note: This information will only show if the app client / app factory has a source map. This will occur if:

If you want to go a step further and automatically issue a simulated transaction and get trace information when there is an error when an ABI method is called you can turn on debug mode:

config.configure(debug=True)

If you do that then the exception will have the traces property within the underlying exception will have key information from the simulation within it and this will get populated into the led.traces property of the thrown error.

When this debug flag is set, it will also emit debugging symbols to allow break-point debugging of the calls if the project root is also configured.

Default arguments

If an ABI method call specifies default argument values for any of its arguments you can pass in None for the value of that argument for the default value to be automatically populated.