algokit-utils 4.1.1b1__py3-none-any.whl → 4.2.0__py3-none-any.whl

algokit_utils/algorand.py

@@ -16,6 +16,7 @@ from algokit_utils.clients.client_manager import AlgoSdkClients, ClientManager
 from algokit_utils.models.network import AlgoClientConfigs, AlgoClientNetworkConfig
 from algokit_utils.protocols.account import TransactionSignerAccountProtocol
 from algokit_utils.transactions.transaction_composer import (
+    ErrorTransformer,
     TransactionComposer,
 )
 from algokit_utils.transactions.transaction_creator import AlgorandClientTransactionCreator
@@ -51,6 +52,7 @@ class AlgorandClient:
         self._cached_suggested_params_expiry: float | None = None
         self._cached_suggested_params_timeout: int = 3_000  # three seconds
         self._default_validity_window: int | None = None
+        self._error_transformers: set[ErrorTransformer] = set()
 
     def set_default_validity_window(self, validity_window: int) -> typing_extensions.Self:
         """
@@ -155,6 +157,25 @@ class AlgorandClient:
 
         return copy.deepcopy(self._cached_suggested_params)
 
+    def register_error_transformer(self, transformer: ErrorTransformer) -> typing_extensions.Self:
+        """Register a function that will be used to transform an error caught when simulating or executing
+        composed transaction groups made from `new_group`
+
+        :param transformer: The error transformer function
+        :return: The AlgorandClient so you can chain method calls
+        """
+        self._error_transformers.add(transformer)
+        return self
+
+    def unregister_error_transformer(self, transformer: ErrorTransformer) -> typing_extensions.Self:
+        """Unregister an error transformer function
+
+        :param transformer: The error transformer function to remove
+        :return: The AlgorandClient so you can chain method calls
+        """
+        self._error_transformers.discard(transformer)
+        return self
+
     def new_group(self) -> TransactionComposer:
         """
         Start a new `TransactionComposer` transaction group
@@ -169,6 +190,7 @@ class AlgorandClient:
             get_signer=lambda addr: self.account.get_signer(addr),
             get_suggested_params=self.get_suggested_params,
             default_validity_window=self._default_validity_window,
+            error_transformers=list(self._error_transformers),
         )
 
     @property

algokit_utils/applications/app_client.py

@@ -1305,11 +1305,15 @@ class AppClient:
         self._default_signer = params.default_signer
         self._approval_source_map = params.approval_source_map
         self._clear_source_map = params.clear_source_map
+        self._last_compiled: dict[str, bytes] = {}  # Track compiled programs for error filtering
         self._state_accessor = _StateAccessor(self)
         self._params_accessor = _MethodParamsBuilder(self)
         self._send_accessor = _TransactionSender(self)
         self._create_transaction_accessor = _TransactionCreator(self)
 
