algokit-utils 2.4.0b1__py3-none-any.whl → 3.0.0__py3-none-any.whl

algokit_utils/dispenser_api.py

@@ -1,178 +1,10 @@
-import contextlib
-import enum
-import logging
-import os
-from dataclasses import dataclass
+import warnings
 
-import httpx
+warnings.warn(
+    "The legacy v2 dispenser api module is deprecated and will be removed in a future version. "
+    "Import from 'algokit_utils.clients.dispenser_api_client' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-logger = logging.getLogger(__name__)
-
-
-class DispenserApiConfig:
-    BASE_URL = "https://api.dispenser.algorandfoundation.tools"
-
-
-class DispenserAssetName(enum.IntEnum):
-    ALGO = 0
-
-
-@dataclass
-class DispenserAsset:
-    asset_id: int
-    decimals: int
-    description: str
-
-
-@dataclass
-class DispenserFundResponse:
-    tx_id: str
-    amount: int
-
-
-@dataclass
-class DispenserLimitResponse:
-    amount: int
-
-
-DISPENSER_ASSETS = {
-    DispenserAssetName.ALGO: DispenserAsset(
-        asset_id=0,
-        decimals=6,
-        description="Algo",
-    ),
-}
-DISPENSER_REQUEST_TIMEOUT = 15
-DISPENSER_ACCESS_TOKEN_KEY = "ALGOKIT_DISPENSER_ACCESS_TOKEN"
-
-
-class TestNetDispenserApiClient:
-    """
-    Client for interacting with the [AlgoKit TestNet Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md).
-    To get started create a new access token via `algokit dispenser login --ci`
-    and pass it to the client constructor as `auth_token`.
-    Alternatively set the access token as environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN`,
-    and it will be auto loaded. If both are set, the constructor argument takes precedence.
-
-    Default request timeout is 15 seconds. Modify by passing `request_timeout` to the constructor.
-    """
-
-    auth_token: str
-    request_timeout = DISPENSER_REQUEST_TIMEOUT
-
-    def __init__(self, auth_token: str | None = None, request_timeout: int = DISPENSER_REQUEST_TIMEOUT):
-        auth_token_from_env = os.getenv(DISPENSER_ACCESS_TOKEN_KEY)
-
-        if auth_token:
-            self.auth_token = auth_token
-        elif auth_token_from_env:
-            self.auth_token = auth_token_from_env
-        else:
-            raise Exception(
-                f"Can't init AlgoKit TestNet Dispenser API client "
-                f"because neither environment variable {DISPENSER_ACCESS_TOKEN_KEY} or "
-                "the auth_token were provided."
-            )
-
-        self.request_timeout = request_timeout
-
-    def _process_dispenser_request(
-        self, *, auth_token: str, url_suffix: str, data: dict | None = None, method: str = "POST"
-    ) -> httpx.Response:
-        """
-        Generalized method to process http requests to dispenser API
-        """
-
-        headers = {"Authorization": f"Bearer {(auth_token)}"}
-
-        # Set request arguments
-        request_args = {
-            "url": f"{DispenserApiConfig.BASE_URL}/{url_suffix}",
-            "headers": headers,
-            "timeout": self.request_timeout,
-        }
-
-        if method.upper() != "GET" and data is not None:
-            request_args["json"] = data
-
-        try:
-            response: httpx.Response = getattr(httpx, method.lower())(**request_args)
-            response.raise_for_status()
-            return response
-
-        except httpx.HTTPStatusError as err:
-            error_message = f"Error processing dispenser API request: {err.response.status_code}"
-            error_response = None
-            with contextlib.suppress(Exception):
-                error_response = err.response.json()
-
-            if error_response and error_response.get("code"):
-                error_message = error_response.get("code")
-
-            elif err.response.status_code == httpx.codes.BAD_REQUEST:
-                error_message = err.response.json()["message"]
-
-            raise Exception(error_message) from err
-
-        except Exception as err:
-            error_message = "Error processing dispenser API request"
-            logger.debug(f"{error_message}: {err}", exc_info=True)
-            raise err
-
-    def fund(self, address: str, amount: int, asset_id: int) -> DispenserFundResponse:
-        """
-        Fund an account with Algos from the dispenser API
-        """
-
-        try:
-            response = self._process_dispenser_request(
-                auth_token=self.auth_token,
-                url_suffix=f"fund/{asset_id}",
-                data={"receiver": address, "amount": amount, "assetID": asset_id},
-                method="POST",
-            )
-
-            content = response.json()
-            return DispenserFundResponse(tx_id=content["txID"], amount=content["amount"])
-
-        except Exception as err:
-            logger.exception(f"Error funding account {address}: {err}")
-            raise err
-
-    def refund(self, refund_txn_id: str) -> None:
-        """
-        Register a refund for a transaction with the dispenser API
-        """
-
-        try:
-            self._process_dispenser_request(
-                auth_token=self.auth_token,
-                url_suffix="refund",
-                data={"refundTransactionID": refund_txn_id},
-                method="POST",
-            )
-
-        except Exception as err:
-            logger.exception(f"Error issuing refund for txn_id {refund_txn_id}: {err}")
-            raise err
-
-    def get_limit(
-        self,
-        address: str,
-    ) -> DispenserLimitResponse:
-        """
-        Get current limit for an account with Algos from the dispenser API
-        """
-
-        try:
-            response = self._process_dispenser_request(
-                auth_token=self.auth_token,
-                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}/limit",
-                method="GET",
-            )
-            content = response.json()
-
-            return DispenserLimitResponse(amount=content["amount"])
-        except Exception as err:
-            logger.exception(f"Error setting limit for account {address}: {err}")
-            raise err
+from algokit_utils.clients.dispenser_api_client import *  # noqa: F403, E402

