From a2269cd99944a8e03d85bb1c420558c23d982336 Mon Sep 17 00:00:00 2001
From: Jaco Greeff <jacogr@gmail.com>
Date: Thu, 16 Apr 2020 18:11:12 +0200
Subject: [PATCH] Explain where args come from and their types (#2186)

* Explain where args come from and their types

* Update api.query.other.md
---
 docs/cookbook/storage.md      | 10 ++++------
 docs/start/api.query.multi.md |  2 +-
 docs/start/api.query.other.md | 15 ++++++++++-----
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/docs/cookbook/storage.md b/docs/cookbook/storage.md
index 59dedd1b32..34c56b255b 100644
--- a/docs/cookbook/storage.md
+++ b/docs/cookbook/storage.md
@@ -38,10 +38,8 @@ In both these cases, entries/keys operate the same way, `.entries()` retrieving
 // Retrieves the entries for all slashes, in all eras (no arg)
 const allEntries = await api.query.staking.nominatorSlashInEra.entries();
 
-allEntries.forEach(([key, value]) => {
-  const era = key.args[0].toHuman();
-  const nominatorId = key.args[1].toString();
-
+// nominatorSlashInEra(EraIndex, AccountId) for the types of the key args
+allEntries.forEach(([{ args: [era, nominatorId] }, value]) => {
   console.log(`${era}: ${nominatorId} slashed ${value.toHuman()}`);
 });
 ```
@@ -52,6 +50,6 @@ While we can retrieve only the keys for a specific era, using a argument for the
 // Retrieves the keys for the slashed validators in era 652
 const slashedKeys = await api.query.staking.nominatorSlashInEra.keys(652);
 
-// key still contains (era, nominatorId) decoded, so args[1]
-console.log(`slashed: ${slashedKeys.map((k) => k.args[1].toString())`);
+// key args still contains [EraIndex, AccountId] decoded
+console.log(`slashed: ${slashedKeys.map(({ args: [era, nominatorId]}) => nominatorId.toString())`);
 ```
diff --git a/docs/start/api.query.multi.md b/docs/start/api.query.multi.md
index 5e7c912856..a880fa9391 100644
--- a/docs/start/api.query.multi.md
+++ b/docs/start/api.query.multi.md
@@ -23,7 +23,7 @@ A couple of items to note in the example above: we don't call `account` directly
 ...
 
 // Retrieve a snapshot of the validators
-const validators = await api.query.session.validators();
+const validatorKeys = await api.query.session.validators.keys();
 
 // Subscribe to the balances for these accounts
 const unsub = await api.query.balances.account.multi(validators, (balances) => {
diff --git a/docs/start/api.query.other.md b/docs/start/api.query.other.md
index 4618f7e3e5..a49cbca20b 100644
--- a/docs/start/api.query.other.md
+++ b/docs/start/api.query.other.md
@@ -71,18 +71,23 @@ exposures.forEach(([key, exposure]) => {
 });
 ```
 
-Here we are querying a double-map, so we supply 1 argument. No arguments on double-maps will be very costly, retrieving all the eras and associated entries. Additionally when `twox64_concat` & `blake2_concat` is used, the key `.args` will contain decoded values of the params, in this case it will contain the actual `AccountId` of the staker. (Since that was not supplied)
+To understand the usage of the `key.args`, you need to understand that map/doublemap keys are stored alongside their lookups. This means that the raw key has hashed parts as well as the raw data. The API will decode the keys and provide the raw key arguments in args. This would mean -
 
-In the same way as above we can simply do `.keys(activeEra.index): StorageKey[]` to retrieve all the keys here, including the individual keys args (available on maps with decodable hashing functions) -
+- if we are querying `api.query.staking.validators(validatorId: AccountId)` via `entries`, the `key.args` would be `[AccountId]`
+- if we are querying `api.query.staking.erasStakers(era: EraIndex, validatorId: AccountId)` via `entries`, the `key.args` would be `[EraIndex, AccountId]`
+
+the same applies to `.keys()` - here the list of keys also have the decoded args, as specified. You can think of `.args` as a tuple with the same types as the types required to retrieve a single entry in the map.
+
+In the first example we are querying a double-map, so we supply 1 argument. No arguments on double-maps will be very costly, retrieving all the eras and associated entries. In the same way as above we can simply do `.keys(activeEra.index): StorageKey[]` to retrieve all the keys here, including the individual keys args (available on maps with decodable hashing functions) -
 
 ```js
 // retrieve all the nominator keys
 const keys = await api.query.staking.nominators.keys();
 
-// extract the first key argument (AccountId) as string
-const nominatorIds = keys.map((key) => key.args[0].toString());
+// extract the first key argument [AccountId] as string
+const nominatorIds = keys.map(({ args: [nominatorId]) => nominatorId);
 
-console.log('all nominators:', nminatorIds.join(', '));
+console.log('all nominators:', nominatorIds.join(', '));
 ```
 
 ## State entries