algokit-utils 5.0.0a3__py3-none-any.whl

algokit_utils/accounts/kmd_account_manager.py

@@ -0,0 +1,206 @@
+from collections.abc import Callable
+from typing import Any
+
+from nacl.signing import SigningKey
+
+from algokit_common.serde import to_wire
+from algokit_kmd_client.client import KmdClient
+from algokit_kmd_client.models._create_wallet_request import CreateWalletRequest
+from algokit_kmd_client.models._export_key_request import ExportKeyRequest
+from algokit_kmd_client.models._generate_key_request import GenerateKeyRequest
+from algokit_kmd_client.models._init_wallet_handle_token_request import InitWalletHandleTokenRequest
+from algokit_kmd_client.models._list_keys_request import ListKeysRequest
+from algokit_transact.signer import AddressWithSigners, generate_address_with_signers
+from algokit_utils.clients.client_manager import ClientManager
+from algokit_utils.config import config
+from algokit_utils.models.amount import AlgoAmount
+from algokit_utils.transactions.transaction_composer import (
+    PaymentParams,
+    TransactionComposer,
+    TransactionComposerParams,
+)
+
+__all__ = ["KmdAccountManager"]
+
+
+class KmdAccountManager:
+    """Provides abstractions over KMD that makes it easier to get and manage accounts."""
+
+    _kmd: KmdClient | None
+
+    def __init__(self, client_manager: ClientManager) -> None:
+        self._client_manager = client_manager
+        try:
+            self._kmd = client_manager.kmd
+        except ValueError:
+            self._kmd = None
+
+    def kmd(self) -> KmdClient:
+        """Returns the KMD client, initializing it if needed.
+
+        :raises Exception: If KMD client is not configured and not running against LocalNet
+        :return: The KMD client
+        """
+        if self._kmd is None:
+            if self._client_manager.is_localnet():
+                kmd_config = ClientManager.get_config_from_environment_or_localnet()
+                if not kmd_config.kmd_config:
+                    raise Exception("Attempt to use KMD client with no KMD configured")
+                self._kmd = ClientManager.get_kmd_client(kmd_config.kmd_config)
+                return self._kmd
+            raise Exception("Attempt to use KMD client with no KMD configured")
+        return self._kmd
+
+    def get_wallet_account(
+        self,
+        wallet_name: str,
+        predicate: Callable[[dict[str, Any]], bool] | None = None,
+        sender: str | None = None,
+    ) -> AddressWithSigners | None:
+        """Returns an Algorand signing account with private key loaded from the given KMD wallet.
+
+        Retrieves an account from a KMD wallet that matches the given predicate, or a random account
+        if no predicate is provided.
+
+        :param wallet_name: The name of the wallet to retrieve an account from
+        :param predicate: Optional filter to use to find the account (otherwise gets a random account from the wallet)
+        :param sender: Optional sender address to use this signer for (aka a rekeyed account)
+        :return: The signing account or None if no matching wallet or account was found
+        """
+        return self._find_wallet_account(
+            wallet_name,
+            predicate,
+            sender,
+        )
+
+    def _find_matching_address(
+        self,
+        addresses: list[str],
+        predicate_or_address: Callable[[dict[str, Any]], bool] | str | None,
+    ) -> str | None:
+        """Find a matching address from a list based on a predicate, specific address, or return the first one."""
+        if not addresses:
+            return None
+
+        if callable(predicate_or_address):
+            for address in addresses:
+                account_info = self._client_manager.algod.account_information(address)
+                if predicate_or_address(to_wire(account_info)):
+                    return address
+            return None
+
+        if isinstance(predicate_or_address, str):
+            return predicate_or_address if predicate_or_address in addresses else None
+
+        return addresses[0]
+
+    def _find_wallet_account(
+        self,
+        wallet_name: str,
+        predicate_or_address: Callable[[dict[str, Any]], bool] | str | None = None,
+        sender: str | None = None,
+    ) -> AddressWithSigners | None:
+        kmd_client = self.kmd()
+        wallets = kmd_client.list_wallets().wallets or []
+        wallet = next((w for w in wallets if w.name == wallet_name), None)
+        if not wallet:
+            return None
+
+        wallet_id = wallet.id_
+        wallet_handle = kmd_client.init_wallet_handle(InitWalletHandleTokenRequest(wallet_id, "")).wallet_handle_token
+        addresses = kmd_client.list_keys_in_wallet(ListKeysRequest(wallet_handle)).addresses or []
+
+        matched_address = self._find_matching_address(addresses, predicate_or_address)
+        if not matched_address:
+            return None
+
+        private_key = kmd_client.export_key(ExportKeyRequest(matched_address, wallet_handle, "")).private_key
+        if not private_key:
+            raise Exception(f"Error exporting key for address {matched_address} from KMD wallet {wallet_name}")
+
+        # private_key is 64 bytes from KMD (seed + public key)
+        seed = private_key[:32]
+        public_key = private_key[32:]
+        signing_key = SigningKey(seed)
+
+        def raw_signer(bytes_to_sign: bytes) -> bytes:
+            return signing_key.sign(bytes_to_sign).signature
+
+        return generate_address_with_signers(
+            ed25519_pubkey=public_key,
+            raw_ed25519_signer=raw_signer,
+            sending_address=sender,
+        )
+
+    def get_or_create_wallet_account(self, name: str, fund_with: AlgoAmount | None = None) -> AddressWithSigners:
+        """Gets or creates a funded account in a KMD wallet of the given name.
+
+        Provides idempotent access to accounts from LocalNet without specifying the private key.
+
+        :param name: The name of the wallet to retrieve / create
+        :param fund_with: The number of Algos to fund the account with when created
+        :return: An Algorand account with private key loaded
+
+        :raises Exception: If error received while creating the wallet or funding the account
+        """
+        fund_with = fund_with or AlgoAmount.from_algo(1000)
+
+        existing = self.get_wallet_account(name)
+        if existing:
+            return existing
+
+        kmd_client = self.kmd()
+        wallet = kmd_client.create_wallet(CreateWalletRequest(wallet_name=name, wallet_password="")).wallet
+        if not wallet:
+            raise Exception(f"Error creating KMD wallet with name {name}")
+        wallet_id = wallet.id_
+        wallet_handle = kmd_client.init_wallet_handle(InitWalletHandleTokenRequest(wallet_id, "")).wallet_handle_token
+        kmd_client.generate_key(GenerateKeyRequest(wallet_handle_token=wallet_handle))
+
+        account = self.get_wallet_account(name)
+        assert account is not None
+
+        config.logger.info(
+            f"LocalNet account '{name}' doesn't yet exist; created account {account.addr} "
+            f"with keys stored in KMD and funding with {fund_with} ALGO"
+        )
+
+        dispenser = self.get_localnet_dispenser_account()
+        TransactionComposer(
+            TransactionComposerParams(
+                algod=self._client_manager.algod,
+                get_signer=lambda _: dispenser.signer,
+                get_suggested_params=self._client_manager.algod.suggested_params,
+            )
+        ).add_payment(
+            PaymentParams(
+                sender=dispenser.addr,
+                receiver=account.addr,
+                amount=fund_with,
+            )
+        ).send()
+        return account
+
+    def get_localnet_dispenser_account(self) -> AddressWithSigners:
+        """Returns an Algorand account with private key loaded for the default LocalNet dispenser account.
+
+        Retrieves the default funded account from LocalNet that can be used to fund other accounts.
+
+        :raises Exception: If not running against LocalNet or dispenser account not found
+        :return: The default LocalNet dispenser account
+        """
+        if not self._client_manager.is_localnet():
+            raise Exception("Can't get LocalNet dispenser account from non LocalNet network")
+
+        genesis_response = self._client_manager.algod.get_genesis()
+        dispenser_addresses = [a.addr for a in genesis_response.alloc if a.comment == "Wallet1"]
+
+        if dispenser_addresses:
+            dispenser = self._find_wallet_account(
+                "unencrypted-default-wallet",
+                dispenser_addresses[0],
+            )
+            if dispenser:
+                return dispenser
+
+        raise Exception("Error retrieving LocalNet dispenser account; couldn't find the default account in KMD")

