@algorandfoundation/algokit-utils 6.2.1 → 7.0.0-alpha.1

package/types/account-manager.d.ts

@@ -1,10 +1,20 @@
-import algosdk from 'algosdk';
+import algosdk, { Address } from 'algosdk';
 import { AccountInformation, MultisigAccount, SigningAccount, TransactionSignerAccount } from './account';
 import { AlgoAmount } from './amount';
 import { ClientManager } from './client-manager';
+import { CommonTransactionParams } from './composer';
+import { TestNetDispenserApiClient } from './dispenser-client';
 import { KmdAccountManager } from './kmd-account-manager';
+import { SendParams, SendSingleTransactionResult } from './transaction';
 import LogicSigAccount = algosdk.LogicSigAccount;
 import Account = algosdk.Account;
+/** Result from performing an ensureFunded call. */
+export interface EnsureFundedResult {
+    /** The transaction ID of the transaction that funded the account. */
+    transactionId: string;
+    /** The amount that was sent to the account. */
+    amountFunded: AlgoAmount;
+}
 /**
  * Returns a `TransactionSigner` for the given account that can sign a transaction.
  * This function has memoization, so will return the same transaction signer for a given account.
@@ -27,6 +37,7 @@ export declare class AccountManager {
      * ```
      */
     constructor(clientManager: ClientManager);
+    private _getComposer;
     /** KMD account manager that allows you to easily get and create accounts using KMD. */
     get kmd(): KmdAccountManager;
     /**
@@ -81,7 +92,16 @@ export declare class AccountManager {
      * ```
      * @returns The `AccountManager` instance for method chaining
      */
-    setSigner(sender: string, signer: algosdk.TransactionSigner): this;
+    setSigner(sender: string | Address, signer: algosdk.TransactionSigner): this;
+    /**
+     * 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.
+     * @param anotherAccountManager Another account manager with signers registered
+     * @param overwriteExisting 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 The `AccountManager` instance for method chaining
+     */
+    setSigners(anotherAccountManager: AccountManager, overwriteExisting?: boolean): void;
     /**
      * Returns the `TransactionSigner` for the given sender address, ready to sign a transaction for that sender.
      *
@@ -95,7 +115,7 @@ export declare class AccountManager {
      * ```
      * @returns The `TransactionSigner` or throws an error if not found and no default signer is set
      */
-    getSigner(sender: string): algosdk.TransactionSigner;
+    getSigner(sender: string | Address): algosdk.TransactionSigner;
     /**
      * Returns the `TransactionSignerAccount` for the given sender address.
      *
@@ -103,14 +123,14 @@ export declare class AccountManager {
      * @param sender The sender address
      * @example
      * ```typescript
-     * const sender = accountManager.random().addr
+     * const sender = accountManager.random()
      * // ...
      * // Returns the `TransactionSignerAccount` for `sender` that has previously been registered
      * const account = accountManager.getAccount(sender)
      * ```
      * @returns The `TransactionSignerAccount` or throws an error if not found
      */
-    getAccount(sender: string): TransactionSignerAccount;
+    getAccount(sender: string | Address): TransactionSignerAccount;
     /**
      * Returns the given sender account's current status, balance and spendable amounts.
      *
@@ -124,28 +144,7 @@ export declare class AccountManager {
      * @param sender The account / address to look up
      * @returns The account information
      */
-    getInformation(sender: string | TransactionSignerAccount): Promise<AccountInformation>;
-    /**
-     * Returns the given sender account's asset holding for a given asset.
-     *
-     * @example
-     * ```typescript
-     * const address = "XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA";
-     * const assetId = 123345;
-     * const accountInfo = await accountManager.getAssetInformation(address, assetId);
-     * ```
-     *
-     * [Response data schema details](https://developer.algorand.org/docs/rest-apis/algod/#get-v2accountsaddressassetsasset-id)
-     * @param sender The address of the sender/account to look up
-     * @param assetId The ID of the asset to return a holding for
-     * @returns The account asset holding information
-     */
-    getAssetInformation(sender: string | TransactionSignerAccount, assetId: number | bigint): Promise<{
-        assetId: bigint;
-        balance: bigint;
-        frozen: boolean;
-        round: bigint;
-    }>;
+    getInformation(sender: string | Address): Promise<AccountInformation>;
     /**
      * Tracks and returns an Algorand account with secret key loaded (i.e. that can sign transactions) by taking the mnemonic secret.
      *
@@ -159,7 +158,7 @@ export declare class AccountManager {
      * @param sender The optional sender address to use this signer for (aka a rekeyed account)
      * @returns The account
      */
