algokit-utils 5.0.0a3__py3-none-any.whl

algokit_utils/clients/dispenser_api_client.py

@@ -0,0 +1,212 @@
+import contextlib
+import enum
+import os
+from dataclasses import dataclass
+
+import httpx
+
+from algokit_utils.config import config
+
+__all__ = [
+    "DISPENSER_ACCESS_TOKEN_KEY",
+    "DISPENSER_ASSETS",
+    "DISPENSER_REQUEST_TIMEOUT",
+    "DispenserApiConfig",
+    "DispenserAsset",
+    "DispenserAssetName",
+    "DispenserFundResponse",
+    "DispenserLimitResponse",
+    "TestNetDispenserApiClient",
+]
+
+
+class DispenserApiConfig:
+    BASE_URL = "https://api.dispenser.algorandfoundation.tools"
+
+
+class DispenserAssetName(enum.IntEnum):
+    ALGO = 0
+
+
+@dataclass
+class DispenserAsset:
+    asset_id: int
+    """The ID of the asset"""
+    decimals: int
+    """The amount of decimal places the asset was created with"""
+    description: str
+    """The description of the asset"""
+
+
+@dataclass
+class DispenserFundResponse:
+    tx_id: str
+    """The transaction ID of the funded transaction"""
+    amount: int
+    """The amount of Algos funded"""
+
+
+@dataclass
+class DispenserLimitResponse:
+    amount: int
+    """The amount of Algos that can be funded"""
+
+
+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.
+    """
+
+    # 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
+
+    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"
+            config.logger.debug(f"{error_message}: {err}", exc_info=True)
+            raise err
+
+    def fund(self, address: str, amount: int, asset_id: int | None = None) -> DispenserFundResponse:  # noqa: ARG002
+        """
+        Fund an account with Algos from the dispenser API
+
+        :param address: The address to fund
+        :param amount: The amount of Algos to fund
+        :param asset_id: The asset ID to fund (deprecated)
+        :return: The transaction ID of the funded transaction
+        :raises Exception: If the dispenser API request fails
+
+        :example:
+            >>> dispenser_client = TestNetDispenserApiClient()
+            >>> dispenser_client.fund(address="SENDER_ADDRESS", amount=1000000)
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}",
+                data={
+                    "receiver": address,
+                    "amount": amount,
+                    "assetID": DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id,
+                },
+                method="POST",
+            )
+
+            content = response.json()
+            return DispenserFundResponse(tx_id=content["txID"], amount=content["amount"])
+
+        except Exception as err:
+            config.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:
+            config.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:
+            config.logger.exception(f"Error setting limit for account {address}: {err}")
+            raise err

algokit_utils/common.py

@@ -0,0 +1,40 @@
+"""Common utilities - user-facing facade for algokit_common.
+
+Users should import from this module instead of algokit_common directly.
+"""
+
+from algokit_common import (
+    ADDRESS_LENGTH,
+    CHECKSUM_BYTE_LENGTH,
+    HASH_BYTES_LENGTH,
+    MAX_TRANSACTION_GROUP_SIZE,
+    MICROALGOS_TO_ALGOS_RATIO,
+    MIN_TXN_FEE,
+    PUBLIC_KEY_BYTE_LENGTH,
+    SIGNATURE_BYTE_LENGTH,
+    TRANSACTION_ID_LENGTH,
+    ZERO_ADDRESS,
+    ProgramSourceMap,
+    address_from_public_key,
+    get_application_address,
+    public_key_from_address,
+    sha512_256,
+)
+
+__all__ = [
+    "ADDRESS_LENGTH",
+    "CHECKSUM_BYTE_LENGTH",
+    "HASH_BYTES_LENGTH",
+    "MAX_TRANSACTION_GROUP_SIZE",
+    "MICROALGOS_TO_ALGOS_RATIO",
+    "MIN_TXN_FEE",
+    "PUBLIC_KEY_BYTE_LENGTH",
+    "SIGNATURE_BYTE_LENGTH",
+    "TRANSACTION_ID_LENGTH",
+    "ZERO_ADDRESS",
+    "ProgramSourceMap",
+    "address_from_public_key",
+    "get_application_address",
+    "public_key_from_address",
+    "sha512_256",
+]

algokit_utils/config.py