algokit_utils/algo25.py

@@ -0,0 +1,46 @@
+"""Algorand 25-word mnemonic utilities.
+
+Re-exports from algokit_algo25 for convenient access via algokit_utils.algo25.
+
+Usage:
+    from algokit_utils import algo25
+    mnemonic = algo25.mnemonic_from_seed(seed)
+
+    # Or import directly:
+    from algokit_utils.algo25 import mnemonic_from_seed, seed_from_mnemonic
+"""
+
+from algokit_algo25 import (
+    FAIL_TO_DECODE_MNEMONIC_ERROR_MSG,
+    KEY_LEN_BYTES,
+    MNEMONIC_LEN,
+    NOT_IN_WORDS_LIST_ERROR_MSG,
+    InvalidMnemonicError,
+    InvalidSeedLengthError,
+    MnemonicError,
+    WordNotFoundError,
+    master_derivation_key_to_mnemonic,
+    mnemonic_from_seed,
+    mnemonic_to_master_derivation_key,
+    secret_key_to_mnemonic,
+    seed_from_mnemonic,
+)
+
+__all__ = [
+    # Constants
+    "FAIL_TO_DECODE_MNEMONIC_ERROR_MSG",
+    "KEY_LEN_BYTES",
+    "MNEMONIC_LEN",
+    "NOT_IN_WORDS_LIST_ERROR_MSG",
+    # Exceptions
+    "InvalidMnemonicError",
+    "InvalidSeedLengthError",
+    "MnemonicError",
+    "WordNotFoundError",
+    # Functions
+    "master_derivation_key_to_mnemonic",
+    "mnemonic_from_seed",
+    "mnemonic_to_master_derivation_key",
+    "secret_key_to_mnemonic",
+    "seed_from_mnemonic",
+]