+        # Register the error transformer to handle app-specific logic errors
+        self._algorand.register_error_transformer(self._handle_call_errors_transform)
+
     @property
     def algorand(self) -> AlgorandClient:
         """Get the Algorand client instance.
@@ -1735,6 +1739,10 @@ class AppClient:
         if result.compiled_clear:
             self._clear_source_map = result.compiled_clear.source_map
 
+        # Store compiled programs for new app error filtering
+        self._last_compiled["approval"] = result.approval_program
+        self._last_compiled["clear"] = result.clear_state_program
+
         return result
 
     def clone(
@@ -1951,6 +1959,74 @@ class AppClient:
         except Exception as e:
             raise self._expose_logic_error(e=e) from None
 
+    def _is_new_app_error_for_this_app(self, error: Exception) -> bool:
+        """Check if an error from a new app (app_id=0) is for this specific app by comparing program bytecode."""
+        if not hasattr(error, "sent_transactions") or not error.sent_transactions:
+            return False
+
+        # Find the transaction that caused the error
+        txn = None
+        for t in error.sent_transactions:
+            if hasattr(t, "get_txid") and t.get_txid() in str(error):
+                txn = t
+                break
+
+        if not txn or not hasattr(txn, "application_call"):
+            return False
+
+        def programs_defined_and_equal(a: bytes | None, b: bytes | None) -> bool:
+            if a is None or b is None:
+                return False
+            return a == b
+
+        app_call = txn.application_call
+        return programs_defined_and_equal(
+            getattr(app_call, "clear_program", None), self._last_compiled.get("clear")
+        ) and programs_defined_and_equal(
+            getattr(app_call, "approval_program", None), self._last_compiled.get("approval")
+        )
+
+    def _handle_call_errors_transform(self, error: Exception) -> Exception:
+        """Error transformer function for app-specific logic errors.
+
+        This will be called by the transaction composer when errors occur during
+        simulate or send operations to provide better error messages with source maps.
+
+        :param error: The error to potentially transform
+        :return: The transformed error if it's an app logic error, otherwise the original error
+        """
+        try:
+            # Check if this is a logic error that we can parse
+            from algokit_utils.errors.logic_error import parse_logic_error
+
+            error_details = parse_logic_error(str(error))
+            if not error_details:
+                # Not a logic error, return unchanged
+                return error
+
+            # Check if this error is for our app
+            should_transform = False
+
+            if self._app_id == 0:
+                # For new apps (app_id == 0), we can't use app ID filtering
+                # Instead check the programs to identify if this is the correct app
+                should_transform = self._is_new_app_error_for_this_app(error)
+            else:
+                # Only handle errors for this specific app
+                app_id_string = f"app={self._app_id}"
+                should_transform = app_id_string in str(error)
+
+            if not should_transform:
+                # Error is not for this app, return unchanged
+                return error
+
+            # This is a logic error for our app, transform it
+            return self._expose_logic_error(e=error)
+
+        except Exception:
+            # If transformation fails, return the original error
+            return error
+
     def _get_sender(self, sender: str | None) -> str:
         if not sender and not self._default_sender:
             raise Exception(

algokit_utils/transactions/transaction_composer.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import base64
 import json
 import re
+from collections.abc import Callable
 from copy import deepcopy
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, TypedDict, Union, cast
@@ -31,15 +32,17 @@ from algokit_utils.models.transaction import SendParams, TransactionWrapper
 from algokit_utils.protocols.account import TransactionSignerAccountProtocol
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
-
     from algosdk.abi import Method
-    from algosdk.v2client.algod import AlgodClient
     from algosdk.v2client.models import SimulateTraceConfig
 
     from algokit_utils.models.amount import AlgoAmount
     from algokit_utils.models.transaction import Arc2TransactionNote
 
+# Type for error transformer function
+# Note: The return type is Any rather than Exception to allow runtime validation
+# that the transformer actually returns an Exception instance
+ErrorTransformer = Callable[[Exception], Any]
+
 
 __all__ = [
     "AppCallMethodCallParams",
@@ -60,6 +63,7 @@ __all__ = [
     "AssetOptOutParams",
     "AssetTransferParams",
     "BuiltTransactions",
+    "ErrorTransformer",
     "MethodCallParams",
     "OfflineKeyRegistrationParams",
     "OnlineKeyRegistrationParams",
@@ -80,6 +84,27 @@ MAX_APP_CALL_FOREIGN_REFERENCES = 8
 MAX_APP_CALL_ACCOUNT_REFERENCES = 4
 
 
+class InvalidErrorTransformerValueError(Exception):
+    """Raised when an error transformer returns a non-error value."""
+
+    def __init__(self, original_error: Exception, value: object) -> None:
+        super().__init__(
+            f"An error transformer returned a non-error value: {value}. "
+            f"The original error before any transformation: {original_error}"
+        )
+
+
+class ErrorTransformerError(Exception):
+    """Raised when an error transformer throws an error."""
+
+    def __init__(self, original_error: Exception, cause: Exception) -> None:
+        super().__init__(
+            f"An error transformer threw an error: {cause}. "
+            f"The original error before any transformation: {original_error}"
+        )
+        self.__cause__ = cause
+
+
 @dataclass(kw_only=True, frozen=True)
 class _CommonTxnParams:
     sender: str
@@ -1333,6 +1358,7 @@ class TransactionComposer:
         defaults to using algod.suggested_params()
     :param default_validity_window: Optional default validity window for transactions in rounds, defaults to 10
     :param app_manager: Optional AppManager instance for compiling TEAL programs, defaults to None
+    :param error_transformers: Optional list of error transformers to use when an error is caught in simulate or send
     """
 
     def __init__(
@@ -1342,6 +1368,7 @@ class TransactionComposer:
         get_suggested_params: Callable[[], algosdk.transaction.SuggestedParams] | None = None,
         default_validity_window: int | None = None,
         app_manager: AppManager | None = None,
+        error_transformers: list[ErrorTransformer] | None = None,
     ):
         # Map of transaction index in the atc to a max logical fee.
         # This is set using the value of either maxFee or staticFee.
