algokit_utils.accounts.account_manager ====================================== .. py:module:: algokit_utils.accounts.account_manager Classes ------- .. autoapisummary:: algokit_utils.accounts.account_manager.EnsureFundedResult algokit_utils.accounts.account_manager.EnsureFundedFromTestnetDispenserApiResult algokit_utils.accounts.account_manager.AccountInformation algokit_utils.accounts.account_manager.AccountManager Module Contents --------------- .. py:class:: EnsureFundedResult Bases: :py:obj:`algokit_utils.transactions.transaction_sender.SendSingleTransactionResult`, :py:obj:`_CommonEnsureFundedParams` Result from performing an ensure funded call. .. py:class:: EnsureFundedFromTestnetDispenserApiResult Bases: :py:obj:`_CommonEnsureFundedParams` Result from performing an ensure funded call using TestNet dispenser API. .. py:class:: AccountInformation Information about an Algorand account's current status, balance and other properties. See `https://dev.algorand.co/reference/rest-apis/algod/#account` for detailed field descriptions. .. py:attribute:: address :type: str The account's address .. py:attribute:: amount :type: algokit_utils.models.amount.AlgoAmount The account's current balance .. py:attribute:: amount_without_pending_rewards :type: algokit_utils.models.amount.AlgoAmount The account's balance without the pending rewards .. py:attribute:: min_balance :type: algokit_utils.models.amount.AlgoAmount The account's minimum required balance .. py:attribute:: pending_rewards :type: algokit_utils.models.amount.AlgoAmount The amount of pending rewards .. py:attribute:: rewards :type: algokit_utils.models.amount.AlgoAmount The amount of rewards earned .. py:attribute:: round :type: int The round for which this information is relevant .. py:attribute:: status :type: str The account's status (e.g., 'Offline', 'Online') .. py:attribute:: total_apps_opted_in :type: int | None :value: None Number of applications this account has opted into .. py:attribute:: total_assets_opted_in :type: int | None :value: None Number of assets this account has opted into .. py:attribute:: total_box_bytes :type: int | None :value: None Total number of box bytes used by this account .. py:attribute:: total_boxes :type: int | None :value: None Total number of boxes used by this account .. py:attribute:: total_created_apps :type: int | None :value: None Number of applications created by this account .. py:attribute:: total_created_assets :type: int | None :value: None Number of assets created by this account .. py:attribute:: apps_local_state :type: list[dict] | None :value: None Local state of applications this account has opted into .. py:attribute:: apps_total_extra_pages :type: int | None :value: None Number of extra pages allocated to applications .. py:attribute:: apps_total_schema :type: dict | None :value: None Total schema for all applications .. py:attribute:: assets :type: list[dict] | None :value: None Assets held by this account .. py:attribute:: auth_addr :type: str | None :value: None If rekeyed, the authorized address .. py:attribute:: closed_at_round :type: int | None :value: None Round when this account was closed .. py:attribute:: created_apps :type: list[dict] | None :value: None Applications created by this account .. py:attribute:: created_assets :type: list[dict] | None :value: None Assets created by this account .. py:attribute:: created_at_round :type: int | None :value: None Round when this account was created .. py:attribute:: deleted :type: bool | None :value: None Whether this account is deleted .. py:attribute:: incentive_eligible :type: bool | None :value: None Whether this account is eligible for incentives .. py:attribute:: last_heartbeat :type: int | None :value: None Last heartbeat round for this account .. py:attribute:: last_proposed :type: int | None :value: None Last round this account proposed a block .. py:attribute:: participation :type: dict | None :value: None Participation information for this account .. py:attribute:: reward_base :type: int | None :value: None Base reward for this account .. py:attribute:: sig_type :type: str | None :value: None Signature type for this account .. py:class:: AccountManager(client_manager: algokit_utils.clients.client_manager.ClientManager) Creates and keeps track of signing accounts that can sign transactions for a sending address. This class provides functionality to create, track, and manage various types of accounts including mnemonic-based, rekeyed, multisig, and logic signature accounts. :param client_manager: The ClientManager client to use for algod and kmd clients :example: >>> account_manager = AccountManager(client_manager) .. py:property:: kmd :type: algokit_utils.accounts.kmd_account_manager.KmdAccountManager KMD account manager that allows you to easily get and create accounts using KMD. :return KmdAccountManager: The 'KmdAccountManager' instance :example: >>> kmd_manager = account_manager.kmd .. py:method:: set_default_signer(signer: algosdk.atomic_transaction_composer.TransactionSigner | algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> typing_extensions.Self Sets the default signer to use if no other signer is specified. If this isn't set and a transaction needs signing for a given sender then an error will be thrown from `get_signer` / `get_account`. :param signer: A `TransactionSigner` signer to use. :returns: The `AccountManager` so method calls can be chained :example: >>> signer_account = account_manager.random() >>> account_manager.set_default_signer(signer_account) .. py:method:: set_signer(sender: str, signer: algosdk.atomic_transaction_composer.TransactionSigner) -> typing_extensions.Self Tracks the given `TransactionSigner` against the given sender address for later signing. :param sender: The sender address to use this signer for :param signer: The `TransactionSigner` to sign transactions with for the given sender :returns: The `AccountManager` instance for method chaining :example: >>> account_manager.set_signer("SENDERADDRESS", transaction_signer) .. py:method:: set_signers(*, another_account_manager: AccountManager, overwrite_existing: bool = True) -> typing_extensions.Self Merges the given `AccountManager` into this one. :param another_account_manager: The `AccountManager` to merge into this one :param overwrite_existing: Whether to overwrite existing signers in this manager :returns: The `AccountManager` instance for method chaining :example: >>> accountManager2.set_signers(accountManager1) .. py:method:: set_signer_from_account(account: algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> typing_extensions.Self set_signer_from_account(signer: algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> typing_extensions.Self Tracks the given account for later signing. Note: If you are generating accounts via the various methods on `AccountManager` (like `random`, `from_mnemonic`, `logic_sig`, etc.) then they automatically get tracked. The method accepts either a positional argument or a keyword argument named 'account' or 'signer'. The 'signer' parameter is deprecated and will show a warning when used. :param *args: Variable positional arguments. The first argument should be a TransactionSignerAccountProtocol. :param **kwargs: Variable keyword arguments. Can include 'account' or 'signer' (deprecated) as TransactionSignerAccountProtocol. :returns: The `AccountManager` instance for method chaining :raises ValueError: If no account or signer argument is provided :example: >>> account_manager = AccountManager(client_manager) >>> # Using positional argument >>> account_manager.set_signer_from_account( ... SigningAccount(private_key=algosdk.account.generate_account()[0]) ... ) >>> # Using keyword argument 'account' >>> account_manager.set_signer_from_account( ... account=LogicSigAccount(AlgosdkLogicSigAccount(program, args)) ... ) >>> # Using deprecated keyword argument 'signer' >>> account_manager.set_signer_from_account( ... signer=MultiSigAccount(multisig_params, [account1, account2]) ... ) .. py:method:: get_signer(sender: str | algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> algosdk.atomic_transaction_composer.TransactionSigner Returns the `TransactionSigner` for the given sender address. If no signer has been registered for that address then the default signer is used if registered. :param sender: The sender address or account :returns: The `TransactionSigner` :raises ValueError: If no signer is found and no default signer is set :example: >>> signer = account_manager.get_signer("SENDERADDRESS") .. py:method:: get_account(sender: str) -> algokit_utils.protocols.account.TransactionSignerAccountProtocol Returns the `TransactionSignerAccountProtocol` for the given sender address. :param sender: The sender address :returns: The `TransactionSignerAccountProtocol` :raises ValueError: If no account is found or if the account is not a regular account :example: >>> sender = account_manager.random().address >>> # ... >>> # Returns the `TransactionSignerAccountProtocol` for `sender` that has previously been registered >>> account = account_manager.get_account(sender) .. py:method:: get_information(sender: str | algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> AccountInformation Returns the given sender account's current status, balance and spendable amounts. See ``_ for response data schema details. :param sender: The address or account compliant with `TransactionSignerAccountProtocol` protocol to look up :returns: The account information :example: >>> address = "XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA" >>> account_info = account_manager.get_information(address) .. py:method:: from_mnemonic(*, mnemonic: str, sender: str | None = None) -> algokit_utils.models.account.SigningAccount Tracks and returns an Algorand account with secret key loaded by taking the mnemonic secret. :param mnemonic: The mnemonic secret representing the private key of an account :param sender: Optional address to use as the sender :returns: The account .. warning:: Be careful how the mnemonic is handled. Never commit it into source control and ideally load it from the environment (ideally via a secret storage service) rather than the file system. :example: >>> account = account_manager.from_mnemonic("mnemonic secret ...") .. py:method:: from_environment(name: str, fund_with: algokit_utils.models.amount.AlgoAmount | None = None) -> algokit_utils.models.account.SigningAccount Tracks and returns an Algorand account with private key loaded by convention from environment variables. 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). :param name: The name identifier of the account :param fund_with: Optional amount to fund the account with when it gets created (when targeting LocalNet) :returns: The account :raises ValueError: If environment variable {NAME}_MNEMONIC is missing when looking for account {NAME} .. note:: Convention: * **Non-LocalNet:** will load `{NAME}_MNEMONIC` as a mnemonic secret. If `{NAME}_SENDER` is defined then it will use that for the sender address (i.e. to support rekeyed accounts) * **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 :example: >>> # If you have a mnemonic secret loaded into `MY_ACCOUNT_MNEMONIC` then you can call: >>> account = account_manager.from_environment('MY_ACCOUNT') >>> # If that code runs against LocalNet then a wallet called `MY_ACCOUNT` will automatically be created >>> # with an account that is automatically funded with the specified amount from the LocalNet dispenser .. py:method:: from_kmd(name: str, predicate: collections.abc.Callable[[dict[str, Any]], bool] | None = None, sender: str | None = None) -> algokit_utils.models.account.SigningAccount Tracks and returns an Algorand account with private key loaded from the given KMD wallet. :param name: The name of the wallet to retrieve an account from :param predicate: Optional filter to use to find the account :param sender: Optional sender address to use this signer for (aka a rekeyed account) :returns: The account :raises ValueError: If unable to find KMD account with given name and predicate :example: >>> # Get default funded account in a LocalNet: >>> defaultDispenserAccount = account.from_kmd('unencrypted-default-wallet', ... lambda a: a.status != 'Offline' and a.amount > 1_000_000_000 ... ) .. py:method:: logicsig(program: bytes, args: list[bytes] | None = None) -> algokit_utils.models.account.LogicSigAccount Tracks and returns an account that represents a logic signature. :param program: The bytes that make up the compiled logic signature :param args: Optional (binary) arguments to pass into the logic signature :returns: A logic signature account wrapper :example: >>> account = account.logicsig(program, [new Uint8Array(3, ...)]) .. py:method:: multisig(metadata: algokit_utils.models.account.MultisigMetadata, signing_accounts: list[algokit_utils.models.account.SigningAccount]) -> algokit_utils.models.account.MultiSigAccount Tracks and returns an account that supports partial or full multisig signing. :param metadata: The metadata for the multisig account :param signing_accounts: The signers that are currently present :returns: A multisig account wrapper :example: >>> account = account_manager.multi_sig( ... version=1, ... threshold=1, ... addrs=["ADDRESS1...", "ADDRESS2..."], ... signing_accounts=[account1, account2] ... ) .. py:method:: random() -> algokit_utils.models.account.SigningAccount Tracks and returns a new, random Algorand account. :returns: The account :example: >>> account = account_manager.random() .. py:method:: localnet_dispenser() -> algokit_utils.models.account.SigningAccount Returns an Algorand account with private key loaded for the default LocalNet dispenser account. This account can be used to fund other accounts. :returns: The account :example: >>> account = account_manager.localnet_dispenser() .. py:method:: dispenser_from_environment() -> algokit_utils.models.account.SigningAccount Returns an account (with private key loaded) that can act as a dispenser from environment variables. If environment variables are not present, returns the default LocalNet dispenser account. :returns: The account :example: >>> account = account_manager.dispenser_from_environment() .. py:method:: rekeyed(*, sender: str, account: algokit_utils.protocols.account.TransactionSignerAccountProtocol) -> algokit_utils.models.account.TransactionSignerAccount | algokit_utils.models.account.SigningAccount Tracks and returns an Algorand account that is a rekeyed version of the given account to a new sender. :param sender: The account or address to use as the sender :param account: The account to use as the signer for this new rekeyed account :returns: The rekeyed account :example: >>> account = account.from_mnemonic("mnemonic secret ...") >>> rekeyed_account = account_manager.rekeyed(account, "SENDERADDRESS...") .. py:method:: rekey_account(account: str, rekey_to: str | algokit_utils.protocols.account.TransactionSignerAccountProtocol, *, signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, note: bytes | None = None, lease: bytes | None = None, static_fee: algokit_utils.models.amount.AlgoAmount | None = None, extra_fee: algokit_utils.models.amount.AlgoAmount | None = None, max_fee: algokit_utils.models.amount.AlgoAmount | None = None, validity_window: int | None = None, first_valid_round: int | None = None, last_valid_round: int | None = None, suppress_log: bool | None = None) -> algokit_utils.transactions.transaction_composer.SendAtomicTransactionComposerResults Rekey an account to a new address. :param account: The account to rekey :param rekey_to: The address or account to rekey to :param signer: Optional transaction signer :param note: Optional transaction note :param lease: Optional transaction lease :param static_fee: Optional static fee :param extra_fee: Optional extra fee :param max_fee: Optional max fee :param validity_window: Optional validity window :param first_valid_round: Optional first valid round :param last_valid_round: Optional last valid round :param suppress_log: Optional flag to suppress logging :returns: The result of the transaction and the transaction that was sent .. warning:: Please be careful with this function and be sure to read the `official rekey guidance `_. :example: >>> # Basic example (with string addresses): >>> algorand.account.rekey_account("ACCOUNTADDRESS", "NEWADDRESS") >>> # Basic example (with signer accounts): >>> algorand.account.rekey_account(account1, newSignerAccount) >>> # Advanced example: >>> algorand.account.rekey_account( ... account="ACCOUNTADDRESS", ... rekey_to="NEWADDRESS", ... lease='lease', ... note='note', ... first_valid_round=1000, ... validity_window=10, ... extra_fee=AlgoAmount.from_micro_algo(1000), ... static_fee=AlgoAmount.from_micro_algo(1000), ... max_fee=AlgoAmount.from_micro_algo(3000), ... suppress_log=True, ... ) .. py:method:: ensure_funded(account_to_fund: str | algokit_utils.models.account.SigningAccount, dispenser_account: str | algokit_utils.models.account.SigningAccount, min_spending_balance: algokit_utils.models.amount.AlgoAmount, min_funding_increment: algokit_utils.models.amount.AlgoAmount | None = None, send_params: algokit_utils.models.transaction.SendParams | None = None, signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, rekey_to: str | None = None, note: bytes | None = None, lease: bytes | None = None, static_fee: algokit_utils.models.amount.AlgoAmount | None = None, extra_fee: algokit_utils.models.amount.AlgoAmount | None = None, max_fee: algokit_utils.models.amount.AlgoAmount | None = None, validity_window: int | None = None, first_valid_round: int | None = None, last_valid_round: int | None = None) -> EnsureFundedResult | None Funds a given account using a dispenser account as a funding source. Ensures the given account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement). See ``_ for details. :param account_to_fund: The account to fund :param dispenser_account: The account to use as a dispenser funding source :param min_spending_balance: The minimum balance of Algo that the account should have available to spend :param min_funding_increment: Optional minimum funding increment :param send_params: Parameters for the send operation, defaults to None :param signer: Optional transaction signer :param rekey_to: Optional rekey address :param note: Optional transaction note :param lease: Optional transaction lease :param static_fee: Optional static fee :param extra_fee: Optional extra fee :param max_fee: Optional maximum fee :param validity_window: Optional validity window :param first_valid_round: Optional first valid round :param last_valid_round: Optional last valid round :returns: The result of executing the dispensing transaction and the `amountFunded` if funds were needed, or None if no funds were needed :example: >>> # Basic example: >>> algorand.account.ensure_funded("ACCOUNTADDRESS", "DISPENSERADDRESS", AlgoAmount.from_algo(1)) >>> # With configuration: >>> algorand.account.ensure_funded( ... "ACCOUNTADDRESS", ... "DISPENSERADDRESS", ... AlgoAmount.from_algo(1), ... min_funding_increment=AlgoAmount.from_algo(2), ... fee=AlgoAmount.from_micro_algo(1000), ... suppress_log=True ... ) .. py:method:: ensure_funded_from_environment(account_to_fund: str | algokit_utils.models.account.SigningAccount, min_spending_balance: algokit_utils.models.amount.AlgoAmount, *, min_funding_increment: algokit_utils.models.amount.AlgoAmount | None = None, send_params: algokit_utils.models.transaction.SendParams | None = None, signer: algosdk.atomic_transaction_composer.TransactionSigner | None = None, rekey_to: str | None = None, note: bytes | None = None, lease: bytes | None = None, static_fee: algokit_utils.models.amount.AlgoAmount | None = None, extra_fee: algokit_utils.models.amount.AlgoAmount | None = None, max_fee: algokit_utils.models.amount.AlgoAmount | None = None, validity_window: int | None = None, first_valid_round: int | None = None, last_valid_round: int | None = None) -> EnsureFundedResult | None Ensure an account is funded from a dispenser account configured in environment. Uses a dispenser account retrieved from the environment, per the `dispenser_from_environment` method, as a funding source such that the given account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement). See ``_ for details. :param account_to_fund: The account to fund :param min_spending_balance: The minimum balance of Algo that the account should have available to spend :param min_funding_increment: Optional minimum funding increment :param send_params: Parameters for the send operation, defaults to None :param signer: Optional transaction signer :param rekey_to: Optional rekey address :param note: Optional transaction note :param lease: Optional transaction lease :param static_fee: Optional static fee :param extra_fee: Optional extra fee :param max_fee: Optional maximum fee :param validity_window: Optional validity window :param first_valid_round: Optional first valid round :param last_valid_round: Optional last valid round :returns: The result of executing the dispensing transaction and the `amountFunded` if funds were needed, or None if no funds were needed .. note:: The dispenser account is retrieved from the account mnemonic stored in process.env.DISPENSER_MNEMONIC and optionally process.env.DISPENSER_SENDER if it's a rekeyed account, or against default LocalNet if no environment variables present. :example: >>> # Basic example: >>> algorand.account.ensure_funded_from_environment("ACCOUNTADDRESS", AlgoAmount.from_algo(1)) >>> # With configuration: >>> algorand.account.ensure_funded_from_environment( ... "ACCOUNTADDRESS", ... AlgoAmount.from_algo(1), ... min_funding_increment=AlgoAmount.from_algo(2), ... fee=AlgoAmount.from_micro_algo(1000), ... suppress_log=True ... ) .. py:method:: ensure_funded_from_testnet_dispenser_api(account_to_fund: str | algokit_utils.models.account.SigningAccount, dispenser_client: algokit_utils.clients.dispenser_api_client.TestNetDispenserApiClient, min_spending_balance: algokit_utils.models.amount.AlgoAmount, *, min_funding_increment: algokit_utils.models.amount.AlgoAmount | None = None) -> EnsureFundedFromTestnetDispenserApiResult | None Ensure an account is funded using the TestNet Dispenser API. Uses the TestNet Dispenser API as a funding source such that the account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement). See ``_ for details. :param account_to_fund: The account to fund :param dispenser_client: The TestNet dispenser funding client :param min_spending_balance: The minimum balance of Algo that the account should have available to spend :param min_funding_increment: Optional minimum funding increment :returns: The result of executing the dispensing transaction and the `amountFunded` if funds were needed, or None if no funds were needed :raises ValueError: If attempting to fund on non-TestNet network :example: >>> # Basic example: >>> account_manager.ensure_funded_from_testnet_dispenser_api( ... "ACCOUNTADDRESS", ... algorand.client.get_testnet_dispenser_from_environment(), ... AlgoAmount.from_algo(1) ... ) >>> # With configuration: >>> account_manager.ensure_funded_from_testnet_dispenser_api( ... "ACCOUNTADDRESS", ... algorand.client.get_testnet_dispenser_from_environment(), ... AlgoAmount.from_algo(1), ... min_funding_increment=AlgoAmount.from_algo(2) ... )