algokit-utils 5.0.0a3__py3-none-any.whl

algokit_utils/models/amount.py

@@ -0,0 +1,198 @@
+from decimal import Decimal
+from functools import total_ordering
+from typing import overload
+
+from typing_extensions import Self
+
+from algokit_common import MICROALGOS_TO_ALGOS_RATIO
+
+__all__ = ["ALGORAND_MIN_TX_FEE", "AlgoAmount", "algo", "micro_algo", "transaction_fees"]
+
+
+@total_ordering
+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 * 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 Decimal(self.amount_in_micro_algo) / Decimal(MICROALGOS_TO_ALGOS_RATIO)
+
+    @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 _coerce_micro_algos(self, other: object, op: str, *, allow_int: bool = False) -> int:
+        if isinstance(other, AlgoAmount):
+            return other.micro_algo
+        if allow_int and isinstance(other, int):
+            return int(other)
+        raise TypeError(f"Unsupported operand type(s) for {op}: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def _coerce_int_scalar(self, other: object, op: str) -> int:
+        if isinstance(other, int):
+            return int(other)
+        raise TypeError(f"Unsupported operand type(s) for {op}: 'AlgoAmount' and '{type(other).__name__}'")
+
+    def __str__(self) -> str:
+        return f"{self.micro_algo:,} µALGO"
+
+    def __int__(self) -> int:
+        return self.micro_algo
+
+    def __add__(self, other: object) -> "AlgoAmount":
+        total_micro_algos = self.micro_algo + self._coerce_micro_algos(other, "+", allow_int=True)
+        return AlgoAmount.from_micro_algo(total_micro_algos)
+
+    def __radd__(self, other: object) -> "AlgoAmount":
+        return self.__add__(other)
+
+    def __iadd__(self, other: object) -> Self:
+        self.amount_in_micro_algo += self._coerce_micro_algos(other, "+", allow_int=True)
+        return self
+
+    def __eq__(self, other: object) -> bool:
+        try:
+            return self.amount_in_micro_algo == self._coerce_micro_algos(other, "==", allow_int=True)
+        except TypeError:
+            return False
+
+    def __lt__(self, other: object) -> bool:
+        other_micro_algos = self._coerce_micro_algos(other, "<", allow_int=True)
+        return self.amount_in_micro_algo < other_micro_algos
+
+    def __sub__(self, other: object) -> "AlgoAmount":
+        total_micro_algos = self.micro_algo - self._coerce_micro_algos(other, "-", allow_int=True)
+        return AlgoAmount.from_micro_algo(total_micro_algos)
+
+    def __rsub__(self, other: object) -> "AlgoAmount":
+        total_micro_algos = self._coerce_micro_algos(other, "-", allow_int=True) - self.micro_algo
+        return AlgoAmount.from_micro_algo(total_micro_algos)
+
+    def __isub__(self, other: object) -> Self:
+        self.amount_in_micro_algo -= self._coerce_micro_algos(other, "-", allow_int=True)
+        return self
+
+    def __mul__(self, other: object) -> "AlgoAmount":
+        factor = self._coerce_int_scalar(other, "*")
+        return AlgoAmount.from_micro_algo(self.micro_algo * factor)
+
+    def __rmul__(self, other: object) -> "AlgoAmount":
+        return self.__mul__(other)
+
+    def __truediv__(self, other: object) -> "AlgoAmount":
+        divisor = self._coerce_int_scalar(other, "/")
+        if divisor == 0:
+            raise ZeroDivisionError("division by zero")
+        return AlgoAmount.from_micro_algo(self.micro_algo // divisor)
+
+    def __rtruediv__(self, other: object) -> Decimal:
+        numerator = self._coerce_int_scalar(other, "/")
+        if self.micro_algo == 0:
+            raise ZeroDivisionError("division by zero")
+        return Decimal(numerator) / Decimal(self.micro_algo)
+
+    def __floordiv__(self, other: object) -> "AlgoAmount":
+        divisor = self._coerce_int_scalar(other, "//")
+        if divisor == 0:
+            raise ZeroDivisionError("division by zero")
+        return AlgoAmount.from_micro_algo(self.micro_algo // divisor)
+
+    def __rfloordiv__(self, other: object) -> Decimal:
+        numerator = self._coerce_int_scalar(other, "//")
+        if self.micro_algo == 0:
+            raise ZeroDivisionError("division by zero")
+        return Decimal(numerator // self.micro_algo)
+
+
+# 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,90 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from algokit_common import ProgramSourceMap
+
+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: ProgramSourceMap | 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: ProgramSourceMap | None = None
+    """The source map for the approval program"""
+    clear_source_map: ProgramSourceMap | 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}`algokit_algod_client.AlgodClient` or
+    {py:class}`algokit_indexer_client.IndexerClient` instance."""
+
+    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,7 @@
+# Re-export SimulateTransactionResult from algod client for simulation traces.
+# Previously this module defined a custom SimulationTrace wrapper class, but
+# now we use the algod client type directly for cross-language consistency.
+
+from algokit_algod_client.models import SimulateTransactionResult
+
+__all__ = ["SimulateTransactionResult"]

algokit_utils/models/state.py

@@ -0,0 +1,53 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import TypeAlias
+
+from algokit_transact import BoxReference as AlgoKitTransactBoxReference
+from algokit_transact.signer import AddressWithTransactionSigner
+
+__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.
+    If the name can't be decoded from UTF-8, the string representation of the bytes is returned instead."""
+    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 | AddressWithTransactionSigner
+
+
+BoxReference = AlgoKitTransactBoxReference

algokit_utils/models/transaction.py

@@ -0,0 +1,49 @@
+from typing import Any, Literal, TypedDict
+
+__all__ = [
+    "Arc2TransactionNote",
+    "BaseArc2Note",
+    "JsonFormatArc2Note",
+    "SendParams",
+    "StringFormatArc2Note",
+    "TransactionNote",
+    "TransactionNoteData",
+]
+
+
+# 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
+
+
+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/protocols/__init__.py

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

algokit_utils/protocols/account.py

@@ -0,0 +1,11 @@
+"""Account protocols - re-exported for convenience."""
+
+from algokit_utils.transact import (
+    AddressWithSigners,
+    AddressWithTransactionSigner,
+)
+
+__all__ = [
+    "AddressWithSigners",
+    "AddressWithTransactionSigner",
+]

algokit_utils/protocols/signer.py

@@ -0,0 +1,17 @@
+"""Signer type aliases - re-exported for convenience."""
+
+from algokit_utils.transact import (
+    BytesSigner,
+    DelegatedLsigSigner,
+    MxBytesSigner,
+    ProgramDataSigner,
+    TransactionSigner,
+)
+
+__all__ = [
+    "BytesSigner",
+    "DelegatedLsigSigner",
+    "MxBytesSigner",
+    "ProgramDataSigner",
+    "TransactionSigner",
+]

algokit_utils/protocols/typed_clients.py

@@ -0,0 +1,110 @@
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar
+
+from typing_extensions import Self
+
+from algokit_common import ProgramSourceMap
+from algokit_utils.protocols.signer import TransactionSigner
+
+if TYPE_CHECKING:
+    from algokit_utils.algorand import AlgorandClient
+    from algokit_utils.applications.app_client import (
+        AppClientBareCallCreateParams,
+        AppClientBareCallParams,
+        AppClientCompilationParams,
+        BaseAppClientMethodCallParams,
+    )
+    from algokit_utils.applications.app_deployer import (
+        ApplicationLookup,
+        OnSchemaBreak,
+        OnUpdate,
+    )
+    from algokit_utils.applications.app_factory import AppFactoryDeployResult
+    from algokit_utils.models import SendParams
+
+__all__ = [
+    "TypedAppClientProtocol",
+    "TypedAppFactoryProtocol",
+]
+
+
+class TypedAppClientProtocol(Protocol):
+    """App Client protocol"""
+
+    @classmethod
+    def from_creator_and_name(
+        cls,
+        *,
+        creator_address: str,
+        app_name: str,
+        default_sender: str | None = None,
+        default_signer: TransactionSigner | None = None,
+        ignore_cache: bool | None = None,
+        app_lookup_cache: "ApplicationLookup | None" = None,
+        algorand: "AlgorandClient",
+    ) -> Self: ...
+
+    @classmethod
+    def from_network(
+        cls,
+        *,
+        app_name: str | None = None,
+        default_sender: str | None = None,
+        default_signer: TransactionSigner | None = None,
+        approval_source_map: ProgramSourceMap | None = None,
+        clear_source_map: ProgramSourceMap | None = None,
+        algorand: "AlgorandClient",
+    ) -> Self: ...
+
+    def __init__(
+        self,
+        *,
+        app_id: int,
+        app_name: str | None = None,
+        default_sender: str | None = None,
+        default_signer: TransactionSigner | None = None,
+        algorand: "AlgorandClient",
+        approval_source_map: ProgramSourceMap | None = None,
+        clear_source_map: ProgramSourceMap | None = None,
+    ) -> None: ...
+
+
+CreateParamsT = TypeVar(  # noqa: PLC0105
+    "CreateParamsT",
+    bound="BaseAppClientMethodCallParams | AppClientBareCallCreateParams | None",
+    contravariant=True,
+)
+UpdateParamsT = TypeVar(  # noqa: PLC0105
+    "UpdateParamsT",
+    bound="BaseAppClientMethodCallParams | AppClientBareCallParams | None",
+    contravariant=True,
+)
+DeleteParamsT = TypeVar(  # noqa: PLC0105
+    "DeleteParamsT",
+    bound="BaseAppClientMethodCallParams | AppClientBareCallParams | None",
+    contravariant=True,
+)
+
+
+class TypedAppFactoryProtocol(Protocol, Generic[CreateParamsT, UpdateParamsT, DeleteParamsT]):
+    """App factory protocol"""
+
+    def __init__(
+        self,
+        algorand: "AlgorandClient",
+        **kwargs: Any,
+    ) -> None: ...
+
+    def deploy(
+        self,
+        *,
+        on_update: "OnUpdate | None" = None,
+        on_schema_break: "OnSchemaBreak | None" = None,
+        create_params: CreateParamsT | None = None,
+        update_params: UpdateParamsT | None = None,
+        delete_params: DeleteParamsT | None = None,
+        existing_deployments: "ApplicationLookup | None" = None,
+        ignore_cache: bool = False,
+        app_name: str | None = None,
+        send_params: "SendParams | None" = None,
+        compilation_params: "AppClientCompilationParams | None" = None,
+    ) -> tuple[TypedAppClientProtocol, "AppFactoryDeployResult"]: ...