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

algokit_utils/models/amount.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import overload
+
+import algosdk
+from typing_extensions import Self
+
+__all__ = ["ALGORAND_MIN_TX_FEE", "AlgoAmount", "algo", "micro_algo", "transaction_fees"]
+
+
+class AlgoAmount:
+    """Wrapper class to ensure safe, explicit conversion between µAlgo, Algo and numbers.
+
+    :example:
+        >>> amount = AlgoAmount(algo=1)
+        >>> amount = AlgoAmount.from_algo(1)
+        >>> amount = AlgoAmount(micro_algo=1_000_000)
+        >>> amount = AlgoAmount.from_micro_algo(1_000_000)
+    """
+
+    @overload
+    def __init__(self, *, micro_algo: int) -> None: ...
+
+    @overload
+    def __init__(self, *, algo: int | Decimal) -> None: ...
+
+    def __init__(
+        self,
+        *,
+        micro_algo: int | None = None,
+        algo: int | Decimal | None = None,
+    ):
+        if micro_algo is None and algo is None:
+            raise ValueError("No amount provided")
+
+        if micro_algo is not None:
+            self.amount_in_micro_algo = int(micro_algo)
+        elif algo is not None:
+            self.amount_in_micro_algo = int(algo * algosdk.constants.MICROALGOS_TO_ALGOS_RATIO)
+        else:
+            raise ValueError("Invalid amount provided")
+
+    @property
+    def micro_algo(self) -> int:
+        """Return the amount as a number in µAlgo.
+
+        :returns: The amount in µAlgo.
+        """
+        return self.amount_in_micro_algo
+
+    @property
+    def algo(self) -> Decimal:
+        """Return the amount as a number in Algo.
+
+        :returns: The amount in Algo.
+        """
+        return algosdk.util.microalgos_to_algos(self.amount_in_micro_algo)  # type: ignore[no-any-return]
+
+    @staticmethod
+    def from_algo(amount: int | Decimal) -> AlgoAmount:
+        """Create an AlgoAmount object representing the given number of Algo.
+
+        :param amount: The amount in Algo.
+        :returns: An AlgoAmount instance.
+
+        :example:
+            >>> amount = AlgoAmount.from_algo(1)
+        """
+        return AlgoAmount(algo=amount)
+
+    @staticmethod
+    def from_micro_algo(amount: int) -> AlgoAmount:
+        """Create an AlgoAmount object representing the given number of µAlgo.
+
+        :param amount: The amount in µAlgo.
+        :returns: An AlgoAmount instance.
+
+        :example:
+            >>> amount = AlgoAmount.from_micro_algo(1_000_000)
+        """
+        return AlgoAmount(micro_algo=amount)
+
+    def __str__(self) -> str:
+        return f"{self.micro_algo:,} µALGO"
+
+    def __int__(self) -> int:
+        return self.micro_algo
+
+    def __add__(self, other: AlgoAmount) -> AlgoAmount:
+        if isinstance(other, AlgoAmount):
+            total_micro_algos = self.micro_algo + other.micro_algo
+        else:
+            raise TypeError(f"Unsupported operand type(s) for +: 'AlgoAmount' and '{type(other).__name__}'")
+        return AlgoAmount.from_micro_algo(total_micro_algos)
+
+    def __radd__(self, other: AlgoAmount) -> AlgoAmount:
+        return self.__add__(other)
+
+    def __iadd__(self, other: AlgoAmount) -> Self:
+        if isinstance(other, AlgoAmount):
+            self.amount_in_micro_algo += other.micro_algo
+        else:
+            raise TypeError(f"Unsupported operand type(s) for +: 'AlgoAmount' and '{type(other).__name__}'")
+        return self
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo == other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo == int(other)
+        raise TypeError(f"Unsupported operand type(s) for ==: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __ne__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo != other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo != int(other)
+        raise TypeError(f"Unsupported operand type(s) for !=: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __lt__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo < other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo < int(other)
+        raise TypeError(f"Unsupported operand type(s) for <: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __le__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo <= other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo <= int(other)
+        raise TypeError(f"Unsupported operand type(s) for <=: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __gt__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo > other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo > int(other)
+        raise TypeError(f"Unsupported operand type(s) for >: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __ge__(self, other: object) -> bool:
+        if isinstance(other, AlgoAmount):
+            return self.amount_in_micro_algo >= other.amount_in_micro_algo
+        elif isinstance(other, int):
+            return self.amount_in_micro_algo >= int(other)
+        raise TypeError(f"Unsupported operand type(s) for >=: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __sub__(self, other: AlgoAmount) -> AlgoAmount:
+        if isinstance(other, AlgoAmount):
+            total_micro_algos = self.micro_algo - other.micro_algo
+        else:
+            raise TypeError(f"Unsupported operand type(s) for -: 'AlgoAmount' and '{type(other).__name__}'")
+        return AlgoAmount.from_micro_algo(total_micro_algos)
+
+    def __rsub__(self, other: int) -> AlgoAmount:
+        if isinstance(other, (int)):
+            total_micro_algos = int(other) - self.micro_algo
+            return AlgoAmount.from_micro_algo(total_micro_algos)
+        raise TypeError(f"Unsupported operand type(s) for -: '{type(other).__name__}' and 'AlgoAmount'")
+
+    def __isub__(self, other: AlgoAmount) -> Self:
+        if isinstance(other, AlgoAmount):
+            self.amount_in_micro_algo -= other.micro_algo
+        else:
+            raise TypeError(f"Unsupported operand type(s) for -: 'AlgoAmount' and '{type(other).__name__}'")
+        return self
+
+
+# Helper functions
+def algo(algo: int) -> AlgoAmount:
+    """Create an AlgoAmount object representing the given number of Algo.
+
+    :param algo: The number of Algo to create an AlgoAmount object for.
+    :return: An AlgoAmount object representing the given number of Algo.
+    """
+    return AlgoAmount.from_algo(algo)
+
+
+def micro_algo(micro_algo: int) -> AlgoAmount:
+    """Create an AlgoAmount object representing the given number of µAlgo.
+
+    :param micro_algo: The number of µAlgo to create an AlgoAmount object for.
+    :return: An AlgoAmount object representing the given number of µAlgo.
+    """
+    return AlgoAmount.from_micro_algo(micro_algo)
+
+
+ALGORAND_MIN_TX_FEE = micro_algo(1_000)
+
+
+def transaction_fees(number_of_transactions: int) -> AlgoAmount:
+    """Calculate the total transaction fees for a given number of transactions.
+
+    :param number_of_transactions: The number of transactions to calculate the fees for.
+    :return: The total transaction fees.
+    """
+
+    total_micro_algos = number_of_transactions * ALGORAND_MIN_TX_FEE.micro_algo
+    return AlgoAmount.from_micro_algo(total_micro_algos)

algokit_utils/models/application.py

@@ -0,0 +1,91 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import algosdk
+from algosdk.source_map import SourceMap
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = [
+    "AppCompilationResult",
+    "AppInformation",
+    "AppSourceMaps",
+    "AppState",
+    "CompiledTeal",
+]
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppState:
+    key_raw: bytes
+    """The key of the state as raw bytes"""
+    key_base64: str
+    """The key of the state"""
+    value_raw: bytes | None
+    """The value of the state as raw bytes"""
+    value_base64: str | None
+    """The value of the state as base64 encoded string"""
+    value: str | int
+    """The value of the state as a string or integer"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppInformation:
+    app_id: int
+    """The ID of the application"""
+    app_address: str
+    """The address of the application"""
+    approval_program: bytes
+    """The approval program"""
+    clear_state_program: bytes
+    """The clear state program"""
+    creator: str
+    """The creator of the application"""
+    global_state: dict[str, AppState]
+    """The global state of the application"""
+    local_ints: int
+    """The number of local ints"""
+    local_byte_slices: int
+    """The number of local byte slices"""
+    global_ints: int
+    """The number of global ints"""
+    global_byte_slices: int
+    """The number of global byte slices"""
+    extra_program_pages: int | None
+    """The number of extra program pages"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class CompiledTeal:
+    """The compiled teal code"""
+
+    teal: str
+    """The teal code"""
+    compiled: str
+    """The compiled teal code"""
+    compiled_hash: str
+    """The compiled hash"""
+    compiled_base64_to_bytes: bytes
+    """The compiled base64 to bytes"""
+    source_map: algosdk.source_map.SourceMap | None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCompilationResult:
+    """The compiled teal code"""
+
+    compiled_approval: CompiledTeal
+    """The compiled approval program"""
+    compiled_clear: CompiledTeal
+    """The compiled clear state program"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppSourceMaps:
+    """The source maps for the application"""
+
+    approval_source_map: SourceMap | None = None
+    """The source map for the approval program"""
+    clear_source_map: SourceMap | None = None
+    """The source map for the clear state program"""

algokit_utils/models/network.py

@@ -0,0 +1,29 @@
+import dataclasses
+
+__all__ = [
+    "AlgoClientConfigs",
+    "AlgoClientNetworkConfig",
+]
+
+
+@dataclasses.dataclass
+class AlgoClientNetworkConfig:
+    """Connection details for connecting to an {py:class}`algosdk.v2client.algod.AlgodClient` or
+    {py:class}`algosdk.v2client.indexer.IndexerClient`"""
+
+    server: str
+    """URL for the service e.g. `http://localhost` or `https://testnet-api.algonode.cloud`"""
+    token: str | None = None
+    """API Token to authenticate with the service e.g '4001' or '8980'"""
+    port: str | int | None = None
+
+    def full_url(self) -> str:
+        """Returns the full URL for the service"""
+        return f"{self.server.rstrip('/')}{f':{self.port}' if self.port else ''}"
+
+
+@dataclasses.dataclass
+class AlgoClientConfigs:
+    algod_config: AlgoClientNetworkConfig
+    indexer_config: AlgoClientNetworkConfig | None
+    kmd_config: AlgoClientNetworkConfig | None

algokit_utils/models/simulate.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+__all__ = ["SimulationTrace"]
+
+
+@dataclass
+class SimulationTrace:
+    app_budget_added: int | None
+    app_budget_consumed: int | None
+    failure_message: str | None
+    exec_trace: dict[str, object]

algokit_utils/models/state.py

@@ -0,0 +1,68 @@
+import base64
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import TypeAlias
+
+from algosdk.atomic_transaction_composer import AccountTransactionSigner
+from algosdk.box_reference import BoxReference as AlgosdkBoxReference
+
+__all__ = [
+    "BoxIdentifier",
+    "BoxName",
+    "BoxReference",
+    "BoxValue",
+    "DataTypeFlag",
+    "TealTemplateParams",
+]
+
+
+@dataclass(kw_only=True, frozen=True)
+class BoxName:
+    """The name of the box"""
+
+    name: str
+    """The name of the box as a string"""
+    name_raw: bytes
+    """The name of the box as raw bytes"""
+    name_base64: str
+    """The name of the box as a base64 encoded string"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class BoxValue:
+    """The value of the box"""
+
+    name: BoxName
+    """The name of the box"""
+    value: bytes
+    """The value of the box as raw bytes"""
+
+
+class DataTypeFlag(IntEnum):
+    BYTES = 1
+    UINT = 2
+
+
+TealTemplateParams: TypeAlias = Mapping[str, str | int | bytes] | dict[str, str | int | bytes]
+
+
+BoxIdentifier: TypeAlias = str | bytes | AccountTransactionSigner
+
+
+class BoxReference(AlgosdkBoxReference):
+    def __init__(self, app_id: int, name: bytes | str):
+        super().__init__(app_index=app_id, name=self._b64_decode(name))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (BoxReference | AlgosdkBoxReference)):
+            return self.app_index == other.app_index and self.name == other.name
+        return False
+
+    def _b64_decode(self, value: str | bytes) -> bytes:
+        if isinstance(value, str):
+            try:
+                return base64.b64decode(value)
+            except Exception:
+                return value.encode("utf-8")
+        return value

algokit_utils/models/transaction.py

@@ -0,0 +1,100 @@
+from typing import Any, Literal, TypedDict, TypeVar
+
+import algosdk
+
+__all__ = [
+    "Arc2TransactionNote",
+    "BaseArc2Note",
+    "JsonFormatArc2Note",
+    "SendParams",
+    "StringFormatArc2Note",
+    "TransactionNote",
+    "TransactionNoteData",
+    "TransactionWrapper",
+]
+
+
+# Define specific types for different formats
+class BaseArc2Note(TypedDict):
+    """Base ARC-0002 transaction note structure"""
+
+    dapp_name: str
+
+
+class StringFormatArc2Note(BaseArc2Note):
+    """ARC-0002 note for string-based formats (m/b/u)"""
+
+    format: Literal["m", "b", "u"]
+    data: str
+
+
+class JsonFormatArc2Note(BaseArc2Note):
+    """ARC-0002 note for JSON format"""
+
+    format: Literal["j"]
+    data: str | dict[str, Any] | list[Any] | int | None
+
+
+# Combined type for all valid ARC-0002 notes
+# See: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md
+Arc2TransactionNote = StringFormatArc2Note | JsonFormatArc2Note
+
+TransactionNoteData = str | None | int | list[Any] | dict[str, Any]
+TransactionNote = bytes | TransactionNoteData | Arc2TransactionNote
+
+TxnTypeT = TypeVar("TxnTypeT", bound=algosdk.transaction.Transaction)
+
+
+class TransactionWrapper:
+    """Wrapper around algosdk.transaction.Transaction with optional property validators"""
+
+    def __init__(self, transaction: algosdk.transaction.Transaction) -> None:
+        self._raw = transaction
+
+    @property
+    def raw(self) -> algosdk.transaction.Transaction:
+        return self._raw
+
+    @property
+    def payment(self) -> algosdk.transaction.PaymentTxn:
+        return self._return_if_type(
+            algosdk.transaction.PaymentTxn,
+        )
+
+    @property
+    def keyreg(self) -> algosdk.transaction.KeyregTxn:
+        return self._return_if_type(algosdk.transaction.KeyregTxn)
+
+    @property
+    def asset_config(self) -> algosdk.transaction.AssetConfigTxn:
+        return self._return_if_type(algosdk.transaction.AssetConfigTxn)
+
+    @property
+    def asset_transfer(self) -> algosdk.transaction.AssetTransferTxn:
+        return self._return_if_type(algosdk.transaction.AssetTransferTxn)
+
+    @property
+    def asset_freeze(self) -> algosdk.transaction.AssetFreezeTxn:
+        return self._return_if_type(algosdk.transaction.AssetFreezeTxn)
+
+    @property
+    def application_call(self) -> algosdk.transaction.ApplicationCallTxn:
+        return self._return_if_type(algosdk.transaction.ApplicationCallTxn)
+
+    @property
+    def state_proof(self) -> algosdk.transaction.StateProofTxn:
+        return self._return_if_type(algosdk.transaction.StateProofTxn)
+
+    def _return_if_type(self, txn_type: type[TxnTypeT]) -> TxnTypeT:
+        if isinstance(self._raw, txn_type):
+            return self._raw
+        raise ValueError(f"Transaction is not of type {txn_type.__name__}")
+
+
+class SendParams(TypedDict, total=False):
+    """Parameters for sending a transaction"""
+
+    max_rounds_to_wait: int | None
+    suppress_log: bool | None
+    populate_app_call_resources: bool | None
+    cover_app_call_inner_transaction_fees: bool | None

algokit_utils/network_clients.py

@@ -1,130 +1,9 @@
-import dataclasses
-import os
-from typing import Literal
-from urllib import parse
+import warnings
 
-from algosdk.kmd import KMDClient
-from algosdk.v2client.algod import AlgodClient
-from algosdk.v2client.indexer import IndexerClient
+warnings.warn(
+    "The legacy v2 network clients module is deprecated and will be removed in a future version.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-__all__ = [
-    "AlgoClientConfig",
-    "get_algod_client",
-    "get_algonode_config",
-    "get_default_localnet_config",
-    "get_indexer_client",
-    "get_kmd_client_from_algod_client",
-    "is_localnet",
-    "is_mainnet",
-    "is_testnet",
-    "AlgoClientConfigs",
-    "get_kmd_client",
-]
-
-
-@dataclasses.dataclass
-class AlgoClientConfig:
-    """Connection details for connecting to an {py:class}`algosdk.v2client.algod.AlgodClient` or
-    {py:class}`algosdk.v2client.indexer.IndexerClient`"""
-
-    server: str
-    """URL for the service e.g. `http://localhost:4001` or `https://testnet-api.algonode.cloud`"""
-    token: str
-    """API Token to authenticate with the service"""
-
-
-@dataclasses.dataclass
-class AlgoClientConfigs:
-    algod_config: AlgoClientConfig
-    indexer_config: AlgoClientConfig
-    kmd_config: AlgoClientConfig | None
-
-
-def get_default_localnet_config(config: Literal["algod", "indexer", "kmd"]) -> AlgoClientConfig:
-    """Returns the client configuration to point to the default LocalNet"""
-    port = {"algod": 4001, "indexer": 8980, "kmd": 4002}[config]
-    return AlgoClientConfig(server=f"http://localhost:{port}", token="a" * 64)
-
-
-def get_algonode_config(
-    network: Literal["testnet", "mainnet"], config: Literal["algod", "indexer"], token: str
-) -> AlgoClientConfig:
-    client = "api" if config == "algod" else "idx"
-    return AlgoClientConfig(
-        server=f"https://{network}-{client}.algonode.cloud",
-        token=token,
-    )
-
-
-def get_algod_client(config: AlgoClientConfig | None = None) -> AlgodClient:
-    """Returns an {py:class}`algosdk.v2client.algod.AlgodClient` from `config` or environment
-
-    If no configuration provided will use environment variables `ALGOD_SERVER`, `ALGOD_PORT` and `ALGOD_TOKEN`"""
-    config = config or _get_config_from_environment("ALGOD")
-    headers = {"X-Algo-API-Token": config.token}
-    return AlgodClient(config.token, config.server, headers)
-
-
-def get_kmd_client(config: AlgoClientConfig | None = None) -> KMDClient:
-    """Returns an {py:class}`algosdk.kmd.KMDClient` from `config` or environment
-
-    If no configuration provided will use environment variables `KMD_SERVER`, `KMD_PORT` and `KMD_TOKEN`"""
-    config = config or _get_config_from_environment("KMD")
-    return KMDClient(config.token, config.server)  # type: ignore[no-untyped-call]
-
-
-def get_indexer_client(config: AlgoClientConfig | None = None) -> IndexerClient:
-    """Returns an {py:class}`algosdk.v2client.indexer.IndexerClient` from `config` or environment.
-
-    If no configuration provided will use environment variables `INDEXER_SERVER`, `INDEXER_PORT` and `INDEXER_TOKEN`"""
-    config = config or _get_config_from_environment("INDEXER")
-    headers = {"X-Indexer-API-Token": config.token}
-    return IndexerClient(config.token, config.server, headers)  # type: ignore[no-untyped-call]
-
-
-def is_localnet(client: AlgodClient) -> bool:
-    """Returns True if client genesis is `devnet-v1` or `sandnet-v1`"""
-    params = client.suggested_params()
-    return params.gen in ["devnet-v1", "sandnet-v1", "dockernet-v1"]
-
-
-def is_mainnet(client: AlgodClient) -> bool:
-    """Returns True if client genesis is `mainnet-v1`"""
-    params = client.suggested_params()
-    return params.gen in ["mainnet-v1.0", "mainnet-v1", "mainnet"]
-
-
-def is_testnet(client: AlgodClient) -> bool:
-    """Returns True if client genesis is `testnet-v1`"""
-    params = client.suggested_params()
-    return params.gen in ["testnet-v1.0", "testnet-v1", "testnet"]
-
-
-def get_kmd_client_from_algod_client(client: AlgodClient) -> KMDClient:
-    """Returns an {py:class}`algosdk.kmd.KMDClient` from supplied `client`
-
-    Will use the same address as provided `client` but on port specified by `KMD_PORT` environment variable,
-    or 4002 by default"""
-    # We can only use Kmd on the LocalNet otherwise it's not exposed so this makes some assumptions
-    # (e.g. same token and server as algod and port 4002 by default)
-    port = os.getenv("KMD_PORT", "4002")
-    server = _replace_kmd_port(client.algod_address, port)
-    return KMDClient(client.algod_token, server)  # type: ignore[no-untyped-call]
-
-
-def _replace_kmd_port(address: str, port: str) -> str:
-    parsed_algod = parse.urlparse(address)
-    kmd_host = parsed_algod.netloc.split(":", maxsplit=1)[0] + f":{port}"
-    kmd_parsed = parsed_algod._replace(netloc=kmd_host)
-    return parse.urlunparse(kmd_parsed)
-
-
-def _get_config_from_environment(environment_prefix: str) -> AlgoClientConfig:
-    server = os.getenv(f"{environment_prefix}_SERVER")
-    if server is None:
-        raise Exception(f"Server environment variable not set: {environment_prefix}_SERVER")
-    port = os.getenv(f"{environment_prefix}_PORT")
-    if port:
-        parsed = parse.urlparse(server)
-        server = parsed._replace(netloc=f"{parsed.hostname}:{port}").geturl()
-    return AlgoClientConfig(server, os.getenv(f"{environment_prefix}_TOKEN", ""))
+from algokit_utils._legacy_v2.network_clients import *  # noqa: F403, E402

algokit_utils/protocols/__init__.py

@@ -0,0 +1,2 @@
+from algokit_utils.protocols.account import *  # noqa: F403
+from algokit_utils.protocols.typed_clients import *  # noqa: F403

algokit_utils/protocols/account.py

@@ -0,0 +1,22 @@
+from typing import Protocol, runtime_checkable
+
+from algosdk.atomic_transaction_composer import TransactionSigner
+
+__all__ = ["TransactionSignerAccountProtocol"]
+
+
+@runtime_checkable
+class TransactionSignerAccountProtocol(Protocol):
+    """An account that has a transaction signer.
+    Implemented by SigningAccount, LogicSigAccount, MultiSigAccount and TransactionSignerAccount abstractions.
+    """
+
+    @property
+    def address(self) -> str:
+        """The address of the account."""
+        ...
+
+    @property
+    def signer(self) -> TransactionSigner:
+        """The transaction signer for the account."""
+        ...