feat: send payment transaction with algokit core

feat: send payment transaction with algokit core

Author: lempira

.github/workflows/build-python.yaml

@@ -22,7 +22,7 @@ jobs:
         uses: ./.github/actions/setup-poetry
 
       - name: Install dependencies
-        run: poetry install --no-interaction
+        run: poetry install --no-interaction --without=experimental
 
       - name: pytest + coverage
         shell: bash

poetry.lock

@@ -12,6 +12,21 @@ py-algorand-sdk = "^2.4.0"
 httpx = ">=0.23.1,<=0.28.1"
 typing-extensions = ">=4.6.0"
 
+[tool.poetry.group.experimental.dependencies]
+algokit-transact = [
+    # macOS
+    {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.10/algokit_transact-1.0.0a10-py3-none-macosx_10_12_x86_64.whl", markers = "sys_platform == 'darwin' and platform_machine == 'x86_64'"},
+    {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.10/algokit_transact-1.0.0a10-py3-none-macosx_11_0_arm64.whl", markers = "sys_platform == 'darwin' and platform_machine == 'arm64'"},
+
+    # Windows
+    {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.10/algokit_transact-1.0.0a10-py3-none-win_amd64.whl", markers = "sys_platform == 'win32' and platform_machine == 'AMD64'"},
+
+    # Linux - manylinux (for most common glibc-based distributions like Ubuntu, Debian, Fedora)
+    {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.10/algokit_transact-1.0.0a10-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", markers = "sys_platform == 'linux' and platform_machine == 'aarch64'"},
+    {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.10/algokit_transact-1.0.0a10-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", markers = "sys_platform == 'linux' and platform_machine == 'x86_64'"},
+]
+algokit-algod-api = {url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgod_api%401.0.0-alpha.11/algokit_algod_api-1.0.0a11-py3-none-any.whl"}
+
 [tool.poetry.group.dev.dependencies]
 pytest = "^8"
 ruff = ">=0.1.6,<=0.11.8"
@@ -27,7 +42,7 @@ poethepoet = ">=0.19,<0.35"
 pytest-httpx = "^0.35.0"
 pytest-xdist = "^3.6.1"
 linkify-it-py = "^2.0.3"
-setuptools = "^75.2.0"
+setuptools = "^80.9.0"
 pydoclint = "^0.6.0"
 pytest-sugar = "^1.0.0"
 types-deprecated = "^1.2.15.20241117"
@@ -130,7 +145,9 @@ suppress-none-returning = true
 "tests/clients/test_algorand_client.py" = ["ERA001"]  
 "src/algokit_utils/_legacy_v2/**/*" = ["E501"]
 "tests/**/*" = ["PLR2004"]  
-"src/algokit_utils/__init__.py" = ["I001", "RUF022"]  # Ignore import sorting for __init__.py
+"src/algokit_utils/__init__.py" = ["I001", "RUF022", "E402"]  # Ignore import sorting for __init__.py
+"src/algokit_utils/transactions/_algokit_core_bridge.py" = ["ANN001"]
+"src/algokit_utils/clients/_algokit_core_bridge.py" = ["ANN001", "ANN202","ANN204"]
 
 [tool.poe.tasks]
 docs = ["docs-html-only", "docs-md-only"]
@@ -174,6 +191,14 @@ disallow_untyped_calls = false
 module = ["tests.transactions.test_transaction_composer"]
 disable_error_code = ["call-overload", "union-attr"]
 
+[[tool.mypy.overrides]]
+module = ["algokit_utils.clients._algokit_core_bridge"]
+disable_error_code = ["attr-defined", "no-untyped-def", "no-untyped-call"]
+
+[[tool.mypy.overrides]]
+module = ["algokit_utils.transactions._algokit_core_bridge"]
+disable_error_code = ["attr-defined", "no-untyped-def", "no-any-return"]
+
 [tool.semantic_release]
 version_toml = "pyproject.toml:tool.poetry.version"
 remove_dist = false

pyproject.toml

@@ -9,6 +9,10 @@
     etc.
 """
 
+import importlib.util
+
+_EXPERIMENTAL_DEPENDENCIES_INSTALLED: bool | None = importlib.util.find_spec("algokit_algod_api") is not None
+
 # Core types and utilities that are commonly used
 from algokit_utils.applications import *  # noqa: F403
 from algokit_utils.assets import *  # noqa: F403

src/algokit_utils/__init__.py

@@ -0,0 +1,52 @@
+import base64
+from collections.abc import Iterable
+
+from algosdk.encoding import msgpack_encode
+from algosdk.transaction import GenericSignedTransaction
+from algosdk.v2client.algod import AlgodClient
+
+from algokit_utils import _EXPERIMENTAL_DEPENDENCIES_INSTALLED
+
+if not _EXPERIMENTAL_DEPENDENCIES_INSTALLED:
+    raise ImportError(
+        "Installing experimental dependencies is necessary to use AlgodClientWithCore. "
+        "Install this package with --group=experimental"
+    )
+
+import algokit_algod_api
+
+
+class AlgodClientWithCore:
+    """
+    A decorator for AlgodClient that extends its functionality with algokit_algod_api capabilities.
+    This class wraps an AlgodClient instance while maintaining the same interface.
+    """
+
+    def __init__(self, algod_client: AlgodClient):
+        self._algod_client = algod_client
+
+        configuration = algokit_algod_api.Configuration(
+            host=algod_client.algod_address, api_key={"api_key": self._algod_client.algod_token}
+        )
+        api_client = algokit_algod_api.ApiClient(configuration)
+        self._algod_core_client = algokit_algod_api.AlgodApi(api_client=api_client)
+
+    def send_raw_transaction(self, txn):
+        """
+        Override the method to send a raw transaction using algokit_algod_api.
+        """
+        return self._algod_core_client.raw_transaction(base64.b64decode(txn))
+
+    def send_transactions(self, txns: Iterable[GenericSignedTransaction]):
+        """
+        Override the method to send multiple transactions using algokit_algod_api.
+        """
+        return self.send_raw_transaction(
+            base64.b64encode(b"".join(base64.b64decode(msgpack_encode(txn)) for txn in txns))
+        )
+
+    def __getattr__(self, name):
+        """
+        Delegate all other method calls to the wrapped AlgodClient instance.
+        """
+        return getattr(self._algod_client, name)

src/algokit_utils/clients/_algokit_core_bridge.py

@@ -13,6 +13,7 @@
 from algosdk.v2client.algod import AlgodClient
 from algosdk.v2client.indexer import IndexerClient
 
+from algokit_utils import _EXPERIMENTAL_DEPENDENCIES_INSTALLED
 from algokit_utils._legacy_v2.application_specification import ApplicationSpecification
 from algokit_utils.applications.app_deployer import ApplicationLookup
 from algokit_utils.applications.app_spec.arc56 import Arc56Contract
@@ -119,7 +120,12 @@ def __init__(self, clients_or_configs: AlgoClientConfigs | AlgoSdkClients, algor
                 if clients_or_configs.kmd_config
                 else None,
             )
-        self._algod = _clients.algod
+        if not _EXPERIMENTAL_DEPENDENCIES_INSTALLED:
+            self._algod = _clients.algod
+        else:
+            from algokit_utils.clients._algokit_core_bridge import AlgodClientWithCore
+
+            self._algod = AlgodClientWithCore(_clients.algod)  # type: ignore[assignment]
         self._indexer = _clients.indexer
         self._kmd = _clients.kmd
         self._algorand = algorand_client

src/algokit_utils/clients/client_manager.py

@@ -33,7 +33,7 @@ class LogicErrorData(TypedDict):
 def parse_logic_error(
     error_str: str,
 ) -> LogicErrorData | None:
-    match = re.match(LOGIC_ERROR, error_str)
+    match = re.search(LOGIC_ERROR, error_str, re.DOTALL)
     if match is None:
         return None
 

src/algokit_utils/errors/logic_error.py

@@ -0,0 +1,76 @@
+import base64
+from typing import cast
+
+import algosdk.transaction
+from algokit_transact import (
+    FeeParams,
+    PaymentTransactionFields,
+    Transaction,
+    TransactionType,
+    address_from_string,
+    assign_fee,
+    encode_transaction_raw,
+)
+
+
+def build_payment_with_core(  # noqa: PLR0913
+    sender,
+    sp,
+    receiver,
+    amt,
+    close_remainder_to=None,
+    note=None,
+    lease=None,
+    rekey_to=None,
+    static_fee=None,
+    max_fee=None,
+    extra_fee=None,
+) -> algosdk.transaction.PaymentTxn:
+    # Determine static fee based on parameters or suggested params
+    static_fee_value = None
+    if static_fee is not None:
+        static_fee_value = static_fee
+    elif sp.flat_fee:
+        static_fee_value = sp.fee
+
+    txn = Transaction(
+        transaction_type=TransactionType.PAYMENT,
+        sender=address_from_string(sender),
+        fee=static_fee_value,
+        first_valid=sp.first,
+        last_valid=sp.last,
+        genesis_hash=base64.b64decode(sp.gh),
+        genesis_id=sp.gen,
+        note=note,
+        lease=lease,
+        rekey_to=address_from_string(rekey_to) if rekey_to else None,
+        payment=PaymentTransactionFields(
+            receiver=address_from_string(receiver),
+            amount=amt,
+            close_remainder_to=address_from_string(close_remainder_to) if close_remainder_to else None,
+        ),
+    )
+
+    if txn.fee is not None:
+        # Static fee is already set, encode and return directly
+        return cast(
+            algosdk.transaction.PaymentTxn,
+            algosdk.encoding.msgpack_decode(base64.b64encode(encode_transaction_raw(txn)).decode("utf-8")),
+        )
+    else:
+        # Use assign_fee with fee parameters
+        min_fee = sp.min_fee or algosdk.constants.MIN_TXN_FEE
+        txn_with_fee = assign_fee(
+            txn,
+            FeeParams(
+                fee_per_byte=sp.fee,
+                min_fee=min_fee,
+                max_fee=max_fee,
+                extra_fee=extra_fee,
+            ),
+        )
+
+        return cast(
+            algosdk.transaction.PaymentTxn,
+            algosdk.encoding.msgpack_decode(base64.b64encode(encode_transaction_raw(txn_with_fee)).decode("utf-8")),
+        )

src/algokit_utils/transactions/_algokit_core_bridge.py

@@ -22,6 +22,7 @@
 from algosdk.v2client.models.simulate_request import SimulateRequest
 from typing_extensions import deprecated
 
+from algokit_utils import _EXPERIMENTAL_DEPENDENCIES_INSTALLED
 from algokit_utils.applications.abi import ABIReturn, ABIValue
 from algokit_utils.applications.app_manager import AppManager
 from algokit_utils.applications.app_spec.arc56 import Method as Arc56Method
@@ -30,6 +31,9 @@
 from algokit_utils.models.transaction import SendParams, TransactionWrapper
 from algokit_utils.protocols.account import TransactionSignerAccountProtocol
 
+if _EXPERIMENTAL_DEPENDENCIES_INSTALLED:
+    from algokit_utils.transactions._algokit_core_bridge import build_payment_with_core
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -1861,6 +1865,17 @@ def send(
             )
         except algosdk.error.AlgodHTTPError as e:
             raise Exception(f"Transaction failed: {e}") from e
+        # We need this code to handle separately an exception thrown by the experimental AlgoKit Algod Client.
+        # However, we can't just import the dependency (as it may not be there) and
+        # we still need to re-throw the exception in all other cases.
+        except Exception as e:
+            if _EXPERIMENTAL_DEPENDENCIES_INSTALLED:
+                from algokit_algod_api.exceptions import BadRequestException
+
+                if isinstance(e, BadRequestException):
+                    raise Exception(f"Transaction failed: {e}") from e
+                raise e
+            raise e
 
     def _handle_simulate_error(self, simulate_response: SimulateAtomicTransactionResponse) -> None:
         # const failedGroup = simulateResponse?.txnGroups[0]
@@ -2250,7 +2265,10 @@ def _build_payment(
             "close_remainder_to": params.close_remainder_to,
         }
 
-        return self._common_txn_build_step(lambda x: algosdk.transaction.PaymentTxn(**x), params, txn_params)
+        if _EXPERIMENTAL_DEPENDENCIES_INSTALLED:
+            return self._common_txn_build_step(lambda x: build_payment_with_core(**x), params, txn_params)
+        else:
+            return self._common_txn_build_step(lambda x: algosdk.transaction.PaymentTxn(**x), params, txn_params)
 
     def _build_asset_create(
         self, params: AssetCreateParams, suggested_params: algosdk.transaction.SuggestedParams

src/algokit_utils/transactions/transaction_composer.py

@@ -5,7 +5,7 @@
 import pytest
 from algosdk.transaction import OnComplete
 
-from algokit_utils import SigningAccount
+from algokit_utils import _EXPERIMENTAL_DEPENDENCIES_INSTALLED, SigningAccount
 from algokit_utils._legacy_v2.application_specification import ApplicationSpecification
 from algokit_utils.algorand import AlgorandClient
 from algokit_utils.applications.app_manager import AppManager
@@ -451,8 +451,8 @@ def test_payment_logging(
         )
     )
 
-    assert mock_debug.call_count == 1
-    log_message = mock_debug.call_args[0][0]
+    assert mock_debug.call_count == 1 if not _EXPERIMENTAL_DEPENDENCIES_INSTALLED else 2
+    log_message = mock_debug.call_args_list[0][0][0]
     assert "Sending 1,000,000 µALGO" in log_message
     assert sender.address in log_message
     assert receiver.address in log_message