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

algokit_utils/_legacy_v2/__init__.py

@@ -0,0 +1,177 @@
+"""AlgoKit Python Utilities (Legacy V2) - a set of utilities for building solutions on Algorand
+
+This module provides commonly used utilities and types at the root level for convenience.
+For more specific functionality, import directly from the relevant submodules:
+
+    from algokit_utils.accounts import KmdAccountManager
+    from algokit_utils.applications import AppClient
+    from algokit_utils.applications.app_spec import Arc52Contract
+    etc.
+"""
+
+# Debugging utilities
+from algokit_utils._legacy_v2._ensure_funded import (
+    EnsureBalanceParameters,
+    EnsureFundedResponse,
+    ensure_funded,
+)
+from algokit_utils._legacy_v2._transfer import (
+    TransferAssetParameters,
+    TransferParameters,
+    transfer,
+    transfer_asset,
+)
+from algokit_utils._legacy_v2.account import (
+    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,
+)
+from algokit_utils._legacy_v2.application_client import (
+    ApplicationClient,
+    execute_atc_with_logic_error,
+    get_next_version,
+    get_sender_from_signer,
+    num_extra_program_pages,
+)
+from algokit_utils._legacy_v2.application_specification import (
+    ApplicationSpecification,
+    AppSpecStateDict,
+    CallConfig,
+    DefaultArgumentDict,
+    DefaultArgumentType,
+    MethodConfigDict,
+    MethodHints,
+    OnCompleteActionName,
+)
+from algokit_utils._legacy_v2.asset import opt_in, opt_out
+from algokit_utils._legacy_v2.common import Program
+from algokit_utils._legacy_v2.deploy import (
+    NOTE_PREFIX,
+    ABICallArgs,
+    ABICallArgsDict,
+    ABICreateCallArgs,
+    ABICreateCallArgsDict,
+    AppDeployMetaData,
+    AppLookup,
+    AppMetaData,
+    AppReference,
+    DeployCallArgs,
+    DeployCallArgsDict,
+    DeployCreateCallArgs,
+    DeployCreateCallArgsDict,
+    DeploymentFailedError,
+    DeployResponse,
+    TemplateValueDict,
+    TemplateValueMapping,
+    get_app_id_from_tx_id,
+    get_creator_apps,
+    replace_template_variables,
+)
+from algokit_utils._legacy_v2.models import (
+    ABIArgsDict,
+    ABIMethod,
+    ABITransactionResponse,
+    Account,
+    CommonCallParameters,
+    CommonCallParametersDict,
+    CreateCallParameters,
+    CreateCallParametersDict,
+    CreateTransactionParameters,
+    OnCompleteCallParameters,
+    OnCompleteCallParametersDict,
+    TransactionParameters,
+    TransactionParametersDict,
+    TransactionResponse,
+)
+from algokit_utils._legacy_v2.network_clients import (
+    AlgoClientConfig,
+    get_algod_client,
+    get_algonode_config,
+    get_default_localnet_config,
+    get_indexer_client,
+    get_kmd_client_from_algod_client,
+    is_localnet,
+    is_mainnet,
+    is_testnet,
+)
+
+__all__ = [
+    "NOTE_PREFIX",
+    "ABIArgsDict",
+    "ABICallArgs",
+    "ABICallArgsDict",
+    "ABICreateCallArgs",
+    "ABICreateCallArgsDict",
+    "ABIMethod",
+    "ABITransactionResponse",
+    "Account",
+    "AlgoClientConfig",
+    "AppDeployMetaData",
+    "AppLookup",
+    "AppMetaData",
+    "AppReference",
+    "AppSpecStateDict",
+    "ApplicationClient",
+    "ApplicationSpecification",
+    "CallConfig",
+    "CommonCallParameters",
+    "CommonCallParametersDict",
+    "CreateCallParameters",
+    "CreateCallParametersDict",
+    "CreateTransactionParameters",
+    "DefaultArgumentDict",
+    "DefaultArgumentType",
+    "DeployCallArgs",
+    "DeployCallArgsDict",
+    "DeployCreateCallArgs",
+    "DeployCreateCallArgsDict",
+    "DeployResponse",
+    "DeploymentFailedError",
+    "EnsureBalanceParameters",
+    "EnsureFundedResponse",
+    "MethodConfigDict",
+    "MethodHints",
+    "OnCompleteActionName",
+    "OnCompleteCallParameters",
+    "OnCompleteCallParametersDict",
+    "Program",
+    "TemplateValueDict",
+    "TemplateValueMapping",
+    "TransactionParameters",
+    "TransactionParametersDict",
+    "TransactionResponse",
+    "TransferAssetParameters",
+    "TransferParameters",
+    # Legacy v2 functions
+    "create_kmd_wallet_account",
+    "ensure_funded",
+    "execute_atc_with_logic_error",
+    "get_account",
+    "get_account_from_mnemonic",
+    "get_algod_client",
+    "get_algonode_config",
+    "get_app_id_from_tx_id",
+    "get_creator_apps",
+    "get_default_localnet_config",
+    "get_dispenser_account",
+    "get_indexer_client",
+    "get_kmd_client_from_algod_client",
+    "get_kmd_wallet_account",
+    "get_localnet_default_account",
+    "get_next_version",
+    "get_or_create_kmd_wallet_account",
+    "get_sender_from_signer",
+    "is_localnet",
+    "is_mainnet",
+    "is_testnet",
+    "num_extra_program_pages",
+    "opt_in",
+    "opt_out",
+    "replace_template_variables",
+    "transfer",
+    "transfer_asset",
+]

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

