algokit-utils 3.0.0b3__py3-none-any.whl → 3.0.0b5__py3-none-any.whl

algokit_utils/applications/app_client.py

@@ -5,7 +5,7 @@ import copy
 import json
 import os
 from collections.abc import Sequence
-from dataclasses import asdict, dataclass, fields
+from dataclasses import asdict, dataclass, fields, replace
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypedDict, TypeVar
 
 import algosdk
@@ -54,6 +54,7 @@ from algokit_utils.transactions.transaction_composer import (
     AppUpdateParams,
     BuiltTransactions,
     PaymentParams,
+    SendAtomicTransactionComposerResults,
 )
 from algokit_utils.transactions.transaction_sender import (
     SendAppTransactionResult,
@@ -76,7 +77,6 @@ __all__ = [
     "AppClient",
     "AppClientBareCallCreateParams",
     "AppClientBareCallParams",
-    "AppClientCallParams",
     "AppClientCompilationParams",
     "AppClientCompilationResult",
     "AppClientCreateSchema",
@@ -85,6 +85,8 @@ __all__ = [
     "AppClientParams",
     "AppSourceMaps",
     "BaseAppClientMethodCallParams",
+    "CommonAppCallCreateParams",
+    "CommonAppCallParams",
     "CreateOnComplete",
     "FundAppAccountParams",
     "get_constant_block_offset",
@@ -201,106 +203,35 @@ class AppClientCompilationParams(TypedDict, total=False):
     deletable: bool | None
 
 
-@dataclass(kw_only=True)
-class FundAppAccountParams:
-    """Parameters for funding an application's account.
-
-    :ivar sender: Optional sender address
-    :ivar signer: Optional transaction signer
-    :ivar rekey_to: Optional address to rekey to
-    :ivar note: Optional transaction note
-    :ivar lease: Optional lease
-    :ivar static_fee: Optional static fee
-    :ivar extra_fee: Optional extra fee
-    :ivar max_fee: Optional maximum fee
-    :ivar validity_window: Optional validity window in rounds
-    :ivar first_valid_round: Optional first valid round
-    :ivar last_valid_round: Optional last valid round
-    :ivar amount: Amount to fund
-    :ivar close_remainder_to: Optional address to close remainder to
-    :ivar on_complete: Optional on complete action
-    """
-
-    sender: str | None = None
-    signer: TransactionSigner | None = None
-    rekey_to: str | None = None
-    note: bytes | None = None
-    lease: bytes | None = None
-    static_fee: AlgoAmount | None = None
-    extra_fee: AlgoAmount | None = None
-    max_fee: AlgoAmount | None = None
-    validity_window: int | None = None
-    first_valid_round: int | None = None
-    last_valid_round: int | None = None
-    amount: AlgoAmount
-    close_remainder_to: str | None = None
-    on_complete: algosdk.transaction.OnComplete | None = None
-
-
-@dataclass(kw_only=True)
-class AppClientCallParams:
-    """Parameters for calling an application.
-
-    :ivar method: Optional ABI method name or signature
-    :ivar args: Optional arguments to pass to method
-    :ivar boxes: Optional box references to load
-    :ivar accounts: Optional account addresses to load
-    :ivar apps: Optional app IDs to load
-    :ivar assets: Optional asset IDs to load
-    :ivar lease: Optional lease
-    :ivar sender: Optional sender address
-    :ivar note: Optional transaction note
-    :ivar send_params: Optional parameters to control transaction sending
-    """
-
-    method: str | None = None
-    args: list | None = None
-    boxes: list | None = None
-    accounts: list[str] | None = None
-    apps: list[int] | None = None
-    assets: list[int] | None = None
-    lease: (str | bytes) | None = None
-    sender: str | None = None
-    note: (bytes | dict | str) | None = None
-    send_params: dict | None = None
-
-
 ArgsT = TypeVar("ArgsT")
 MethodT = TypeVar("MethodT")
 
 
 @dataclass(kw_only=True, frozen=True)
-class BaseAppClientMethodCallParams(Generic[ArgsT, MethodT]):
-    """Base parameters for application method calls.
+class CommonAppCallParams:
+    """Common configuration for app call transaction parameters
+
+    :ivar account_references: List of account addresses to reference
+    :ivar app_references: List of app IDs to reference
+    :ivar asset_references: List of asset IDs to reference
+    :ivar box_references: List of box references to include
+    :ivar extra_fee: Additional fee to add to transaction
+    :ivar lease: Transaction lease value
+    :ivar max_fee: Maximum fee allowed for transaction
+    :ivar note: Arbitrary note for the transaction
+    :ivar rekey_to: Address to rekey account to
+    :ivar sender: Sender address override
+    :ivar signer: Custom transaction signer
+    :ivar static_fee: Fixed fee for transaction
+    :ivar validity_window: Number of rounds valid
+    :ivar first_valid_round: First valid round number
+    :ivar last_valid_round: Last valid round number"""
 
-    :ivar method: Method to call
-    :ivar args: Optional arguments to pass to method
-    :ivar account_references: Optional account references
-    :ivar app_references: Optional application references
-    :ivar asset_references: Optional asset references
-    :ivar box_references: Optional box references
-    :ivar extra_fee: Optional extra fee
-    :ivar first_valid_round: Optional first valid round
-    :ivar lease: Optional lease
-    :ivar max_fee: Optional maximum fee
-    :ivar note: Optional note
-    :ivar rekey_to: Optional rekey to address
-    :ivar sender: Optional sender address
-    :ivar signer: Optional transaction signer
-    :ivar static_fee: Optional static fee
-    :ivar validity_window: Optional validity window
-    :ivar last_valid_round: Optional last valid round
-    :ivar on_complete: Optional on complete action
-    """
-
-    method: MethodT
-    args: ArgsT | None = None
     account_references: list[str] | None = None
     app_references: list[int] | None = None
     asset_references: list[int] | None = None
-    box_references: Sequence[BoxReference | BoxIdentifier] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
     extra_fee: AlgoAmount | None = None
-    first_valid_round: int | None = None
     lease: bytes | None = None
     max_fee: AlgoAmount | None = None
     note: bytes | None = None
@@ -309,82 +240,85 @@ class BaseAppClientMethodCallParams(Generic[ArgsT, MethodT]):
     signer: TransactionSigner | None = None
     static_fee: AlgoAmount | None = None
     validity_window: int | None = None
+    first_valid_round: int | None = None
     last_valid_round: int | None = None
-    on_complete: algosdk.transaction.OnComplete | None = None
+    on_complete: OnComplete | None = None
+
+
+@dataclass(frozen=True)
+class AppClientCreateSchema:
+    """Schema for application creation.
+
+    :ivar extra_program_pages: Optional number of extra program pages
+    :ivar schema: Optional application creation schema
+    """
+
+    extra_program_pages: int | None = None
+    schema: AppCreateSchema | None = None
 
 
 @dataclass(kw_only=True, frozen=True)
-class AppClientMethodCallParams(
-    BaseAppClientMethodCallParams[
-        Sequence[ABIValue | ABIStruct | AppMethodCallTransactionArgument | None],
-        str,
-    ]
-):
-    """Parameters for application method calls."""
+class CommonAppCallCreateParams(AppClientCreateSchema, CommonAppCallParams):
+    """Common configuration for app create call transaction parameters."""
+
+    on_complete: CreateOnComplete | None = None
 
 
 @dataclass(kw_only=True, frozen=True)
-class AppClientBareCallParams:
+class FundAppAccountParams(CommonAppCallParams):
+    """Parameters for funding an application's account.
+
+    :ivar amount: Amount to fund
+    :ivar close_remainder_to: Optional address to close remainder to
+    """
+
+    amount: AlgoAmount
+    close_remainder_to: str | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppClientBareCallParams(CommonAppCallParams):
     """Parameters for bare application calls.
 
-    :ivar signer: Optional transaction signer
-    :ivar rekey_to: Optional rekey to address
-    :ivar lease: Optional lease
-    :ivar static_fee: Optional static fee
-    :ivar extra_fee: Optional extra fee
-    :ivar max_fee: Optional maximum fee
-    :ivar validity_window: Optional validity window
-    :ivar first_valid_round: Optional first valid round
-    :ivar last_valid_round: Optional last valid round
-    :ivar sender: Optional sender address
-    :ivar note: Optional note
     :ivar args: Optional arguments
-    :ivar account_references: Optional account references
-    :ivar app_references: Optional application references
-    :ivar asset_references: Optional asset references
-    :ivar box_references: Optional box references
     """
 
-    signer: TransactionSigner | None = None
-    rekey_to: str | None = None
-    lease: bytes | None = None
-    static_fee: AlgoAmount | None = None
-    extra_fee: AlgoAmount | None = None
-    max_fee: AlgoAmount | None = None
-    validity_window: int | None = None
-    first_valid_round: int | None = None
-    last_valid_round: int | None = None
-    sender: str | None = None
-    note: bytes | None = None
     args: list[bytes] | None = None
-    account_references: list[str] | None = None
-    app_references: list[int] | None = None
-    asset_references: list[int] | None = None
-    box_references: list[BoxReference | BoxIdentifier] | None = None
 
 
 @dataclass(frozen=True)
-class AppClientCreateSchema:
-    """Schema for application creation.
+class AppClientBareCallCreateParams(CommonAppCallCreateParams):
+    """Parameters for creating application with bare call."""
 
-    :ivar extra_program_pages: Optional number of extra program pages
-    :ivar schema: Optional application creation schema
-    """
+    on_complete: CreateOnComplete | None = None
 
-    extra_program_pages: int | None = None
-    schema: AppCreateSchema | None = None
 
+@dataclass(kw_only=True, frozen=True)
+class BaseAppClientMethodCallParams(Generic[ArgsT, MethodT], CommonAppCallParams):
+    """Base parameters for application method calls.
 
-@dataclass(frozen=True)
-class AppClientBareCallCreateParams(AppClientCreateSchema, AppClientBareCallParams):
-    """Parameters for creating application with bare call."""
+    :ivar method: Method to call
+    :ivar args: Optional arguments to pass to method
+    :ivar on_complete: Optional on complete action
+    """
 
-    on_complete: OnComplete | None = None
+    method: MethodT
+    args: ArgsT | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppClientMethodCallParams(
+    BaseAppClientMethodCallParams[
+        Sequence[ABIValue | ABIStruct | AppMethodCallTransactionArgument | None],
+        str,
+    ]
+):
+    """Parameters for application method calls."""
 
 
 @dataclass(frozen=True)
 class AppClientMethodCallCreateParams(AppClientCreateSchema, AppClientMethodCallParams):
-    """Parameters for creating application with method call."""
+    """Parameters for creating application with method call"""
 
     on_complete: CreateOnComplete | None = None
 
@@ -1256,28 +1190,51 @@ class _TransactionSender:
         :param params: Parameters for the application call including method and transaction options
         :param send_params: Send parameters
         :return: The result of sending or simulating the transaction, including ABI return value if applicable
+        :raises ValueError: If the transaction is read-only and `max_fee` is not provided
         """
         is_read_only_call = (
             params.on_complete == algosdk.transaction.OnComplete.NoOpOC or params.on_complete is None
         ) and self._app_spec.get_arc56_method(params.method).readonly
 
         if is_read_only_call:
+            readonly_params = params
+            readonly_send_params = send_params or SendParams()
+
+            # Read-only calls do not require fees to be paid, as they are only simulated on the network.
+            # Therefore there is no value in calculating the minimum fee needed for a successful app call with inners.
+            # As a a result we only need to send a single simulate call,
+            # however to do this successfully we need to ensure fees for the transaction are fully covered using maxFee.
+            if readonly_send_params.get("cover_app_call_inner_transaction_fees"):
+                if params.max_fee is None:
+                    raise ValueError(
+                        "Please provide a `max_fee` for the transaction when `cover_app_call_inner_transaction_fees` is enabled."  # noqa: E501
+                    )
+                readonly_params = replace(readonly_params, static_fee=params.max_fee, extra_fee=None)
+
             method_call_to_simulate = self._algorand.new_group().add_app_call_method_call(
-                self._client.params.call(params)
-            )
-            send_params = send_params or SendParams()
-            simulate_response = self._client._handle_call_errors(
-                lambda: method_call_to_simulate.simulate(
-                    allow_unnamed_resources=send_params.get("populate_app_call_resources") or True,
-                    skip_signatures=True,
-                    allow_more_logs=True,
-                    allow_empty_signatures=True,
-                    extra_opcode_budget=None,
-                    exec_trace_config=None,
-                    simulation_round=None,
-                )
+                self._client.params.call(readonly_params)
             )
 
+            def run_simulate() -> SendAtomicTransactionComposerResults:
+                try:
+                    return method_call_to_simulate.simulate(
+                        allow_unnamed_resources=readonly_send_params.get("populate_app_call_resources") or True,
+                        skip_signatures=True,
+                        allow_more_logs=True,
+                        allow_empty_signatures=True,
+                        extra_opcode_budget=None,
+                        exec_trace_config=None,
+                        simulation_round=None,
+                    )
+                except Exception as e:
+                    if readonly_send_params.get("cover_app_call_inner_transaction_fees") and "fee too small" in str(e):
+                        raise ValueError(
+                            "Fees were too small. You may need to increase the transaction `maxFee`."
+                        ) from e
+                    raise
+
+            simulate_response = self._client._handle_call_errors(run_simulate)
+
             return SendAppTransactionResult[Arc56ReturnValueType](
                 tx_ids=simulate_response.tx_ids,
                 transactions=simulate_response.transactions,
@@ -1616,7 +1573,7 @@ class AppClient:
         program: bytes | None = None,
         approval_source_info: ProgramSourceInfo | None = None,
         clear_source_info: ProgramSourceInfo | None = None,
-    ) -> Exception:
+    ) -> LogicError | Exception:
         source_map = clear_source_map if is_clear_state_program else approval_source_map
 
         error_details = parse_logic_error(str(e))
@@ -1682,20 +1639,24 @@ class AppClient:
                     get_line_for_pc=custom_get_line_for_pc,
                     traces=None,
                 )
-
         if error_message:
             import re
 
             message = e.logic_error_str if isinstance(e, LogicError) else str(e)
             app_id = re.search(r"(?<=app=)\d+", message)
             tx_id = re.search(r"(?<=transaction )\S+(?=:)", message)
-            error = Exception(
+            runtime_error_message = (
                 f"Runtime error when executing {app_spec.name} "
                 f"(appId: {app_id.group() if app_id else 'N/A'}) in transaction "
                 f"{tx_id.group() if tx_id else 'N/A'}: {error_message}"
             )
-            error.__cause__ = e
-            return error
+            if isinstance(e, LogicError):
+                e.message = runtime_error_message
+                return e
+            else:
+                error = Exception(runtime_error_message)
+                error.__cause__ = e
+                return error
 
         return e
 

algokit_utils/applications/app_factory.py

@@ -23,7 +23,6 @@ from algokit_utils.applications.app_client import (
     AppClientBareCallParams,
     AppClientCompilationParams,
     AppClientCompilationResult,
-    AppClientCreateSchema,
     AppClientMethodCallCreateParams,
     AppClientMethodCallParams,
     AppClientParams,
@@ -88,17 +87,12 @@ class AppFactoryParams:
 
 
 @dataclass(kw_only=True, frozen=True)
-class _AppFactoryCreateBaseParams(AppClientCreateSchema):
+class AppFactoryCreateParams(AppClientBareCallCreateParams):
     on_complete: CreateOnComplete | None = None
 
 
 @dataclass(kw_only=True, frozen=True)
-class AppFactoryCreateParams(_AppFactoryCreateBaseParams, AppClientBareCallParams):
-    pass
-
-
-@dataclass(kw_only=True, frozen=True)
-class AppFactoryCreateMethodCallParams(_AppFactoryCreateBaseParams, AppClientMethodCallParams):
+class AppFactoryCreateMethodCallParams(AppClientMethodCallCreateParams):
     pass
 
 

algokit_utils/assets/asset_manager.py

@@ -43,13 +43,13 @@ class AssetInformation:
     :ivar decimals: The amount of decimal places the asset was created with
     :ivar default_frozen: Whether the asset was frozen by default for all accounts, defaults to None
     :ivar manager: The address of the optional account that can manage the configuration of the asset and destroy it,
-    defaults to None
+        defaults to None
     :ivar reserve: The address of the optional account that holds the reserve (uncirculated supply) units of the asset,
-    defaults to None
+        defaults to None
     :ivar freeze: The address of the optional account that can be used to freeze or unfreeze holdings of this asset,
-    defaults to None
+        defaults to None
     :ivar clawback: The address of the optional account that can clawback holdings of this asset from any account,
-    defaults to None
+        defaults to None
     :ivar unit_name: The optional name of the unit of this asset (e.g. ticker name), defaults to None
     :ivar unit_name_b64: The optional name of the unit of this asset as bytes, defaults to None
     :ivar asset_name: The optional name of the asset, defaults to None
@@ -57,7 +57,7 @@ class AssetInformation:
     :ivar url: Optional URL where more information about the asset can be retrieved, defaults to None
     :ivar url_b64: Optional URL where more information about the asset can be retrieved as bytes, defaults to None
     :ivar metadata_hash: 32-byte hash of some metadata that is relevant to the asset and/or asset holders,
-    defaults to None
+        defaults to None
     """
 
     asset_id: int

algokit_utils/clients/client_manager.py

@@ -77,8 +77,8 @@ def _get_config_from_environment(environment_prefix: str) -> AlgoClientNetworkCo
     port = os.getenv(f"{environment_prefix}_PORT")
     if port:
         parsed = parse.urlparse(server)
-        server = parsed._replace(netloc=f"{parsed.hostname}:{port}").geturl()
-    return AlgoClientNetworkConfig(server, os.getenv(f"{environment_prefix}_TOKEN", ""))
+        server = parsed._replace(netloc=f"{parsed.hostname}").geturl()
+    return AlgoClientNetworkConfig(server, os.getenv(f"{environment_prefix}_TOKEN", ""), port=port)
 
 
 class ClientManager:
@@ -351,15 +351,18 @@ class ClientManager:
         )
 
     @staticmethod
-    def get_algod_client(config: AlgoClientNetworkConfig | None = None) -> AlgodClient:
+    def get_algod_client(config: AlgoClientNetworkConfig) -> AlgodClient:
         """Get an Algod client from config or environment.
 
         :param config: Optional client configuration
         :return: Algod client instance
         """
-        config = config or _get_config_from_environment("ALGOD")
         headers = {"X-Algo-API-Token": config.token or ""}
-        return AlgodClient(algod_token=config.token or "", algod_address=config.server, headers=headers)
+        return AlgodClient(
+            algod_token=config.token or "",
+            algod_address=config.full_url(),
+            headers=headers,
+        )
 
     @staticmethod
     def get_algod_client_from_environment() -> AlgodClient:
@@ -370,14 +373,13 @@ class ClientManager:
         return ClientManager.get_algod_client(ClientManager.get_algod_config_from_environment())
 
     @staticmethod
-    def get_kmd_client(config: AlgoClientNetworkConfig | None = None) -> KMDClient:
+    def get_kmd_client(config: AlgoClientNetworkConfig) -> KMDClient:
         """Get a KMD client from config or environment.
 
         :param config: Optional client configuration
         :return: KMD client instance
         """
-        config = config or _get_config_from_environment("KMD")
-        return KMDClient(config.token, config.server)
+        return KMDClient(config.token, config.full_url())
 
     @staticmethod
     def get_kmd_client_from_environment() -> KMDClient:
@@ -388,15 +390,18 @@ class ClientManager:
         return ClientManager.get_kmd_client(ClientManager.get_kmd_config_from_environment())
 
     @staticmethod
-    def get_indexer_client(config: AlgoClientNetworkConfig | None = None) -> IndexerClient:
+    def get_indexer_client(config: AlgoClientNetworkConfig) -> IndexerClient:
         """Get an Indexer client from config or environment.
 
         :param config: Optional client configuration
         :return: Indexer client instance
         """
-        config = config or _get_config_from_environment("INDEXER")
         headers = {"X-Indexer-API-Token": config.token}
-        return IndexerClient(indexer_token=config.token, indexer_address=config.server, headers=headers)
+        return IndexerClient(
+            indexer_token=config.token,
+            indexer_address=config.full_url(),
+            headers=headers,
+        )
 
     @staticmethod
     def get_indexer_client_from_environment() -> IndexerClient:
@@ -611,7 +616,7 @@ class ClientManager:
             else {"algod": 4001, "indexer": 8980, "kmd": 4002}[config_or_port]
         )
 
-        return AlgoClientNetworkConfig(server=f"http://localhost:{port}", token="a" * 64)
+        return AlgoClientNetworkConfig(server="http://localhost", token="a" * 64, port=port)
 
     @staticmethod
     def get_algod_config_from_environment() -> AlgoClientNetworkConfig:

algokit_utils/clients/dispenser_api_client.py

@@ -71,6 +71,9 @@ class TestNetDispenserApiClient:
     Default request timeout is 15 seconds. Modify by passing `request_timeout` to the constructor.
     """
 
+    # NOTE: ensures pytest does not think this is a test
+    # https://docs.pytest.org/en/stable/example/pythoncollection.html#customizing-test-collection
+    __test__ = False
     auth_token: str
     request_timeout = DISPENSER_REQUEST_TIMEOUT