AccountManager

@algorandfoundation/algokit-utils / types/account-manager / AccountManager

types/account-manager.AccountManager

Creates and keeps track of signing accounts that can sign transactions for a sending address.

Table of contents

Constructors

• constructor

Properties

• _accounts
• _clientManager
• _defaultSigner
• _kmdAccountManager

Accessors

• kmd

Methods

• _getComposer
• _getEnsureFundedAmount
• dispenserFromEnvironment
• ensureFunded
• ensureFundedFromEnvironment
• ensureFundedFromTestNetDispenserApi
• fromEnvironment
• fromKmd
• fromMnemonic
• getAccount
• getInformation
• getSigner
• localNetDispenser
• logicsig
• multisig
• random
• rekeyAccount
• rekeyed
• setDefaultSigner
• setSigner
• setSignerFromAccount
• setSigners
• signerAccount

Constructors

constructor

• new AccountManager(clientManager): AccountManager

Create a new account manager.

Parameters

Name	Type	Description
clientManager	ClientManager	The ClientManager client to use for algod and kmd clients

Returns

AccountManager

Example

const accountManager = new AccountManager(clientManager);

Defined in

src/types/account-manager.ts:60

Properties

_accounts

• Private _accounts: Object = {}

Index signature

▪ [address: string]: TransactionSignerAccount

Defined in

src/types/account-manager.ts:49

---

_clientManager

• Private _clientManager: ClientManager

Defined in

src/types/account-manager.ts:47

---

_defaultSigner

• Private Optional _defaultSigner: TransactionSigner

Defined in

src/types/account-manager.ts:50

---

_kmdAccountManager

• Private _kmdAccountManager: KmdAccountManager

Defined in

src/types/account-manager.ts:48

Accessors

kmd

• get kmd(): KmdAccountManager

KMD account manager that allows you to easily get and create accounts using KMD.

Returns

KmdAccountManager

The KmdAccountManager instance.

Example

const kmdManager = accountManager.kmd;

Defined in

src/types/account-manager.ts:81

Methods

_getComposer

▸ _getComposer(getSuggestedParams?): TransactionComposer

Parameters

Name	Type
getSuggestedParams?	() => Promise<SuggestedParams>

Returns

TransactionComposer

Defined in

src/types/account-manager.ts:65

---

_getEnsureFundedAmount

▸ _getEnsureFundedAmount(sender, minSpendingBalance, minFundingIncrement?): Promise<undefined | AlgoAmount>

Parameters

Name	Type
sender	Address
minSpendingBalance	AlgoAmount
minFundingIncrement?	AlgoAmount

Returns

Promise<undefined | AlgoAmount>

Defined in

src/types/account-manager.ts:528

---

dispenserFromEnvironment

▸ dispenserFromEnvironment(): Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

Returns an account (with private key loaded) that can act as a dispenser from environment variables, or against default LocalNet if no environment variables present.

Note: requires a Node.js environment to execute.

If present, it will load the account mnemonic stored in process.env.DISPENSER_MNEMONIC and optionally process.env.DISPENSER_SENDER if it’s a rekeyed account.

Returns

Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

The account

Example

const account = await accountManager.dispenserFromEnvironment();

Defined in

src/types/account-manager.ts:441

---

ensureFunded

▸ ensureFunded(accountToFund, dispenserAccount, minSpendingBalance, options?): Promise<undefined | { confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] } & EnsureFundedResult>

Funds a given account using a dispenser account 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).

https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr

Parameters

Name	Type	Description
accountToFund	string | Address	The account to fund
dispenserAccount	string | Address	The account to use as a dispenser funding source
minSpendingBalance	AlgoAmount	The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
options?	{ minFundingIncrement?: AlgoAmount } & SendParams & Omit<CommonTransactionParams, "sender">	Optional parameters to control the funding increment, transaction or execution of the transaction

Returns

Promise<undefined | { confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] } & EnsureFundedResult>

