From c17f93a3ec260ce6ecaae5c211e75f1c9c4660c4 Mon Sep 17 00:00:00 2001 From: Jaco Greeff Date: Tue, 25 Feb 2020 17:01:41 +0100 Subject: [PATCH] Update docs for system.account (#1944) --- .../examples/promise/03_listen_to_balance_change/index.js | 4 ++-- .../03_listen_to_multiple_balances_change/index.js | 2 +- docs/examples/promise/05_read_storage/index.js | 6 +++--- docs/examples/promise/05_read_storage_at/index.js | 4 ++-- .../index.js | 2 +- docs/examples/promise/09_transfer_events/index.js | 2 +- docs/examples/rx/03_listen_to_balance_change/index.js | 4 ++-- docs/examples/rx/05_read_storage/index.js | 8 ++++---- docs/start/FAQ.md | 2 +- docs/start/api.query.md | 4 ++-- docs/start/api.query.multi.md | 4 ++-- docs/start/api.query.other.md | 2 +- docs/start/api.query.subs.md | 2 +- docs/start/typescript.md | 2 +- 14 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/examples/promise/03_listen_to_balance_change/index.js b/docs/examples/promise/03_listen_to_balance_change/index.js index d353ec19f2..2ffbbd736b 100755 --- a/docs/examples/promise/03_listen_to_balance_change/index.js +++ b/docs/examples/promise/03_listen_to_balance_change/index.js @@ -13,13 +13,13 @@ async function main () { // Retrieve the initial balance. Since the call has no callback, it is simply a promise // that resolves to the current on-chain value - let [previousNonce, { free: previousFree }] = await api.query.system.account(Alice); + let { nonce: previousNonce, data: { free: previousFree } } = await api.query.system.account(Alice); console.log(`${Alice} has a balance of ${previousFree}, nonce ${previousNonce}`); console.log(`You may leave this example running and start example 06 or transfer any value to ${Alice}`); // Here we subscribe to any balance changes and update the on-screen value - api.query.system.account(Alice, ([currentNonce, { free: currentFree }]) => { + api.query.system.account(Alice, ({ nonce: currentNonce, data: { free: currentFree } }) => { // Calculate the delta const change = currentFree.sub(previousFree); diff --git a/docs/examples/promise/03_listen_to_multiple_balances_change/index.js b/docs/examples/promise/03_listen_to_multiple_balances_change/index.js index 493d6df113..3dad6c1376 100755 --- a/docs/examples/promise/03_listen_to_multiple_balances_change/index.js +++ b/docs/examples/promise/03_listen_to_multiple_balances_change/index.js @@ -16,7 +16,7 @@ async function main () { // Subscribe and listen to several balance changes api.query.system.account.multi([ALICE, BOB], (balances) => { - console.log('Change detected, new balances: ', balances.map(([, { free }]) => free)); + console.log('Change detected, new balances: ', balances.map(({ data: { free } }) => free)); }); } diff --git a/docs/examples/promise/05_read_storage/index.js b/docs/examples/promise/05_read_storage/index.js index 2259020e91..28d30a9995 100755 --- a/docs/examples/promise/05_read_storage/index.js +++ b/docs/examples/promise/05_read_storage/index.js @@ -12,7 +12,7 @@ async function main () { const api = await ApiPromise.create(); // Make our basic chain state/storage queries, all in one go - const [[accountNonce], now, validators] = await Promise.all([ + const [{ nonce: accountNonce }, now, validators] = await Promise.all([ api.query.system.account(ALICE), api.query.timestamp.now(), api.query.session.validators() @@ -32,8 +32,8 @@ async function main () { // Print out the authorityIds and balances of all validators console.log('validators', validators.map((authorityId, index) => ({ address: authorityId.toString(), - balance: validatorBalances[index][1].free.toString(), - nonce: validatorBalances[index][0].toString() + balance: validatorBalances[index].data.free.toHuman(), + nonce: validatorBalances[index].nonce.toHuman() }))); } } diff --git a/docs/examples/promise/05_read_storage_at/index.js b/docs/examples/promise/05_read_storage_at/index.js index f15d73f297..8f2ff8bf4e 100755 --- a/docs/examples/promise/05_read_storage_at/index.js +++ b/docs/examples/promise/05_read_storage_at/index.js @@ -21,12 +21,12 @@ async function main () { // the format is always `.at(, ...params)` const balance = await api.query.system.account.at(parentHash, ALICE); - console.log(`Alice's balance at ${parentHash.toHex()} was ${balance[1].free}`); + console.log(`Alice's balance at ${parentHash.toHex()} was ${balance.data.free}`); // Now perform a multi query, returning multiple balances at once const balances = await api.query.system.account.multi([ALICE, BOB]); - console.log(`Current balances for Alice and Bob are ${balances[0][1].free} and ${balances[1][1].free}`); + console.log(`Current balances for Alice and Bob are ${balances[0].data.free} and ${balances[1].data.free}`); } main().catch(console.error).finally(() => process.exit()); diff --git a/docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/index.js b/docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/index.js index 6667f58d31..f4d97e1c70 100644 --- a/docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/index.js +++ b/docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/index.js @@ -19,7 +19,7 @@ async function main () { const alice = keyring.addFromUri('//Alice'); // Get nonce for account - const [nonce] = await api.query.system.account(alice.address); + const [{ nonce } = await api.query.system.account(alice.address); // Get current block const signedBlock = await api.rpc.chain.getBlock(); diff --git a/docs/examples/promise/09_transfer_events/index.js b/docs/examples/promise/09_transfer_events/index.js index 9baa25db59..b787af6f7f 100755 --- a/docs/examples/promise/09_transfer_events/index.js +++ b/docs/examples/promise/09_transfer_events/index.js @@ -24,7 +24,7 @@ async function main () { const keyring = testKeyring.default(); // Get the nonce for the admin key - const [nonce] = await api.query.system.account(ALICE); + const { nonce } = await api.query.system.account(ALICE); // Find the actual keypair in the keyring const alicePair = keyring.getPair(ALICE); diff --git a/docs/examples/rx/03_listen_to_balance_change/index.js b/docs/examples/rx/03_listen_to_balance_change/index.js index cf632a0443..04f6133b31 100644 --- a/docs/examples/rx/03_listen_to_balance_change/index.js +++ b/docs/examples/rx/03_listen_to_balance_change/index.js @@ -25,12 +25,12 @@ async function main () { if (balance[0] === 'first') { // Now we know that if the previous value emitted as balance[0] is `first`, // then balance[1] is the initial value of Alice account. - console.log(`Alice ${Alice} has a balance of ${balance[1][1].free}`); + console.log(`Alice ${Alice} has a balance of ${balance[1].data.free}`); console.log('You may leave this example running and start the "Make a transfer" example or transfer any value to Alice address'); return; } - const change = balance[1][1].free.sub(balance[0][1].free); + const change = balance[1].data.free.sub(balance[0].date.free); // Only display value changes if (!change.isZero()) { diff --git a/docs/examples/rx/05_read_storage/index.js b/docs/examples/rx/05_read_storage/index.js index 8c12795c28..0d049acd25 100644 --- a/docs/examples/rx/05_read_storage/index.js +++ b/docs/examples/rx/05_read_storage/index.js @@ -36,16 +36,16 @@ function main () { }) ) // Then we're subscribing to the emitted results - .subscribe(([[accountNonce], blockPeriod, validators, validatorBalances]) => { - console.log(`accountNonce(${Alice}) ${accountNonce}`); + .subscribe(([{ nonce }, blockPeriod, validators, validatorBalances]) => { + console.log(`accountNonce(${Alice}) ${nonce}`); console.log(`blockPeriod ${blockPeriod.toNumber()} seconds`); if (validatorBalances) { // And lastly we print out the authorityIds and balances of all validators console.log('validators', validators.map((authorityId, index) => ({ address: authorityId.toString(), - balance: validatorBalances[index][1].free.toString(), - nonce: validatorBalances[index][0].toString() + balance: validatorBalances[index].data.free.toString(), + nonce: validatorBalances[index].data.toString() }))); } }); diff --git a/docs/start/FAQ.md b/docs/start/FAQ.md index 1565a8882f..546aaed2c1 100644 --- a/docs/start/FAQ.md +++ b/docs/start/FAQ.md @@ -36,7 +36,7 @@ The length for this transaction validity is set to 50 blocks, which translates t ## My chain does not support system.account queries -The API always tracks the latest Substrate master in terms of examples. This means that nonce & balance queries are done via the `api.query.system.account()` which returns a Tuple `(Index, AccountData)` where the first is the nonce, the second a struct containing the free and reserved balances. As with all `api.query.*` endpoints, this is decorated based on what the chain you connect to support, via the metadata exchange. +The API always tracks the latest Substrate master in terms of examples. This means that nonce & balance queries are done via the `api.query.system.account()` which returns a struct `{ nonce: Index, data: AccountData }` where the `data` is struct containing the free and reserved balances. As with all `api.query.*` endpoints, this is decorated based on what the chain you connect to support, via the metadata exchange. It is possible that you are connecting to an older chain that has not been upgraded yet. For these chains, this storage entry won't be available (yet). To query the nonce on older chains, you can do a query to `api.query.system.accountNonce()` and balances can be retrieved via `api.query.balances.freeBalance()`. diff --git a/docs/start/api.query.md b/docs/start/api.query.md index bbbe107476..efee1fe6b8 100644 --- a/docs/start/api.query.md +++ b/docs/start/api.query.md @@ -17,7 +17,7 @@ const ADDR = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFabHE'; const now = await api.query.timestamp.now(); // Retrieve the account balance & nonce via the system module -const [nonce, balance] = await api.query.system.account(ADDR); +const { nonce, data: balance } = await api.query.system.account(ADDR); console.log(`${now}: balance of ${balance.free} and a nonce of ${nonce}`); ``` @@ -27,7 +27,7 @@ There have been some additions in the code above comparing with retrieving runti ```js ... // Retrieve last block timestamp, account nonce & balances -const [now, [nonce, balances]] = await Promise.all([ +const [now, { nonce, data: balances }] = await Promise.all([ api.query.timestamp.now(), api.query.system.account(ADDR) ]); diff --git a/docs/start/api.query.multi.md b/docs/start/api.query.multi.md index 29ff6aeb3b..5e7c912856 100644 --- a/docs/start/api.query.multi.md +++ b/docs/start/api.query.multi.md @@ -11,7 +11,7 @@ Where possible, the use of multi queries are encouraged since it tracks a number // Subscribe to balance changes for 2 accounts, ADDR1 & ADDR2 (already defined) const unsub = await api.query.system.account.multi([ADDR1, ADDR2], (balances) => { - const [[, balance1], [, balance2]] = balances; + const [{ data: balance1 }, { data: balance2 }] = balances; console.log(`The balances are ${balance1.free} and ${balance2.free}`); }); @@ -44,7 +44,7 @@ The previous `.multi` examples assumes that we do queries for the same types, i. const unsub = await api.queryMulti([ api.query.timestamp.now, [api.query.system.account, ADDR] -], ([now, [nonce, balance]]) => { +], ([now, { nonce, data: balance }]) => { console.log(`${now}: balance of ${balance.free} and a nonce of ${nonce}`); }); ``` diff --git a/docs/start/api.query.other.md b/docs/start/api.query.other.md index ba4addf829..dd0f126747 100644 --- a/docs/start/api.query.other.md +++ b/docs/start/api.query.other.md @@ -13,7 +13,7 @@ Quite often is is useful (taking pruning into account, more on this later) to re const lastHdr = await api.rpc.chain.getHeader(); // Retrieve the balance at both the current and the parent hashes -const [[, balanceNow], [, balancePrev]] = await Promise.all([ +const [{ data: balanceNow }, { data: balancePrev }] = await Promise.all([ api.query.system.account.at(lastHdr.hash, ADDR), api.query.system.account.at(lastHdr.parentHash, ADDR) ]); diff --git a/docs/start/api.query.subs.md b/docs/start/api.query.subs.md index 6e77efdc96..23d72d8aa7 100644 --- a/docs/start/api.query.subs.md +++ b/docs/start/api.query.subs.md @@ -25,7 +25,7 @@ If we had a query with parameters, i.e. where we wish to perform a query for a s ... // Subscribe to balance changes for our account -const unsub = await api.query.system.account(ADDR, ([nonce, balance]) => { +const unsub = await api.query.system.account(ADDR, ({ nonce, data: balance }) => { console.log(`free balance is ${balance.freee} with ${balance.reserved} reserved and a nonce of ${nonce}`); }); ``` diff --git a/docs/start/typescript.md b/docs/start/typescript.md index 7529a49751..d39c3c0856 100644 --- a/docs/start/typescript.md +++ b/docs/start/typescript.md @@ -33,7 +33,7 @@ However, to make this sane from a developer perspective the injected methods are import { AccountData, Index } from '@polkadot/types/interfaces'; ... -const [nonce, balance] = await api.query.system.account<[Index, AccountData]>(ADDR); +const { nonce, data: balances } = await api.query.system.account<[Index, AccountData]>(ADDR); ``` In both these case we can instruct the TypeScript compiler that the type we are expecting in `Index` and `Balance` respectively, not just pure `Codec`. This means that functions like `.toNumber()` is available on both these types - as opposed to just the [general type defaults](types.basics.md#everything-is-a-type) with `.toHex()` and friends.