algokit_utils/errors/__init__.py

@@ -0,0 +1 @@
+from algokit_utils.errors.logic_error import *  # noqa: F403

algokit_utils/errors/logic_error.py

@@ -0,0 +1,121 @@
+import base64
+import re
+from collections.abc import Callable
+from copy import copy
+from typing import TYPE_CHECKING, TypedDict
+
+from algosdk.atomic_transaction_composer import (
+    SimulateAtomicTransactionResponse,
+)
+
+from algokit_utils.models.simulate import SimulationTrace
+
+if TYPE_CHECKING:
+    from algosdk.source_map import SourceMap as AlgoSourceMap
+__all__ = [
+    "LogicError",
+    "LogicErrorData",
+    "parse_logic_error",
+]
+
+
+LOGIC_ERROR = (
+    ".*transaction (?P<transaction_id>[A-Z0-9]+): logic eval error: (?P<message>.*). Details: .*pc=(?P<pc>[0-9]+).*"
+)
+
+
+class LogicErrorData(TypedDict):
+    transaction_id: str
+    message: str
+    pc: int
+
+
+def parse_logic_error(
+    error_str: str,
+) -> LogicErrorData | None:
+    match = re.match(LOGIC_ERROR, error_str)
+    if match is None:
+        return None
+
+    return {
+        "transaction_id": match.group("transaction_id"),
+        "message": match.group("message"),
+        "pc": int(match.group("pc")),
+    }
+
+
+class LogicError(Exception):
+    def __init__(
+        self,
+        *,
+        logic_error_str: str,
+        program: str,
+        source_map: "AlgoSourceMap | None",
+        transaction_id: str,
+        message: str,
+        pc: int,
+        logic_error: Exception | None = None,
+        traces: list[SimulationTrace] | None = None,
+        get_line_for_pc: Callable[[int], int | None] | None = None,
+    ):
+        self.logic_error = logic_error
+        self.logic_error_str = logic_error_str
+        try:
+            self.program = base64.b64decode(program).decode("utf-8")
+        except Exception:
+            self.program = program
+        self.source_map = source_map
+        self.lines = self.program.split("\n")
+        self.transaction_id = transaction_id
+        self.message = message
+        self.pc = pc
+        self.traces = traces
+        self.line_no = (
+            self.source_map.get_line_for_pc(self.pc)
+            if self.source_map
+            else get_line_for_pc(self.pc)
+            if get_line_for_pc
+            else None
+        )
+
+    def __str__(self) -> str:
+        return (
+            f"Txn {self.transaction_id} had error '{self.message}' at PC {self.pc}"
+            + (":" if self.line_no is None else f" and Source Line {self.line_no}:")
+            + f"\n{self.trace()}"
+        )
+
+    def trace(self, lines: int = 5) -> str:
+        if self.line_no is None:
+            return """
+Could not determine TEAL source line for the error as no approval source map was provided, to receive a trace of the
+error please provide an approval SourceMap. Either by:
+    1.Providing template_values when creating the ApplicationClient, so a SourceMap can be obtained automatically OR
+    2.Set approval_source_map from a previously compiled approval program OR
+    3.Import a previously exported source map using import_source_map"""
+
+        program_lines = copy(self.lines)
+        program_lines[self.line_no] += "\t\t<-- Error"
+        lines_before = max(0, self.line_no - lines)
+        lines_after = min(len(program_lines), self.line_no + lines)
+        return "\n\t" + "\n\t".join(program_lines[lines_before:lines_after])
+
+
+def create_simulate_traces_for_logic_error(simulate: SimulateAtomicTransactionResponse) -> list[SimulationTrace]:
+    traces = []
+    if hasattr(simulate, "simulate_response") and hasattr(simulate, "failed_at") and simulate.failed_at:
+        for txn_group in simulate.simulate_response["txn-groups"]:
+            app_budget_added = txn_group.get("app-budget-added", None)
+            app_budget_consumed = txn_group.get("app-budget-consumed", None)
+            failure_message = txn_group.get("failure-message", None)
+            txn_result = txn_group.get("txn-results", [{}])[0]
+            exec_trace = txn_result.get("exec-trace", {})
+            traces.append(
+                SimulationTrace(
+                    app_budget_added=app_budget_added,
+                    app_budget_consumed=app_budget_consumed,
+                    failure_message=failure_message,
+                    exec_trace=exec_trace,
+                )
+            )
+    return traces

