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

algokit_utils/accounts/kmd_account_manager.py

@@ -0,0 +1,161 @@
+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()
+                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,
+    ) -> 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,359 @@
+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
+        :example:
+            >>> algorand = AlgorandClient.mainnet().set_default_validity_window(1000);
+        """
+        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
+        :example:
+            >>> signer = SigningAccount(private_key=..., address=...)
+            >>> 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:
+            >>> signer = SigningAccount(private_key=..., address=...)
+            >>> algorand = AlgorandClient.mainnet().set_signer(signer.addr, signer.signer)
+        """
+        self._account_manager.set_signer(sender, signer)
+        return self
+
+    def set_signer_from_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
+        :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(SigningAccount(private_key=..., address=...))
+            >>> accountManager.set_signer_from_account(MultisigAccount(metadata, signing_accounts))
+            >>> accountManager.set_signer_from_account(account)
+        """
+        self._account_manager.set_default_signer(signer)
+        return self
+
+    def set_suggested_params_cache(
+        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
+        :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) -> 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 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(
+            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.
+
+        :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)
+        )