algokit-utils 3.0.0b1__py3-none-any.whl → 3.0.0b2__py3-none-any.whl

algokit_utils/_legacy_v2/logic_error.py

@@ -0,0 +1,14 @@
+from typing_extensions import deprecated
+
+from algokit_utils.errors.logic_error import LogicError as NewLogicError
+from algokit_utils.errors.logic_error import parse_logic_error
+
+__all__ = [
+    "LogicError",
+    "parse_logic_error",
+]
+
+
+@deprecated("Use algokit_utils.models.error.LogicError instead")
+class LogicError(NewLogicError):
+    pass

algokit_utils/{models.py → _legacy_v2/models.py}

@@ -2,17 +2,20 @@ import dataclasses
 from collections.abc import Sequence
 from typing import Any, Generic, Protocol, TypeAlias, TypedDict, TypeVar
 
-import algosdk.account
 from algosdk import transaction
 from algosdk.abi import Method
 from algosdk.atomic_transaction_composer import (
-    AccountTransactionSigner,
     AtomicTransactionResponse,
     SimulateAtomicTransactionResponse,
     TransactionSigner,
 )
-from algosdk.encoding import decode_address
-from deprecated import deprecated
+from typing_extensions import deprecated
+
+from algokit_utils.models.account import SigningAccount
+from algokit_utils.models.simulate import SimulationTrace
+
+# Imports from latest sdk version that rely on models previously used in legacy v2 (but moved to root models/*)
+
 
 __all__ = [
     "ABIArgsDict",
@@ -24,6 +27,7 @@ __all__ = [
     "CreateTransactionParameters",
     "OnCompleteCallParameters",
     "OnCompleteCallParametersDict",
+    "SimulationTrace",
     "TransactionParameters",
     "TransactionResponse",
 ]
@@ -31,35 +35,10 @@ __all__ = [
 ReturnType = TypeVar("ReturnType")
 
 
+@deprecated("Use 'SigningAccount' instead")
 @dataclasses.dataclass(kw_only=True)
-class Account:
-    """Holds the private_key and address for an account"""
-
-    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 = algosdk.account.address_from_private_key(self.private_key)  # type: ignore[no-untyped-call]
-
-    @property
-    def public_key(self) -> bytes:
-        """The public key for this account"""
-        public_key = decode_address(self.address)  # type: ignore[no-untyped-call]
-        assert isinstance(public_key, bytes)
-        return public_key
-
-    @property
-    def signer(self) -> AccountTransactionSigner:
-        """An AccountTransactionSigner for this account"""
-        return AccountTransactionSigner(self.private_key)
-
-    @staticmethod
-    def new_account() -> "Account":
-        private_key, address = algosdk.account.generate_account()  # type: ignore[no-untyped-call]
-        return Account(private_key=private_key)
+class Account(SigningAccount):
+    """An account that can be used to sign transactions"""
 
 
 @dataclasses.dataclass(kw_only=True)
@@ -155,86 +134,25 @@ class TransactionParameters:
 
 # CreateTransactionParameters is used by algokit-client-generator clients
 @dataclasses.dataclass(kw_only=True)
-class CreateTransactionParameters:
+class CreateTransactionParameters(TransactionParameters):
     """Additional parameters that can be included in a transaction when calling a create method"""
 
-    signer: TransactionSigner | None = None
-    """Signer to use when signing this transaction"""
-    sender: str | None = None
-    """Sender of this transaction"""
-    suggested_params: transaction.SuggestedParams | None = None
-    """SuggestedParams to use for this transaction"""
-    note: bytes | str | None = None
-    """Note for this transaction"""
-    lease: bytes | str | None = None
-    """Lease value for this transaction"""
-    boxes: Sequence[tuple[int, bytes | bytearray | str | int]] | None = None
-    """Box references to include in transaction. A sequence of (app id, box key) tuples"""
-    accounts: list[str] | None = None
-    """Accounts to include in transaction"""
-    foreign_apps: list[int] | None = None
-    """List of foreign apps (by app id) to include in transaction"""
-    foreign_assets: list[int] | None = None
-    """List of foreign assets (by asset id) to include in transaction"""
-    rekey_to: str | None = None
-    """Address to rekey to"""
     extra_pages: int | None = None
 
 
 @dataclasses.dataclass(kw_only=True)
-class OnCompleteCallParameters:
+class OnCompleteCallParameters(TransactionParameters):
     """Additional parameters that can be included in a transaction when using the
     ApplicationClient.call/compose_call methods"""
 
-    signer: TransactionSigner | None = None
-    """Signer to use when signing this transaction"""
-    sender: str | None = None
-    """Sender of this transaction"""
-    suggested_params: transaction.SuggestedParams | None = None
-    """SuggestedParams to use for this transaction"""
-    note: bytes | str | None = None
-    """Note for this transaction"""
-    lease: bytes | str | None = None
-    """Lease value for this transaction"""
-    boxes: Sequence[tuple[int, bytes | bytearray | str | int]] | None = None
-    """Box references to include in transaction. A sequence of (app id, box key) tuples"""
-    accounts: list[str] | None = None
-    """Accounts to include in transaction"""
-    foreign_apps: list[int] | None = None
-    """List of foreign apps (by app id) to include in transaction"""
-    foreign_assets: list[int] | None = None
-    """List of foreign assets (by asset id) to include in transaction"""
-    rekey_to: str | None = None
-    """Address to rekey to"""
     on_complete: transaction.OnComplete | None = None
 
 
 @dataclasses.dataclass(kw_only=True)
-class CreateCallParameters:
+class CreateCallParameters(OnCompleteCallParameters):
     """Additional parameters that can be included in a transaction when using the
     ApplicationClient.create/compose_create methods"""
 
-    signer: TransactionSigner | None = None
-    """Signer to use when signing this transaction"""
-    sender: str | None = None
-    """Sender of this transaction"""
-    suggested_params: transaction.SuggestedParams | None = None
-    """SuggestedParams to use for this transaction"""
-    note: bytes | str | None = None
-    """Note for this transaction"""
-    lease: bytes | str | None = None
-    """Lease value for this transaction"""
-    boxes: Sequence[tuple[int, bytes | bytearray | str | int]] | None = None
-    """Box references to include in transaction. A sequence of (app id, box key) tuples"""
-    accounts: list[str] | None = None
-    """Accounts to include in transaction"""
-    foreign_apps: list[int] | None = None
-    """List of foreign apps (by app id) to include in transaction"""
-    foreign_assets: list[int] | None = None
-    """List of foreign assets (by asset id) to include in transaction"""
-    rekey_to: str | None = None
-    """Address to rekey to"""
-    on_complete: transaction.OnComplete | None = None
     extra_pages: int | None = None
 
 
@@ -263,72 +181,31 @@ class TransactionParametersDict(TypedDict, total=False):
     """Address to rekey to"""
 
 
-class OnCompleteCallParametersDict(TypedDict, total=False):
+class OnCompleteCallParametersDict(TransactionParametersDict, total=False):
     """Additional parameters that can be included in a transaction when using the
     ApplicationClient.call/compose_call methods"""
 
-    signer: TransactionSigner
-    """Signer to use when signing this transaction"""
-    sender: str
-    """Sender of this transaction"""
-    suggested_params: transaction.SuggestedParams
-    """SuggestedParams to use for this transaction"""
-    note: bytes | str
-    """Note for this transaction"""
-    lease: bytes | str
-    """Lease value for this transaction"""
-    boxes: Sequence[tuple[int, bytes | bytearray | str | int]]
-    """Box references to include in transaction. A sequence of (app id, box key) tuples"""
-    accounts: list[str]
-    """Accounts to include in transaction"""
-    foreign_apps: list[int]
-    """List of foreign apps (by app id) to include in transaction"""
-    foreign_assets: list[int]
-    """List of foreign assets (by asset id) to include in transaction"""
-    rekey_to: str
-    """Address to rekey to"""
     on_complete: transaction.OnComplete
 
 
-class CreateCallParametersDict(TypedDict, total=False):
+class CreateCallParametersDict(OnCompleteCallParametersDict, total=False):
     """Additional parameters that can be included in a transaction when using the
     ApplicationClient.create/compose_create methods"""
 
-    signer: TransactionSigner
-    """Signer to use when signing this transaction"""
-    sender: str
-    """Sender of this transaction"""
-    suggested_params: transaction.SuggestedParams
-    """SuggestedParams to use for this transaction"""
-    note: bytes | str
-    """Note for this transaction"""
-    lease: bytes | str
-    """Lease value for this transaction"""
-    boxes: Sequence[tuple[int, bytes | bytearray | str | int]]
-    """Box references to include in transaction. A sequence of (app id, box key) tuples"""
-    accounts: list[str]
-    """Accounts to include in transaction"""
-    foreign_apps: list[int]
-    """List of foreign apps (by app id) to include in transaction"""
-    foreign_assets: list[int]
-    """List of foreign assets (by asset id) to include in transaction"""
-    rekey_to: str
-    """Address to rekey to"""
-    on_complete: transaction.OnComplete
     extra_pages: int
 
 
 # Pre 1.3.1 backwards compatibility
-@deprecated(reason="Use TransactionParameters instead", version="1.3.1")
+@deprecated("Use TransactionParameters instead")
 class RawTransactionParameters(TransactionParameters):
     """Deprecated, use TransactionParameters instead"""
 
 
-@deprecated(reason="Use TransactionParameters instead", version="1.3.1")
+@deprecated("Use TransactionParameters instead")
 class CommonCallParameters(TransactionParameters):
     """Deprecated, use TransactionParameters instead"""
 
 
-@deprecated(reason="Use TransactionParametersDict instead", version="1.3.1")
+@deprecated("Use TransactionParametersDict instead")
 class CommonCallParametersDict(TransactionParametersDict):
     """Deprecated, use TransactionParametersDict instead"""

algokit_utils/_legacy_v2/network_clients.py

@@ -0,0 +1,140 @@
+import dataclasses
+import os
+from typing import Literal
+from urllib import parse
+
+from algosdk.kmd import KMDClient
+from algosdk.v2client.algod import AlgodClient
+from algosdk.v2client.indexer import IndexerClient
+from typing_extensions import deprecated
+
+__all__ = [
+    "AlgoClientConfig",
+    "AlgoClientConfigs",
+    "get_algod_client",
+    "get_algonode_config",
+    "get_default_localnet_config",
+    "get_indexer_client",
+    "get_kmd_client",
+    "get_kmd_client_from_algod_client",
+    "is_localnet",
+    "is_mainnet",
+    "is_testnet",
+]
+
+
+@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
+
+
+@deprecated("Use AlgorandClient.client.algod")
+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)
+
+
+@deprecated("Use AlgorandClient.testnet() or AlgorandClient.mainnet() instead")
+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,
+    )
+
+
+@deprecated("Use AlgorandClient.from_environment() instead.")
+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)
+
+
+@deprecated("Use AlgorandClient.default_localnet().kmd instead")
+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)
+
+
+@deprecated("Use AlgorandClient.client.from_environment().indexer instead")
+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)
+
+
+@deprecated("Use AlgorandClient.client.is_localnet() instead")
+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"]
+
+
+@deprecated("Use AlgorandClient.client.is_mainnet() instead")
+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"]
+
+
+@deprecated("Use AlgorandClient.client.is_testnet() instead")
+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"]
+
+
+@deprecated("Use AlgorandClient.default_localnet().kmd instead")
+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)
+
+
+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", ""))

