fix: algosdk configs respecting port field; Edge case for auto fee handling for readonly calls

Author: aorumbayev

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

@@ -15,11 +15,11 @@ Connection details for connecting to an {py:class}\`algosdk.v2client.algod.Algod
 
 #### server *: str*
 
-URL for the service e.g. http://localhost:4001 or https://testnet-api.algonode.cloud
+URL for the service e.g. http://localhost or https://testnet-api.algonode.cloud
 
 #### token *: str | None* *= None*
 
-API Token to authenticate with the service
+API Token to authenticate with the service e.g ‘4001’ or ‘8980’
 
 #### port *: str | int | None* *= None*
 

docs/markdown/autoapi/algokit_utils/transactions/transaction_composer/index.md

@@ -819,7 +819,7 @@ Simulate transaction group execution with configurable validation rules.
 * **Parameters:**
   * **allow_more_logs** – Whether to allow more logs than the standard limit
   * **allow_empty_signatures** – Whether to allow transactions with empty signatures
-  * **allow_unnamed_resources** – Whether to allow unnamed resources
+  * **allow_unnamed_resources** – Whether to allow unnamed resources.
   * **extra_opcode_budget** – Additional opcode budget to allocate
   * **exec_trace_config** – Configuration for execution tracing
   * **simulation_round** – Round number to simulate at

docs/markdown/capabilities/transaction-composer.md

@@ -226,3 +226,120 @@ This feature is particularly useful when:
 - Developing applications where resource requirements may change dynamically
 
 Note: Resource population uses simulation under the hood to detect required resources, so it may add a small overhead to transaction preparation time.
+
+### Covering App Call Inner Transaction Fees
+
+`cover_app_call_inner_transaction_fees` automatically calculate the required fee for a parent app call transaction that sends inner transactions. It leverages the simulate endpoint to discover the inner transactions sent and calculates a fee delta to resolve the optimal fee. This feature also takes care of accounting for any surplus transaction fee at the various levels, so as to effectively minimise the fees needed to successfully handle complex scenarios. This setting only applies when you have constucted at least one app call transaction.
+
+For example:
+
+```python
+myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
+result = algorand
+  .new_group()
+  .add_app_call_method_call(AppCallMethodCallParams(
+    sender: 'SENDER',
+    app_id=123,
+    method=myMethod,
+    args=[1, 2, 3],
+    max_fee=AlgoAmount.from_micro_algo(5000), # NOTE: a maxFee value is required when enabling coverAppCallInnerTransactionFees
+  ))
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+```
+
+Assuming the app account is not covering any of the inner transaction fees, if `my_method` in the above example sends 2 inner transactions, then the fee calculated for the parent transaction will be 3000 µALGO when the transaction is sent to the network.
+
+The above example also has a `max_fee` of 5000 µALGO specified. An exception will be thrown if the transaction fee execeeds that value, which allows you to set fee limits. The `max_fee` field is required when enabling `cover_app_call_inner_transaction_fees`.
+
+Because `max_fee` is required and an `algosdk.Transaction` does not hold any max fee information, you cannot use the generic `add_transaction()` method on the composer with `cover_app_call_inner_transaction_fees` enabled. Instead use the below, which provides a better overall experience:
+
+```python
+my_method = algosdk.abi.Method.from_signature('my_method()void')
+
+# Does not work
+result = algorand
+  .new_group()
+  .add_transaction(localnet.algorand.create_transaction.app_call_method_call(
+    AppCallMethodCallParams(
+        sender='SENDER',
+        app_id=123,
+        method=my_method,
+        args=[1, 2, 3],
+        max_fee=AlgoAmount.from_micro_algos(5000), # This is only used to create the algosdk.Transaction object and isn't made available to the composer.
+      )
+    ).transactions[0]
+  )
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+
+# Works as expected
+result = algorand
+  .new_group()
+  .add_app_call_method_call(AppCallMethodCallParams(
+    sender='SENDER',
+    app_id=123,
+    method=my_method,
+    args=[1, 2, 3],
+    max_fee=AlgoAmount.from_micro_algos(5000),
+  ))
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+```
+
+A more complex valid scenario which leverages an app client to send an ABI method call with ABI method call transactions argument is below:
+
+```python
+app_factory = algorand.client.get_app_factory(
+  app_spec='APP_SPEC',
+  default_sender=sender.addr,
+)
+
+app_client_1, _ = app_factory.send.bare.create()
+app_client_2, _ = app_factory.send.bare.create()
+
+payment_arg = algorand.create_transaction.payment(
+  PaymentParams(
+    sender=sender.addr,
+    receiver=receiver.addr,
+    amount=AlgoAmount.from_micro_algos(1),
+  )
+)
+
+# Note the use of .params. here, this ensure that maxFee is still available to the composer
+app_call_arg = app_client_2.params.call(
+  AppCallMethodCallParams(
+    method='my_other_method',
+    args=[],
+    max_fee=AlgoAmount.from_micro_algos(2000),
+  )
+)
+
+result = app_client_1.algorand
+  .new_group()
+  .add_app_call_method_call(
+    app_client_1.params.call(
+      AppClientMethodCallParams(
+        method='my_method',
+        args=[payment_arg, app_call_arg],
+        max_fee=AlgoAmount.from_micro_algos(5000),
+      )
+    ),
+  )
+  .send({"cover_app_call_inner_transaction_fees": True})
+```
+
+This feature should efficiently calculate the minimum fee needed to execute an app call transaction with inners, however we always recommend testing your specific scenario behaves as expected before releasing.
+
+#### Read-only calls
+
+When interacting with read-only calls, the transactions are not sent to the network, instead a simulation is performed to evaluate the transaction.
+However, a read-only call will still consume the op budget, so to prevent this, by the default, the following logic is applied:
+
+1. If `max_fee` is not specified, `algokit-utils` will automatically set `max_fee` to `10` Algo.
+2. If `max_fee` is specified, provided `max_fee` value will be respected when calculating required fee per read-only call.
+
+In either cases, resource population and app call inner transaction fees will still be automatically calculated and applied as per the rules above however there is no need to explicitly specify `populate_app_call_resources=True` or `cover_app_call_inner_transaction_fees=True` when sending read-only calls.
+
+### Covering App Call Op Budget
+
+The high level Algorand contract authoring languages all have support for ensuring appropriate app op budget is available via `ensure_budget` in Algorand Python, `ensureBudget` in Algorand TypeScript and `increaseOpcodeBudget` in TEALScript. This is great, as it allows contract authors to ensure appropriate budget is available by automatically sending op-up inner transactions to increase the budget available. These op-up inner transactions require the fees to be covered by an account, which is generally the responsibility of the application consumer.
+
+Application consumers may not be immediately aware of the number of op-up inner transactions sent, so it can be difficult for them to determine the exact fees required to successfully execute an application call. Fortunately the `cover_app_call_inner_transaction_fees` setting above can be leveraged to automatically cover the fees for any op-up inner transaction that an application sends. Additionally if a contract author decides to cover the fee for an op-up inner transaction, then the application consumer will not be charged a fee for that transaction.

docs/source/capabilities/transaction-composer.md

@@ -226,3 +226,120 @@ This feature is particularly useful when:
 - Developing applications where resource requirements may change dynamically
 
 Note: Resource population uses simulation under the hood to detect required resources, so it may add a small overhead to transaction preparation time.
+
+### Covering App Call Inner Transaction Fees
+
+`cover_app_call_inner_transaction_fees` automatically calculate the required fee for a parent app call transaction that sends inner transactions. It leverages the simulate endpoint to discover the inner transactions sent and calculates a fee delta to resolve the optimal fee. This feature also takes care of accounting for any surplus transaction fee at the various levels, so as to effectively minimise the fees needed to successfully handle complex scenarios. This setting only applies when you have constucted at least one app call transaction.
+
+For example:
+
+```python
+myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
+result = algorand
+  .new_group()
+  .add_app_call_method_call(AppCallMethodCallParams(
+    sender: 'SENDER',
+    app_id=123,
+    method=myMethod,
+    args=[1, 2, 3],
+    max_fee=AlgoAmount.from_micro_algo(5000), # NOTE: a maxFee value is required when enabling coverAppCallInnerTransactionFees
+  ))
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+```
+
+Assuming the app account is not covering any of the inner transaction fees, if `my_method` in the above example sends 2 inner transactions, then the fee calculated for the parent transaction will be 3000 µALGO when the transaction is sent to the network.
+
+The above example also has a `max_fee` of 5000 µALGO specified. An exception will be thrown if the transaction fee execeeds that value, which allows you to set fee limits. The `max_fee` field is required when enabling `cover_app_call_inner_transaction_fees`.
+
+Because `max_fee` is required and an `algosdk.Transaction` does not hold any max fee information, you cannot use the generic `add_transaction()` method on the composer with `cover_app_call_inner_transaction_fees` enabled. Instead use the below, which provides a better overall experience:
+
+```python
+my_method = algosdk.abi.Method.from_signature('my_method()void')
+
+# Does not work
+result = algorand
+  .new_group()
+  .add_transaction(localnet.algorand.create_transaction.app_call_method_call(
+    AppCallMethodCallParams(
+        sender='SENDER',
+        app_id=123,
+        method=my_method,
+        args=[1, 2, 3],
+        max_fee=AlgoAmount.from_micro_algos(5000), # This is only used to create the algosdk.Transaction object and isn't made available to the composer.
+      )
+    ).transactions[0]
+  )
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+
+# Works as expected
+result = algorand
+  .new_group()
+  .add_app_call_method_call(AppCallMethodCallParams(
+    sender='SENDER',
+    app_id=123,
+    method=my_method,
+    args=[1, 2, 3],
+    max_fee=AlgoAmount.from_micro_algos(5000),
+  ))
+  .send(send_params={"cover_app_call_inner_transaction_fees": True})
+```
+
+A more complex valid scenario which leverages an app client to send an ABI method call with ABI method call transactions argument is below:
+
+```python
+app_factory = algorand.client.get_app_factory(
+  app_spec='APP_SPEC',
+  default_sender=sender.addr,
+)
+
+app_client_1, _ = app_factory.send.bare.create()
+app_client_2, _ = app_factory.send.bare.create()
+
+payment_arg = algorand.create_transaction.payment(
+  PaymentParams(
+    sender=sender.addr,
+    receiver=receiver.addr,
+    amount=AlgoAmount.from_micro_algos(1),
+  )
+)
+
+# Note the use of .params. here, this ensure that maxFee is still available to the composer
+app_call_arg = app_client_2.params.call(
+  AppCallMethodCallParams(
+    method='my_other_method',
+    args=[],
+    max_fee=AlgoAmount.from_micro_algos(2000),
+  )
+)
+
+result = app_client_1.algorand
+  .new_group()
+  .add_app_call_method_call(
+    app_client_1.params.call(
+      AppClientMethodCallParams(
+        method='my_method',
+        args=[payment_arg, app_call_arg],
+        max_fee=AlgoAmount.from_micro_algos(5000),
+      )
+    ),
+  )
+  .send({"cover_app_call_inner_transaction_fees": True})
+```
+
+This feature should efficiently calculate the minimum fee needed to execute an app call transaction with inners, however we always recommend testing your specific scenario behaves as expected before releasing.
+
+#### Read-only calls
+
+When interacting with read-only calls, the transactions are not sent to the network, instead a simulation is performed to evaluate the transaction.
+However, a read-only call will still consume the op budget, so to prevent this, by the default, the following logic is applied:
+
+1. If `max_fee` is not specified, `algokit-utils` will automatically set `max_fee` to `10` Algo.
+2. If `max_fee` is specified, provided `max_fee` value will be respected when calculating required fee per read-only call.
+
+In either cases, resource population and app call inner transaction fees will still be automatically calculated and applied as per the rules above however there is no need to explicitly specify `populate_app_call_resources=True` or `cover_app_call_inner_transaction_fees=True` when sending read-only calls.
+
+### Covering App Call Op Budget
+
+The high level Algorand contract authoring languages all have support for ensuring appropriate app op budget is available via `ensure_budget` in Algorand Python, `ensureBudget` in Algorand TypeScript and `increaseOpcodeBudget` in TEALScript. This is great, as it allows contract authors to ensure appropriate budget is available by automatically sending op-up inner transactions to increase the budget available. These op-up inner transactions require the fees to be covered by an account, which is generally the responsibility of the application consumer.
+
+Application consumers may not be immediately aware of the number of op-up inner transactions sent, so it can be difficult for them to determine the exact fees required to successfully execute an application call. Fortunately the `cover_app_call_inner_transaction_fees` setting above can be leveraged to automatically cover the fees for any op-up inner transaction that an application sends. Additionally if a contract author decides to cover the fee for an op-up inner transaction, then the application consumer will not be charged a fee for that transaction.

src/algokit_utils/clients/client_manager.py

@@ -361,7 +361,7 @@ def get_algod_client(config: AlgoClientNetworkConfig | None = None) -> AlgodClie
         headers = {"X-Algo-API-Token": config.token or ""}
         return AlgodClient(
             algod_token=config.token or "",
-            algod_address=f'{config.server}{f':{config.port}' if config.port else ''}',
+            algod_address=config.full_url(),
             headers=headers,
         )
 
@@ -381,7 +381,7 @@ def get_kmd_client(config: AlgoClientNetworkConfig | None = None) -> KMDClient:
         :return: KMD client instance
         """
         config = config or _get_config_from_environment("KMD")
-        return KMDClient(config.token, f'{config.server}{f':{config.port}' if config.port else ''}')
+        return KMDClient(config.token, config.full_url())
 
     @staticmethod
     def get_kmd_client_from_environment() -> KMDClient:
@@ -402,7 +402,7 @@ def get_indexer_client(config: AlgoClientNetworkConfig | None = None) -> Indexer
         headers = {"X-Indexer-API-Token": config.token}
         return IndexerClient(
             indexer_token=config.token,
-            indexer_address=f'{config.server}{f":{config.port}" if config.port else ''}',
+            indexer_address=config.full_url(),
             headers=headers,
         )
 

src/algokit_utils/models/network.py

@@ -17,6 +17,10 @@ class AlgoClientNetworkConfig:
     """API Token to authenticate with the service e.g '4001' or '8980'"""
     port: str | int | None = None
 
+    def full_url(self) -> str:
+        """Returns the full URL for the service"""
+        return f"{self.server}{f':{self.port}' if self.port else ''}"
+
 
 @dataclasses.dataclass
 class AlgoClientConfigs:

src/algokit_utils/transactions/transaction_composer.py

@@ -614,6 +614,12 @@ class _TransactionWithPriority:
 NULL_SIGNER: TransactionSigner = algosdk.atomic_transaction_composer.EmptySigner()
 
 
+def _get_dummy_max_fees_for_simulated_opups(group_len: int) -> dict[int, AlgoAmount]:
+    from algokit_utils.models.amount import AlgoAmount
+
+    return {i: AlgoAmount(algo=10) for i in range(group_len)}
+
+
 def _encode_lease(lease: str | bytes | None) -> bytes | None:
     if lease is None:
         return None
@@ -801,16 +807,6 @@ def _num_extra_program_pages(approval: bytes | None, clear: bytes | None) -> int
     return max(0, (total - 1) // algosdk.constants.APP_PAGE_MAX_SIZE)
 
 
-def populate_app_call_resources(atc: AtomicTransactionComposer, algod: AlgodClient) -> AtomicTransactionComposer:
-    """Populate application call resources based on simulation results.
-
-    :param atc: The AtomicTransactionComposer containing transactions
-    :param algod: Algod client for simulation
-    :return: Modified AtomicTransactionComposer with populated resources
-    """
-    return prepare_group_for_sending(atc, algod, populate_app_call_resources=True)
-
-
 def prepare_group_for_sending(  # noqa: C901, PLR0912, PLR0915
     atc: AtomicTransactionComposer,
     algod: AlgodClient,
@@ -1600,6 +1596,8 @@ def build_transactions(self) -> BuiltTransactions:
                     signers[idx] = ts.signer
                 if isinstance(ts, TransactionWithSignerAndContext) and ts.context.abi_method:
                     method_calls[idx] = ts.context.abi_method
+                    if ts.context.max_fee:
+                        self._txn_max_fees[idx] = ts.context.max_fee
                 idx += 1
 
         return BuiltTransactions(transactions=transactions, method_calls=method_calls, signers=signers)
@@ -1681,7 +1679,7 @@ def simulate(
 
         :param allow_more_logs: Whether to allow more logs than the standard limit
         :param allow_empty_signatures: Whether to allow transactions with empty signatures
-        :param allow_unnamed_resources: Whether to allow unnamed resources
+        :param allow_unnamed_resources: Whether to allow unnamed resources.
         :param extra_opcode_budget: Additional opcode budget to allocate
         :param exec_trace_config: Configuration for execution tracing
         :param simulation_round: Round number to simulate at
@@ -1701,6 +1699,17 @@ def simulate(
         else:
             self.build()
 
+        atc = prepare_group_for_sending(
+            atc,
+            self._algod,
+            populate_app_call_resources=allow_unnamed_resources,
+            cover_app_call_inner_transaction_fees=allow_unnamed_resources,
+            additional_atc_context=AdditionalAtcContext(
+                suggested_params=self._get_suggested_params(),
+                max_fees=self._txn_max_fees or _get_dummy_max_fees_for_simulated_opups(atc.get_tx_count()),
+            ),
+        )
+
         if config.debug and config.project_root and config.trace_all:
             response = simulate_and_persist_response(
                 atc,