feat: Add transferable field to /accounts/{accountId}/balance-info (#1722)

* Add transferable balance to balance-info

* Add docs

* Fix error messaging and tests

* Remove ! hack

* fix grammar

Author: TarikGul

docs/dist/app.bundle.js

@@ -4309,6 +4309,14 @@ components:
             Note, that some runtimes may not have support for frozen and if so the following 
             will be returned `frozen does not exist for this runtime`
           format: unsignedInteger
+        transferable:
+          type: string
+          description: The amount that can be transferred from this account. This is calculated using the formula
+            `free - max(maybeEd, frozen - reserve)` where `maybeEd` is the existential deposit if there are frozen
+            funds or reserves, otherwise it is zero. This represents the actual spendable balance.
+            Note, that some historical runtimes may not have support for the current formula used and if so the following
+            will be returned `transferable not supported for this runtime`.
+          format: unsignedInteger
         locks:
           type: array
           description: Array of locks on a balance. There can be many of these on

docs/src/openapi-v1.yaml

@@ -179,6 +179,7 @@ describe('AccountsBalanceInfoService', () => {
 					},
 				],
 				miscFrozen: '100000000000',
+				transferable: 'transferable formula not supported for this runtime',
 				nonce: '6',
 				reserved: '0',
 				tokenSymbol: 'DOT',

src/services/accounts/AccountsBalanceInfoService.spec.ts

@@ -90,6 +90,7 @@ export class AccountsBalanceInfoService extends AbstractService {
 					miscFrozen: 'miscFrozen does not exist for this runtime',
 					feeFrozen: 'feeFrozen does not exist for this runtime',
 					frozen: 'frozen does not exist for this runtime',
+					transferable: 'transferable formula not supported for this runtime',
 					locks: this.inDenominationLocks(denominate, locks, decimal),
 				};
 			} else {
@@ -106,11 +107,15 @@ export class AccountsBalanceInfoService extends AbstractService {
 
 			const { data, nonce } = accountInfo;
 
-			let free, reserved, feeFrozen, miscFrozen, frozen;
+			let free, reserved, feeFrozen, miscFrozen, frozen, transferable;
 			if (accountInfo.data?.frozen) {
+				const deriveData = await this.api.derive.balances.all(address);
 				free = data.free;
 				reserved = data.reserved;
 				frozen = data.frozen;
+				transferable = deriveData.transferable
+					? deriveData.transferable
+					: 'transferable formula not supported for this runtime';
 				miscFrozen = 'miscFrozen does not exist for this runtime';
 				feeFrozen = 'feeFrozen does not exist for this runtime';
 			} else {
@@ -119,6 +124,7 @@ export class AccountsBalanceInfoService extends AbstractService {
 				reserved = tmpData.reserved;
 				feeFrozen = tmpData.feeFrozen;
 				miscFrozen = tmpData.miscFrozen;
+				transferable = 'transferable formula not supported for this runtime';
 				frozen = 'frozen does not exist for this runtime';
 			}
 
@@ -138,6 +144,8 @@ export class AccountsBalanceInfoService extends AbstractService {
 						typeof miscFrozen === 'string' ? miscFrozen : this.inDenominationBal(denominate, miscFrozen, decimal),
 					feeFrozen: typeof feeFrozen === 'string' ? feeFrozen : this.inDenominationBal(denominate, feeFrozen, decimal),
 					frozen: typeof frozen === 'string' ? frozen : this.inDenominationBal(denominate, frozen, decimal),
+					transferable:
+						typeof transferable === 'string' ? transferable : this.inDenominationBal(denominate, transferable, decimal),
 					locks: this.inDenominationLocks(denominate, locks, decimal),
 				};
 			} else {
@@ -188,19 +196,24 @@ export class AccountsBalanceInfoService extends AbstractService {
 
 		if (accountData && locks && accountInfo) {
 			const { nonce } = accountInfo;
-			let free, reserved, feeFrozen, miscFrozen, frozen;
+			let free, reserved, feeFrozen, miscFrozen, frozen, transferable;
 			if ((accountData as AccountData).miscFrozen) {
 				const tmpData = accountData as AccountData;
 				free = tmpData.free;
 				reserved = tmpData.reserved;
 				feeFrozen = tmpData.feeFrozen;
 				miscFrozen = tmpData.miscFrozen;
 				frozen = 'frozen does not exist for this runtime';
+				transferable = 'transferable formula not supported for this runtime';
 			} else {
+				const deriveData = await this.api.derive.balances.all(address);
 				const tmpData = accountData as PalletBalancesAccountData;
 				free = tmpData.free;
 				reserved = tmpData.reserved;
 				frozen = tmpData.frozen;
+				transferable = deriveData.transferable
+					? deriveData.transferable
+					: 'transferable formula not supported for this runtime';
 				feeFrozen = 'feeFrozen does not exist for this runtime';
 				miscFrozen = 'miscFrozen does not exist for this runtime';
 			}
@@ -215,6 +228,8 @@ export class AccountsBalanceInfoService extends AbstractService {
 					typeof miscFrozen === 'string' ? miscFrozen : this.inDenominationBal(denominate, miscFrozen, decimal),
 				feeFrozen: typeof feeFrozen === 'string' ? feeFrozen : this.inDenominationBal(denominate, feeFrozen, decimal),
 				frozen: typeof frozen === 'string' ? frozen : this.inDenominationBal(denominate, frozen, decimal),
+				transferable:
+					typeof transferable === 'string' ? transferable : this.inDenominationBal(denominate, transferable, decimal),
 				locks: this.inDenominationLocks(denominate, locks, decimal),
 			};
 		} else {

src/services/accounts/AccountsBalanceInfoService.ts

@@ -10,6 +10,7 @@
   "miscFrozen": "100000000000",
   "feeFrozen": "100000000000",
   "frozen": "frozen does not exist for this runtime",
+  "transferable": "transferable formula not supported for this runtime",
   "locks": [
     {
       "id": "0x7374616b696e6720",

src/services/test-helpers/responses/accounts/balanceInfo789629.json

@@ -10,6 +10,7 @@
     "miscFrozen": "111111",
     "feeFrozen": "111111",
     "frozen": "frozen does not exist for this runtime",
+    "transferable": "transferable formula not supported for this runtime",
     "locks": [
         {
             "id": "0x7374616b696e6720",

src/services/test-helpers/responses/accounts/balanceInfoFeeFrozen.json

@@ -28,6 +28,15 @@ export interface IAccountBalanceInfo {
 	miscFrozen: Balance | string;
 	feeFrozen: Balance | string;
 	frozen: Balance | string;
+	/**
+	 * Calculated transferable balance. This uses the formula: free - max(maybeEd, frozen - reserve)
+	 * Where `maybeEd` means if there is no frozen and reserves it will be zero, else it will be the existential deposit.
+	 * This is only correct when the return type of `api.query.system.account` is `FrameSystemAccountInfo`.
+	 * Which is the most up to date calculation for transferable balances.
+	 *
+	 * ref: https://github.com/paritytech/polkadot-sdk/issues/1833
+	 */
+	transferable: Balance | string;
 	locks: Vec<BalanceLock> | IBalanceLock[];
 	rcBlockNumber?: string;
 	ahTimestamp?: string;