@algorandfoundation/algokit-utils 1.0.0-beta.12 → 1.0.0-beta.13

package/package.json

@@ -2,7 +2,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "name": "@algorandfoundation/algokit-utils",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "private": false,
   "description": "A set of core Algorand utilities written in TypeScript and released via npm that make it easier to build solutions on Algorand.",
   "author": "Algorand Foundation",

package/transfer.d.ts

@@ -1,6 +1,6 @@
 import { Algodv2 } from 'algosdk';
 import { SendTransactionResult } from './types/transaction';
-import { AlgoTransferParams } from './types/transfer';
+import { AlgoTransferParams, EnsureFundedParams } from './types/transfer';
 /**
  * Transfer ALGOs between two accounts.
  * @param transfer The transfer definition
@@ -8,4 +8,14 @@ import { AlgoTransferParams } from './types/transfer';
  * @returns The transaction object and optionally the confirmation if it was sent to the chain (`skipSending` is `false` or unset)
  */
 export declare function transferAlgos(transfer: AlgoTransferParams, algod: Algodv2): Promise<SendTransactionResult>;
+/**
+ * Funds a given account using a funding source such that it has a certain amount of algos free to spend (accounting for ALGOs locked in minimum balance requirement).
+ *
+ * @see https://developer.algorand.org/docs/get-details/accounts/#minimum-balance
+ *
+ * @param funding The funding configuration
+ * @param client An algod client
+ * @returns undefined if nothing was needed or the transaction send result
+ */
+export declare function ensureFunded(funding: EnsureFundedParams, client: Algodv2): Promise<SendTransactionResult | undefined>;
 //# sourceMappingURL=transfer.d.ts.map

package/transfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAG1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkBhH"}
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAG1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAEzE;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkBhH;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAgC3H"}

package/transfer.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transferAlgos = void 0;
+exports.ensureFunded = exports.transferAlgos = void 0;
 const algosdk_1 = __importDefault(require("algosdk"));
 const _1 = require("./");
 const transaction_1 = require("./transaction");
@@ -30,4 +30,36 @@ async function transferAlgos(transfer, algod) {
     return (0, transaction_1.sendTransaction)({ transaction, from, sendParams }, algod);
 }
 exports.transferAlgos = transferAlgos;
+/**
+ * Funds a given account using a funding source such that it has a certain amount of algos free to spend (accounting for ALGOs locked in minimum balance requirement).
+ *
+ * @see https://developer.algorand.org/docs/get-details/accounts/#minimum-balance
+ *
+ * @param funding The funding configuration
+ * @param client An algod client
+ * @returns undefined if nothing was needed or the transaction send result
+ */
+async function ensureFunded(funding, client) {
+    const { accountToFund, fundingSource, minSpendingBalance, minFundingIncrement, transactionParams, note, ...sendParams } = funding;
+    const addressToFund = typeof accountToFund === 'string' ? accountToFund : (0, transaction_1.getSenderAddress)(accountToFund);
+    const accountInfo = await client.accountInformation(addressToFund).do();
+    const balance = Number(accountInfo.amount);
+    const minimumBalanceRequirement = (0, _1.microAlgos)(Number(accountInfo['min-balance']));
+    const currentSpendingBalance = (0, _1.microAlgos)(balance - +minimumBalanceRequirement);
+    if (minSpendingBalance > currentSpendingBalance) {
+        const minFundAmount = (0, _1.microAlgos)(+minSpendingBalance - +currentSpendingBalance);
+        const fundAmount = (0, _1.microAlgos)(Math.max(+minFundAmount, minFundingIncrement?.microAlgos ?? 0));
+        _1.Config.logger.info(`Funding ${addressToFund} ${fundAmount} from ${(0, transaction_1.getSenderAddress)(fundingSource)} to reach minimum spend amount of ${minSpendingBalance} (balance = ${balance}, min_balance_req = ${minimumBalanceRequirement})`);
+        return await transferAlgos({
+            from: fundingSource,
+            to: addressToFund,
+            note: note ?? 'Funding account to meet minimum requirement',
+            amount: fundAmount,
+            transactionParams,
+            ...sendParams,
+        }, client);
+    }
+    return undefined;
+}
+exports.ensureFunded = ensureFunded;
 //# sourceMappingURL=transfer.js.map

