@algorandfoundation/algokit-utils 2.3.3-beta.3 → 2.3.3-beta.5

package/types/account.d.ts

@@ -1,66 +1,128 @@
-import algosdk, { Account, MultisigMetadata, Transaction, TransactionSigner } from 'algosdk';
+import algosdk, { Account, Algodv2, Kmd, MultisigMetadata, TransactionSigner } from 'algosdk';
+import { AccountConfig, MultisigAccount, SigningAccount, TransactionSignerAccount } from './types/account';
+import { AlgoAmount } from './types/amount';
+import { SendTransactionFrom } from './types/transaction';
 /**
- * The account name identifier used for fund dispensing in test environments
+ * Returns an account wrapper that supports partial or full multisig signing.
+ * @param multisigParams The parameters that define the multisig account
+ * @param signingAccounts The signers that are currently present
+ * @returns A multisig account wrapper
  */
-export declare const DISPENSER_ACCOUNT = "DISPENSER";
-/** Account wrapper that supports partial or full multisig signing. */
-export declare class MultisigAccount {
-    _params: algosdk.MultisigMetadata;
-    _signingAccounts: (algosdk.Account | SigningAccount)[];
-    _addr: string;
-    _signer: TransactionSigner;
-    /** The parameters for the multisig account */
-    get params(): Readonly<algosdk.MultisigMetadata>;
-    /** The list of accounts that are present to sign */
-    get signingAccounts(): Readonly<(algosdk.Account | SigningAccount)[]>;
-    /** The address of the multisig account */
-    get addr(): Readonly<string>;
-    get signer(): TransactionSigner;
-    constructor(multisigParams: MultisigMetadata, signingAccounts: (Account | SigningAccount)[]);
-    /**
-     * Sign the given transaction
-     * @param transaction Either a transaction object or a raw, partially signed transaction
-     * @returns The transaction signed by the present signers
-     */
-    sign(transaction: Transaction | Uint8Array): Uint8Array;
-}
-/** Account wrapper that supports a rekeyed account */
-export declare class SigningAccount implements Account {
-    private _account;
-    private _signer;
-    private _sender;
-    /**
-     * Algorand address of the sender
-     */
-    get addr(): Readonly<string>;
-    /**
-     * Secret key belonging to the signer
-     */
-    get sk(): Readonly<Uint8Array>;
-    /**
-     * Transaction signer for the underlying signing account
-     */
-    get signer(): TransactionSigner;
-    /**
-     * Algorand account of the sender address and signer private key
-     */
-    get sender(): Account;
-    constructor(account: Account, sender: string | undefined);
-}
-/** A wrapper around `TransactionSigner` that also has the sender address. */
-export interface TransactionSignerAccount {
-    addr: Readonly<string>;
-    signer: TransactionSigner;
-}
-/** Config for an account config */
-export interface AccountConfig {
-    /** Mnemonic for an account */
-    accountMnemonic: string;
-    /** Address of a rekeyed account */
-    senderAddress?: string;
-    /** Account name used to retrieve config */
-    accountName: string;
-    /** @deprecated Renamed to senderAddress in 2.3.1 */
-    senderMnemonic?: string;
-}
+export declare function multisigAccount(multisigParams: MultisigMetadata, signingAccounts: (Account | SigningAccount)[]): MultisigAccount;
+/**
+ * Returns an account wrapper that supports a rekeyed account.
+ * @param signer The account, with private key loaded, that is signing
+ * @param sender The address of the rekeyed account that will act as a sender
+ * @returns The SigningAccount wrapper
+ */
+export declare function rekeyedAccount(signer: Account, sender: string): SigningAccount;
+/**
+ * Returns an account wrapper that supports a transaction signer with associated sender address.
+ * @param signer The transaction signer
+ * @param sender The address of sender account
+ * @returns The SigningAccount wrapper
+ */
+export declare function transactionSignerAccount(signer: TransactionSigner, sender: string): TransactionSignerAccount;
+/** Returns an Algorand account with secret key loaded (i.e. that can sign transactions) by taking the mnemonic secret.
+ *
+ * This is a wrapper around algosdk.mnemonicToSecretKey to provide a more friendly/obvious name.
+ *
+ * @param mnemonicSecret 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.
+ */
+export declare function mnemonicAccount(mnemonicSecret: string): Account;
+/** Returns a new, random Algorand account with secret key loaded.
+ *
+ * This is a wrapper around algosdk.generateAccount to provide a more friendly/obvious name.
+ *
+ */
+export declare function randomAccount(): Account;
+/**  @deprecated use getAccount(account: { config: AccountConfig; fundWith?: AlgoAmount }, algod: Algodv2, kmdClient?: Kmd) instead
+ *
+ * Returns an Algorand account with private key loaded by convention 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).
+ *
+ * @example Default
+ *
+ * If you have a mnemonic secret loaded into `process.env.ACCOUNT_MNEMONIC` then you can call the following to get that private key loaded into an account object:
+ * ```typescript
+ * const account = await getAccount('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 account The details of the account to get, either the name identifier (string) or an object with:
+ *   * `name`: The name identifier of the account
+ *   * `fundWith`: The 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 algod An algod client
+ * @param kmdClient An optional KMD client to use to create an account (when targeting LocalNet), if not specified then a default KMD client will be loaded from environment variables
+ * @returns The requested account with private key loaded from the environment variables or when targeting LocalNet from KMD (idempotently creating and funding the account)
+ */
+export declare function getAccount(account: {
+    name: string;
+    fundWith?: AlgoAmount;
+} | string, algod: Algodv2, kmdClient?: Kmd): Promise<Account | SigningAccount>;
+/**
+ * Returns an Algorand account with private key loaded by convention based on the given name identifier.
+ *
+ * Note: This function expects to run in a Node.js environment.
+ *
+ * @example Default
+ *
+ * If you have a mnemonic secret loaded into `process.env.ACCOUNT_MNEMONIC` then you can call the following to get that private key loaded into an account object:
+ * ```typescript
+ * const account = await getAccount({config: getAccountConfigFromEnvironment('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 account The details of the account to get, an object with:
+ *   * `config`: Account configuration. To get from environment use getAccountConfigFromEnvironment(accountName)
+ *   * `fundWith`: The 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 algod An algod client
+ * @param kmdClient An optional KMD client to use to create an account (when targeting LocalNet), if not specified then a default KMD client will be loaded from environment variables
+ * @returns The requested account with private key loaded from the environment variables or when targeting LocalNet from KMD (idempotently creating and funding the account)
+ */
+export declare function getAccount(account: {
+    config: AccountConfig;
+    fundWith?: AlgoAmount;
+}, algod: Algodv2, kmdClient?: Kmd): Promise<Account | SigningAccount>;
+/** Returns an account's address as a byte array
+ *
+ * @param account Either an account (with private key loaded) or the string address of an account
+ */
+export declare function getAccountAddressAsUint8Array(account: SendTransactionFrom | string): Uint8Array;
+/** Returns the string address of an Algorand account from a base64 encoded version of the underlying byte array of the address public key
+ *
+ * @param addressEncodedInB64 The base64 encoded version of the underlying byte array of the address public key
+ */
+export declare function getAccountAddressAsString(addressEncodedInB64: string): string;
+/** Returns an account (with private key loaded) that can act as a dispenser
+ *
+ * If running on LocalNet then it will return the default dispenser account automatically,
+ *  otherwise it will load the account mnemonic stored in process.env.DISPENSER_MNEMONIC
+ *
+ * @param algod An algod client
+ * @param kmd A KMD client, if not specified then a default KMD client will be loaded from environment variables
+ */
+export declare function getDispenserAccount(algod: Algodv2, kmd?: Kmd): Promise<algosdk.Account | SigningAccount>;
+/** Returns the Account configuration from environment variables
+ *
+ * @param accountName account name
+ *
+ * @example environment variables
+ * {accountName}_MNEMONIC
+ * {accountName}_SENDER
+ *
+ */
+export declare function getAccountConfigFromEnvironment(accountName: string): AccountConfig;
 //# sourceMappingURL=account.d.ts.map