-    fromMnemonic(mnemonicSecret: string, sender?: string): TransactionSignerAccount & {
+    fromMnemonic(mnemonicSecret: string, sender?: string | Address): algosdk.Address & TransactionSignerAccount & {
         account: SigningAccount;
     };
     /**
@@ -174,9 +173,9 @@ export declare class AccountManager {
      * @param sender The sender address to use as the new sender
      * @returns The account
      */
-    rekeyed(account: TransactionSignerAccount, sender: string): TransactionSignerAccount & {
+    rekeyed(sender: string | Address, account: TransactionSignerAccount): algosdk.Address & TransactionSignerAccount & {
         account: {
-            addr: string;
+            addr: algosdk.Address;
             signer: algosdk.TransactionSigner;
         };
     };
@@ -200,14 +199,14 @@ export declare class AccountManager {
      * 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) ALGOs from the default LocalNet dispenser.
+     * 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.
      *
      * @param name The name identifier of the account
-     * @param fundWith The optional amount to fund the account with when it gets created (when targeting LocalNet), if not specified then 1000 Algos will be funded from the dispenser account
+     * @param fundWith 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 The account
      */
-    fromEnvironment(name: string, fundWith?: AlgoAmount): Promise<TransactionSignerAccount & {
+    fromEnvironment(name: string, fundWith?: AlgoAmount): Promise<algosdk.Address & TransactionSignerAccount & {
         account: SigningAccount;
     }>;
     /**
@@ -225,7 +224,7 @@ export declare class AccountManager {
      * ```
      * @returns The account
      */
-    fromKmd(name: string, predicate?: (account: Record<string, any>) => boolean, sender?: string): Promise<TransactionSignerAccount & {
+    fromKmd(name: string, predicate?: (account: Record<string, any>) => boolean, sender?: string | Address): Promise<algosdk.Address & TransactionSignerAccount & {
         account: SigningAccount;
     }>;
     /**
@@ -240,7 +239,7 @@ export declare class AccountManager {
      * @param signingAccounts The signers that are currently present
      * @returns A multisig account wrapper
      */
-    multisig(multisigParams: algosdk.MultisigMetadata, signingAccounts: (algosdk.Account | SigningAccount)[]): TransactionSignerAccount & {
+    multisig(multisigParams: algosdk.MultisigMetadata, signingAccounts: (algosdk.Account | SigningAccount)[]): algosdk.Address & TransactionSignerAccount & {
         account: MultisigAccount;
     };
     /**
@@ -254,7 +253,7 @@ export declare class AccountManager {
      * @param args The (binary) arguments to pass into the logic signature
      * @returns A logic signature account wrapper
      */
-    logicsig(program: Uint8Array, args?: Array<Uint8Array>): TransactionSignerAccount & {
+    logicsig(program: Uint8Array, args?: Array<Uint8Array>): algosdk.Address & TransactionSignerAccount & {
         account: algosdk.LogicSigAccount;
     };
     /**
@@ -266,7 +265,7 @@ export declare class AccountManager {
      * ```
      * @returns The account
      */
-    random(): TransactionSignerAccount & {
+    random(): algosdk.Address & TransactionSignerAccount & {
         account: algosdk.Account;
     };
     /**
@@ -285,7 +284,7 @@ export declare class AccountManager {
      *
      * @returns The account
      */
-    dispenserFromEnvironment(): Promise<TransactionSignerAccount & {
+    dispenserFromEnvironment(): Promise<algosdk.Address & TransactionSignerAccount & {
         account: SigningAccount;
     }>;
     /**
@@ -297,8 +296,134 @@ export declare class AccountManager {
      * ```
      * @returns The account
      */
-    localNetDispenser(): Promise<TransactionSignerAccount & {
+    localNetDispenser(): Promise<algosdk.Address & TransactionSignerAccount & {
         account: SigningAccount;
     }>;
+    /**
+     * Rekey an account to a new address.
+     *
+     * **Note:** Please be careful with this function and be sure to read the [official rekey guidance](https://developer.algorand.org/docs/get-details/accounts/rekey/).
+     *
+     * @param account The account to rekey
+     * @param rekeyTo 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`
+     * @param options Any parameters to control the transaction or execution of the transaction
+     *
+     * @example Basic example (with string addresses)
+     * ```typescript
+     * await algorand.account.rekeyAccount({account: "ACCOUNTADDRESS", rekeyTo: "NEWADDRESS"})
+     * ```
+     * @example Basic example (with signer accounts)
+     * ```typescript
+     * await algorand.account.rekeyAccount({account: account1, rekeyTo: newSignerAccount})
+     * ```
+     * @example Advanced example
+     * ```typescript
+     * await algorand.account.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,
+     * })
+     * ```
+     * @returns The result of the transaction and the transaction that was sent
+     */
+    rekeyAccount(account: string | Address, rekeyTo: string | Address | TransactionSignerAccount, options?: Omit<CommonTransactionParams, 'sender'> & SendParams): Promise<SendSingleTransactionResult>;
+    private _getEnsureFundedAmount;
+    /**
+     * 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://developer.algorand.org/docs/get-details/accounts/#minimum-balance
+     *
+     * @param accountToFund The account to fund
+     * @param dispenserAccount The account to use as a dispenser funding source
+     * @param minSpendingBalance The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
+     * @param options Optional parameters to control the funding increment, transaction or execution of the transaction
+     * @example Example using AlgorandClient
+     * ```typescript
+     * // Basic example
+     * await algorand.account.ensureFunded("ACCOUNTADDRESS", "DISPENSERADDRESS", algokit.algo(1))
+     * // With configuration
+     * await algorand.account.ensureFunded("ACCOUNTADDRESS", "DISPENSERADDRESS", algokit.algo(1),
+     *  { minFundingIncrement: algokit.algo(2), fee: (1000).microAlgo(), suppressLog: true }
+     * )
+     * ```
+     * @returns
+     * - The result of executing the dispensing transaction and the `amountFunded` if funds were needed.
+     * - `undefined` if no funds were needed.
+     */
+    ensureFunded(accountToFund: string | Address, dispenserAccount: string | Address, minSpendingBalance: AlgoAmount, options?: {
+        minFundingIncrement?: AlgoAmount;
+    } & SendParams & Omit<CommonTransactionParams, 'sender'>): Promise<(SendSingleTransactionResult & EnsureFundedResult) | undefined>;
+    /**
+     * 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://developer.algorand.org/docs/get-details/accounts/#minimum-balance
+     *
+     * @param accountToFund The account to fund
+     * @param minSpendingBalance The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
+     * @param options Optional parameters to control the funding increment, transaction or execution of the transaction
+     * @example Example using AlgorandClient
+     * ```typescript
+     * // Basic example
+     * await algorand.account.ensureFundedFromEnvironment("ACCOUNTADDRESS", algokit.algo(1))
+     * // With configuration
+     * await algorand.account.ensureFundedFromEnvironment("ACCOUNTADDRESS", algokit.algo(1),
+     *  { minFundingIncrement: algokit.algo(2), fee: (1000).microAlgo(), suppressLog: true }
+     * )
+     * ```
+     * @returns
+     * - The result of executing the dispensing transaction and the `amountFunded` if funds were needed.
+     * - `undefined` if no funds were needed.
+     */
+    ensureFundedFromEnvironment(accountToFund: string | Address, minSpendingBalance: AlgoAmount, options?: {
+        minFundingIncrement?: AlgoAmount;
+    } & SendParams & Omit<CommonTransactionParams, 'sender'>): Promise<(SendSingleTransactionResult & EnsureFundedResult) | undefined>;
+    /**
+     * 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://developer.algorand.org/docs/get-details/accounts/#minimum-balance
+     *
+     * @param accountToFund The account to fund
+     * @param dispenserClient The TestNet dispenser funding client
+     * @param minSpendingBalance The minimum balance of Algo that the account should have available to spend (i.e. on top of minimum balance requirement)
+     * @param options Optional parameters to control the funding increment, transaction or execution of the transaction
+     * @example Example using AlgorandClient
+     * ```typescript
+     * // Basic example
+     * await algorand.account.ensureFundedUsingDispenserAPI("ACCOUNTADDRESS", algorand.client.getTestNetDispenserFromEnvironment(), algokit.algo(1))
+     * // With configuration
+     * await algorand.account.ensureFundedUsingDispenserAPI("ACCOUNTADDRESS", algorand.client.getTestNetDispenserFromEnvironment(), algokit.algo(1),
+     *  { minFundingIncrement: algokit.algo(2) }
+     * )
+     * ```
+     * @returns
+     * - The result of executing the dispensing transaction and the `amountFunded` if funds were needed.
+     * - `undefined` if no funds were needed.
+     */
+    ensureFundedFromTestNetDispenserApi(accountToFund: string | Address, dispenserClient: TestNetDispenserApiClient, minSpendingBalance: AlgoAmount, options?: {
+        minFundingIncrement?: AlgoAmount;
+    }): Promise<EnsureFundedResult | undefined>;
 }
-//# sourceMappingURL=account-manager.d.ts.map