algokit_utils/algorand.py

@@ -0,0 +1,383 @@
+import copy
+import time
+
+import typing_extensions
+
+from algokit_algod_client import AlgodClient
+from algokit_algod_client import models as algod_models
+from algokit_indexer_client import IndexerClient
+from algokit_kmd_client.client import KmdClient
+from algokit_transact.signer import AddressWithTransactionSigner
+from algokit_utils.accounts.account_manager import AccountManager
+from algokit_utils.applications.app_deployer import AppDeployer
+from algokit_utils.applications.app_manager import AppManager
+from algokit_utils.assets.asset_manager import AssetManager
+from algokit_utils.clients.client_manager import AlgoSdkClients, ClientManager
+from algokit_utils.models.network import AlgoClientConfigs, AlgoClientNetworkConfig
+from algokit_utils.protocols.signer import TransactionSigner
+from algokit_utils.transactions.transaction_composer import (
+    ErrorTransformer,
+    TransactionComposer,
+    TransactionComposerParams,
+)
+from algokit_utils.transactions.transaction_creator import AlgorandClientTransactionCreator
+from algokit_utils.transactions.transaction_sender import AlgorandClientTransactionSender
+
+__all__ = [
+    "AlgorandClient",
+]
+
+
+class AlgorandClient:
+    """A client that brokers easy access to Algorand functionality."""
+
+    def __init__(self, config: AlgoClientConfigs | AlgoSdkClients):
+        self._client_manager: ClientManager = ClientManager(clients_or_configs=config, algorand_client=self)
+        self._account_manager: AccountManager = AccountManager(self._client_manager)
+        self._asset_manager: AssetManager = AssetManager(self._client_manager.algod, lambda: self.new_group())
+        self._app_manager: AppManager = AppManager(self._client_manager.algod)
+        self._transaction_sender = AlgorandClientTransactionSender(
+            new_group=lambda: self.new_group(),
+            asset_manager=self._asset_manager,
+            app_manager=self._app_manager,
+            algod_client=self._client_manager.algod,
+        )
+        self._app_deployer: AppDeployer = AppDeployer(
+            self._app_manager, self._transaction_sender, self._client_manager.indexer_if_present
+        )
+        self._transaction_creator = AlgorandClientTransactionCreator(
+            new_group=lambda: self.new_group(),
+        )
+
+        self._cached_suggested_params: algod_models.SuggestedParams | None = None
+        self._cached_suggested_params_expiry: float | None = None
+        self._cached_suggested_params_timeout: int = 3_000  # three seconds
+        self._default_validity_window: int | None = None
+        self._error_transformers: set[ErrorTransformer] = set()
+
+    def set_default_validity_window(self, validity_window: int) -> typing_extensions.Self:
+        """
+        Sets the default validity window for transactions.
+
+        :param validity_window: The number of rounds between the first and last valid rounds
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_default_validity_window(1000);
+        """
+        self._default_validity_window = validity_window
+        return self
+
+    def set_default_signer(self, signer: TransactionSigner | AddressWithTransactionSigner) -> typing_extensions.Self:
+        """
+        Sets the default signer to use if no other signer is specified.
+
+        :param signer: The signer to use, either a `TransactionSigner` or an `AddressWithTransactionSigner`
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> signer = account_manager.random()  # Returns AddressWithSigners
+            >>> algorand = AlgorandClient.mainnet().set_default_signer(signer)
+        """
+        self._account_manager.set_default_signer(signer)
+        return self
+
+    def set_signer(self, sender: str, signer: TransactionSigner) -> typing_extensions.Self:
+        """
+        Tracks the given account for later signing.
+
+        :param sender: The sender address to use this signer for
+        :param signer: The signer to sign transactions with for the given sender
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> account = account_manager.random()  # Returns AddressWithSigners
+            >>> algorand = AlgorandClient.mainnet().set_signer(account.addr, account.signer)
+        """
+        self._account_manager.set_signer(sender, signer)
+        return self
+
+    def set_signer_from_account(self, signer: AddressWithTransactionSigner) -> typing_extensions.Self:
+        """
+        Sets the default signer to use if no other signer is specified.
+
+        :param signer: The signer to use, either a `TransactionSigner` or an `AddressWithTransactionSigner`
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> accountManager = AlgorandClient.mainnet()
+            >>> accountManager.set_signer_from_account(TransactionSignerAccount(address=..., signer=...))
+            >>> accountManager.set_signer_from_account(algosdk.LogicSigAccount(program, args))
+            >>> accountManager.set_signer_from_account(account_manager.random())  # AddressWithSigners
+            >>> accountManager.set_signer_from_account(MultisigAccount(metadata, sub_signers))
+            >>> accountManager.set_signer_from_account(account)
+        """
+        self._account_manager.set_default_signer(signer)
+        return self
+
+    def set_suggested_params_cache(
+        self, suggested_params: algod_models.SuggestedParams, until: float | None = None
+    ) -> typing_extensions.Self:
+        """
+        Sets a cache value to use for suggested params.
+
+        :param suggested_params: The suggested params to use
+        :param until: A timestamp until which to cache, or if not specified then the timeout is used
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_suggested_params_cache(suggested_params, time.time() + 3.6e6)
+        """
+        self._cached_suggested_params = suggested_params
+        self._cached_suggested_params_expiry = until or time.time() + self._cached_suggested_params_timeout
+        return self
+
+    def set_suggested_params_cache_timeout(self, timeout: int) -> typing_extensions.Self:
+        """
+        Sets the timeout for caching suggested params.
+
+        :param timeout: The timeout in milliseconds
+        :return: The `AlgorandClient` so method calls can be chained
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_suggested_params_cache_timeout(10_000)
+        """
+        self._cached_suggested_params_timeout = timeout
+        return self
+
+    def get_suggested_params(self) -> algod_models.SuggestedParams:
+        """
+        Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)
+
+        :example:
+            >>> algorand = AlgorandClient.mainnet().get_suggested_params()
+        """
+        if self._cached_suggested_params and (
+            self._cached_suggested_params_expiry is None or self._cached_suggested_params_expiry > time.time()
+        ):
+            return copy.deepcopy(self._cached_suggested_params)
+
+        self._cached_suggested_params = self._client_manager.algod.suggested_params()
+        self._cached_suggested_params_expiry = time.time() + self._cached_suggested_params_timeout
+
+        return copy.deepcopy(self._cached_suggested_params)
+
+    def register_error_transformer(self, transformer: ErrorTransformer) -> typing_extensions.Self:
+        """Register a function that will be used to transform an error caught when simulating or executing
+        composed transaction groups made from `new_group`
+
+        :param transformer: The error transformer function
+        :return: The AlgorandClient so you can chain method calls
+        """
+        self._error_transformers.add(transformer)
+        return self
+
+    def unregister_error_transformer(self, transformer: ErrorTransformer) -> typing_extensions.Self:
+        """Unregister an error transformer function
+
+        :param transformer: The error transformer function to remove
+        :return: The AlgorandClient so you can chain method calls
+        """
+        self._error_transformers.discard(transformer)
+        return self
+
+    def new_group(self) -> TransactionComposer:
+        """
+        Start a new `TransactionComposer` transaction group
+
+        :example:
+            >>> composer = AlgorandClient.mainnet().new_group()
+            >>> result = await composer.add_transaction(payment).send()
+        """
+
+        return TransactionComposer(
+            TransactionComposerParams(
+                algod=self.client.algod,
+                get_signer=lambda addr: self.account.get_signer(addr),
+                get_suggested_params=self.get_suggested_params,
+                default_validity_window=self._default_validity_window,
+                app_manager=self._app_manager,
+                error_transformers=list(self._error_transformers),
+            )
+        )
+
+    @property
+    def client(self) -> ClientManager:
+        """
+        Get clients, including algosdk clients and app clients.
+
+        :example:
+            >>> clientManager = AlgorandClient.mainnet().client
+        """
+        return self._client_manager
+
+    @property
+    def account(self) -> AccountManager:
+        """Get or create accounts that can sign transactions.
+
+        :example:
+            >>> accountManager = AlgorandClient.mainnet().account
+        """
+        return self._account_manager
+
+    @property
+    def asset(self) -> AssetManager:
+        """
+        Get or create assets.
+
+        :example:
+            >>> assetManager = AlgorandClient.mainnet().asset
+        """
+        return self._asset_manager
+
+    @property
+    def app(self) -> AppManager:
+        """
+        Get or create applications.
+
+        :example:
+            >>> appManager = AlgorandClient.mainnet().app
+        """
+        return self._app_manager
+
+    @property
+    def app_deployer(self) -> AppDeployer:
+        """
+        Get or create applications.
+
+        :example:
+            >>> appDeployer = AlgorandClient.mainnet().app_deployer
+        """
+        return self._app_deployer
+
+    @property
+    def send(self) -> AlgorandClientTransactionSender:
+        """
+        Methods for sending a transaction and waiting for confirmation
+
+        :example:
+            >>> result = await AlgorandClient.mainnet().send.payment(
+            >>> PaymentParams(
+            >>>  sender="SENDERADDRESS",
+            >>>  receiver="RECEIVERADDRESS",
+            >>>  amount=AlgoAmount(algo-1)
+            >>> ))
+        """
+        return self._transaction_sender
+
+    @property
+    def create_transaction(self) -> AlgorandClientTransactionCreator:
+        """
+        Methods for building transactions
+
+        :example:
+            >>> transaction = AlgorandClient.mainnet().create_transaction.payment(
+            >>> PaymentParams(
+            >>>  sender="SENDERADDRESS",
+            >>>  receiver="RECEIVERADDRESS",
+            >>>  amount=AlgoAmount(algo=1)
+            >>> ))
+        """
+        return self._transaction_creator
+
+    @staticmethod
+    def default_localnet() -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` pointing at default LocalNet ports and API token.
+
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.default_localnet()
+        """
+        return AlgorandClient(
+            AlgoClientConfigs(
+                algod_config=ClientManager.get_default_localnet_config("algod"),
+                indexer_config=ClientManager.get_default_localnet_config("indexer"),
+                kmd_config=ClientManager.get_default_localnet_config("kmd"),
+            )
+        )
+
+    @staticmethod
+    def testnet() -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` pointing at TestNet using AlgoNode.
+
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.testnet()
+        """
+        return AlgorandClient(
+            AlgoClientConfigs(
+                algod_config=ClientManager.get_algonode_config("testnet", "algod"),
+                indexer_config=ClientManager.get_algonode_config("testnet", "indexer"),
+                kmd_config=None,
+            )
+        )
+
+    @staticmethod
+    def mainnet() -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` pointing at MainNet using AlgoNode.
+
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.mainnet()
+        """
+        return AlgorandClient(
+            AlgoClientConfigs(
+                algod_config=ClientManager.get_algonode_config("mainnet", "algod"),
+                indexer_config=ClientManager.get_algonode_config("mainnet", "indexer"),
+                kmd_config=None,
+            )
+        )
+
+    @staticmethod
+    def from_clients(
+        algod: AlgodClient, indexer: IndexerClient | None = None, kmd: KmdClient | None = None
+    ) -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` pointing to the given client(s).
+
+        :param algod: The algod client to use
+        :param indexer: The indexer client to use
+        :param kmd: The kmd client to use
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_clients(algod, indexer, kmd)
+        """
+        return AlgorandClient(AlgoSdkClients(algod=algod, indexer=indexer, kmd=kmd))
+
+    @staticmethod
+    def from_environment() -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` loading the configuration from environment variables.
+
+        Retrieve configurations from environment variables when defined or get defaults.
+
+        Expects to be called from a Python environment.
+
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_environment()
+        """
+        return AlgorandClient(ClientManager.get_config_from_environment_or_localnet())
+
+    @staticmethod
+    def from_config(
+        algod_config: AlgoClientNetworkConfig,
+        indexer_config: AlgoClientNetworkConfig | None = None,
+        kmd_config: AlgoClientNetworkConfig | None = None,
+    ) -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` from the given config.
+
+        :param algod_config: The config to use for the algod client
+        :param indexer_config: The config to use for the indexer client
+        :param kmd_config: The config to use for the kmd client
+        :return: The `AlgorandClient`
+
+        :example:
+            >>> algorand = AlgorandClient.from_config(algod_config, indexer_config, kmd_config)
+        """
+        return AlgorandClient(
+            AlgoClientConfigs(algod_config=algod_config, indexer_config=indexer_config, kmd_config=kmd_config)
+        )

algokit_utils/applications/__init__.py

@@ -0,0 +1,7 @@
+from algokit_utils.applications.abi import *  # noqa: F403
+from algokit_utils.applications.app_client import *  # noqa: F403
+from algokit_utils.applications.app_deployer import *  # noqa: F403
+from algokit_utils.applications.app_factory import *  # noqa: F403
+from algokit_utils.applications.app_manager import *  # noqa: F403
+from algokit_utils.applications.app_spec import *  # noqa: F403
+from algokit_utils.applications.enums import *  # noqa: F403