package/types/account.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/types/account.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE5F;;GAEG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAE5C,sEAAsE;AACtE,qBAAa,eAAe;IAC1B,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAA;IACjC,gBAAgB,EAAE,CAAC,OAAO,CAAC,OAAO,GAAG,cAAc,CAAC,EAAE,CAAA;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,iBAAiB,CAAA;IAE1B,8CAA8C;IAC9C,IAAI,MAAM,IAAI,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAE/C;IAED,oDAAoD;IACpD,IAAI,eAAe,IAAI,QAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,GAAG,cAAc,CAAC,EAAE,CAAC,CAEpE;IAED,0CAA0C;IAC1C,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,CAE3B;IAED,IAAI,MAAM,IAAI,iBAAiB,CAE9B;gBAEW,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC,OAAO,GAAG,cAAc,CAAC,EAAE;IAU3F;;;;OAIG;IACI,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU;CAY/D;AAED,sDAAsD;AACtD,qBAAa,cAAe,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,OAAO,CAAQ;IAEvB;;OAEG;IACH,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,CAE3B;IAED;;OAEG;IACH,IAAI,EAAE,IAAI,QAAQ,CAAC,UAAU,CAAC,CAE7B;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAKpB;gBAEW,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS;CAKzD;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACtB,MAAM,EAAE,iBAAiB,CAAA;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAA;IACvB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IAEnB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB"}
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAK7F,OAAO,EAAE,aAAa,EAAqB,eAAe,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAC7H,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC,OAAO,GAAG,cAAc,CAAC,EAAE,mBAE9G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAE7D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAE5G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAGvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,MAAM,EACzD,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,GAAG,GACd,OAAO,CAAC,OAAO,GAAG,cAAc,CAAC,CAAA;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,EACzD,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,GAAG,GACd,OAAO,CAAC,OAAO,GAAG,cAAc,CAAC,CAAA;AA6EpC;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,cAElF;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,6CAIlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAUlF"}