algokit_utils/logic_error.py

@@ -1,85 +1,10 @@
-import re
-from copy import copy
-from typing import TYPE_CHECKING, TypedDict
+import warnings
 
-from algokit_utils.models import SimulationTrace
-
-if TYPE_CHECKING:
-    from algosdk.source_map import SourceMap as AlgoSourceMap
-
-__all__ = [
-    "LogicError",
-    "parse_logic_error",
-]
-
-LOGIC_ERROR = (
-    ".*transaction (?P<transaction_id>[A-Z0-9]+): logic eval error: (?P<message>.*). Details: .*pc=(?P<pc>[0-9]+).*"
+warnings.warn(
+    "The legacy v2 logic error module is deprecated and will be removed in a future version. "
+    "Use 'from algokit_utils.errors import LogicError' instead.",
+    DeprecationWarning,
+    stacklevel=2,
 )
 
-
-class LogicErrorData(TypedDict):
-    transaction_id: str
-    message: str
-    pc: int
-
-
-def parse_logic_error(
-    error_str: str,
-) -> LogicErrorData | None:
-    match = re.match(LOGIC_ERROR, error_str)
-    if match is None:
-        return None
-
-    return {
-        "transaction_id": match.group("transaction_id"),
-        "message": match.group("message"),
-        "pc": int(match.group("pc")),
-    }
-
-
-class LogicError(Exception):
-    def __init__(  # noqa: PLR0913
-        self,
-        *,
-        logic_error_str: str,
-        program: str,
-        source_map: "AlgoSourceMap | None",
-        transaction_id: str,
-        message: str,
-        pc: int,
-        logic_error: Exception | None = None,
-        traces: list[SimulationTrace] | None = None,
-    ):
-        self.logic_error = logic_error
-        self.logic_error_str = logic_error_str
-        self.program = program
-        self.source_map = source_map
-        self.lines = program.split("\n")
-        self.transaction_id = transaction_id
-        self.message = message
-        self.pc = pc
-        self.traces = traces
-
-        self.line_no = self.source_map.get_line_for_pc(self.pc) if self.source_map else None
-
-    def __str__(self) -> str:
-        return (
-            f"Txn {self.transaction_id} had error '{self.message}' at PC {self.pc}"
-            + (":" if self.line_no is None else f" and Source Line {self.line_no}:")
-            + f"\n{self.trace()}"
-        )
-
-    def trace(self, lines: int = 5) -> str:
-        if self.line_no is None:
-            return """
-Could not determine TEAL source line for the error as no approval source map was provided, to receive a trace of the
-error please provide an approval SourceMap. Either by:
-    1.) Providing template_values when creating the ApplicationClient, so a SourceMap can be obtained automatically OR
-    2.) Set approval_source_map from a previously compiled approval program OR
-    3.) Import a previously exported source map using import_source_map"""
-
-        program_lines = copy(self.lines)
-        program_lines[self.line_no] += "\t\t<-- Error"
-        lines_before = max(0, self.line_no - lines)
-        lines_after = min(len(program_lines), self.line_no + lines)
-        return "\n\t" + "\n\t".join(program_lines[lines_before:lines_after])
+from algokit_utils.errors.logic_error import *  # noqa: F403, E402

algokit_utils/models/__init__.py

@@ -0,0 +1,8 @@
+from algokit_utils._legacy_v2.models import *  # noqa: F403
+from algokit_utils.models.account import *  # noqa: F403
+from algokit_utils.models.amount import *  # noqa: F403
+from algokit_utils.models.application import *  # noqa: F403
+from algokit_utils.models.network import *  # noqa: F403
+from algokit_utils.models.simulate import *  # noqa: F403
+from algokit_utils.models.state import *  # noqa: F403
+from algokit_utils.models.transaction import *  # noqa: F403

algokit_utils/models/account.py

@@ -0,0 +1,217 @@
+import dataclasses
+
+import algosdk
+import algosdk.atomic_transaction_composer
+from algosdk.atomic_transaction_composer import AccountTransactionSigner, LogicSigTransactionSigner, TransactionSigner
+from algosdk.transaction import LogicSigAccount as AlgosdkLogicSigAccount
+from algosdk.transaction import Multisig, MultisigTransaction
+from typing_extensions import deprecated
+
+__all__ = [
+    "DISPENSER_ACCOUNT_NAME",
+    "LogicSigAccount",
+    "MultiSigAccount",
+    "MultisigMetadata",
+    "SigningAccount",
+    "TransactionSignerAccount",
+]
+
+
+DISPENSER_ACCOUNT_NAME = "DISPENSER"
+
+
+@dataclasses.dataclass(kw_only=True)
+class TransactionSignerAccount:
+    """A basic transaction signer account."""
+
+    address: str
+    signer: TransactionSigner
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.address, str):
+            raise TypeError("Address must be a string")
+        if not isinstance(self.signer, TransactionSigner):
+            raise TypeError("Signer must be a TransactionSigner instance")
+
+
+@dataclasses.dataclass(kw_only=True)
+class SigningAccount:
+    """Holds the private key and address for an account.
+
+    Provides access to the account's private key, address, public key and transaction signer.
+    """
+
+    private_key: str
+    """Base64 encoded private key"""
+    address: str = dataclasses.field(default="")
+    """Address for this account"""
+
+    def __post_init__(self) -> None:
+        if not self.address:
+            self.address = str(algosdk.account.address_from_private_key(self.private_key))
+
+    @property
+    def public_key(self) -> bytes:
+        """The public key for this account.
+
+        :return: The public key as bytes
+        """
+        public_key = algosdk.encoding.decode_address(self.address)
+        assert isinstance(public_key, bytes)
+        return public_key
+
+    @property
+    def signer(self) -> AccountTransactionSigner:
+        """Get an AccountTransactionSigner for this account.
+
+        :return: A transaction signer for this account
+        """
+        return AccountTransactionSigner(self.private_key)
+
+    @deprecated(
+        "Use `algorand.account.random()` or `SigningAccount(private_key=algosdk.account.generate_account()[0])` instead"
+    )
+    @staticmethod
+    def new_account() -> "SigningAccount":
+        """Create a new random account.
+
+        :return: A new Account instance
+        """
+        private_key, address = algosdk.account.generate_account()
+        return SigningAccount(private_key=private_key)
+
+
+@dataclasses.dataclass(kw_only=True)
+class MultisigMetadata:
+    """Metadata for a multisig account.
+
+    Contains the version, threshold and addresses for a multisig account.
+    """
+
+    version: int
+    threshold: int
+    addresses: list[str]
+
+
+@dataclasses.dataclass(kw_only=True)
+class MultiSigAccount:
+    """Account wrapper that supports partial or full multisig signing.
+
+    Provides functionality to manage and sign transactions for a multisig account.
+
+    :param multisig_params: The parameters for the multisig account
+    :param signing_accounts: The list of accounts that can sign
+    """
+
+    _params: MultisigMetadata
+    _signing_accounts: list[SigningAccount]
+    _addr: str
+    _signer: TransactionSigner
+    _multisig: Multisig
+
+    def __init__(self, multisig_params: MultisigMetadata, signing_accounts: list[SigningAccount]) -> None:
+        self._params = multisig_params
+        self._signing_accounts = signing_accounts
+        self._multisig = Multisig(multisig_params.version, multisig_params.threshold, multisig_params.addresses)
+        self._addr = str(self._multisig.address())
+        self._signer = algosdk.atomic_transaction_composer.MultisigTransactionSigner(
+            self._multisig,
+            [account.private_key for account in signing_accounts],
+        )
+
+    @property
+    def multisig(self) -> Multisig:
+        """Get the underlying `algosdk.transaction.Multisig` object instance.
+
+        :return: The `algosdk.transaction.Multisig` object instance
+        """
+        return self._multisig
+
+    @property
+    def params(self) -> MultisigMetadata:
+        """Get the parameters for the multisig account.
+
+        :return: The multisig account parameters
+        """
+        return self._params
+
+    @property
+    def signing_accounts(self) -> list[SigningAccount]:
+        """Get the list of accounts that are present to sign.
+
+        :return: The list of signing accounts
+        """
+        return self._signing_accounts
+
+    @property
+    def address(self) -> str:
+        """Get the address of the multisig account.
+
+        :return: The multisig account address
+        """
+        return self._addr
+
+    @property
+    def signer(self) -> TransactionSigner:
+        """Get the transaction signer for this multisig account.
+
+        :return: The multisig transaction signer
+        """
+        return self._signer
+
+    def sign(self, transaction: algosdk.transaction.Transaction) -> MultisigTransaction:
+        """Sign the given transaction with all present signers.
+
+        :param transaction: Either a transaction object or a raw, partially signed transaction
+        :return: The transaction signed by the present signers
+        """
+        msig_txn = MultisigTransaction(
+            transaction,
+            self._multisig,
+        )
+        for signer in self._signing_accounts:
+            msig_txn.sign(signer.private_key)
+
+        return msig_txn
+
+
+@dataclasses.dataclass(kw_only=True)
+class LogicSigAccount:
+    """Account wrapper that supports logic sig signing.
+
+    Provides functionality to manage and sign transactions for a logic sig account.
+    """
+
+    _signer: LogicSigTransactionSigner
+
+    def __init__(self, program: bytes, args: list[bytes] | None) -> None:
+        self._signer = LogicSigTransactionSigner(AlgosdkLogicSigAccount(program, args))
+
+    @property
+    def lsig(self) -> AlgosdkLogicSigAccount:
+        """Get the underlying `algosdk.transaction.LogicSigAccount` object instance.
+
+        :return: The `algosdk.transaction.LogicSigAccount` object instance
+        """
+        return self._signer.lsig
+
+    @property
+    def address(self) -> str:
+        """Get the address of the logic sig account.
+
+        If the LogicSig is delegated to another account, this will return the address of that account.
+
+        If the LogicSig is not delegated to another account, this will return an escrow address that is the hash of
+        the LogicSig's program code.
+
+        :return: The logic sig account address
+        """
+        return self._signer.lsig.address()
+
+    @property
+    def signer(self) -> LogicSigTransactionSigner:
+        """Get the transaction signer for this multisig account.
+
+        :return: The multisig transaction signer
+        """
+        return self._signer