@@ -4,15 +4,16 @@ from algosdk.account import address_from_private_key
 from algosdk.atomic_transaction_composer import AccountTransactionSigner
 from algosdk.transaction import SuggestedParams
 from algosdk.v2client.algod import AlgodClient
+from typing_extensions import deprecated
 
-from algokit_utils._transfer import TransferParameters, transfer
-from algokit_utils.account import get_dispenser_account
-from algokit_utils.dispenser_api import (
+from algokit_utils._legacy_v2._transfer import TransferParameters, transfer
+from algokit_utils._legacy_v2.account import get_dispenser_account
+from algokit_utils._legacy_v2.models import Account
+from algokit_utils._legacy_v2.network_clients import is_testnet
+from algokit_utils.clients.dispenser_api_client import (
     DispenserAssetName,
     TestNetDispenserApiClient,
 )
-from algokit_utils.models import Account
-from algokit_utils.network_clients import is_testnet
 
 
 @dataclass(kw_only=True)
@@ -63,7 +64,7 @@ def _get_address_to_fund(parameters: EnsureBalanceParameters) -> str:
     if isinstance(parameters.account_to_fund, str):
         return parameters.account_to_fund
     else:
-        return str(address_from_private_key(parameters.account_to_fund.private_key))  # type: ignore[no-untyped-call]
+        return str(address_from_private_key(parameters.account_to_fund.private_key))
 
 
 def _get_account_info(client: AlgodClient, address_to_fund: str) -> dict:
@@ -111,28 +112,28 @@ def _fund_using_transfer(
             fee_micro_algos=parameters.fee_micro_algos,
         ),
     )
-    transaction_id = response.get_txid()  # type: ignore[no-untyped-call]
+    transaction_id = response.get_txid()
     return EnsureFundedResponse(transaction_id=transaction_id, amount=response.amt)
 
 
+@deprecated(
+    "Use `algorand.account.ensure_funded()`, `algorand.account.ensure_funded_from_environment()`, "
+    "or `algorand.account.ensure_funded_from_testnet_dispenser_api()` instead"
+)
 def ensure_funded(
     client: AlgodClient,
     parameters: EnsureBalanceParameters,
 ) -> EnsureFundedResponse | None:
     """
-    Funds a given account using a funding source such that it has a certain amount of algos free to spend
-    (accounting for ALGOs locked in minimum balance requirement)
-    see <https://developer.algorand.org/docs/get-details/accounts/#minimum-balance>
-
+    Funds a given account using a funding source to ensure it has sufficient spendable ALGOs.
 
-    Args:
-        client (AlgodClient): An instance of the AlgodClient class from the AlgoSDK library.
-        parameters (EnsureBalanceParameters): An instance of the EnsureBalanceParameters class that
-        specifies the account to fund and the minimum spending balance.
+    Ensures the target account has enough ALGOs free to spend after accounting for ALGOs locked in minimum balance
+    requirements. See https://developer.algorand.org/docs/get-details/accounts/#minimum-balance for details on minimum
+    balance requirements.
 
-    Returns:
-        PaymentTxn | str | None: If funds are needed, the function returns a payment transaction or a
-        string indicating that the dispenser API was used. If no funds are needed, the function returns None.
+    :param client: An instance of the AlgodClient class from the AlgoSDK library
+    :param parameters: Parameters specifying the account to fund and minimum spending balance requirements
+    :return: If funds are needed, returns payment transaction details or dispenser API response. Returns None if no funding needed
     """
 
     address_to_fund = _get_address_to_fund(parameters)

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

