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

algokit_utils/accounts/kmd_account_manager.py

@@ -0,0 +1,159 @@
+from collections.abc import Callable
+from typing import Any, cast
+
+from algosdk.kmd import KMDClient
+
+from algokit_utils.clients.client_manager import ClientManager
+from algokit_utils.config import config
+from algokit_utils.models.account import SigningAccount
+from algokit_utils.models.amount import AlgoAmount
+from algokit_utils.transactions.transaction_composer import PaymentParams, TransactionComposer
+
+__all__ = ["KmdAccount", "KmdAccountManager"]
+
+logger = config.logger
+
+
+class KmdAccount(SigningAccount):
+    """Account retrieved from KMD with signing capabilities, extending base Account.
+
+    Provides an account implementation that can be used to sign transactions using keys stored in KMD.
+
+    :param private_key: Base64 encoded private key
+    :param address: Optional address override for rekeyed accounts, defaults to None
+    """
+
+    def __init__(self, private_key: str, address: str | None = None) -> None:
+        super().__init__(private_key=private_key, address=address or "")
+
+
+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()
+                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,
+    ) -> KmdAccount | 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
+        """
+
+        kmd_client = self.kmd()
+        wallets = kmd_client.list_wallets()
+        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(wallet_id, "")
+        addresses = kmd_client.list_keys(wallet_handle)
+
+        matched_address = None
+        if predicate:
+            for address in addresses:
+                account_info = self._client_manager.algod.account_info(address)
+                if predicate(cast(dict[str, Any], account_info)):
+                    matched_address = address
+                    break
+        else:
+            matched_address = next(iter(addresses), None)
+
+        if not matched_address:
+            return None
+
+        private_key = kmd_client.export_key(wallet_handle, "", matched_address)
+        return KmdAccount(private_key=private_key, address=sender)
+
+    def get_or_create_wallet_account(self, name: str, fund_with: AlgoAmount | None = None) -> KmdAccount:
+        """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
+        """
+        fund_with = fund_with or AlgoAmount.from_algo(1000)
+
+        existing = self.get_wallet_account(name)
+        if existing:
+            return existing
+
+        kmd_client = self.kmd()
+        wallet_id = kmd_client.create_wallet(name, "")["id"]
+        wallet_handle = kmd_client.init_wallet_handle(wallet_id, "")
+        kmd_client.generate_key(wallet_handle)
+
+        account = self.get_wallet_account(name)
+        assert account is not None
+
+        logger.info(
+            f"LocalNet account '{name}' doesn't yet exist; created account {account.address} "
+            f"with keys stored in KMD and funding with {fund_with} ALGO"
+        )
+
+        dispenser = self.get_localnet_dispenser_account()
+        TransactionComposer(
+            algod=self._client_manager.algod,
+            get_signer=lambda _: dispenser.signer,
+            get_suggested_params=self._client_manager.algod.suggested_params,
+        ).add_payment(
+            PaymentParams(
+                sender=dispenser.address,
+                receiver=account.address,
+                amount=fund_with,
+            )
+        ).send()
+        return account
+
+    def get_localnet_dispenser_account(self) -> KmdAccount:
+        """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")
+
+        dispenser = self.get_wallet_account(
+            "unencrypted-default-wallet",
+            lambda a: a["status"] != "Offline" and a["amount"] > 1_000_000_000,  # noqa: PLR2004
+        )
+        if not dispenser:
+            raise Exception("Error retrieving LocalNet dispenser account; couldn't find the default account in KMD")
+
+        return dispenser

algokit_utils/algorand.py

@@ -0,0 +1,265 @@
+import copy
+import time
+
+import typing_extensions
+from algosdk.atomic_transaction_composer import TransactionSigner
+from algosdk.kmd import KMDClient
+from algosdk.transaction import SuggestedParams
+from algosdk.v2client.algod import AlgodClient
+from algosdk.v2client.indexer import IndexerClient
+
+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.account import TransactionSignerAccountProtocol
+from algokit_utils.transactions.transaction_composer import (
+    TransactionComposer,
+)
+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: 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
+
+    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
+        """
+        self._default_validity_window = validity_window
+        return self
+
+    def set_default_signer(
+        self, signer: TransactionSigner | TransactionSignerAccountProtocol
+    ) -> 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 a `TransactionSignerAccountProtocol`
+        :return: The `AlgorandClient` so method calls can be chained
+        """
+        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
+        """
+        self._account_manager.set_signer(sender, signer)
+        return self
+
+    def set_signer_account(self, signer: TransactionSignerAccountProtocol) -> 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 a `TransactionSignerAccountProtocol`
+        :return: The `AlgorandClient` so method calls can be chained
+        """
+        self._account_manager.set_default_signer(signer)
+        return self
+
+    def set_suggested_params(
+        self, suggested_params: 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
+        """
+        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_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
+        """
+        self._cached_suggested_params_timeout = timeout
+        return self
+
+    def get_suggested_params(self) -> SuggestedParams:
+        """Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)"""
+        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 new_group(self) -> TransactionComposer:
+        """Start a new `TransactionComposer` transaction group"""
+        return TransactionComposer(
+            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,
+        )
+
+    @property
+    def client(self) -> ClientManager:
+        """Get clients, including algosdk clients and app clients."""
+        return self._client_manager
+
+    @property
+    def account(self) -> AccountManager:
+        """Get or create accounts that can sign transactions."""
+        return self._account_manager
+
+    @property
+    def asset(self) -> AssetManager:
+        """Get or create assets."""
+        return self._asset_manager
+
+    @property
+    def app(self) -> AppManager:
+        return self._app_manager
+
+    @property
+    def app_deployer(self) -> AppDeployer:
+        """Get or create applications."""
+        return self._app_deployer
+
+    @property
+    def send(self) -> AlgorandClientTransactionSender:
+        """Methods for sending a transaction and waiting for confirmation"""
+        return self._transaction_sender
+
+    @property
+    def create_transaction(self) -> AlgorandClientTransactionCreator:
+        """Methods for building transactions"""
+        return self._transaction_creator
+
+    @staticmethod
+    def default_localnet() -> "AlgorandClient":
+        """
+        Returns an `AlgorandClient` pointing at default LocalNet ports and API token.
+
+        :return: The `AlgorandClient`
+        """
+        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`
+        """
+        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`
+        """
+        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`
+        """
+        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`
+        """
+        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`
+        """
+        return AlgorandClient(
+            AlgoClientConfigs(algod_config=algod_config, indexer_config=indexer_config, kmd_config=kmd_config)
+        )