• The result of executing the dispensing transaction and the amountFunded if funds were needed.
• undefined if no funds were needed.

Example

// Basic example
await accountManager.ensureFunded('ACCOUNTADDRESS', 'DISPENSERADDRESS', algokit.algo(1));
// With configuration
await accountManager.ensureFunded('ACCOUNTADDRESS', 'DISPENSERADDRESS', algokit.algo(1), {
  minFundingIncrement: algokit.algo(2),
  fee: (1000).microAlgo(),
  suppressLog: true,
});

Defined in

src/types/account-manager.ts:561

---

ensureFundedFromEnvironment

▸ ensureFundedFromEnvironment(accountToFund, minSpendingBalance, options?): Promise<undefined | { confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] } & EnsureFundedResult>

Funds a given account using a dispenser account retrieved from the environment, per the dispenserFromEnvironment 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).

Note: requires a Node.js environment to execute.

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.

https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr

Parameters

Name	Type	Description
accountToFund	string | Address	The account to fund
minSpendingBalance	AlgoAmount	The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
options?	{ minFundingIncrement?: AlgoAmount } & SendParams & Omit<CommonTransactionParams, "sender">	Optional parameters to control the funding increment, transaction or execution of the transaction

Returns

Promise<undefined | { confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] } & EnsureFundedResult>

• The result of executing the dispensing transaction and the amountFunded if funds were needed.
• undefined if no funds were needed.

Example

// Basic example
await accountManager.ensureFundedFromEnvironment('ACCOUNTADDRESS', algokit.algo(1));
// With configuration
await accountManager.ensureFundedFromEnvironment('ACCOUNTADDRESS', algokit.algo(1), {
  minFundingIncrement: algokit.algo(2),
  fee: (1000).microAlgo(),
  suppressLog: true,
});

Defined in

src/types/account-manager.ts:623

---

ensureFundedFromTestNetDispenserApi

▸ ensureFundedFromTestNetDispenserApi(accountToFund, dispenserClient, minSpendingBalance, options?): Promise<undefined | EnsureFundedResult>

Funds a given account using 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).

https://dev.algorand.co/concepts/smart-contracts/costs-constraints#mbr

Parameters

Name	Type	Description
accountToFund	string | Address	The account to fund
dispenserClient	TestNetDispenserApiClient	The TestNet dispenser funding client
minSpendingBalance	AlgoAmount	The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
options?	Object	Optional parameters to control the funding increment, transaction or execution of the transaction
options.minFundingIncrement?	AlgoAmount	-

Returns

Promise<undefined | EnsureFundedResult>

• The result of executing the dispensing transaction and the amountFunded if funds were needed.
• undefined if no funds were needed.

Example

// Basic example
await accountManager.ensureFundedFromTestNetDispenserApi(
  'ACCOUNTADDRESS',
  algorand.client.getTestNetDispenserFromEnvironment(),
  algokit.algo(1),
);
// With configuration
await accountManager.ensureFundedFromTestNetDispenserApi(
  'ACCOUNTADDRESS',
  algorand.client.getTestNetDispenserFromEnvironment(),
  algokit.algo(1),
  { minFundingIncrement: algokit.algo(2) },
);

Defined in

src/types/account-manager.ts:679

---

fromEnvironment

▸ fromEnvironment(name, fundWith?): Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

Tracks and returns an Algorand account with private key loaded by convention from environment variables based on the given name identifier.

Note: This function expects to run in a Node.js environment.

Convention:

• Non-LocalNet: will load process.env[‘{NAME}_MNEMONIC’] as a mnemonic secret; Note: Be careful how the mnemonic is handled, never commit it into source control and ideally load it via a secret storage service rather than the file system. If process.env[‘{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

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	Type	Description
name	string	The name identifier of the account
fundWith?	AlgoAmount	The optional amount to fund the account with when it gets created (when targeting LocalNet), if not specified then 1000 ALGO will be funded from the dispenser account

Returns

Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

The account

Example

If you have a mnemonic secret loaded into process.env.MY_ACCOUNT_MNEMONIC then you can call the following to get that private key loaded into an account object:

const account = await accountManager.fromEnvironment('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 1000 (default) ALGO from the default LocalNet dispenser. If not running against LocalNet then it will use proces.env.MY_ACCOUNT_MNEMONIC as the private key and (if present) process.env.MY_ACCOUNT_SENDER as the sender address.

Defined in

src/types/account-manager.ts:334

---

fromKmd

▸ fromKmd(name, predicate?, sender?): Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

Tracks and returns an Algorand account with private key loaded from the given KMD wallet (identified by name).

Parameters

Name	Type	Description
name	string	The name of the wallet to retrieve an account from
predicate?	(account: Record<string, any>) => boolean	An optional filter to use to find the account (otherwise it will return a random account from the wallet)
sender?	string | Address	The optional sender address to use this signer for (aka a rekeyed account)

Returns

Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

The account

Example

const defaultDispenserAccount = await accountManager.fromKmd(
  'unencrypted-default-wallet',
  a => a.status !== 'Offline' && a.amount > 1_000_000_000,
);

Defined in

src/types/account-manager.ts:370

---

fromMnemonic

▸ fromMnemonic(mnemonicSecret, sender?): Address & TransactionSignerAccount & { account: SigningAccount }

Tracks and returns an Algorand account with secret key loaded (i.e. that can sign transactions) by taking the mnemonic secret.

Parameters

Name	Type	Description
mnemonicSecret	string	The mnemonic secret representing the private key of an account; Note: 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.
sender?	string | Address	The optional sender address to use this signer for (aka a rekeyed account)

Returns

Address & TransactionSignerAccount & { account: SigningAccount }

The account

Example

const account = accountManager.fromMnemonic('mnemonic secret ...');
const rekeyedAccount = accountManager.fromMnemonic('mnemonic secret ...', 'SENDERADDRESS...');

Defined in

src/types/account-manager.ts:286

---

getAccount

▸ getAccount(sender): TransactionSignerAccount

Returns the TransactionSignerAccount for the given sender address.

If no signer has been registered for that address then an error is thrown.

Parameters

Name	Type	Description
sender	string | Address	The sender address

Returns

TransactionSignerAccount

The TransactionSignerAccount or throws an error if not found

Example

const sender = accountManager.random();
// ...
// Returns the `TransactionSignerAccount` for `sender` that has previously been registered
const account = accountManager.getAccount(sender);

Defined in

src/types/account-manager.ts:222

---

getInformation

▸ getInformation(sender): Promise<AccountInformation>

Returns the given sender account’s current status, balance and spendable amounts.

Response data schema details

Parameters

Name	Type	Description
sender	string | Address	The account / address to look up

Returns

Promise<AccountInformation>

The account information

Example

const address = 'XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA';
const accountInfo = await accountManager.getInformation(address);

Defined in

src/types/account-manager.ts:241

---

getSigner

▸ getSigner(sender): TransactionSigner

Returns the TransactionSigner for the given sender address, ready to sign a transaction for that sender.

If no signer has been registered for that address then the default signer is used if registered and if not then an error is thrown.

Parameters

Name	Type	Description
sender	string | Address	The sender address

Returns

TransactionSigner

The TransactionSigner or throws an error if not found and no default signer is set

Example

const signer = accountManager.getSigner('SENDERADDRESS');

Defined in

src/types/account-manager.ts:202

---

localNetDispenser

▸ localNetDispenser(): Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

Returns an Algorand account with private key loaded for the default LocalNet dispenser account (that can be used to fund other accounts).

Returns

Promise<Address & TransactionSignerAccount & { account: SigningAccount }>

The account

Example

const account = await accountManager.localNetDispenser();

Defined in

src/types/account-manager.ts:460

---

logicsig

▸ logicsig(program, args?): Address & TransactionSignerAccount & { account: LogicSigAccount }

Tracks and returns an account that represents a logic signature.

Parameters

Name	Type	Description
program	Uint8Array	The bytes that make up the compiled logic signature
args?	Uint8Array[]	The (binary) arguments to pass into the logic signature

Returns

Address & TransactionSignerAccount & { account: LogicSigAccount }

A logic signature account wrapper

Example

const account = accountManager.logicsig(program, [new Uint8Array(3, ...)])

Defined in

src/types/account-manager.ts:408

---

multisig

▸ multisig(multisigParams, signingAccounts): Address & TransactionSignerAccount & { account: MultisigAccount }

Tracks and returns an account that supports partial or full multisig signing.

Parameters

Name	Type	Description
multisigParams	MultisigMetadata	The parameters that define the multisig account
signingAccounts	(default | SigningAccount)[]	The signers that are currently present

Returns

Address & TransactionSignerAccount & { account: MultisigAccount }

A multisig account wrapper

Example

const account = accountManager.multisig(
  { version: 1, threshold: 1, addrs: ['ADDRESS1...', 'ADDRESS2...'] },
  [(await accountManager.fromEnvironment('ACCOUNT1')).account],
);

Defined in

src/types/account-manager.ts:393

---

random

▸ random(): Address & TransactionSignerAccount & { account: default }

Tracks and returns a new, random Algorand account with secret key loaded.

Returns

Address & TransactionSignerAccount & { account: default }

The account

Example

const account = accountManager.random();

Defined in

src/types/account-manager.ts:421

---

rekeyAccount

▸ rekeyAccount(account, rekeyTo, options?): Promise<{ confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] }>

Rekey an account to a new address.

Note: Please be careful with this function and be sure to read the official rekey guidance.

Parameters

Name	Type	Description
account	string | Address	The account to rekey
rekeyTo	string | Address | TransactionSignerAccount	The account address or signing account of the account that will be used to authorise transactions for the rekeyed account going forward. If a signing account is provided that will now be tracked as the signer for account in this AccountManager
options?	Omit<CommonTransactionParams, "sender"> & SendParams	Any parameters to control the transaction or execution of the transaction

Returns

Promise<{ confirmation: PendingTransactionResponse ; confirmations: PendingTransactionResponse[] ; groupId: string ; returns?: ABIReturn[] ; transaction: Transaction ; transactions: Transaction[] ; txIds: string[] }>

The result of the transaction and the transaction that was sent

Example

await accountManager.rekeyAccount({ account: 'ACCOUNTADDRESS', rekeyTo: 'NEWADDRESS' });

Example

await accountManager.rekeyAccount({ account: account1, rekeyTo: newSignerAccount });

Example

await accountManager.rekeyAccount({
  account: 'ACCOUNTADDRESS',
  rekeyTo: 'NEWADDRESS',
  lease: 'lease',
  note: 'note',
  firstValidRound: 1000n,
  validityWindow: 10,
  extraFee: (1000).microAlgo(),
  staticFee: (1000).microAlgo(),
  // Max fee doesn't make sense with extraFee AND staticFee
  //  already specified, but here for completeness
  maxFee: (3000).microAlgo(),
  maxRoundsToWaitForConfirmation: 5,
  suppressLog: true,
});

Defined in

src/types/account-manager.ts:503

---

rekeyed

▸ rekeyed(sender, account): Address & TransactionSignerAccount & { account: { addr: Address ; signer: TransactionSigner = account.signer } }

Tracks and returns an Algorand account that is a rekeyed version of the given account to a new sender.

Parameters

Name	Type	Description
sender	string | Address	The sender address to use as the new sender
account	TransactionSignerAccount	The account to use as the signer for this new rekeyed account

Returns

Address & TransactionSignerAccount & { account: { addr: Address ; signer: TransactionSigner = account.signer } }

The account

Example

const account = accountManager.fromMnemonic('mnemonic secret ...');
const rekeyedAccount = accountManager.rekeyed(account, 'SENDERADDRESS...');

Defined in

src/types/account-manager.ts:303

---

setDefaultSigner

▸ setDefaultSigner(signer): AccountManager

Sets the default signer to use if no other signer is specified.

If this isn’t set an a transaction needs signing for a given sender then an error will be thrown from getSigner / getAccount.

Parameters

Name	Type	Description
signer	TransactionSigner | TransactionSignerAccount	The signer to use, either a TransactionSigner or a TransactionSignerAccount

Returns

AccountManager

The AccountManager so method calls can be chained

Example

const signer = accountManager.random(); // Can be anything that returns a `algosdk.TransactionSigner` or `TransactionSignerAccount`
accountManager.setDefaultSigner(signer);

// When signing a transaction, if there is no signer registered for the sender then the default signer will be used
const signer = accountManager.getSigner('SENDERADDRESS');

Defined in

src/types/account-manager.ts:101

---

setSigner

▸ setSigner(sender, signer): AccountManager

Tracks the given algosdk.TransactionSigner against the given sender address for later signing.

Parameters

Name	Type	Description
sender	string | Address	The sender address to use this signer for
signer	TransactionSigner	The algosdk.TransactionSigner to sign transactions with for the given sender

Returns

AccountManager

The AccountManager instance for method chaining

Example

const accountManager = new AccountManager(clientManager).setSigner(
  'SENDERADDRESS',
  transactionSigner,
);

Defined in

src/types/account-manager.ts:165

---

setSignerFromAccount

▸ setSignerFromAccount(account): AccountManager

Tracks the given account for later signing.

Note: If you are generating accounts via the various methods on AccountManager (like random, fromMnemonic, logicsig, etc.) then they automatically get tracked.

Parameters

Name	Type	Description
account	MultisigAccount | default | SigningAccount | TransactionSignerAccount | LogicSigAccount	The account to register, which can be a TransactionSignerAccount or a algosdk.Account, algosdk.LogicSigAccount, SigningAccount or MultisigAccount

Returns

AccountManager

The AccountManager instance for method chaining

Example

const accountManager = new AccountManager(clientManager)
  .setSignerFromAccount(algosdk.generateAccount())
  .setSignerFromAccount(new algosdk.LogicSigAccount(program, args))
  .setSignerFromAccount(new SigningAccount(mnemonic, sender))
  .setSignerFromAccount(
    new MultisigAccount({ version: 1, threshold: 1, addrs: ['ADDRESS1...', 'ADDRESS2...'] }, [
      account1,
      account2,
    ]),
  )
  .setSignerFromAccount({ addr: 'SENDERADDRESS', signer: transactionSigner });

Defined in

src/types/account-manager.ts:149

---

setSigners

▸ setSigners(anotherAccountManager, overwriteExisting?): AccountManager

Takes all registered signers from the given AccountManager and adds them to this AccountManager.

This is useful for situations where you have multiple contexts you are building accounts in such as unit tests.

Parameters

Name	Type	Default value	Description
anotherAccountManager	AccountManager	undefined	Another account manager with signers registered
overwriteExisting	boolean	true	Whether or not to overwrite any signers that have the same sender address with the ones in the other account manager or not (default: true)

Returns

AccountManager

The AccountManager instance for method chaining

Example

accountManager2.setSigners(accountManager1);

Defined in

src/types/account-manager.ts:182

---

signerAccount

▸ signerAccount<T>(account): Address & TransactionSignerAccount & { account: T }

Records the given account (that can sign) against the address of the provided account for later retrieval and returns a TransactionSignerAccount along with the original account in an account property.

Type parameters

Name	Type
T	extends MultisigAccount | default | SigningAccount | TransactionSignerAccount | LogicSigAccount

Parameters

Name	Type
account	T

Returns

Address & TransactionSignerAccount & { account: T }

Defined in

src/types/account-manager.ts:111