package/transfer.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer.js","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA0C;AAC1C,yBAA2B;AAC3B,+CAA8G;AAI9G;;;;;GAKG;AACI,KAAK,UAAU,aAAa,CAAC,QAA4B,EAAE,KAAc;IAC9E,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,UAAU,EAAE,GAAG,QAAQ,CAAA;IAE7E,MAAM,WAAW,GAAG,iBAAO,CAAC,2CAA2C,CAAC;QACtE,IAAI,EAAE,IAAA,8BAAgB,EAAC,IAAI,CAAC;QAC5B,EAAE,EAAE,EAAE;QACN,MAAM,EAAE,MAAM,CAAC,UAAU;QACzB,IAAI,EAAE,IAAA,mCAAqB,EAAC,IAAI,CAAC;QACjC,eAAe,EAAE,MAAM,IAAA,kCAAoB,EAAC,iBAAiB,EAAE,KAAK,CAAC;QACrE,gBAAgB,EAAE,SAAS;QAC3B,OAAO,EAAE,SAAS;KACnB,CAAC,CAAA;IAEF,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE;QAC3B,SAAM,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,gBAAgB,MAAM,CAAC,UAAU,eAAe,IAAA,8BAAgB,EAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;KAClI;IAED,OAAO,IAAA,6BAAe,EAAC,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,CAAC,CAAA;AAClE,CAAC;AAlBD,sCAkBC"}
+{"version":3,"file":"transfer.js","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA0C;AAC1C,yBAAuC;AACvC,+CAA8G;AAI9G;;;;;GAKG;AACI,KAAK,UAAU,aAAa,CAAC,QAA4B,EAAE,KAAc;IAC9E,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,UAAU,EAAE,GAAG,QAAQ,CAAA;IAE7E,MAAM,WAAW,GAAG,iBAAO,CAAC,2CAA2C,CAAC;QACtE,IAAI,EAAE,IAAA,8BAAgB,EAAC,IAAI,CAAC;QAC5B,EAAE,EAAE,EAAE;QACN,MAAM,EAAE,MAAM,CAAC,UAAU;QACzB,IAAI,EAAE,IAAA,mCAAqB,EAAC,IAAI,CAAC;QACjC,eAAe,EAAE,MAAM,IAAA,kCAAoB,EAAC,iBAAiB,EAAE,KAAK,CAAC;QACrE,gBAAgB,EAAE,SAAS;QAC3B,OAAO,EAAE,SAAS;KACnB,CAAC,CAAA;IAEF,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE;QAC3B,SAAM,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,gBAAgB,MAAM,CAAC,UAAU,eAAe,IAAA,8BAAgB,EAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;KAClI;IAED,OAAO,IAAA,6BAAe,EAAC,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,CAAC,CAAA;AAClE,CAAC;AAlBD,sCAkBC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,YAAY,CAAC,OAA2B,EAAE,MAAe;IAC7E,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAA;IAEjI,MAAM,aAAa,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAA,8BAAgB,EAAC,aAAa,CAAC,CAAA;IAEzG,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAA;IACvE,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;IAC1C,MAAM,yBAAyB,GAAG,IAAA,aAAU,EAAC,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IAChF,MAAM,sBAAsB,GAAG,IAAA,aAAU,EAAC,OAAO,GAAG,CAAC,yBAAyB,CAAC,CAAA;IAE/E,IAAI,kBAAkB,GAAG,sBAAsB,EAAE;QAC/C,MAAM,aAAa,GAAG,IAAA,aAAU,EAAC,CAAC,kBAAkB,GAAG,CAAC,sBAAsB,CAAC,CAAA;QAC/E,MAAM,UAAU,GAAG,IAAA,aAAU,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,mBAAmB,EAAE,UAAU,IAAI,CAAC,CAAC,CAAC,CAAA;QAC7F,SAAM,CAAC,MAAM,CAAC,IAAI,CAChB,WAAW,aAAa,IAAI,UAAU,SAAS,IAAA,8BAAgB,EAC7D,aAAa,CACd,qCAAqC,kBAAkB,eAAe,OAAO,uBAAuB,yBAAyB,GAAG,CAClI,CAAA;QACD,OAAO,MAAM,aAAa,CACxB;YACE,IAAI,EAAE,aAAa;YACnB,EAAE,EAAE,aAAa;YACjB,IAAI,EAAE,IAAI,IAAI,6CAA6C;YAC3D,MAAM,EAAE,UAAU;YAClB,iBAAiB;YACjB,GAAG,UAAU;SACd,EACD,MAAM,CACP,CAAA;KACF;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAhCD,oCAgCC"}

package/types/amount.d.ts

@@ -10,6 +10,8 @@ export declare class AlgoAmount {
     } | {
         microAlgos: number;
     });
+    toString(): string;
+    valueOf(): number;
     /** Create a @see {AlgoAmount} object representing the given number of Algos */
     static Algos(amount: number): AlgoAmount;
     /** Create a @see {AlgoAmount} object representing the given number of µAlgos */

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,+EAA+E;IAC/E,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM;IAI3B,gFAAgF;IAChF,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM;CAGjC"}
+{"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,OAAO,IAAI,MAAM;IAIjB,+EAA+E;IAC/E,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM;IAI3B,gFAAgF;IAChF,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM;CAGjC"}

package/types/amount.js