@@ -6,30 +6,29 @@ import algosdk.transaction
 from algosdk.account import address_from_private_key
 from algosdk.atomic_transaction_composer import AccountTransactionSigner
 from algosdk.transaction import AssetTransferTxn, PaymentTxn, SuggestedParams
+from typing_extensions import deprecated
 
-from algokit_utils.models import Account
+from algokit_utils._legacy_v2.models import Account
 
 if TYPE_CHECKING:
     from algosdk.v2client.algod import AlgodClient
 
-__all__ = ["TransferParameters", "transfer", "TransferAssetParameters", "transfer_asset"]
+__all__ = ["TransferAssetParameters", "TransferParameters", "transfer", "transfer_asset"]
 logger = logging.getLogger(__name__)
 
 
 @dataclasses.dataclass(kw_only=True)
 class TransferParametersBase:
-    """Parameters for transferring µALGOs between accounts
-
-    Args:
-        from_account (Account | AccountTransactionSigner): The account (with private key) or signer that will send
-            the µALGOs
-        to_address (str): The account address that will receive the µALGOs
-        suggested_params (SuggestedParams | None): (optional) transaction parameters
-        note (str | bytes | None): (optional) transaction note
-        fee_micro_algos (int | None): (optional) The flat fee you want to pay, useful for covering extra fees in a
-            transaction group or app call
-        max_fee_micro_algos (int | None): (optional) The maximum fee that you are happy to pay (default: unbounded)
-            - if this is set it's possible the transaction could get rejected during network congestion
+    """Parameters for transferring µALGOs between accounts.
+
+    This class contains the base parameters needed for transferring µALGOs between Algorand accounts.
+
+    :ivar from_account: The account (with private key) or signer that will send the µALGOs
+    :ivar to_address: The account address that will receive the µALGOs
+    :ivar suggested_params: Transaction parameters, defaults to None
+    :ivar note: Transaction note, defaults to None
+    :ivar fee_micro_algos: The flat fee you want to pay, useful for covering extra fees in a transaction group or app call, defaults to None
+    :ivar max_fee_micro_algos: The maximum fee that you are happy to pay - if this is set it's possible the transaction could get rejected during network congestion, defaults to None
     """
 
     from_account: Account | AccountTransactionSigner
@@ -49,13 +48,13 @@ class TransferParameters(TransferParametersBase):
 
 @dataclasses.dataclass(kw_only=True)
 class TransferAssetParameters(TransferParametersBase):
-    """Parameters for transferring assets between accounts
+    """Parameters for transferring assets between accounts.
+
+    Defines the parameters needed to transfer Algorand Standard Assets (ASAs) between accounts.
 
-    Args:
-       asset_id (int): The asset id that will be transfered
-       amount (int): The amount to send
-       clawback_from (str | None): An address of a target account from which to perform a clawback operation. Please
-           note, in such cases senderAccount must be equal to clawback field on ASA metadata.
+    :param asset_id: The asset id that will be transferred
+    :param amount: The amount of the asset to send
+    :param clawback_from: An address of a target account from which to perform a clawback operation. Please note, in such cases senderAccount must be equal to clawback field on ASA metadata, defaults to None
     """
 
     asset_id: int
@@ -80,6 +79,7 @@ def _check_fee(transaction: PaymentTxn | AssetTransferTxn, max_fee: int | None)
             )
 
 
+@deprecated("Use the `TransactionComposer` abstraction instead to construct appropriate transfer transactions")
 def transfer(client: "AlgodClient", parameters: TransferParameters) -> PaymentTxn:
     """Transfer µALGOs between accounts"""
 
@@ -93,13 +93,14 @@ def transfer(client: "AlgodClient", parameters: TransferParameters) -> PaymentTx
         amt=params.micro_algos,
         note=params.note.encode("utf-8") if isinstance(params.note, str) else params.note,
         sp=params.suggested_params,
-    )  # type: ignore[no-untyped-call]
+    )
 
     result = _send_transaction(client=client, transaction=transaction, parameters=params)
     assert isinstance(result, PaymentTxn)
     return result
 
 
+@deprecated("Use the `TransactionComposer` abstraction instead to construct appropriate transfer transactions")
 def transfer_asset(client: "AlgodClient", parameters: TransferAssetParameters) -> AssetTransferTxn:
     """Transfer assets between accounts"""
 
@@ -117,7 +118,7 @@ def transfer_asset(client: "AlgodClient", parameters: TransferAssetParameters) -
         note=params.note,
         index=params.asset_id,
         rekey_to=None,
