algokit_utils.accounts.account_manager¶
Classes¶
Result from performing an ensure funded call. |
|
Result from performing an ensure funded call using TestNet dispenser API. |
|
Information about an Algorand account's current status, balance and other properties. |
|
Creates and keeps track of signing accounts that can sign transactions for a sending address. |
Module Contents¶
- class algokit_utils.accounts.account_manager.EnsureFundedResult¶
Bases:
algokit_utils.transactions.transaction_sender.SendSingleTransactionResult
,_CommonEnsureFundedParams
Result from performing an ensure funded call.
- class algokit_utils.accounts.account_manager.EnsureFundedFromTestnetDispenserApiResult¶
Bases:
_CommonEnsureFundedParams
Result from performing an ensure funded call using TestNet dispenser API.
- class algokit_utils.accounts.account_manager.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.
- address: str¶
The account’s address
- amount: algokit_utils.models.amount.AlgoAmount¶
The account’s current balance
- amount_without_pending_rewards: algokit_utils.models.amount.AlgoAmount¶
The account’s balance without the pending rewards
- min_balance: algokit_utils.models.amount.AlgoAmount¶
The account’s minimum required balance
- pending_rewards: algokit_utils.models.amount.AlgoAmount¶
The amount of pending rewards
- rewards: algokit_utils.models.amount.AlgoAmount¶
The amount of rewards earned
- round: int¶
The round for which this information is relevant
- status: str¶
The account’s status (e.g., ‘Offline’, ‘Online’)
- total_apps_opted_in: int | None = None¶
Number of applications this account has opted into
- total_assets_opted_in: int | None = None¶
Number of assets this account has opted into
- total_box_bytes: int | None = None¶
Total number of box bytes used by this account
- total_boxes: int | None = None¶
Total number of boxes used by this account
- total_created_apps: int | None = None¶
Number of applications created by this account
- total_created_assets: int | None = None¶
Number of assets created by this account
- apps_local_state: list[dict] | None = None¶
Local state of applications this account has opted into
- apps_total_extra_pages: int | None = None¶
Number of extra pages allocated to applications
- apps_total_schema: dict | None = None¶
Total schema for all applications
- assets: list[dict] | None = None¶
Assets held by this account
- auth_addr: str | None = None¶
If rekeyed, the authorized address
- closed_at_round: int | None = None¶
Round when this account was closed
- created_apps: list[dict] | None = None¶
Applications created by this account
- created_assets: list[dict] | None = None¶
Assets created by this account
- created_at_round: int | None = None¶
Round when this account was created
- deleted: bool | None = None¶
Whether this account is deleted
- incentive_eligible: bool | None = None¶
Whether this account is eligible for incentives
- last_heartbeat: int | None = None¶
Last heartbeat round for this account
- last_proposed: int | None = None¶
Last round this account proposed a block
- participation: dict | None = None¶
Participation information for this account
- reward_base: int | None = None¶
Base reward for this account
- sig_type: str | None = None¶
Signature type for this account
- class algokit_utils.accounts.account_manager.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.
- Parameters:
client_manager – The ClientManager client to use for algod and kmd clients
- Example:
>>> account_manager = AccountManager(client_manager)
- property kmd: 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
- 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.
- Parameters:
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)
- 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.
- Parameters:
sender – The sender address to use this signer for
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)
- set_signers(*, another_account_manager: AccountManager, overwrite_existing: bool = True) typing_extensions.Self ¶
Merges the given AccountManager into this one.
- Parameters:
another_account_manager – The AccountManager to merge into this one
overwrite_existing – Whether to overwrite existing signers in this manager
- Returns:
The AccountManager instance for method chaining
- Example:
>>> accountManager2.set_signers(accountManager1)
- 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.
- Parameters:
*args –
Variable positional arguments. The first argument should be a TransactionSignerAccountProtocol.
**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]) ... )
- 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.
- Parameters:
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")
- get_account(sender: str) algokit_utils.protocols.account.TransactionSignerAccountProtocol ¶
Returns the TransactionSignerAccountProtocol for the given sender address.
- Parameters:
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)
- get_information(sender: str | algokit_utils.protocols.account.TransactionSignerAccountProtocol) AccountInformation ¶
Returns the given sender account’s current status, balance and spendable amounts.
See https://dev.algorand.co/reference/rest-apis/algod/#account for response data schema details.
- Parameters:
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)
- 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.
- Parameters:
mnemonic – The mnemonic secret representing the private key of an account
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 ...")
- 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).
- Parameters:
name – The name identifier of the account
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
- 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.
- Parameters:
name – The name of the wallet to retrieve an account from
predicate – Optional filter to use to find the account
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 ... )
- logicsig(program: bytes, args: list[bytes] | None = None) algokit_utils.models.account.LogicSigAccount ¶
Tracks and returns an account that represents a logic signature.
- Parameters:
program – The bytes that make up the compiled logic signature
args – Optional (binary) arguments to pass into the logic signature
- Returns:
A logic signature account wrapper
- Example:
>>> account = account.logicsig(program, [new Uint8Array(3, ...)])
- 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.
- Parameters:
metadata – The metadata for the multisig account
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] ... )
- random() algokit_utils.models.account.SigningAccount ¶
Tracks and returns a new, random Algorand account.
- Returns:
The account
- Example:
>>> account = account_manager.random()
- 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()
- 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()
- 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.
- Parameters:
sender – The account or address to use as the sender
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...")
- 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.
- Parameters:
account – The account to rekey
rekey_to – The address or account to rekey to
signer – Optional transaction signer
note – Optional transaction note
lease – Optional transaction lease
static_fee – Optional static fee
extra_fee – Optional extra fee
max_fee – Optional max fee
validity_window – Optional validity window
first_valid_round – Optional first valid round
last_valid_round – Optional last valid round
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, ... )
- 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 https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr for details.
- Parameters:
account_to_fund – The account to fund
dispenser_account – The account to use as a dispenser funding source
min_spending_balance – The minimum balance of Algo that the account should have available to spend
min_funding_increment – Optional minimum funding increment
send_params – Parameters for the send operation, defaults to None
signer – Optional transaction signer
rekey_to – Optional rekey address
note – Optional transaction note
lease – Optional transaction lease
static_fee – Optional static fee
extra_fee – Optional extra fee
max_fee – Optional maximum fee
validity_window – Optional validity window
first_valid_round – Optional first valid round
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 ... )
- 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 https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr for details.
- Parameters:
account_to_fund – The account to fund
min_spending_balance – The minimum balance of Algo that the account should have available to spend
min_funding_increment – Optional minimum funding increment
send_params – Parameters for the send operation, defaults to None
signer – Optional transaction signer
rekey_to – Optional rekey address
note – Optional transaction note
lease – Optional transaction lease
static_fee – Optional static fee
extra_fee – Optional extra fee
max_fee – Optional maximum fee
validity_window – Optional validity window
first_valid_round – Optional first valid round
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 ... )
- 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 https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr for details.
- Parameters:
account_to_fund – The account to fund
dispenser_client – The TestNet dispenser funding client
min_spending_balance – The minimum balance of Algo that the account should have available to spend
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) ... )