package/types/amount.d.ts

@@ -1,24 +1,20 @@
-/** Wrapper class to ensure safe, explicit conversion between µAlgos, Algos and numbers */
-export declare class AlgoAmount {
-    private amountInMicroAlgos;
-    /** Return the amount as a number in µAlgos */
-    get microAlgos(): number;
-    /** Return the amount as a number in Algos */
-    get algos(): number;
-    constructor(amount: {
-        algos: number;
-    } | {
-        microAlgos: number;
-    });
-    toString(): string;
-    /** valueOf allows you to use `AlgoAmount` in comparison operations such as `<` and `>=` etc.,
-     * but it's not recommended to use this to convert to a number, it's much safer to explicitly call
-     * the algos or microAlgos properties
-     */
-    valueOf(): number;
-    /** Create a `AlgoAmount` object representing the given number of Algos */
-    static Algos(amount: number): AlgoAmount;
-    /** Create a `AlgoAmount` object representing the given number of µAlgos */
-    static MicroAlgos(amount: number): AlgoAmount;
+import { AlgoAmount } from './types/amount';
+declare global {
+    interface Number {
+        microAlgos(this: number): AlgoAmount;
+        algos(this: number): AlgoAmount;
+    }
 }
+/** Returns an amount of Algos using AlgoAmount
+ * @param algos The amount in Algos
+ */
+export declare const algos: (algos: number) => AlgoAmount;
+/** Returns an amount of µAlgos using AlgoAmount
+ * @param microAlgos The amount in µAlgos
+ */
+export declare const microAlgos: (microAlgos: number) => AlgoAmount;
+/** Returns an amount of µAlgos to cover standard fees for the given number of transactions using AlgoAmount
+ * @param numberOfTransactions The of standard transaction fees to return the amount of ALGOs
+ */
+export declare const transactionFees: (numberOfTransactions: number) => AlgoAmount;
 //# sourceMappingURL=amount.d.ts.map

package/types/amount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/types/amount.ts"],"names":[],"mappings":"AAEA,0FAA0F;AAC1F,qBAAa,UAAU;IACrB,OAAO,CAAC,kBAAkB,CAAA;IAE1B,8CAA8C;IAC9C,IAAI,UAAU,WAEb;IAED,6CAA6C;IAC7C,IAAI,KAAK,WAER;gBAEW,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAI9D,QAAQ,IAAI,MAAM;IAIlB;;;OAGG;IACH,OAAO,IAAI,MAAM;IAIjB,0EAA0E;IAC1E,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM;IAI3B,2EAA2E;IAC3E,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM;CAGjC"}
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/amount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;QACpC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAChC;CACF;AAUD;;GAEG;AACH,eAAO,MAAM,KAAK,UAAW,MAAM,eAElC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,eAAgB,MAAM,eAE5C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,yBAA0B,MAAM,eAE3D,CAAA"}