feat: app factory #248

aorumbayev · 2025-09-02T16:00:51Z

App factory implementation following the AppClient

Copilot

Pull Request Overview

This PR introduces an app factory pattern for Algorand application deployment in the Rust crate, following the established patterns from Python and TypeScript implementations. The factory provides a high-level interface for creating, updating, and deploying applications using ARC-56 specifications.

Key changes:

New AppFactory struct with fluent API for application lifecycle management
Integration with existing AppDeployer for idempotent deployment operations
Enhanced AlgorandClient with persistent app deployer functionality

Reviewed Changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
crates/algokit_utils/src/applications/app_factory/	Core factory implementation with modular design (types, compilation, transaction builders, etc.)
crates/algokit_utils/src/applications/app_client/types.rs	Changed AlgorandClient parameter to Arc for shared ownership
crates/algokit_utils/src/clients/algorand_client.rs	Added persistent AppDeployer instance and app_deployer() accessor method
crates/algokit_utils/src/applications/app_deployer.rs	Enhanced with extra program pages calculation and localnet retry logic
crates/algokit_utils/tests/applications/app_factory.rs	Comprehensive test suite covering factory creation, deployment, and ABI scenarios

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

… in app client; more tests

* wip - PR feedback * wip - convert errors to snafu * wip * chore: replace utils CommonTransactionParams with macro * chore(python/algokit_transact): bump version to 1.0.0-alpha.60 [skip ci] * wip - converting string to error types * chore: simplify add_app_method_call_internal * chore: additional tweaks whilst implementing TS composer * chore(python/algokit_transact): bump version to 1.0.0-alpha.61 [skip ci] * chore: adjust transaction creator types, as they were previously a bit strange * wip - fixing compile issues * fix types for transaction_builder * chore: tweaks to both transaction creator and client manager * wip - map storage * wip - app state * wip - some clean up * wip - fix compile issues * make app state accessor better * wip - box * box done * fix params_builder * chore(python/algokit_transact): bump version to 1.0.0-alpha.62 [skip ci] * fix up the app client * wip - fix simulate * fix simulate + send params * clean up compilation.rs * remove extract_abi_return_from_result * wip - fixing tests * wip - resolve compile error app_client tests * wip - fixing tests * chore: add default signer support to AppClientParams * wip - structs * fix field type + encode/decode logic * test * convert storage key to abi storage key * convert storage map to abi storage map * convert box to use abi storage key * fix build * wip- struct in default value * convert default value * fix up - it builds now * wip - fixing tests --------- Co-authored-by: engineering-ci[bot] <179917785+engineering-ci[bot]@users.noreply.github.com> Co-authored-by: Neil Campbell <[email protected]> Co-authored-by: Altynbek Orumbayev <[email protected]>

…account for TransactionWithSigner Ensure transaction-typed ABI args inherit the method signer when not explicitly set

crates/algokit_utils/src/applications/app_client/params_builder.rs

crates/algokit_utils/src/applications/app_client/sender.rs

crates/algokit_utils/src/applications/app_factory/compilation.rs

crates/algokit_utils/src/applications/app_factory/params_builder.rs

crates/algokit_utils/src/applications/app_factory/types.rs

crates/algokit_utils/src/applications/app_factory/transaction_sender.rs

crates/algokit_utils/src/applications/app_factory/sender.rs

PatrickDinh · 2025-09-22T00:34:18Z

crates/algokit_utils/src/applications/app_factory/types.rs