@@ -1355,6 +1382,35 @@ class TransactionComposer:
         self._default_validity_window: int = default_validity_window or 10
         self._default_validity_window_is_explicit: bool = default_validity_window is not None
         self._app_manager = app_manager or AppManager(algod)
+        self._error_transformers: list[ErrorTransformer] = error_transformers or []
+
+    def _transform_error(self, original_error: Exception) -> Exception:
+        """Transform an error using registered error transformers.
+
+        :param original_error: The original error to transform
+        :return: The transformed error or the original error if transformation fails
+        """
+        transformed_exception: Exception = original_error
+
+        for transformer in self._error_transformers:
+            try:
+                result = transformer(transformed_exception)
+                if not isinstance(result, Exception):
+                    return InvalidErrorTransformerValueError(original_error, result)
+                transformed_exception = result
+            except Exception as error_from_transformer:
+                return ErrorTransformerError(original_error, error_from_transformer)
+
+        return transformed_exception
+
+    def register_error_transformer(self, transformer: ErrorTransformer) -> TransactionComposer:
+        """Register a function that will be used to transform an error caught when simulating or sending.
+
+        :param transformer: The error transformer function
+        :return: The composer so you can chain method calls
+        """
+        self._error_transformers.append(transformer)
+        return self
 
     def add_transaction(
         self, transaction: algosdk.transaction.Transaction, signer: TransactionSigner | None = None
@@ -1828,7 +1884,7 @@ class TransactionComposer:
 
         :param params: Parameters for the send operation
         :return: The transaction send results
-        :raises Exception: If the transaction fails
+        :raises self._transform_error: If the transaction fails (may be transformed by error transformers)
         """
         group = self.build().transactions
 
@@ -1859,8 +1915,8 @@ class TransactionComposer:
                     max_fees=self._txn_max_fees,
                 ),
             )
-        except algosdk.error.AlgodHTTPError as e:
-            raise Exception(f"Transaction failed: {e}") from e
+        except Exception as original_error:
+            raise self._transform_error(original_error) from original_error
 
     def _handle_simulate_error(self, simulate_response: SimulateAtomicTransactionResponse) -> None:
         # const failedGroup = simulateResponse?.txnGroups[0]
@@ -1872,7 +1928,8 @@ class TransactionComposer:
                 f"Transaction failed at transaction(s) {', '.join(failed_at) if failed_at else 'N/A'} in the group. "
                 f"{failure_message}"
             )
-            raise Exception(error_message)
+            original_error = Exception(error_message)
+            raise self._transform_error(original_error) from original_error
 
     def simulate(
         self,

{algokit_utils-4.1.1b1.dist-info → algokit_utils-4.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: algokit-utils
-Version: 4.1.1b1
+Version: 4.2.0
 Summary: Utilities for Algorand development for use by AlgoKit
 License: MIT
 Author: Algorand Foundation

{algokit_utils-4.1.1b1.dist-info → algokit_utils-4.2.0.dist-info}/RECORD

@@ -16,12 +16,12 @@ algokit_utils/account.py,sha256=gyGrBSoafUh8WV677IzYGkYoxtzzElsgxGMp4SgA4pk,410
 algokit_utils/accounts/__init__.py,sha256=_LyY0se6TaQOes7vAcmbpt6pmG4VKlzfTt37-IjwimA,138
 algokit_utils/accounts/account_manager.py,sha256=dIECz1QzkvV4bzsqoUJ4cRzJ6evHcRM2TpQpBf8l0ng,42242
 algokit_utils/accounts/kmd_account_manager.py,sha256=qPlklyoIk0B6B78GZX-VKwSgmfZBKgp5U2k51fg1YXg,6459
-algokit_utils/algorand.py,sha256=OvYMolOGK-tupKLDohtP_P59jlELIWW2hRqf1CYfrns,13732
+algokit_utils/algorand.py,sha256=gRRWEwThmvAzS5ZKmlUHcqKxFz3XXMqairwi93nTatg,14730
 algokit_utils/application_client.py,sha256=5UIxXIBjukjRyjZPCeXmaNlAftbb3TziV7EfBolW79k,337
 algokit_utils/application_specification.py,sha256=wV0H088IudMqlxsW-gsZIfJyKA4e-zVwxJ-cR__ouBA,1379
 algokit_utils/applications/__init__.py,sha256=NGjhpBeExsQZOAYCT2QUFag1xuKoFiX-Ux5SR2GNzd8,452
 algokit_utils/applications/abi.py,sha256=OjTdn4szJPPeC8XmosdDYtkIIVgQSWAnqz2DHw5OH9g,10117
-algokit_utils/applications/app_client.py,sha256=891BMnUOIOenEWgeelSIMgi0Wj4kggluWiKAu6-GYrE,88208
+algokit_utils/applications/app_client.py,sha256=6D6zZimJlRD6-EsNXfyC7uXPxYAKvC0JSrp-qcgcYPY,91494
 algokit_utils/applications/app_deployer.py,sha256=xJCu7SU66OTg5misSbSF0QI8abRB-DWAwAVKd1kNcPI,30685
 algokit_utils/applications/app_factory.py,sha256=jVAzoK1J9S-BTGHA5BLxT-cl0pWhPdf222W4fYpFihE,45352
 algokit_utils/applications/app_manager.py,sha256=8bboIswlwBQhPIqilSBMaxd83yHjIpkloezmtgcAdZY,22301
@@ -61,10 +61,10 @@ algokit_utils/protocols/account.py,sha256=CowaVY7ErBP84TWBHNvBjkZy18whPb8HIlMZtJ
 algokit_utils/protocols/typed_clients.py,sha256=UrQrHbN2SvS8pEFJ8JQodvouoWeBrQOQGZGyBQx1KLM,3322
 algokit_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 algokit_utils/transactions/__init__.py,sha256=7fYF3m6DyOGzbV36MT5svo0wSkj9AIz496kWgIWSAlk,225
-algokit_utils/transactions/transaction_composer.py,sha256=eK-6l2W1CkbKID1ezi-zCs_TxA2i5ZTm3YTl8sT2Zfw,103995
+algokit_utils/transactions/transaction_composer.py,sha256=iOIa_9hknbpCQc2hRyX-aBoHG-NGRxGnEAJstwGVKgw,106645
 algokit_utils/transactions/transaction_creator.py,sha256=cuP6Xm-fhGoCc2FNSbLiEg3iQRwW38rfdTzsqPyEcpM,29053
 algokit_utils/transactions/transaction_sender.py,sha256=Wi3ws9S-Df1JeTlaSTXmq-WS24Gsq7WGsKk1B0z23ao,50117
-algokit_utils-4.1.1b1.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
-algokit_utils-4.1.1b1.dist-info/METADATA,sha256=aq5pFQLu2tIVXOqbt9WKKfcfek9y4KDPx5DfFx79eL0,2421
-algokit_utils-4.1.1b1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-algokit_utils-4.1.1b1.dist-info/RECORD,,
+algokit_utils-4.2.0.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
+algokit_utils-4.2.0.dist-info/METADATA,sha256=_65fNn_a68EmdV4pGJgXsA2EtFo-Qj1JrivWZ6nrGOI,2419
+algokit_utils-4.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+algokit_utils-4.2.0.dist-info/RECORD,,