algokit_utils/account.py

@@ -1,183 +1,12 @@
-import logging
-import os
-from typing import TYPE_CHECKING, Any
-
-from algosdk.account import address_from_private_key
-from algosdk.mnemonic import from_private_key, to_private_key
-from algosdk.util import algos_to_microalgos
-
-from algokit_utils._transfer import TransferParameters, transfer
-from algokit_utils.models import Account
-from algokit_utils.network_clients import get_kmd_client_from_algod_client, is_localnet
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from algosdk.kmd import KMDClient
-    from algosdk.v2client.algod import AlgodClient
-
-__all__ = [
-    "create_kmd_wallet_account",
-    "get_account",
-    "get_account_from_mnemonic",
-    "get_dispenser_account",
-    "get_kmd_wallet_account",
-    "get_localnet_default_account",
-    "get_or_create_kmd_wallet_account",
-]
-
-logger = logging.getLogger(__name__)
-_DEFAULT_ACCOUNT_MINIMUM_BALANCE = 1_000_000_000
-
-
-def get_account_from_mnemonic(mnemonic: str) -> Account:
-    """Convert a mnemonic (25 word passphrase) into an Account"""
-    private_key = to_private_key(mnemonic)  # type: ignore[no-untyped-call]
-    address = address_from_private_key(private_key)  # type: ignore[no-untyped-call]
-    return Account(private_key=private_key, address=address)
-
-
-def create_kmd_wallet_account(kmd_client: "KMDClient", name: str) -> Account:
-    """Creates a wallet with specified name"""
-    wallet_id = kmd_client.create_wallet(name, "")["id"]  # type: ignore[no-untyped-call]
-    wallet_handle = kmd_client.init_wallet_handle(wallet_id, "")  # type: ignore[no-untyped-call]
-    kmd_client.generate_key(wallet_handle)  # type: ignore[no-untyped-call]
-
-    key_ids: list[str] = kmd_client.list_keys(wallet_handle)  # type: ignore[no-untyped-call]
-    account_key = key_ids[0]
-
-    private_account_key = kmd_client.export_key(wallet_handle, "", account_key)  # type: ignore[no-untyped-call]
-    return get_account_from_mnemonic(from_private_key(private_account_key))  # type: ignore[no-untyped-call]
-
-
-def get_or_create_kmd_wallet_account(
-    client: "AlgodClient", name: str, fund_with_algos: float = 1000, kmd_client: "KMDClient | None" = None
-) -> Account:
-    """Returns a wallet with specified name, or creates one if not found"""
-    kmd_client = kmd_client or get_kmd_client_from_algod_client(client)
-    account = get_kmd_wallet_account(client, kmd_client, name)
-
-    if account:
-        account_info = client.account_info(account.address)
-        assert isinstance(account_info, dict)
-        if account_info["amount"] > 0:
-            return account
-        logger.debug(f"Found existing account in LocalNet with name '{name}', but no funds in the account.")
-    else:
-        account = create_kmd_wallet_account(kmd_client, name)
-
-        logger.debug(
-            f"Couldn't find existing account in LocalNet with name '{name}'. "
-            f"So created account {account.address} with keys stored in KMD."
-        )
-
-    logger.debug(f"Funding account {account.address} with {fund_with_algos} ALGOs")
-
-    if fund_with_algos:
-        transfer(
-            client,
-            TransferParameters(
-                from_account=get_dispenser_account(client),
-                to_address=account.address,
-                micro_algos=algos_to_microalgos(fund_with_algos),  # type: ignore[no-untyped-call]
-            ),
-        )
-
-    return account
-
-
-def _is_default_account(account: dict[str, Any]) -> bool:
-    return bool(account["status"] != "Offline" and account["amount"] > _DEFAULT_ACCOUNT_MINIMUM_BALANCE)
-
-
-def get_localnet_default_account(client: "AlgodClient") -> Account:
-    """Returns the default Account in a LocalNet instance"""
-    if not is_localnet(client):
-        raise Exception("Can't get a default account from non LocalNet network")
-
-    account = get_kmd_wallet_account(
-        client, get_kmd_client_from_algod_client(client), "unencrypted-default-wallet", _is_default_account
-    )
-    assert account
-    return account
-
-
-def get_dispenser_account(client: "AlgodClient") -> Account:
-    """Returns an Account based on DISPENSER_MNENOMIC environment variable or the default account on LocalNet"""
-    if is_localnet(client):
-        return get_localnet_default_account(client)
-    return get_account(client, "DISPENSER")
-
-
-def get_kmd_wallet_account(
-    client: "AlgodClient",
-    kmd_client: "KMDClient",
-    name: str,
-    predicate: "Callable[[dict[str, Any]], bool] | None" = None,
-) -> Account | None:
-    """Returns wallet matching specified name and predicate or None if not found"""
-    wallets: list[dict] = kmd_client.list_wallets()  # type: ignore[no-untyped-call]
-
-    wallet = next((w for w in wallets if w["name"] == name), None)
-    if wallet is None:
-        return None
-
-    wallet_id = wallet["id"]
-    wallet_handle = kmd_client.init_wallet_handle(wallet_id, "")  # type: ignore[no-untyped-call]
-    key_ids: list[str] = kmd_client.list_keys(wallet_handle)  # type: ignore[no-untyped-call]
-    matched_account_key = None
-    if predicate:
-        for key in key_ids:
-            account = client.account_info(key)
-            assert isinstance(account, dict)
-            if predicate(account):
-                matched_account_key = key
-    else:
-        matched_account_key = next(key_ids.__iter__(), None)
-
-    if not matched_account_key:
-        return None
-
-    private_account_key = kmd_client.export_key(wallet_handle, "", matched_account_key)  # type: ignore[no-untyped-call]
-    return get_account_from_mnemonic(from_private_key(private_account_key))  # type: ignore[no-untyped-call]
-
-
-def get_account(
-    client: "AlgodClient", name: str, fund_with_algos: float = 1000, kmd_client: "KMDClient | None" = None
-) -> Account:
-    """Returns an Algorand account with private key loaded by convention based on the given name identifier.
-
-    # Convention
-
-    **Non-LocalNet:** will load `os.environ[f"{name}_MNEMONIC"]` as a mnemonic secret
-    Be careful how the mnemonic is handled, never commit it into source control and ideally load it via a
-    secret storage service rather than the file system.
-
-    **LocalNet:** will load the account from a KMD wallet called {name} and if that wallet doesn't exist it will
-    create it and fund the account for you
-
-    This allows you to write code that will work seamlessly in production and local development (LocalNet) without
-    manual config locally (including when you reset the LocalNet).
-
-    # Example
-    If you have a mnemonic secret loaded into `os.environ["ACCOUNT_MNEMONIC"]` then you can call the following to get
-    that private key loaded into an account object:
-    ```python
-    account = get_account('ACCOUNT', algod)
-    ```
-
-    If that code runs against LocalNet then a wallet called 'ACCOUNT' will automatically be created with an account
-    that is automatically funded with 1000 (default) ALGOs from the default LocalNet dispenser.
-    """
-
-    mnemonic_key = f"{name.upper()}_MNEMONIC"
-    mnemonic = os.getenv(mnemonic_key)
-    if mnemonic:
-        return get_account_from_mnemonic(mnemonic)
-
-    if is_localnet(client):
-        account = get_or_create_kmd_wallet_account(client, name, fund_with_algos, kmd_client)
-        os.environ[mnemonic_key] = from_private_key(account.private_key)  # type: ignore[no-untyped-call]
-        return account
-
-    raise Exception(f"Missing environment variable '{mnemonic_key}' when looking for account '{name}'")
+import warnings
+
+warnings.warn(
+    """The legacy v2 account module is deprecated and will be removed in a future version.
+    Use `SigningAccount` abstraction from `algokit_utils.models` instead or
+    classes compliant with `TransactionSignerAccountProtocol` obtained from `AccountManager`.
+""",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from algokit_utils._legacy_v2.account import *  # noqa: F403, E402

algokit_utils/accounts/__init__.py

@@ -0,0 +1,2 @@
+from algokit_utils.accounts.account_manager import *  # noqa: F403
+from algokit_utils.accounts.kmd_account_manager import *  # noqa: F403