+
+#[derive(Clone, Debug)]
+pub struct AppFactoryMethodCallResult<T> {
+    inner: T,


For other part of the project, we are moving away from using nested structs, especially for public facing structs. For example, in this PR I removed the common_params from the send result. Do you think that we should do the same here too?

AppFactoryMethodCallResult acts as a thin wrapper on top of SendAppResult type plus adds the parsed arc56 returns. The derefs below the lines you mentioned ensure that everything from SendAppResult is accessible from the root of the AppFactoryMethodCallResult - the user does not have to do extra hops to .inner in this case. So not sure we want to tweak it since all send result fields are immediately accessible

TIL about the power of deref. However, This section from the Rust docs makes me wonder if this is suitable for public facing types.

When to implement Deref or DerefMut The same advice applies to both deref traits. In general, deref traits should be implemented if: a value of the type transparently behaves like a value of the target type; the implementation of the deref function is cheap; and users of the type will not be surprised by any deref coercion behavior. In general, deref traits should not be implemented if: the deref implementations could fail unexpectedly; or the type has methods that are likely to collide with methods on the target type; or committing to deref coercion as part of the public API is not desirable.

Especially this bit or committing to deref coercion as part of the public API is not desirable.

I am fairly new to Rust but deref seems to create a hidden API surface. For example, I didn't know about it until you pointed out to me that I could access everything inside inner because the AppFactoryMethodCallResult implement the deref trait.
What do you think?

considering that common params are removed in app client result types in https://github.com/algorandfoundation/algokit-core/pull/260/files - i considered using a macro for the app factory return types but ultimately the only change needed is extra arc56_return abivalue field - i ended up redeclaring fields instead of using deref or a macro

I agree, this is the most pragmatic approach

crates/algokit_utils/src/applications/app_factory/transaction_sender.rs

crates/algokit_utils/src/applications/app_factory/sender.rs

crates/algokit_utils/src/applications/app_factory/transaction_builder.rs

crates/algokit_utils/src/applications/app_factory/mod.rs

…_templates

crates/algokit_utils/src/applications/app_factory/compilation.rs

crates/algokit_utils/src/applications/app_factory/transaction_builder.rs

crates/algokit_utils/src/applications/app_factory/mod.rs

crates/algokit_utils/src/applications/app_factory/transaction_sender.rs

crates/algokit_utils/src/applications/app_factory/mod.rs

PatrickDinh · 2025-09-23T01:12:24Z

crates/algokit_utils/src/transactions/composer.rs

+    fn signer_mut(&mut self) -> &mut Option<Arc<dyn TransactionSigner>>;
+}
+
+fn set_default_signer_if_missing(


nitpick: maybe a better name for this method is set_signer_if_missing

renamed to set_method_signer_if_missing which i think is slightly more explicit lmk if you are ok with this

PatrickDinh · 2025-09-23T01:33:02Z

crates/algokit_utils/src/applications/app_factory/types.rs

+
+#[derive(Clone, Debug)]
+pub struct AppFactoryMethodCallResult<T> {
+    inner: T,


TIL about the power of deref. However, This section from the Rust docs makes me wonder if this is suitable for public facing types.

When to implement Deref or DerefMut The same advice applies to both deref traits. In general, deref traits should be implemented if: a value of the type transparently behaves like a value of the target type; the implementation of the deref function is cheap; and users of the type will not be surprised by any deref coercion behavior. In general, deref traits should not be implemented if: the deref implementations could fail unexpectedly; or the type has methods that are likely to collide with methods on the target type; or committing to deref coercion as part of the public API is not desirable.

Especially this bit or committing to deref coercion as part of the public API is not desirable.

I am fairly new to Rust but deref seems to create a hidden API surface. For example, I didn't know about it until you pointed out to me that I could access everything inside inner because the AppFactoryMethodCallResult implement the deref trait.
What do you think?

engineering-ci · 2025-09-26T09:45:17Z

🎉 This PR is included in version 1.0.0-alpha.68 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

aorumbayev changed the title ~~feat: app factory initial version~~ feat: app factory Sep 2, 2025

aorumbayev marked this pull request as ready for review September 2, 2025 22:35

aorumbayev requested a review from a team as a code owner September 2, 2025 22:35

aorumbayev requested review from a team, lempira and neilcampbell and removed request for a team September 2, 2025 22:35

aorumbayev force-pushed the feat/application-client branch from 6a166c7 to 6d27d07 Compare September 3, 2025 21:57

aorumbayev force-pushed the feat/app-factory branch from 30ec996 to ae01c00 Compare September 3, 2025 22:04

aorumbayev requested a review from Copilot September 3, 2025 22:05

Copilot AI reviewed Sep 3, 2025

View reviewed changes

aorumbayev force-pushed the feat/application-client branch from 1be959c to fb7ee7f Compare September 4, 2025 16:20

aorumbayev force-pushed the feat/app-factory branch from ae01c00 to d9de8df Compare September 4, 2025 16:28

aorumbayev mentioned this pull request Sep 4, 2025

feat: app client #236

Merged

aorumbayev and others added 9 commits September 12, 2025 00:15

feat: app client and initial batch of tests transpiled from py

4ccf619

chore: fix merge conflicts against main; refine common fixture usage

07d6863

feat: config singleton and event emitter

46871f7

chore: minor comments

0c04a92

chore: pr comments

78abbb6

refactor: addressing pr comments

9c577ae

refactor: add native struct support to abi crate; refine abi handling…

9406350

… in app client; more tests

chore: merge conflicts and clippy warning fixes

092606d

aorumbayev force-pushed the feat/application-client branch from afe47d6 to 092606d Compare September 11, 2025 22:32

aorumbayev added 6 commits September 12, 2025 17:20

tests: app client state access tests;

d33f36d

fix(composer): propagate method-level signer to transaction args and …

18323a0

…account for TransactionWithSigner Ensure transaction-typed ABI args inherit the method signer when not explicitly set

fix: add missing signer fields to app call params

0253ba6

chore: wip more tests

06e8ec6

chore: wip

b69acb1

chore: refining logic error handling; additional app client tests

4646499

chore: merge conflicts wip

226315d

aorumbayev force-pushed the feat/app-factory branch from 7d7e0f2 to 4c1741d Compare September 19, 2025 11:02

chore: refining appfactory

94dc537

aorumbayev force-pushed the feat/app-factory branch from 4c1741d to 94dc537 Compare September 19, 2025 12:15

aorumbayev requested a review from PatrickDinh September 19, 2025 12:49

aorumbayev marked this pull request as ready for review September 19, 2025 12:53

chore: remove panic statements from factory tests

29cef4c

aorumbayev force-pushed the feat/app-factory branch from 8f334f6 to 29cef4c Compare September 19, 2025 17:56

PatrickDinh reviewed Sep 22, 2025

View reviewed changes

aorumbayev added 8 commits September 22, 2025 11:53

fix(app_client): propagate compiled programs across update flows

ba8ef54

fix(app_factory): align default handling and client factory API

f0e9892

refactor(app_factory): simplify factory send/builder create flow

e669cc9

refactor: tweak default handling and sender bindings in factory

f44bc23

refactor: move teal decoding into arc56 contract; refine compile_teal…

a2b46b3

…_templates

refactor: ensure abi errors are propagated properly in factory

848dcdf

refactor: rename sender to transaction_sender in factory and client

0d08308

refactor: pr comments and additional docstrings

41605ec

aorumbayev requested a review from PatrickDinh September 22, 2025 16:44

refactor: adding separate logicerror context for reuse in app factory

5e54f61

aorumbayev force-pushed the feat/app-factory branch from caad694 to 5e54f61 Compare September 22, 2025 16:44

PatrickDinh reviewed Sep 23, 2025

View reviewed changes

aorumbayev force-pushed the feat/app-factory branch from 57792e3 to 41ef7a8 Compare September 23, 2025 08:54

refactor: remaining pr comments

f1fea56

aorumbayev force-pushed the feat/app-factory branch from 41ef7a8 to f1fea56 Compare September 23, 2025 09:01

PatrickDinh approved these changes Sep 23, 2025

View reviewed changes

aorumbayev merged commit c10195d into main Sep 23, 2025
14 checks passed

aorumbayev deleted the feat/app-factory branch September 23, 2025 10:32

engineering-ci bot added the released on @main label Sep 26, 2025

feat: app factory #248

feat: app factory #248

Uh oh!

Conversation

aorumbayev commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PatrickDinh Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

aorumbayev Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

PatrickDinh Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

aorumbayev Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

PatrickDinh Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PatrickDinh Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

aorumbayev Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PatrickDinh Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

engineering-ci bot commented Sep 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aorumbayev commented Sep 2, 2025 •

edited

Loading

aorumbayev Sep 23, 2025 •

edited

Loading