@@ -18,6 +18,12 @@ class AlgoAmount {
     constructor(amount) {
         this.amountInMicroAlgos = 'microAlgos' in amount ? amount.microAlgos : algosdk_1.default.algosToMicroalgos(amount.algos);
     }
+    toString() {
+        return `${this.microAlgos.toLocaleString('en-US')} µALGO${this.microAlgos === 1 ? '' : 's'}`;
+    }
+    valueOf() {
+        return this.microAlgos;
+    }
     /** Create a @see {AlgoAmount} object representing the given number of Algos */
     static Algos(amount) {
         return new AlgoAmount({ algos: amount });

package/types/amount.js.map

@@ -1 +1 @@
-{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../src/types/amount.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA6B;AAE7B,0FAA0F;AAC1F,MAAa,UAAU;IAGrB,8CAA8C;IAC9C,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,kBAAkB,CAAA;IAChC,CAAC;IAED,6CAA6C;IAC7C,IAAI,KAAK;QACP,OAAO,iBAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;IAC3D,CAAC;IAED,YAAY,MAAkD;QAC5D,IAAI,CAAC,kBAAkB,GAAG,YAAY,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAChH,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,KAAK,CAAC,MAAc;QACzB,OAAO,IAAI,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC1C,CAAC;IAED,gFAAgF;IAChF,MAAM,CAAC,UAAU,CAAC,MAAc;QAC9B,OAAO,IAAI,UAAU,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;IAC/C,CAAC;CACF;AA1BD,gCA0BC"}
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../src/types/amount.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA6B;AAE7B,0FAA0F;AAC1F,MAAa,UAAU;IAGrB,8CAA8C;IAC9C,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,kBAAkB,CAAA;IAChC,CAAC;IAED,6CAA6C;IAC7C,IAAI,KAAK;QACP,OAAO,iBAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;IAC3D,CAAC;IAED,YAAY,MAAkD;QAC5D,IAAI,CAAC,kBAAkB,GAAG,YAAY,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAChH,CAAC;IAED,QAAQ;QACN,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IAC9F,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,KAAK,CAAC,MAAc;QACzB,OAAO,IAAI,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC1C,CAAC;IAED,gFAAgF;IAChF,MAAM,CAAC,UAAU,CAAC,MAAc;QAC9B,OAAO,IAAI,UAAU,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;IAC/C,CAAC;CACF;AAlCD,gCAkCC"}

package/types/transfer.d.ts

@@ -1,6 +1,7 @@
 import { SuggestedParams } from 'algosdk';
 import { AlgoAmount } from './amount';
 import { SendTransactionFrom, SendTransactionParams, TransactionNote } from './transaction';
+/** Parameters for @see transferAlgos call. */
 export interface AlgoTransferParams extends SendTransactionParams {
     /** The account (with private key loaded) that will send the µALGOs */
     from: SendTransactionFrom;
@@ -13,4 +14,19 @@ export interface AlgoTransferParams extends SendTransactionParams {
     /** The (optional) transaction note */
     note?: TransactionNote;
 }
+/** Parameters for @see ensureFunded call. */
+export interface EnsureFundedParams extends SendTransactionParams {
+    /** The account to fund */
+    accountToFund: SendTransactionFrom | string;
+    /** The account to use as a funding source */
+    fundingSource: SendTransactionFrom;
+    /** The minimum balance of ALGOs that the account should have available to spend (i.e. on top of minimum balance requirement) */
+    minSpendingBalance: AlgoAmount;
+    /** When issuing a funding amount, the minimum amount to transfer (avoids many small transfers if this gets called often on an active account) */
+    minFundingIncrement?: AlgoAmount;
+    /** Optional transaction parameters */
+    transactionParams?: SuggestedParams;
+    /** The (optional) transaction note, default: "Funding account to meet minimum requirement" */
+    note?: TransactionNote;
+}
 //# sourceMappingURL=transfer.d.ts.map

package/types/transfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../src/types/transfer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE3F,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,sEAAsE;IACtE,IAAI,EAAE,mBAAmB,CAAA;IACzB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,yBAAyB;IACzB,MAAM,EAAE,UAAU,CAAA;IAClB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,eAAe,CAAA;IACnC,sCAAsC;IACtC,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB"}
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../src/types/transfer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE3F,8CAA8C;AAC9C,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,sEAAsE;IACtE,IAAI,EAAE,mBAAmB,CAAA;IACzB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,yBAAyB;IACzB,MAAM,EAAE,UAAU,CAAA;IAClB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,eAAe,CAAA;IACnC,sCAAsC;IACtC,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,0BAA0B;IAC1B,aAAa,EAAE,mBAAmB,GAAG,MAAM,CAAA;IAC3C,6CAA6C;IAC7C,aAAa,EAAE,mBAAmB,CAAA;IAClC,gIAAgI;IAChI,kBAAkB,EAAE,UAAU,CAAA;IAC9B,iJAAiJ;IACjJ,mBAAmB,CAAC,EAAE,UAAU,CAAA;IAChC,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,eAAe,CAAA;IACnC,8FAA8F;IAC9F,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB"}