@@ -0,0 +1,159 @@
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+# Environment variable to override the project root
+ALGOKIT_PROJECT_ROOT = os.getenv("ALGOKIT_PROJECT_ROOT")
+ALGOKIT_CONFIG_FILENAME = ".algokit.toml"
+
+
+class AlgoKitLogger(logging.Logger):
+    def __init__(self, name: str = "algokit-utils-py", level: int = logging.NOTSET):
+        super().__init__(name, level)
+
+    def _log(self, level: int, msg: object, args, exc_info=None, extra=None, stack_info=False, stacklevel=1) -> None:  # type: ignore[no-untyped-def]  # noqa: FBT002, ANN001
+        """
+        Overrides the base _log method to allow suppressing individual log calls.
+        When a caller passes suppress_log=True in the extra keyword, the log call is ignored.
+        """
+
+        # Check if the 'suppress_log' flag is provided in the extra dictionary.
+        if extra and extra.get("suppress_log", False):
+            return
+        # Call the parent _log
+        super()._log(level, msg, args, exc_info, extra, stack_info, stacklevel)
+
+    @classmethod
+    def get_null_logger(cls) -> logging.Logger:
+        """Return a logger that does nothing (a null logger)."""
+        null_logger = logging.getLogger("null")
+        null_logger.handlers.clear()
+        null_logger.addHandler(logging.NullHandler())
+        null_logger.propagate = False
+        return null_logger
+
+
+# Set our custom logger class as the default.
+logging.setLoggerClass(AlgoKitLogger)
+
+
+class UpdatableConfig:
+    """
+    Class to manage and update configuration settings for the AlgoKit project.
+
+    Attributes:
+        debug (bool): Indicates whether debug mode is enabled.
+        project_root (Path | None): The path to the project root directory.
+        trace_all (bool): Indicates whether to trace all operations.
+        trace_buffer_size_mb (int | float): The size of the trace buffer in megabytes.
+        max_search_depth (int): The maximum depth to search for a specific file.
+        populate_app_call_resources (bool): Whether to populate app call resources.
+        logger (logging.Logger): The logger instance to use. Defaults to an AlgoKitLogger instance.
+    """
+
+    def __init__(self) -> None:
+        self._logger: logging.Logger = AlgoKitLogger()
+        self._debug: bool = False
+        self._project_root: Path | None = None
+        self._trace_all: bool = False
+        self._trace_buffer_size_mb: int | float = 256  # megabytes
+        self._max_search_depth: int = 10
+        self._populate_app_call_resources: bool = True
+        self._configure_project_root()
+
+    def _configure_project_root(self) -> None:
+        """
+        Configures the project root by searching for a specific file within a depth limit.
+        """
+        current_path = Path(__file__).resolve()
+        for _ in range(self._max_search_depth):
+            self._logger.debug(f"Searching in: {current_path}")
+            if (current_path / ALGOKIT_CONFIG_FILENAME).exists():
+                self._project_root = current_path
+                break
+            current_path = current_path.parent
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Returns the logger instance."""
+        return self._logger
+
+    @property
+    def debug(self) -> bool:
+        """Returns the debug status."""
+        return self._debug
+
+    @property
+    def project_root(self) -> Path | None:
+        """Returns the project root path."""
+        return self._project_root
+
+    @property
+    def trace_all(self) -> bool:
+        """Indicates whether simulation traces for all operations should be stored."""
+        return self._trace_all
+
+    @property
+    def trace_buffer_size_mb(self) -> int | float:
+        """Returns the size of the trace buffer in megabytes."""
+        return self._trace_buffer_size_mb
+
+    @property
+    def populate_app_call_resource(self) -> bool:
+        """Indicates whether or not to populate app call resources."""
+        return self._populate_app_call_resources
+
+    def with_debug(self, func: Callable[[], str | None]) -> None:
+        """
+        Executes a function with debug mode temporarily enabled.
+        """
+        original_debug = self._debug
+        try:
+            self._debug = True
+            func()
+        finally:
+            self._debug = original_debug
+
+    def configure(
+        self,
+        *,
+        debug: bool | None = None,
+        project_root: Path | None = None,
+        trace_all: bool = False,
+        trace_buffer_size_mb: float = 256,
+        max_search_depth: int = 10,
+        populate_app_call_resources: bool = True,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        """
+        Configures various settings for the application.
+
+        :param debug: Whether debug mode is enabled.
+        :param project_root: The path to the project root directory.
+        :param trace_all: Whether to trace all operations. Defaults to False.
+        :param trace_buffer_size_mb: The trace buffer size in megabytes. Defaults to 256.
+        :param max_search_depth: The maximum depth to search for a specific file. Defaults to 10.
+        :param populate_app_call_resources: Whether to populate app call resources. Defaults to True.
+        :param logger: A custom logger to use. Defaults to AlgoKitLogger instance.
+        """
+        if logger is not None:
+            self._logger = logger
+
+        if debug is not None:
+            self._debug = debug
+            # Update logger's level so debug messages are processed only when debug is True.
+            self._logger.setLevel(logging.DEBUG)
+
+        if project_root is not None:
+            self._project_root = project_root.resolve(strict=True)
+        elif debug is not None and ALGOKIT_PROJECT_ROOT:
+            self._project_root = Path(ALGOKIT_PROJECT_ROOT).resolve(strict=True)
+
+        self._trace_all = trace_all
+        self._trace_buffer_size_mb = trace_buffer_size_mb
+        self._max_search_depth = max_search_depth
+        self._populate_app_call_resources = populate_app_call_resources
+
+
+config = UpdatableConfig()

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,160 @@
+import base64
+import re
+from collections.abc import Callable, Mapping, Sequence
+from copy import copy
+from typing import TYPE_CHECKING, TypedDict
+
+from algokit_algod_client.models import (
+    PendingTransactionResponse,
+    SimulateTransactionResult,
+    SimulationTransactionExecTrace,
+)
+from algokit_common import ProgramSourceMap
+
+if TYPE_CHECKING:
+    pass
+__all__ = [
+    "LogicError",
+    "LogicErrorData",
+    "create_simulate_traces_for_logic_error",
+    "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: "ProgramSourceMap | None",
+        transaction_id: str,
+        message: str,
+        pc: int,
+        logic_error: Exception | None = None,
+        traces: list[SimulateTransactionResult] | 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 AppClient, 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: object) -> list[SimulateTransactionResult]:
+    """Extract simulation traces from a simulate response for logic error debugging.
+
+    Args:
+        simulate: An object with simulate_response and failed_at attributes.
+
+    Returns:
+        A list of SimulateTransactionResult objects extracted from the simulation response.
+    """
+    traces: list[SimulateTransactionResult] = []
+    simulate_response = getattr(simulate, "simulate_response", None)
+    failed_at = getattr(simulate, "failed_at", None)
+
+    if not failed_at or not isinstance(simulate_response, Mapping):
+        return traces
+
+    txn_groups = simulate_response.get("txn-groups", [])
+    if not isinstance(txn_groups, Sequence):
+        return traces
+
+    for txn_group in txn_groups:
+        if not isinstance(txn_group, Mapping):
+            continue
+        txn_results = txn_group.get("txn-results", [])
+
+        if not isinstance(txn_results, Sequence):
+            continue
+
+        for txn_result in txn_results:
+            if not isinstance(txn_result, Mapping):
+                continue
+            exec_trace_raw = txn_result.get("exec-trace")
+            app_budget_consumed = txn_result.get("app-budget-consumed")
+            logic_sig_budget_consumed = txn_result.get("logic-sig-budget-consumed")
+            txn_result_inner = txn_result.get("txn-result", {})
+            logs_raw = txn_result_inner.get("logs", []) if isinstance(txn_result_inner, Mapping) else []
+            logs = [base64.b64decode(log) if isinstance(log, str) else log for log in logs_raw] if logs_raw else None
+
+            # Create PendingTransactionResponse with logs for the SimulateTransactionResult
+            # Note: txn is required but we don't have it from raw JSON, use placeholder
+            pending_response = PendingTransactionResponse(
+                txn=None,  # type: ignore[arg-type]  # placeholder for raw response parsing
+                logs=logs,
+            )
+
+            # Create SimulateTransactionResult with available data
+            traces.append(
+                SimulateTransactionResult(
+                    txn_result=pending_response,
+                    app_budget_consumed=app_budget_consumed,
+                    logic_sig_budget_consumed=logic_sig_budget_consumed,
+                    exec_trace=exec_trace_raw if isinstance(exec_trace_raw, SimulationTransactionExecTrace) else None,
+                )
+            )
+    return traces

algokit_utils/models/__init__.py

@@ -0,0 +1,7 @@
+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,12 @@
+from algokit_transact import AddressWithSigners, LogicSigAccount, MultisigAccount, MultisigMetadata
+
+__all__ = [
+    "DISPENSER_ACCOUNT_NAME",
+    "AddressWithSigners",
+    "LogicSigAccount",
+    "MultisigAccount",
+    "MultisigMetadata",
+]
+
+
+DISPENSER_ACCOUNT_NAME = "DISPENSER"