fix: minor improvements based on internal feedback

docs/markdown/autoapi/algokit_utils/accounts/account_manager/index.md

@@ -234,7 +234,7 @@ Returns the TransactionSignerAccountProtocol for the given sender address.
 * **Example:**
 
 ```pycon
->>> sender = account_manager.random()
+>>> sender = account_manager.random().address
 >>> # ...
 >>> # Returns the `TransactionSignerAccountProtocol` for `sender` that has previously been registered
 >>> account = account_manager.get_account(sender)

docs/markdown/autoapi/algokit_utils/applications/app_factory/index.md

@@ -2,16 +2,16 @@
 
 ## Classes
 
-| [`AppFactoryParams`](#algokit_utils.applications.app_factory.AppFactoryParams)                                           |                                                     |
-|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
-| [`AppFactoryCreateParams`](#algokit_utils.applications.app_factory.AppFactoryCreateParams)                               | Schema for application creation.                    |
-| [`AppFactoryCreateMethodCallParams`](#algokit_utils.applications.app_factory.AppFactoryCreateMethodCallParams)           | Schema for application creation.                    |
-| [`AppFactoryCreateMethodCallResult`](#algokit_utils.applications.app_factory.AppFactoryCreateMethodCallResult)           | Base class for transaction results.                 |
-| [`SendAppFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppFactoryTransactionResult)             | Result of an application transaction.               |
-| [`SendAppUpdateFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppUpdateFactoryTransactionResult) | Result of updating an application.                  |
-| [`SendAppCreateFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppCreateFactoryTransactionResult) | Result of creating a new application.               |
-| [`AppFactoryDeployResult`](#algokit_utils.applications.app_factory.AppFactoryDeployResult)                               | Result from deploying an application via AppFactory |
-| [`AppFactory`](#algokit_utils.applications.app_factory.AppFactory)                                                       |                                                     |
+| [`AppFactoryParams`](#algokit_utils.applications.app_factory.AppFactoryParams)                                           |                                                      |
+|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
+| [`AppFactoryCreateParams`](#algokit_utils.applications.app_factory.AppFactoryCreateParams)                               | Parameters for creating application with bare call.  |
+| [`AppFactoryCreateMethodCallParams`](#algokit_utils.applications.app_factory.AppFactoryCreateMethodCallParams)           | Parameters for creating application with method call |
+| [`AppFactoryCreateMethodCallResult`](#algokit_utils.applications.app_factory.AppFactoryCreateMethodCallResult)           | Base class for transaction results.                  |
+| [`SendAppFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppFactoryTransactionResult)             | Result of an application transaction.                |
+| [`SendAppUpdateFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppUpdateFactoryTransactionResult) | Result of updating an application.                   |
+| [`SendAppCreateFactoryTransactionResult`](#algokit_utils.applications.app_factory.SendAppCreateFactoryTransactionResult) | Result of creating a new application.                |
+| [`AppFactoryDeployResult`](#algokit_utils.applications.app_factory.AppFactoryDeployResult)                               | Result from deploying an application via AppFactory  |
+| [`AppFactory`](#algokit_utils.applications.app_factory.AppFactory)                                                       |                                                      |
 
 ## Module Contents
 
@@ -33,23 +33,17 @@
 
 ### *class* algokit_utils.applications.app_factory.AppFactoryCreateParams
 
-Bases: `_AppFactoryCreateBaseParams`, [`algokit_utils.applications.app_client.AppClientBareCallParams`](../app_client/index.md#algokit_utils.applications.app_client.AppClientBareCallParams)
+Bases: [`algokit_utils.applications.app_client.AppClientBareCallCreateParams`](../app_client/index.md#algokit_utils.applications.app_client.AppClientBareCallCreateParams)
 
-Schema for application creation.
+Parameters for creating application with bare call.
 
-* **Variables:**
-  * **extra_program_pages** – Optional number of extra program pages
-  * **schema** – Optional application creation schema
+#### on_complete *: algokit_utils.applications.app_client.CreateOnComplete | None* *= None*
 
 ### *class* algokit_utils.applications.app_factory.AppFactoryCreateMethodCallParams
 
-Bases: `_AppFactoryCreateBaseParams`, [`algokit_utils.applications.app_client.AppClientMethodCallParams`](../app_client/index.md#algokit_utils.applications.app_client.AppClientMethodCallParams)
+Bases: [`algokit_utils.applications.app_client.AppClientMethodCallCreateParams`](../app_client/index.md#algokit_utils.applications.app_client.AppClientMethodCallCreateParams)
 
-Schema for application creation.
-
-* **Variables:**
-  * **extra_program_pages** – Optional number of extra program pages
-  * **schema** – Optional application creation schema
+Parameters for creating application with method call
 
 ### *class* algokit_utils.applications.app_factory.AppFactoryCreateMethodCallResult
 

docs/markdown/autoapi/algokit_utils/models/amount/index.md

@@ -1,26 +1,45 @@
 # algokit_utils.models.amount
 
+## Attributes
+
+| [`ALGORAND_MIN_TX_FEE`](#algokit_utils.models.amount.ALGORAND_MIN_TX_FEE)   |    |
+|-----------------------------------------------------------------------------|----|
+
 ## Classes
 
 | [`AlgoAmount`](#algokit_utils.models.amount.AlgoAmount)   | Wrapper class to ensure safe, explicit conversion between µAlgo, Algo and numbers.   |
 |-----------------------------------------------------------|--------------------------------------------------------------------------------------|
 
+## Functions
+
+| [`algo`](#algokit_utils.models.amount.algo)(→ AlgoAmount)                         | Create an AlgoAmount object representing the given number of Algo.       |
+|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------|
+| [`micro_algo`](#algokit_utils.models.amount.micro_algo)(→ AlgoAmount)             | Create an AlgoAmount object representing the given number of µAlgo.      |
+| [`transaction_fees`](#algokit_utils.models.amount.transaction_fees)(→ AlgoAmount) | Calculate the total transaction fees for a given number of transactions. |
+
 ## Module Contents
 
-### *class* algokit_utils.models.amount.AlgoAmount(amount: dict[str, int | decimal.Decimal])
+### *class* algokit_utils.models.amount.AlgoAmount(\*, micro_algos: int)
+
+### *class* algokit_utils.models.amount.AlgoAmount(\*, micro_algo: int)
+
+### *class* algokit_utils.models.amount.AlgoAmount(\*, algos: int | decimal.Decimal)
+
+### *class* algokit_utils.models.amount.AlgoAmount(\*, algo: int | decimal.Decimal)
 
 Wrapper class to ensure safe, explicit conversion between µAlgo, Algo and numbers.
 
-* **Parameters:**
-  **amount** – A dictionary containing either algos, algo, microAlgos, or microAlgo as key
-  and their corresponding value as an integer or Decimal.
-* **Raises:**
-  **ValueError** – If an invalid amount format is provided.
 * **Example:**
 
 ```pycon
->>> amount = AlgoAmount({"algos": 1})
->>> amount = AlgoAmount({"microAlgos": 1_000_000})
+>>> amount = AlgoAmount(algos=1)
+>>> amount = AlgoAmount(algo=1)
+>>> amount = AlgoAmount.from_algos(1)
+>>> amount = AlgoAmount.from_algo(1)
+>>> amount = AlgoAmount(micro_algos=1_000_000)
+>>> amount = AlgoAmount(micro_algo=1_000_000)
+>>> amount = AlgoAmount.from_micro_algos(1_000_000)
+>>> amount = AlgoAmount.from_micro_algo(1_000_000)
 ```
 
 #### *property* micro_algos *: int*
@@ -106,3 +125,32 @@ Create an AlgoAmount object representing the given number of µAlgo.
 ```pycon
 >>> amount = AlgoAmount.from_micro_algo(1_000_000)
 ```
+
+### algokit_utils.models.amount.algo(algos: int) → [AlgoAmount](#algokit_utils.models.amount.AlgoAmount)
+
+Create an AlgoAmount object representing the given number of Algo.
+
+* **Parameters:**
+  **algos** – The number of Algo to create an AlgoAmount object for.
+* **Returns:**
+  An AlgoAmount object representing the given number of Algo.
+
+### algokit_utils.models.amount.micro_algo(microalgos: int) → [AlgoAmount](#algokit_utils.models.amount.AlgoAmount)
+
+Create an AlgoAmount object representing the given number of µAlgo.
+
+* **Parameters:**
+  **microalgos** – The number of µAlgo to create an AlgoAmount object for.
+* **Returns:**
+  An AlgoAmount object representing the given number of µAlgo.
+
+### algokit_utils.models.amount.ALGORAND_MIN_TX_FEE
+
+### algokit_utils.models.amount.transaction_fees(number_of_transactions: int) → [AlgoAmount](#algokit_utils.models.amount.AlgoAmount)
+
+Calculate the total transaction fees for a given number of transactions.
+
+* **Parameters:**
+  **number_of_transactions** – The number of transactions to calculate the fees for.
+* **Returns:**
+  The total transaction fees.

docs/markdown/capabilities/amount.md

@@ -21,10 +21,10 @@ from algokit_utils import AlgoAmount
 There are a few ways to create an `AlgoAmount`:
 
 - Algo
-  - Constructor: `AlgoAmount({"algo": 10})` or `AlgoAmount({"algos": 10})`
+  - Constructor: `AlgoAmount(algo=10)` or `AlgoAmount(algos=10)`
   - Static helper: `AlgoAmount.from_algo(10)` or `AlgoAmount.from_algos(10)`
 - microAlgo
-  - Constructor: `AlgoAmount({"microAlgo": 10_000})` or `AlgoAmount({"microAlgos": 10_000})`
+  - Constructor: `AlgoAmount(micro_algo=10_000)` or `AlgoAmount(micro_algos=10_000)`
   - Static helper: `AlgoAmount.from_micro_algo(10_000)` or `AlgoAmount.from_micro_algos(10_000)`
 
 ### Extracting a value from `AlgoAmount`
@@ -49,7 +49,7 @@ The `AlgoAmount` class supports arithmetic operations:
 Example:
 
 ```python
-amount1 = AlgoAmount({"algo": 1})
-amount2 = AlgoAmount({"microAlgo": 500_000})
+amount1 = AlgoAmount(algo=1)
+amount2 = AlgoAmount(micro_algo=500_000)
 total = amount1 + amount2  # Results in 1.5 Algo
 ```

docs/markdown/v3-migration-guide.md

@@ -149,71 +149,41 @@ arc56_app_spec = Arc56Contract.from_arc32(testing_app_arc32_app_spec)
 
 > Despite auto conversion of ARC-32 to ARC-56, we recommend recompiling your contract to a fully compliant ARC-56 specification given that auto conversion would skip populating information that can’t be parsed from raw ARC-32.
 
-### Step 5 - Update `ApplicationClient` usage
+### Step 5 - Replace `ApplicationClient` usage
 
-The application client has been in v2 has been responsible for instantiation, deployment and calling of the application. In v3, this has been split into `AppClient`, `AppDeployer` and `AppFactory` to better reflect the different responsibilities:
+The existing `ApplicationClient` (untyped app client) class is still present until at least v4, but it’s worthwhile migrating to the new [`AppClient` and `AppFactory` classes](capabilities/app-client.md). These new clients are [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) compatible, but also support [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) app specs and will continue to support this indefinitely until such time the community deems they are deprecated.
 
-```python
-"""Before (v2 deployment)"""
-from algokit_utils import ApplicationClient, OnUpdate, OnSchemaBreak
-
-# Initialize client with manual configuration
-app_client = ApplicationClient(
-    algod_client=algod,
-    app_spec=app_spec,
-    creator=creator,
-    app_name="MyApp"
-)
-
-# Deployment with versioning and update policies
-deploy_result = app_client.deploy(
-    version="1.0",
-    allow_update=True,
-    allow_delete=False,
-    on_update=OnUpdate.UpdateApp,
-    on_schema_break=OnSchemaBreak.Fail
-)
+All of the functionality in `ApplicationClient` is available within the new classes, but their interface is slightly different to make it easier to use and more consistent with the new `AlgorandClient` functionality. The key existing methods that have changed all have `@deprecation` notices to help guide you on this, but broadly the changes are:
 
-# Post-deployment calls
-response = app_client.call("initialize", args=["config"])
+- The app resolution semantics, now have static methods that determine different ways of constructing a client and the constructor itself is very simple (requiring `app_id`)
+- If you want to call `create` or `deploy` then you need an `AppFactory` to do that, and then it will in turn give you an `AppClient` instance that is connected to the app you just created / deployed. This significantly simplifies the app client because now the app client has a clear operating purpose: allow for calls and state management for an *instance* of an app, whereas the app factory handles all of the calls when you don’t have an instance yet (or may or may not have an instance in the case of `deploy`).
+- This means that you can simply access `client.app_id` and `client.app_address` on `AppClient` since these values are known statically and won’t change (previously associated calls to `app_address`, `app_id` properties potentially required extra API calls as the values weren’t always available).
+- Adding `fund_app_account` which serves as a convenience method to top up the balance of address associated with application.
+- All of the methods that return or execute a transaction (`update`, `call`, `opt_in`, etc.) are now exposed in an interface similar to the one in [`AlgorandClient`](capabilities/algorand-client.md#creating-and-issuing-transactions), namely (where `{call_type}` is one of: `update` / `delete` / `opt_in` / `close_out` / `clear_state` / `call`):
+  - `appClient.create_transaction.{callType}` to get a transaction for an ABI method call
+  - `appClient.send.{call_type}` to sign and send a transaction for an ABI method call
+  - `appClient.params.{call_type}` to get a [params object](capabilities/algorand-client.md#transaction-parameters) for an ABI method call
+  - `appClient.create_transaction.bare.{call_type}` to get a transaction for a bare app call
+  - `appClient.send.bare.{call_type}` to sign and send a transaction for a bare app call
+  - `appClient.params.bare.{call_type}` to get a [params object](capabilities/algorand-client.md#transaction-parameters) for a bare app call
+- The semantics to resolve the application is now available via [simpler entrypoints within `algorand.client`](capabilities/app-client.md#appclient)
+- When making an ABI method call, the method arguments property is are now passed via explicit `args` field in a parameters dataclass applicable to the method call.
+- The foreign reference arrays have been renamed to align with typed parameters on `ts` and related core `algosdk`:
+  - `boxes` -> `box_references`
+  - `apps` -> `app_references`
+  - `assets` -> `asset_references`
+  - `accounts` -> `account_references`
+- The return value for methods that send a transaction will have any ABI return value directly in the `abi_return` property rather than the low level algosdk `ABIResult` type while also automatically decoding values based on provided ARC56 spec.
 
+### Step 6 - Replace typed app client usage
 
-"""After (v3 factory-based deployment)"""
-from algokit_utils import AppFactory, OnUpdate, OnSchemaBreak
-
-# Factory-based deployment with compiled parameters
-app_factory = AppFactory(
-    AppFactoryParams(
-        algorand=algorand,
-        app_spec=app_spec,
-        app_name="MyApp",
-        compilation_params=AppClientCompilationParams(
-            deploy_time_params={"VERSION": 1},
-            updatable=True,  # Replaces allow_update
-            deletable=False  # Replaces allow_delete
-        )
-    )
-)
-
-app_client, deploy_result = app_factory.deploy(
-    version="1.0",
-    on_update=OnUpdate.UpdateApp,
-    on_schema_break=OnSchemaBreak.Fail,
-) # Returns a tuple of (app_client, deploy_result)
-
-# Type-safe post-deployment calls
-response = app_client.send.call("setup", args=[{"max_users": 100}])
-```
+Version 2 of the Python typed app client generator introduces breaking changes to the generated client that support the new `AppFactory` and `AppClient` functionality along with adding ARC-56 support. The generated client has better typing support for things like state commensurate with the new capabilities within ARC-56.
 
-Notable changes:
+It’s worth noting that because we have maintained backwards compatibility with the pre v2 `algokit-utils-py` stateless functions, older typed clients generated using version 1 of the Python typed client generator will work against v3 of utils, however you won’t have access to the new features or ARC-56 support.
 
-- Split between `AppClient`, `AppDeployer` (for raw creation/deployment) and `AppFactory` (for creation/deployment using factory patterns). In majority of cases, you will only need `AppFactory` as it provides convenience methods for instantiation of `AppClient` and mediates calls to `AppDeployer`.
-- More structured transaction building with `.params`, `.create_transaction`, and `.send`
-- Consistent parameter naming (`args` instead of `method_args`, `box_references` instead of `boxes`)
-- ARC-56 support for state management
-- Improved error handling and debugging support
+If you want to convert from an older typed client to a new one you will need to make certain changes. Refer to [client generator v2 migration guide](https://github.com/algorandfoundation/algokit-client-generator-py/blob/main/docs/v2-migration.md).
 
-### Step 6 - Update `AppClient` State Management
+### Step 7 - Update `AppClient` State Management
 
 State management is now more structured and type-safe:
 
@@ -240,7 +210,7 @@ boxes = app_client.state.box.get_all()
 map_value = app_client.state.box.get_map_value("map_name", "key")
 ```
 
-### Step 7 - Update Asset Management
+### Step 8 - Update Asset Management
 
 Asset management is now more consistent:
 

docs/source/capabilities/amount.md

@@ -21,10 +21,10 @@ from algokit_utils import AlgoAmount
 There are a few ways to create an `AlgoAmount`:
 
 - Algo
-  - Constructor: `AlgoAmount({"algo": 10})` or `AlgoAmount({"algos": 10})`
+  - Constructor: `AlgoAmount(algo=10)` or `AlgoAmount(algos=10)`
   - Static helper: `AlgoAmount.from_algo(10)` or `AlgoAmount.from_algos(10)`
 - microAlgo
-  - Constructor: `AlgoAmount({"microAlgo": 10_000})` or `AlgoAmount({"microAlgos": 10_000})`
+  - Constructor: `AlgoAmount(micro_algo=10_000)` or `AlgoAmount(micro_algos=10_000)`
   - Static helper: `AlgoAmount.from_micro_algo(10_000)` or `AlgoAmount.from_micro_algos(10_000)`
 
 ### Extracting a value from `AlgoAmount`
@@ -49,7 +49,7 @@ The `AlgoAmount` class supports arithmetic operations:
 Example:
 
 ```python
-amount1 = AlgoAmount({"algo": 1})
-amount2 = AlgoAmount({"microAlgo": 500_000})
+amount1 = AlgoAmount(algo=1)
+amount2 = AlgoAmount(micro_algo=500_000)
 total = amount1 + amount2  # Results in 1.5 Algo
 ```