-    )  # type: ignore[no-untyped-call]
+    )
 
     result = _send_transaction(client=client, transaction=xfer_txn, parameters=params)
     assert isinstance(result, AssetTransferTxn)
@@ -148,5 +149,5 @@ def _get_address(account: Account | AccountTransactionSigner) -> str:
     if type(account) is Account:
         return account.address
     else:
-        address = address_from_private_key(account.private_key)  # type: ignore[no-untyped-call]
+        address = address_from_private_key(account.private_key)
         return str(address)

algokit_utils/_legacy_v2/account.py

@@ -0,0 +1,203 @@
+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 typing_extensions import deprecated
+
+from algokit_utils._legacy_v2._transfer import TransferParameters, transfer
+from algokit_utils._legacy_v2.models import Account
+from algokit_utils._legacy_v2.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
+
+
+@deprecated(
+    "Use `algorand.account.from_mnemonic()` instead. Example: " "`account = algorand.account.from_mnemonic(mnemonic)`"
+)
+def get_account_from_mnemonic(mnemonic: str) -> Account:
+    """Convert a mnemonic (25 word passphrase) into an Account"""
+    private_key = to_private_key(mnemonic)
+    address = str(address_from_private_key(private_key))
+    return Account(private_key=private_key, address=address)
+
+
+@deprecated("Use `algorand.account.from_kmd()` instead. Example: " "`account = algorand.account.from_kmd(name)`")
+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"]
+    wallet_handle = kmd_client.init_wallet_handle(wallet_id, "")
+    kmd_client.generate_key(wallet_handle)
+
+    key_ids: list[str] = kmd_client.list_keys(wallet_handle)
+    account_key = key_ids[0]
+
+    private_account_key = kmd_client.export_key(wallet_handle, "", account_key)
+    return get_account_from_mnemonic(from_private_key(private_account_key))
+
+
+@deprecated(
+    "Use `algorand.account.from_kmd()` instead. Example: "
+    "`account = algorand.account.from_kmd(name, fund_with=AlgoAmount.from_algo(1000))`"
+)
+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),
+            ),
+        )
+
+    return account
+
+
+def _is_default_account(account: dict[str, Any]) -> bool:
+    return bool(account["status"] != "Offline" and account["amount"] > _DEFAULT_ACCOUNT_MINIMUM_BALANCE)
+
+
+@deprecated(
+    "Use `algorand.account.from_kmd()` instead. Example: "
+    "`account = algorand.account.from_kmd('unencrypted-default-wallet', lambda a: a['status'] != 'Offline' and a['amount'] > 1_000_000_000)`"
+)
+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
+
+
+@deprecated(
+    "Use `algorand.account.dispenser_from_environment()` or `algorand.account.localnet_dispenser()` instead. "
+    "Example: `dispenser = algorand.account.dispenser_from_environment()`"
+)
+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")
+
+
+@deprecated(
+    "Use `algorand.account.from_kmd()` instead. Example: " "`account = algorand.account.from_kmd(name, predicate)`"
+)
+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()
+
+    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, "")
+    key_ids: list[str] = kmd_client.list_keys(wallet_handle)
+    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)
+    return get_account_from_mnemonic(from_private_key(private_account_key))
+
+
+@deprecated(
+    "Use `algorand.account.from_environment()` or `algorand.account.from_kmd()` or `algorand.account.random()` instead. "
+    "Example: "
+    "`account = algorand.account.from_environment('ACCOUNT', AlgoAmount.from_algo(1000))`"
+)
+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.
+    Returns an Algorand account with private key loaded by convention based on the given name identifier.
+
+    For non-LocalNet environments, loads the mnemonic secret from environment variable {name}_MNEMONIC.
+    For LocalNet environments, loads or creates an account from a KMD wallet named {name}.
+
+    :example:
+    >>> # If you have a mnemonic secret loaded into `os.environ["ACCOUNT_MNEMONIC"]` then you can call:
+    >>> 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.
+
+    :param client: The Algorand client to use
+    :param name: The name identifier to use for loading/creating the account
+    :param fund_with_algos: Amount of Algos to fund new LocalNet accounts with, defaults to 1000
+    :param kmd_client: Optional KMD client to use for LocalNet wallet operations
+    :raises Exception: If required environment variable is missing in non-LocalNet environment
+    :return: An Account object with loaded private key
+    """
+
+    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)
+        return account
+
+    raise Exception(f"Missing environment variable '{mnemonic_key}' when looking for account '{name}'")