Add doc about subscribing to balance changes for several accounts (#982)

* Add doc about subscribing to balance changes for several accounts

* Fix typo

docs/METHODS_STORAGE.md

@@ -46,6 +46,9 @@ ___
 ▸ **freeBalance**(`AccountId`): `Balance`
 - **summary**:   The 'free' balance of a given account.   This is the only balance that matters in terms of most operations on tokens. It  alone is used to determine the balance when in the contract execution environment. When this  balance falls below the value of `ExistentialDeposit`, then the 'current account' is  deleted: specifically `FreeBalance`. Further, the `OnFreeBalanceZero` callback  is invoked, giving a chance to external modules to clean up data associated with  the deleted account.   `system::AccountNonce` is also deleted if `ReservedBalance` is also zero (it also gets  collapsed to zero if it ever becomes less than `ExistentialDeposit`.
 
+▸ **freeBalance.multi**(`[AccountId1, ...AccountIdn]`): `[Balance1, ...Balancen]`
+- **summary**:   You may subscribe to balance changes for multiple adddresses. This is done using the `api.query.balances.freeBalance.multi([addresses...], (balances) => {...}`
+
 ▸ **locks**(`AccountId`): `Vec<BalanceLock>`
 - **summary**:   Any liquidity locks on some account balances.
 

docs/examples/promise/03_listen_to_multiple_balances_change/README.md

@@ -0,0 +1,5 @@
+# Listen to balance changes
+
+This example shows how to instantiate a Polkadot API object and use it to connect to a node and retrieve balance updates.
+
+<<< @/docs/examples/promise/03_listen_to_balance_change/index.js

docs/examples/promise/03_listen_to_multiple_balances_change/index.js

@@ -0,0 +1,24 @@
+// @ts-check
+// Import the API
+const { ApiPromise } = require('@polkadot/api');
+
+// Known account we want to use (available on dev chain, with funds)
+const Alice = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
+const Bob = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+
+async function main () {
+  // Create an await for the API
+  const api = await ApiPromise.create();
+
+  const ALICE = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
+  const BOB = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+
+  console.log('Tracking balances for:', [ALICE, BOB])
+
+  // Subscribe and listen to several balance changes
+  api.query.balances.freeBalance.multi([ALICE, BOB], (balances) => {
+    console.log('Change detected, new balances: ', balances)
+  });
+}
+
+main().catch(console.error);

docs/examples/promise/03_listen_to_multiple_balances_change/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "03_listen_to_multiple_balances_change",
+  "version": "0.2.0",
+  "description": "Example showing how to subscribe to multiple balances change",
+  "main": "index.js",
+  "author": "chevdor",
+  "license": "MIT",
+  "scripts": {
+    "clean": "rimraf node_modules",
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@polkadot/api": "*"
+  },
+  "devDependencies": {
+    "rimraf": "^2.6.2"
+  }
+}