[CI Skip] 0.100.1

skip-checks: true

.123trigger

@@ -1 +1 @@
-6
+16

.circleci/config.yml

@@ -1,24 +0,0 @@
-version: 2
-jobs:
-  build:
-    branches:
-      ignore:
-        - gh-pages
-    working_directory: ~/polkadot-js
-    docker:
-      - image: circleci/node:10
-    steps:
-      - checkout
-      - restore_cache:
-          key: dependency-cache-{{ checksum "yarn.lock" }}
-      - run:
-          name: install-deps
-          command: yarn install --frozen-lockfile
-      - save_cache:
-          key: dependency-cache-{{ checksum "yarn.lock" }}
-          paths:
-            - ./node_modules
-            - ~/.cache/yarn
-      - run:
-          name: build
-          command: yarn polkadot-dev-circleci-build

.codeclimate.yml

@@ -4,5 +4,6 @@ exclude_patterns:
 - "**/*.test.js"
 - "**/*.test.ts"
 - "docs/**/*.js"
+- "packages/api/src/query.types.ts"
 - "packages/types/src/interfaces/"
 - "packages/types/src/scripts/"

.eslintrc.js

@@ -2,6 +2,12 @@ const base = require('@polkadot/dev/config/eslint');
 
 module.exports = {
   ...base,
+  parserOptions: {
+    ...base.parserOptions,
+    project: [
+      './tsconfig.json'
+    ]
+  },
   rules: {
     ...base.rules,
     // add override for any (a metric ton of them, initial conversion)

.github/workflows/pr-any.yml

@@ -0,0 +1,71 @@
+name: PR
+on: [pull_request]
+
+jobs:
+  lint:
+    name: Linting
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: lint
+      run: |
+        yarn install --frozen-lockfile
+        yarn lint
+
+  test:
+    name: Testing
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: test
+      run: |
+        yarn install --frozen-lockfile
+        yarn test
+
+  build_code:
+    name: Build Code
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: build
+      run: |
+        yarn install --frozen-lockfile
+        yarn build
+
+  build_docs:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: build
+      run: |
+        yarn install --frozen-lockfile
+        yarn docs

.github/workflows/push-master.yml

@@ -0,0 +1,67 @@
+name: Master
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build_code:
+    name: Build Code
+    if: "! contains(github.event.head_commit.message, '[CI Skip]')"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+      with:
+        token: ${{ secrets.GH_PAT }}
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: build
+      env:
+        CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+        GH_PAT: ${{ secrets.GH_PAT }}
+        GH_TOKEN: ${{ secrets.GH_PAT }}
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      run: |
+        yarn install --frozen-lockfile
+        yarn polkadot-dev-ghact-build
+
+  build_docs:
+    name: Build Docs
+    if: "! contains(github.event.head_commit.message, '[CI Skip]')"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: build
+      env:
+        GH_PAT: ${{ secrets.GH_PAT }}
+        GH_TOKEN: ${{ secrets.GH_PAT }}
+        GH_PAGES_SRC: build-docs
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        yarn install --frozen-lockfile
+        yarn polkadot-dev-ghact-docs
+
+  dummy:
+    name: Dummy
+    if: "contains(github.event.head_commit.message, '[CI Skip]')"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+    steps:
+    - name: dummy
+      run: |
+        echo "Dummy skip step"

.gitignore

@@ -12,6 +12,7 @@ tmp/
 .env.production.local
 .npmrc
 .rpt2_cache
+.vscode/
 cc-test-reporter
 lerna-debug.log*
 npm-debug.log*

.travis.yml

@@ -1,28 +0,0 @@
-language: node_js
-node_js:
-  - "10"
-env:
-  global:
-    - CC_TEST_REPORTER_ID=b8983d04997f43ff9b9df9aa92904967547680e2a229af812b3cf14985713e84
-    - GH_PAGES_SRC="build-docs"
-cache:
-  yarn: true
-  directories:
-    - node_modules
-before_install:
-  - curl -o- -L https://yarnpkg.com/install.sh | bash
-  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-  - chmod +x ./cc-test-reporter
-  - export PATH=$HOME/.yarn/bin::$(yarn global bin):$PATH
-before_script:
-  - ./cc-test-reporter before-build
-script:
-  - yarn polkadot-dev-travis-build
-after_script:
-  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
-deploy:
-  skip_cleanup: true
-  provider: script
-  script: yarn polkadot-dev-travis-deploy
-  on:
-    branch: master

CHANGELOG.md

@@ -1,3 +1,112 @@
+# 0.100.1
+
+- **Important** This will the the last API version with Substrate 1.x support. Although you will still be able to use subsequent versions with older chans, dependent libraries such as sr25519 may not be compatible.
+- Add support for the Substrate identity module
+- Remove the `codec/Data` type, to remove a conflict with Substrate. This type is now named `Raw`
+- Fix for linked maps using `Option`
+- Add support for `BTreeSet` (Thanks to https://github.com/satellitex)
+- Add support for Metadata v10
+- Add support for latest Polkadot/Substrate types
+- Add `paymentInfo` to submittables to calculate fees
+
+# 0.99.1
+
+- **Breaking change** The `Data` and `U8a` type has been renamed and just replaced with the `Raw` type
+- **Breaking change** The `api.derive.staking.info` has been split into 2 - `staking.query` for non-balance related information (more effective) and `staking.account` that enhances query for all the information previously found `.info`
+- Cleanup `DoubleMap` hashing to always hash over the full value (in the case of `Vec<T>`, this includes the length)
+- Update democracy derives to take care of nextTally and lowestU*nbaked
+- Add additional derives for both council & treasury
+- Alignment with latest Polkadot/Substrate master branch types
+
+# 0.98.1
+
+- Make the TypeScript generation script mor re-usable (Thanks to https://github.com/xlc)
+- Add `.entries()` for all map-types, returning storage keys and values
+- Add `.signAsync` to submittable extrinsics (Thanks to https://github.com/c410-f3r)
+- Cleanup circular references between internal dependencies
+- Support for new Substrate democracy with preimages in derive
+- Alignment of types with Substrate/Polkadot master branches
+
+# 0.97.1
+
+- **Breaking change** Add the passing on an explicit `Registry` to all calls to `createType` as well as all codec classes. If you are upgrading form an older version, use the [migration guide](UPGRADING.md) to walk through the changes required.
+- **Breaking change** The metadata classes have been moved from `@polkadot/types` into `@polkadot/metadata`. If you explicitly create `Metadata` classes, you now would need to do so with the `import Metadata from '@polkadot/metadata';` This is a decorated class, where the previous metadata is now available on `Metadata.metadata`, alongside decorated `consts.*`', `tx.*` and `query.*`.
+- **Breaking change** Session `Keys` defaults to 4 keys now (Substrate master), depending on your node config, you would want to override with e.g. `Keys: 'SessionKeys3'` (1, 2, 3, 4, 5 & 6)
+- **Breaking change** `ValidatorPrefs` now default to the new percentage commission model, to use the previous `validatorPayment`, you can override with `ValidatorPrefs: 'ValidatorPrefsTo196'`
+- `api.derive.*` now has built-in memomization
+- Various fixes and cleanups to `api.derive.*` including era length progress and vesting calculations
+- Aligned all types with the latest Polkadot & Substrate, including Kusama CC3
+- Support for Metadata V9, which adjusts the hashing methods of storage entries
+- Support for Metadata V10 (still un-released), which includes prefixed map support
+
+# 0.96.1
+
+- Updated types for latest Kusama
+- Add `filterRecords` (in addition to `findRecord`) on submittable results
+- Various ABI v2 contract fixes
+- Update derive for elections (incl. RunnersUp) and heartbeat derives (with blocks & messages)
+- Add vesting totals & locked breakdowns to derive balances
+- Update council derives for the latest Substrate master support (with constants)
+- Derive cleanups, including sharing of instances between the API and internal to derives
+
+# 0.95.2
+
+- Temporary removal of `account_nextIndex` use, will be re-added in a future release
+
+# 0.95.1
+
+- Support Extrinsic V4 with additional signature indicator (Latest Polkadot/Substrate/Kusama)
+- Adjust subscription update checks to avoid duplicated data updates
+- Support Metadata V8 (exposes per-module `decl_error` definitions)
+- Support next generation contracts ABI (with additional type definitions)
+- Support for `BTreeMap<K, V>` types and definitions
+- All latest Polkadot & Substrate types (as per master branches)
+- **Breaking change** `Call.injectMethods` is moved to `Call.injectMetadata` to align with `Events` (This _should_ not be used externally, however mentioned as breaking here)
+
+# 0.94.1
+
+- Add handling of `Result<Ok, Error>` definitions
+- Adjust API cloning now takes RPC filters from source into account
+- Simplification of isPedantic checks and less overhead on StorageData types
+- Cleanups and fixes around RPC and derive type definitions
+- Fix `derive.imOnline.receivedHeatbeats` to query via indexes
+- Adjustment of `api.derive.elections.{approvalsOf|approvalsOfAt}` to allow ss58 address input
+- Cleanup `Enum` `.eq` handling to be more exhaustive
+- Add documentation for custom extrinsic formats (advanced chains)
+- Update to latest substrate master metadata
+
+# 0.93.1
+
+- Support for Kusama CC2
+- In extrinsic submission, use `rpc.account.nextIndex` to retrieve the nonce when available
+- For TypeScript users `api.query.*.*` is now properly typed for default Substrate calls, i.e. `api.query.balances.freeBalance(...)` will return a `Balance` type. Additionally the `api.queryMulti` and `.multi` on queries not allow generic type params.
+- Add `api.rpc.accounts.nextIndex`, `api.rpc.contracts.call` and `api.rpc.rpc.methods` calls. Optional calls (such as account/contracts) is decorated based on the results from `rpc.methods`, so they don't show up on nodes where they are not active.
+- Updated types to support the latest Polkadot/Substrate master changes
+- Support recursive type registration (self-referencing via `Box`) in addition to better sanitation of user-defined-types
+- Documentation and example updates (thanks mostly to contributions)
+
+# 0.92.1
+
+- The API now correctly sets the ss58 prefix as retrieved from the chain properties via `ss58Format`
+- Bump to `@polkadot/util` 1.4.1, removing use of `ExtError`
+- The `Keyring` from `@polkadot/keyring` is now exposed on the API as well. You can do `import { Keyring } from '@polkadot/api'` - this alleviates the need for extra dependencies (apart from `@polkadot/api`), and since the keyring is critical for signing operations, aligns everything in one bundle
+- Support the latest Polkadot & Substrate master branches (incl. metadata updates)
+- Getting started documentation has been made available
+
+# 0.91.1
+
+- This release was focussed on stability, with a number of cleanups and bug-fixes
+- Adjustments for Substrate 1.x chain detection (with auto-types) and Substrate 2.x support has been extended with all latest types
+- The `getRuntimeVersion` and `subscribeRuntimeVersion` RPCs are now only available on the `rpc.state.*` endpoints. This aligns with the Substrate implementation.
+- The `author_insertKey` RPC's last argument `publicKey` is now required, as to reflect Substrate implementation.
+- Support for extrinsics with versions that is not in the base Substrate implementation (V1-V3) can now be done by providing an implementation for `ExtrinsicUnknown`
+- Redeemed balance calculation if `api.derive` now returns the correct  values again (bug fix)
+- added the `yarn chain:info [--ws URL]` utility to extract a calls-only metadata version
+- Missing types are now logged via a `console.warn`, not via `.error`
+- `Extrinsic`, `ExtrinsicPayload` & `SignerPayload` is registered in the type registry and can be overriden now
+  - **Breaking change** `SignerPayload` is renamed to `SignerPayloadJSON`
+  - **Breaking change** `SignerPayloadJSON`, `SignerPayloadRawBase` and `SignerPayloadRaw` are all moved to `@polkadot/types`
+
 # 0.90.1
 
 If you are upgrading form an older version, use the CHANGELOG hand-in-hand with the [migration guide](UPGRADING.md).
@@ -7,7 +116,7 @@ If you are upgrading form an older version, use the CHANGELOG hand-in-hand with
 - **Breaking change** `Api.create(...)` and `new Api(...)` now only takes an options Object, so if you passed the provider directly previously, you need to swap the use to `Api.create({ provider: ... })`
 - **Breaking change** Runtime types have been extended and moved to definitions instead of classes
   - Primitive types for `i*` and `u*` (e.g. `u32`) are now only available in their lowercase versions. Additionally `Vector` is now only available as `Vec`, and `Method` has been renamed to `Call`, in both cases aligning with Rust.
-  - `Moment` now implements as `u64` as per the Substrate codebase. (It it up to the user to interpret, for substrate 2.x it is not mili-second resolution)
+  - `Moment` now implements as `u64` as per the Substrate codebase. (It it up to the user to interpret, for substrate 2.x it is not ms resolution)
   - For creation of types, it is recommended to use `createType(<TypeName>, <value>)` instead of e.g. `new Proposal(...)`. When passing these to methods/queries, construction should not be needed, the raw value can be passed.
   - For moved types, a previous import would have been from `@polkadot/types`, i.e. `import { SetIndex } from '@polkadot/types`, now just the interfaces (TypeScript) are available via `import { SetIndex } from '@polkadot/types/interfaces`
   - `usize` is now a blacklisted type that will throw on construction. Since it is platform-specific, it creates incompatibilities between native (generally `u64`) and WASM (always `u32`) code. Use one of the `u32` or `u64` types explicitly.
@@ -91,7 +200,7 @@ If you are upgrading form an older version, use the CHANGELOG hand-in-hand with
 # 0.77.1
 
 - Support Metadata v4, which introduces the use of a custom hasher to hash storage map keys.
-- Add TresuryProposal (not the same as democracy, type aliassed)
+- Add TreasuryProposal (not the same as democracy, type aliased)
 
 
 # 0.76.1
@@ -113,7 +222,7 @@ If you are upgrading form an older version, use the CHANGELOG hand-in-hand with
   - For extrinsic status results, if you have checked the type returns, i.e. `result.type === 'Finalised'` now check on the status for `result.status.isFinalized` or `result.status.isBroadcast`, ... (the `type` property is now accessible only on `result.status.type`)
   - If using `subscribeFinalisedHeads` update this to `subscribeFinalizedHeads` (likewise `getFinalisedHead` should be updated to `getFinalizedHead` and `derive.bestNumberFinalized`)
 
-- The underlying ss58 addess checksums have changed
+- The underlying ss58 address checksums have changed
   - The updated keyring with support for this has been made available
   - All examples have been updated with sr25519 addresses (with the new checksums)
 
@@ -131,12 +240,12 @@ If you are upgrading form an older version, use the CHANGELOG hand-in-hand with
 # 0.51.1
 
 - Support metadata V2 as per latest substrate master
-- Update metadata with new types as per lastest substrate master
+- Update metadata with new types as per latest substrate master
 
 
 # 0.50.1
 
-- Lastest util-crypto (usage of WASM with JS fallbacks if not available)
+- Latest util-crypto (usage of WASM with JS fallbacks if not available)
 - Update upstream @polkadot dependencies (for new crypto)
 
 
@@ -159,7 +268,7 @@ If you are upgrading form an older version, use the CHANGELOG hand-in-hand with
 # 0.46.1
 
 - Extended type registration to now handle internal types as well. Additionally the built-in Extrinsic type can now we overridden with a custom version.
-- Where `Extrinsic` and `Method` is used as types, considder importing `{ IMethod, IExtrinsic }` from `@polkadot/types/types`, especially in the cases where this is uased from a `SubmittableExtrinsic`
+- Where `Extrinsic` and `Method` is used as types, consider importing `{ IMethod, IExtrinsic }` from `@polkadot/types/types`, especially in the cases where this is used from a `SubmittableExtrinsic`
 - The `typeRegistry` constant is now `getTypeRegistry()` as a function
 
 
@@ -182,7 +291,7 @@ console.log('llo', llo.unwrapOr('not set') /* Option<BlockNumber> */)
 
 # 0.44.1
 
-- Split primitives and types into seperate folders. This should not affect external use since the exports remain the same, however does have an impact where classes are referenced directly. e.g.
+- Split primitives and types into separate folders. This should not affect external use since the exports remain the same, however does have an impact where classes are referenced directly. e.g.
 
 ```js
 // old (affected)
@@ -200,7 +309,7 @@ import { Method, Signature } from '@polkadot/types';
 
 # 0.43.1
 
-- Intrduces support for the new keyring with sr25519 support in addition to ed25519. While this does not change the exposed API, it is considerred breaking since @polkadot/keyring has interface changes. (Unless needed, don't rush the upgrade)
+- Introduces support for the new keyring with sr25519 support in addition to ed25519. While this does not change the exposed API, it is considered breaking since @polkadot/keyring has interface changes. (Unless needed, don't rush the upgrade)
 
 
 # 0.42.1
@@ -211,7 +320,7 @@ import { Method, Signature } from '@polkadot/types';
 
 # 0.41.1
 
-- Support the V1 metadata specification from Substrate in addition to the currently testnet-active V0 version
+- Support the V1 metadata specification from Substrate in addition to the currently testnet active V0 version
 
 
 # 0.40.1
@@ -231,7 +340,7 @@ Substrate has been updated with a breaking new transaction format where the Inde
 
 # 0.37.1
 
-api-observable has been removed. This was only used in /apps and inconsistent with the api/rx and api/promise APIs. Future work will include derivates like was included in api-observable into the base.
+api-observable has been removed. This was only used in /apps and inconsistent with the api/rx and api/promise APIs. Future work will include derives like was included in api-observable into the base.
 
 Tuples now return single types when only one type is available, i.e. `(AccountId)` would now resolve as `AccountId`. The extra type wrapper adds no benefit to users here.
 

README.md

@@ -22,7 +22,7 @@ The API is split up into a number of internal packages -
 - [@polkadot/api](packages/api/) The API library, providing both Promise and RxJS Observable-based interfaces. This is the main user-facing entry point.
 - [@polkadot/api-derive](packages/api-derive/) Derived results that are injected into the API, allowing for combinations of various query results (only used internally and exposed on the Api instances via `api.derive.*`)
 - [@polkadot/api-metadata](packages/api-metadata/) Base extrinsic, storage and constant injectors for injection
-- [@polkadot/rpc-core](packages/rpc-core/) Wrapper around all [JSON-RPC methods](https://polkadot.js.org/api/METHODS_RPC.html) exposed by a Polkadot network client
+- [@polkadot/rpc-core](packages/rpc-core/) Wrapper around all [JSON-RPC methods](https://polkadot.js.org/api/substrate/rpc.html) exposed by a Polkadot network client
 - [@polkadot/rpc-provider](packages/rpc-provider/) Providers for connecting to nodes, including WebSockets and Http
 
 Type definitions for interfaces as exposed by Polkadot & Substrate clients -

UPGRADING.md

@@ -2,7 +2,91 @@
 
 This is an upgrade guide for users of the API. It does not attempt to detail each version (the [CHANGELOG](CHANGELOG.md) has all the changes between versions), but rather tries to explain the rationale behind major breaking changes and how users of the API should handle this.
 
-While we try to keep the user-facing interfaces as stable as possible, sometimes you just need to make additions to move forward and improve things down the road, as painful as they may be. Like you, we are also users of the API, and eat our own dogfood - and as such, feel any pains introduced first.
+While we try to keep the user-facing interfaces as stable as possible, sometimes you just need to make additions to move forward and improve things down the road, as painful as they may be. Like you, we are also users of the API, and eat our own dog food - and as such, feel any pains introduced first.
+
+
+## 0.97.1 (and newer)
+
+The 0.97 series lays the groundwork to allow type registration  to be ties to a specific chain and a specific Api instance. In the past, 2 Api instances in the same process would share types, which mean that you could not connect to 2 independent chains with different types. This is very problematic for Polkadot chains, where the idea is to connect to multiple chains.
+
+When using the Api, a new `Registry` will be created on using `new Api(...)` or `Api.create(...)` and this will be transparently passed when creating types. In the cases where you create type instances explicitly or create type classes for injection, you would need to make adjustments.
+
+### Type classes
+
+In a number of instances, developers are creating classes and making these available for interacting with their chains. For instance, an example of a custom type could be -
+
+```js
+import { Struct, Text, u32 } from '@polkadot/types';
+
+export class Preferences extends Struct {
+  constructor (value?: ahy) {
+    super({
+      name: Text,
+      id: u32
+    }, value);
+  }
+
+  ...
+}
+```
+
+In the current iteration, the underlying `@polkadot/types` bases structures now require a `Registry` to be passed as the first parameter. This means that the above signature would be adjusted to -
+
+```js
+// the next import is only required for TypeScript
+import { Registry } from '@polkadot/types/types';
+import { Struct, Text, u32 } from '@polkadot/types';
+
+export class Preferences extends Struct {
+  constructor (registry: Registry, value?: ahy) {
+    super(registry, {
+      name: Text,
+      id: u32
+    }, value);
+  }
+
+  ...
+}
+```
+
+Where the type is used or returned from the API, the `Registry` will be automatically passed to class creation.
+
+### createType
+
+Previously, when creating a type instance such as `BlockNumber`, you would do `api.createType('BlockNumber', <initValue>)`, this is unchanged. In the cases where you directly import from `@polkadot/types`, the following pattern is required -
+
+```js
+import { createType } from '@polkadot/types';
+
+...
+const blockNumber = createType(api.registry, 'BlockNumber', 12345);
+```
+
+In some cases, you would want to explicitly pass a `Registry` interface to the API, instead of relying on it explicitly. This is generally applicable in the cases where you want to use the `createType` independently from the API -
+
+```js
+import { ApiPromise } from '@polkadot/api';
+import { TypeRegistry, createType } from '@polkadot/types';
+
+...
+const registry = new TypeRegistry();
+const blockNumber = createType(registry, 'BlockNumber', 12345);
+const api = await ApiPromise.create({ registry });
+```
+
+### Extrinsic metadata
+
+In some applications, the undocumented `findFunction` has been used to determine the Api has the metadata for a specific extrinsic. The has been exposed on top of `GenericCall`, and it typically used in applications such as signers. Along with the compulsory registry, the above functions have been moved to the `Registry` itself, so if you previously had -
+
+```js
+const { meta, method, section } = GenericCall.findFunction(extrinsic.callIndex);
+```
+
+You need to change it to -
+
+```js
+const { meta, method, section } = registry.findMetaCall(extrinsic.callIndex);
+```
 
 ## 0.90.1 (and newer), from 0.81.1 (and older)
 
@@ -29,10 +113,10 @@ To better align with the actual types from the metadata, and avoid (too much) co
 
 The [@polkadot/api](packages/api) has always handled the conversion of types for parameters when making calls or queries. For example, when making a transfer to `BOB` (address), any of the following is valid -
 
-- `api.tx.balances.transfer(BOB, 12345)` - value specied as a number
-- `api.tx.balances.transfer(BOB, '12345')` - value specied as a string
-- `api.tx.balances.transfer(BOB, '0x3039')` - value specied as a hex
-- `api.tx.balances.transfer(BOB, new BN(12345))` - value specied as a [BN](https://github.com/indutny/bn.js/)
+- `api.tx.balances.transfer(BOB, 12345)` - value specified as a number
+- `api.tx.balances.transfer(BOB, '12345')` - value specified as a string
+- `api.tx.balances.transfer(BOB, '0x3039')` - value specified as a hex
+- `api.tx.balances.transfer(BOB, new BN(12345))` - value specified as a [BN](https://github.com/indutny/bn.js/)
 
 Internally the API will take the input and convert the value into a `Balance`, serialize it using the SCALE codec and transfer it to the node. In some cases users would construct the `Balance` type manually, by importing the class and calling `new` on it. This last approach has now been removed, and where classes are still available (limited reach), discouraged.
 
@@ -108,7 +192,7 @@ export class MyStruct extends Struct {
 }
 ```
 
-Internally the [@polkadot/types](packages/types) package now only defines classes where there are specific encoding logic applied. For all other types, the definitions are done via a JSON-like format and then the TypeScript definitions are generated from these. (In a world where nodes inject types and the type definitions are not needed, this functionality will be useful to allow TS devs to auto-generate type definitions based on what the node defines.)
+Internally the [@polkadot/types](packages/types) package now only defines classes where there are specific encoding logic applied. For all other types, the definitions are done via a JSON-like format and then the TypeScript definitions are generated from these. (In a world where nodes inject types and the type definitions are not needed, this functionality will be useful to allow TS developers to auto-generate type definitions based on what the node defines.)
 
 ### Signing transactions (Signer interface)
 

copy-to-apps.sh

@@ -1,13 +1,13 @@
-#!/bin/sh
+#!/bin/bash
 
 function copy_folder () {
   SRC="packages/$1/build"
-  DST="apps/node_modules/@polkadot/$2"
+  DST="../apps/node_modules/@polkadot/$2"
 
-  echo "** Copying $SRC to apps/$DST"
+  echo "** Copying $SRC to $DST"
 
-  rm -rf ../$DST
-  cp -r $SRC ../$DST
+  rm -rf $DST
+  cp -r $SRC $DST
 }
 
 yarn polkadot-dev-build-ts
@@ -15,7 +15,7 @@ yarn polkadot-dev-build-ts
 copy_folder "api" "api"
 copy_folder "api-contract" "api-contract"
 copy_folder "api-derive" "api-derive"
-copy_folder "api-metadata" "api-metadata"
+copy_folder "metadata" "metadata"
 copy_folder "rpc-core" "rpc-core"
 copy_folder "rpc-provider" "rpc-provider"
 copy_folder "type-jsonrpc" "jsonrpc"

docs/.vuepress/config.js

@@ -22,11 +22,37 @@ module.exports = {
     ],
     search: false,
     sidebar: [
+      {
+        title: 'Getting started',
+        path: '/start/',
+        collapsable: false,
+        sidebarDepth: 0,
+        children: [
+          ['start/install.md', 'Installation'],
+          ['start/basics.md', 'Basics & Metadata'],
+          ['start/create.md', 'Creating an instance'],
+          ['start/api.consts.md', 'Runtime Constants'],
+          ['start/api.query.md', 'State queries'],
+          ['start/api.rpc.md', 'RPC calls'],
+          ['start/api.query.subs.md', 'Query subscriptions'],
+          ['start/api.query.multi.md', 'Multi queries'],
+          ['start/api.query.other.md', 'Query extras'],
+          ['start/api.tx.md', 'Transactions'],
+          ['start/keyring.md', 'Keyring'],
+          ['start/api.tx.subs.md', 'Transaction subscriptions'],
+          ['start/api.tx.wrap.md', 'Complex transactions'],
+          ['start/types.basics.md', 'Type basics'],
+          ['start/types.extend.md', 'Extending types'],
+          ['start/extrinsic.extend.md', 'Extending extrinsics'],
+          ['start/typescript.md', 'TypeScript interfaces'],
+          ['start/FAQ.md', 'FAQ']
+        ]
+      },
       {
         title: 'Examples (Promise API)',
         path: '/examples/promise/',
         collapsable: false,
-        sidebarDepth: 1,
+        sidebarDepth: 0,
         children: [
           ['examples/promise/01_simple_connect/', 'Simple connect'],
           ['examples/promise/02_listen_to_blocks/', 'Listen to blocks'],
@@ -40,15 +66,15 @@ module.exports = {
         ]
       },
       {
-        title: 'Substrate interfaces',
+        title: 'Substrate defaults',
         collapsable: false,
         sidebarDepth: 0,
         children: [
-          ['/METHODS_RPC.md', 'Substrate RPC'],
-          ['/METHODS_CONSTANTS.md', 'Constants (defaults)'],
-          ['/METHODS_STORAGE.md', 'State storage (defaults)'],
-          ['/METHODS_EXTRINSICS.md', 'Extrinsics (defaults)'],
-          ['/METHODS_EVENTS.md', 'System events (defaults)']
+          ['substrate/rpc.md', 'Substrate RPC'],
+          ['substrate/constants.md', 'Constants'],
+          ['substrate/storage.md', 'State storage'],
+          ['substrate/extrinsics.md', 'Extrinsics'],
+          ['substrate/events.md', 'System events']
         ]
       },
       ['/api/', '@polkadot/api'],

docs/METHODS_CONSTANTS.md

@@ -1,220 +0,0 @@
-## Constants
-
-_The following sections contain the module constants, also known as parameter types.
-- **[babe](#babe)**
-
-- **[balances](#balances)**
-
-- **[contracts](#contracts)**
-
-- **[democracy](#democracy)**
-
-- **[elections](#elections)**
-
-- **[finalityTracker](#finalityTracker)**
-
-- **[session](#session)**
-
-- **[staking](#staking)**
-
-- **[timestamp](#timestamp)**
-
-- **[treasury](#treasury)**
-
-
-___
-
-
-### babe
-
-▸ **epochDuration**: `u64`
-- **summary**:   The number of **slots** that an epoch takes. We couple sessions to  epochs, i.e. we start a new session once the new epoch begins.
-
-▸ **expectedBlockTime**: `Moment`
-- **summary**:   The expected average block time at which BABE should be creating  blocks. Since BABE is probabilistic it is not trivial to figure out  what the expected average block time should be based on the slot  duration and the security parameter `c` (where `1 - c` represents  the probability of a slot being empty).
-
-___
-
-
-### balances
-
-▸ **creationFee**: `Balance`
-- **summary**:   The fee required to create an account.
-
-▸ **existentialDeposit**: `Balance`
-- **summary**:   The minimum amount required to keep an account open.
-
-▸ **transactionBaseFee**: `Balance`
-- **summary**:   The fee to be paid for making a transaction; the base.
-
-▸ **transactionByteFee**: `Balance`
-- **summary**:   The fee to be paid for making a transaction; the per-byte portion.
-
-▸ **transferFee**: `Balance`
-- **summary**:   The fee required to make a transfer.
-
-___
-
-
-### contracts
-
-▸ **blockGasLimit**: `Gas`
-- **summary**:   The maximum amount of gas that could be expended per block. A reasonable  default value is 10_000_000.
-
-▸ **callBaseFee**: `Gas`
-- **summary**:   The base fee charged for calling into a contract. A reasonable default  value is 135.
-
-▸ **contractFee**: `BalanceOf`
-- **summary**:   The fee required to create a contract instance. A reasonable default value  is 21.
-
-▸ **createBaseFee**: `Gas`
-- **summary**:   The base fee charged for creating a contract. A reasonable default value  is 175.
-
-▸ **creationFee**: `BalanceOf`
-- **summary**:   The fee required to create an account.
-
-▸ **maxDepth**: `u32`
-- **summary**:   The maximum nesting level of a call/create stack. A reasonable default  value is 100.
-
-▸ **maxValueSize**: `u32`
-- **summary**:   The maximum size of a storage value in bytes. A reasonable default is 16 KiB.
-
-▸ **rentByteFee**: `BalanceOf`
-- **summary**:   Price of a byte of storage per one block interval. Should be greater than 0.
-
-▸ **rentDepositOffset**: `BalanceOf`
-- **summary**:   The amount of funds a contract should deposit in order to offset  the cost of one byte.   Let's suppose the deposit is 1,000 BU (balance units)/byte and the rent is 1 BU/byte/day,  then a contract with 1,000,000 BU that uses 1,000 bytes of storage would pay no rent.  But if the balance reduced to 500,000 BU and the storage stayed the same at 1,000,  then it would pay 500 BU/day.
-
-▸ **signedClaimHandicap**: `BlockNumber`
-- **summary**:   Number of block delay an extrinsic claim surcharge has.   When claim surcharge is called by an extrinsic the rent is checked  for current_block - delay
-
-▸ **storageSizeOffset**: `u32`
-- **summary**:   Size of a contract at the time of creation. This is a simple way to ensure  that empty contracts eventually gets deleted.
-
-▸ **surchargeReward**: `BalanceOf`
-- **summary**:   Reward that is received by the party whose touch has led  to removal of a contract.
-
-▸ **tombstoneDeposit**: `BalanceOf`
-- **summary**:   The minimum amount required to generate a tombstone.
-
-▸ **transactionBaseFee**: `BalanceOf`
-- **summary**:   The fee to be paid for making a transaction; the base.
-
-▸ **transactionByteFee**: `BalanceOf`
-- **summary**:   The fee to be paid for making a transaction; the per-byte portion.
-
-▸ **transferFee**: `BalanceOf`
-- **summary**:   The fee required to make a transfer.
-
-___
-
-
-### democracy
-
-▸ **cooloffPeriod**: `BlockNumber`
-- **summary**:   Period in blocks where an external proposal may not be re-submitted after being vetoed.
-
-▸ **emergencyVotingPeriod**: `BlockNumber`
-- **summary**:   Minimum voting period allowed for an emergency referendum.
-
-▸ **enactmentPeriod**: `BlockNumber`
-- **summary**:   The minimum period of locking and the period between a proposal being approved and enacted.   It should generally be a little more than the unstake period to ensure that  voting stakers have an opportunity to remove themselves from the system in the case where  they are on the losing side of a vote.
-
-▸ **launchPeriod**: `BlockNumber`
-- **summary**:   How often (in blocks) new public referenda are launched.
-
-▸ **minimumDeposit**: `BalanceOf`
-- **summary**:   The minimum amount to be used as a deposit for a public referendum proposal.
-
-▸ **votingPeriod**: `BlockNumber`
-- **summary**:   How often (in blocks) to check for new votes.
-
-___
-
-
-### elections
-
-▸ **approvalSetSize**: `u32`
-- **summary**:   The chunk size of the approval vector.
-
-▸ **candidacyBond**: `BalanceOf`
-- **summary**:   How much should be locked up in order to submit one's candidacy. A reasonable  default value is 9.
-
-▸ **carryCount**: `u32`
-- **summary**:   How many runners-up should have their approvals persist until the next  vote. A reasonable default value is 2.
-
-▸ **decayRatio**: `u32`
-- **summary**:   Decay factor of weight when being accumulated. It should typically be set to  __at least__ `membership_size -1` to keep the collective secure.  When set to `N`, it indicates `(1/N)^t` of staked is decayed at weight  increment step `t`. 0 will result in no weight being added at all (normal  approval voting). A reasonable default value is 24.
-
-▸ **inactiveGracePeriod**: `VoteIndex`
-- **summary**:   How many vote indices need to go by after a target voter's last vote before  they can be reaped if their approvals are moot. A reasonable default value  is 1.
-
-▸ **presentSlashPerVoter**: `BalanceOf`
-- **summary**:   The punishment, per voter, if you provide an invalid presentation. A  reasonable default value is 1.
-
-▸ **voterSetSize**: `u32`
-- **summary**:   The chunk size of the voter vector.
-
-▸ **votingBond**: `BalanceOf`
-- **summary**:   How much should be locked up in order to be able to submit votes.
-
-▸ **votingFee**: `BalanceOf`
-- **summary**:   The amount of fee paid upon each vote submission, unless if they submit a  _hole_ index and replace it.
-
-▸ **votingPeriod**: `BlockNumber`
-- **summary**:   How often (in blocks) to check for new votes. A reasonable default value  is 1000.
-
-___
-
-
-### finalityTracker
-
-▸ **reportLatency**: `BlockNumber`
-- **summary**:   The delay after which point things become suspicious. Default is 1000.
-
-▸ **windowSize**: `BlockNumber`
-- **summary**:   The number of recent samples to keep from this chain. Default is 101.
-
-___
-
-
-### session
-
-▸ **dedupKeyPrefix**: `Bytes`
-- **summary**:   Used as first key for `NextKeys` and `KeyOwner` to put all the data into the same branch  of the trie.
-
-___
-
-
-### staking
-
-▸ **bondingDuration**: `EraIndex`
-- **summary**:   Number of eras that staked funds must remain bonded for.
-
-▸ **sessionsPerEra**: `SessionIndex`
-- **summary**:   Number of sessions per era.
-
-___
-
-
-### timestamp
-
-▸ **minimumPeriod**: `Moment`
-- **summary**:   The minimum period between blocks. Beware that this is different to the *expected* period  that the block production apparatus provides. Your chosen consensus system will generally  work with this to determine a sensible block time. e.g. For Aura, it will be double this  period on default settings.
-
-___
-
-
-### treasury
-
-▸ **burn**: `Permill`
-- **summary**:   Percentage of spare funds (if any) that are burnt per spend period.
-
-▸ **proposalBond**: `Permill`
-- **summary**:   Fraction of a proposal's value that should be bonded in order to place the proposal.  An accepted proposal gets these back. A rejected proposal does not.
-
-▸ **proposalBondMinimum**: `BalanceOf`
-- **summary**:   Minimum amount of funds that should be placed in a deposit for making a proposal.
-
-▸ **spendPeriod**: `BlockNumber`
-- **summary**:   Period between successive spends.

docs/METHODS_EVENTS.md

@@ -1,284 +0,0 @@
-## Events
-
-Events are emitted for certain operations on the runtime. The following sections describe the events that are part of the default Substrate runtime.
-- **[balances](#balances)**
-
-- **[contracts](#contracts)**
-
-- **[council](#council)**
-
-- **[democracy](#democracy)**
-
-- **[elections](#elections)**
-
-- **[grandpa](#grandpa)**
-
-- **[imOnline](#imOnline)**
-
-- **[indices](#indices)**
-
-- **[offences](#offences)**
-
-- **[session](#session)**
-
-- **[staking](#staking)**
-
-- **[sudo](#sudo)**
-
-- **[system](#system)**
-
-- **[technicalCommittee](#technicalCommittee)**
-
-- **[technicalMembership](#technicalMembership)**
-
-- **[treasury](#treasury)**
-
-
-___
-
-
-### balances
-
-▸ **NewAccount**(`AccountId`, `Balance`)
-- **summary**:   A new account was created.
-
-▸ **ReapedAccount**(`AccountId`)
-- **summary**:   An account was reaped.
-
-▸ **Transfer**(`AccountId`, `AccountId`, `Balance`, `Balance`)
-- **summary**:   Transfer succeeded (from, to, value, fees).
-
-___
-
-
-### contracts
-
-▸ **CodeStored**(`Hash`)
-- **summary**:   Code with the specified hash has been stored.
-
-▸ **Contract**(`AccountId`, `Bytes`)
-- **summary**:   An event from contract of account.
-
-▸ **Dispatched**(`AccountId`, `bool`)
-- **summary**:   A call was dispatched from the given account. The bool signals whether it was  successful execution or not.
-
-▸ **Instantiated**(`AccountId`, `AccountId`)
-- **summary**:   Contract deployed by address at the specified address.
-
-▸ **ScheduleUpdated**(`u32`)
-- **summary**:   Triggered when the current schedule is updated.
-
-▸ **Transfer**(`AccountId`, `AccountId`, `Balance`)
-- **summary**:   Transfer happened `from` to `to` with given `value` as part of a `call` or `create`.
-
-___
-
-
-### council
-
-▸ **Approved**(`Hash`)
-- **summary**:   A motion was approved by the required threshold.
-
-▸ **Disapproved**(`Hash`)
-- **summary**:   A motion was not approved by the required threshold.
-
-▸ **Executed**(`Hash`, `bool`)
-- **summary**:   A motion was executed; `bool` is true if returned without error.
-
-▸ **MemberExecuted**(`Hash`, `bool`)
-- **summary**:   A single member did some action; `bool` is true if returned without error.
-
-▸ **Proposed**(`AccountId`, `ProposalIndex`, `Hash`, `MemberCount`)
-- **summary**:   A motion (given hash) has been proposed (by given account) with a threshold (given  `MemberCount`).
-
-▸ **Voted**(`AccountId`, `Hash`, `bool`, `MemberCount`, `MemberCount`)
-- **summary**:   A motion (given hash) has been voted on by given account, leaving  a tally (yes votes and no votes given respectively as `MemberCount`).
-
-___
-
-
-### democracy
-
-▸ **Cancelled**(`ReferendumIndex`)
-
-▸ **Delegated**(`AccountId`, `AccountId`)
-
-▸ **Executed**(`ReferendumIndex`, `bool`)
-
-▸ **ExternalTabled**()
-
-▸ **NotPassed**(`ReferendumIndex`)
-
-▸ **Passed**(`ReferendumIndex`)
-
-▸ **Proposed**(`PropIndex`, `Balance`)
-
-▸ **Started**(`ReferendumIndex`, `VoteThreshold`)
-
-▸ **Tabled**(`PropIndex`, `Balance`, `Vec<AccountId>`)
-
-▸ **Undelegated**(`AccountId`)
-
-▸ **Vetoed**(`AccountId`, `Hash`, `BlockNumber`)
-
-___
-
-
-### elections
-
-▸ **BadReaperSlashed**(`AccountId`)
-- **summary**:   slashed reaper
-
-▸ **TallyFinalized**(`Vec<AccountId>`, `Vec<AccountId>`)
-- **summary**:   A tally (for approval votes of seat(s)) has ended (with one or more new members).
-
-▸ **TallyStarted**(`u32`)
-- **summary**:   A tally (for approval votes of seat(s)) has started.
-
-▸ **VoterReaped**(`AccountId`, `AccountId`)
-- **summary**:   reaped voter, reaper
-
-___
-
-
-### grandpa
-
-▸ **NewAuthorities**(`Vec<(AuthorityId,u64)>`)
-- **summary**:   New authority set has been applied.
-
-▸ **Paused**()
-- **summary**:   Current authority set has been paused.
-
-▸ **Resumed**()
-- **summary**:   Current authority set has been resumed.
-
-___
-
-
-### imOnline
-
-▸ **HeartbeatReceived**(`AuthorityId`)
-- **summary**:   A new heartbeat was received from `AuthorityId`
-
-___
-
-
-### indices
-
-▸ **NewAccountIndex**(`AccountId`, `AccountIndex`)
-- **summary**:   A new account index was assigned.   This event is not triggered when an existing index is reassigned  to another `AccountId`.
-
-___
-
-
-### offences
-
-▸ **Offence**(`Kind`, `OpaqueTimeSlot`)
-- **summary**:   There is an offence reported of the given `kind` happened at the `session_index` and  (kind-specific) time slot. This event is not deposited for duplicate slashes.
-
-___
-
-
-### session
-
-▸ **NewSession**(`SessionIndex`)
-- **summary**:   New session has happened. Note that the argument is the session index, not the block  number as the type might suggest.
-
-___
-
-
-### staking
-
-▸ **OldSlashingReportDiscarded**(`SessionIndex`)
-- **summary**:   An old slashing report from a prior era was discarded because it could  not be processed.
-
-▸ **Reward**(`Balance`)
-- **summary**:   All validators have been rewarded by the given balance.
-
-▸ **Slash**(`AccountId`, `Balance`)
-- **summary**:   One validator (and its nominators) has been slashed by the given amount.
-
-___
-
-
-### sudo
-
-▸ **KeyChanged**(`AccountId`)
-- **summary**:   The sudoer just switched identity; the old key is supplied.
-
-▸ **Sudid**(`bool`)
-- **summary**:   A sudo just took place.
-
-___
-
-
-### system
-
-▸ **ExtrinsicFailed**()
-- **summary**:   An extrinsic failed.
-
-▸ **ExtrinsicSuccess**()
-- **summary**:   An extrinsic completed successfully.
-
-___
-
-
-### technicalCommittee
-
-▸ **Approved**(`Hash`)
-- **summary**:   A motion was approved by the required threshold.
-
-▸ **Disapproved**(`Hash`)
-- **summary**:   A motion was not approved by the required threshold.
-
-▸ **Executed**(`Hash`, `bool`)
-- **summary**:   A motion was executed; `bool` is true if returned without error.
-
-▸ **MemberExecuted**(`Hash`, `bool`)
-- **summary**:   A single member did some action; `bool` is true if returned without error.
-
-▸ **Proposed**(`AccountId`, `ProposalIndex`, `Hash`, `MemberCount`)
-- **summary**:   A motion (given hash) has been proposed (by given account) with a threshold (given  `MemberCount`).
-
-▸ **Voted**(`AccountId`, `Hash`, `bool`, `MemberCount`, `MemberCount`)
-- **summary**:   A motion (given hash) has been voted on by given account, leaving  a tally (yes votes and no votes given respectively as `MemberCount`).
-
-___
-
-
-### technicalMembership
-
-▸ **Dummy**(`PhantomData`)
-- **summary**:   Phantom member, never used.
-
-▸ **MemberAdded**()
-- **summary**:   The given member was added; see the transaction for who.
-
-▸ **MemberRemoved**()
-- **summary**:   The given member was removed; see the transaction for who.
-
-▸ **MembersReset**()
-- **summary**:   The membership was reset; see the transaction for who the new set is.
-
-▸ **MembersSwapped**()
-- **summary**:   Two members were swapped; see the transaction for who.
-
-___
-
-
-### treasury
-
-▸ **Awarded**(`ProposalIndex`, `Balance`, `AccountId`)
-- **summary**:   Some funds have been allocated.
-
-▸ **Burnt**(`Balance`)
-- **summary**:   Some of our funds have been burnt.
-
-▸ **Proposed**(`ProposalIndex`)
-- **summary**:   New proposal.
-
-▸ **Rollover**(`Balance`)
-- **summary**:   Spending has finished; this is the amount that rolls over until next spend.
-
-▸ **Spending**(`Balance`)
-- **summary**:   We have ended a spend period and will now allocate funds.

docs/METHODS_EXTRINSICS.md

@@ -1,359 +0,0 @@
-## Extrinsics
-
-_The following sections contain Extrinsics methods are part of the default Substrate runtime._
-- **[authorship](#authorship)**
-
-- **[babe](#babe)**
-
-- **[balances](#balances)**
-
-- **[contracts](#contracts)**
-
-- **[council](#council)**
-
-- **[democracy](#democracy)**
-
-- **[elections](#elections)**
-
-- **[finalityTracker](#finalityTracker)**
-
-- **[grandpa](#grandpa)**
-
-- **[imOnline](#imOnline)**
-
-- **[session](#session)**
-
-- **[staking](#staking)**
-
-- **[sudo](#sudo)**
-
-- **[system](#system)**
-
-- **[technicalCommittee](#technicalCommittee)**
-
-- **[technicalMembership](#technicalMembership)**
-
-- **[timestamp](#timestamp)**
-
-- **[treasury](#treasury)**
-
-
-___
-
-
-### authorship
-
-▸ **setUncles**(new_uncles: `Vec<Header>`)
-- **summary**:   Provide a set of uncles.
-
-___
-
-
-### babe
-
-▸ **setPendingSecondarySlotsChange**(change: `Option<bool>`)
-- **summary**:   Sets a pending change to enable / disable secondary slot assignment.  The pending change will be set at the end of the current epoch and  will be enacted at `current_epoch + 2`.
-
-___
-
-
-### balances
-
-▸ **setBalance**(who: `Address`, new_free: `Compact<Balance>`, new_reserved: `Compact<Balance>`)
-- **summary**:   Set the balances of a given account.   This will alter `FreeBalance` and `ReservedBalance` in storage. it will  also decrease the total issuance of the system (`TotalIssuance`).  If the new free or reserved balance is below the existential deposit,  it will reset the account nonce (`system::AccountNonce`).   The dispatch origin for this call is `root`.   # <weight>  - Independent of the arguments.  - Contains a limited number of reads and writes.  # </weight>
-
-▸ **transfer**(dest: `Address`, value: `Compact<Balance>`)
-- **summary**:   Transfer some liquid free balance to another account.   `transfer` will set the `FreeBalance` of the sender and receiver.  It will decrease the total issuance of the system by the `TransferFee`.  If the sender's account is below the existential deposit as a result  of the transfer, the account will be reaped.   The dispatch origin for this call must be `Signed` by the transactor.   # <weight>  - Dependent on arguments but not critical, given proper implementations for    input config types. See related functions below.  - It contains a limited number of reads and writes internally and no complex computation.   Related functions:     - `ensure_can_withdraw` is always called internally but has a bounded complexity.    - Transferring balances to accounts that did not exist before will cause       `T::OnNewAccount::on_new_account` to be called.    - Removing enough funds from an account will trigger      `T::DustRemoval::on_unbalanced` and `T::OnFreeBalanceZero::on_free_balance_zero`.   # </weight>
-
-___
-
-
-### contracts
-
-▸ **call**(dest: `Address`, value: `Compact<BalanceOf>`, gas_limit: `Compact<Gas>`, data: `Bytes`)
-- **summary**:   Makes a call to an account, optionally transferring some balance.   * If the account is a smart-contract account, the associated code will be  executed and any value will be transferred.  * If the account is a regular account, any value will be transferred.  * If no account exists and the call value is not less than `existential_deposit`,  a regular account will be created and any value will be transferred.
-
-▸ **claimSurcharge**(dest: `AccountId`, aux_sender: `Option<AccountId>`)
-- **summary**:   Allows block producers to claim a small reward for evicting a contract. If a block producer  fails to do so, a regular users will be allowed to claim the reward.   If contract is not evicted as a result of this call, no actions are taken and  the sender is not eligible for the reward.
-
-▸ **create**(endowment: `Compact<BalanceOf>`, gas_limit: `Compact<Gas>`, code_hash: `CodeHash`, data: `Bytes`)
-- **summary**:   Creates a new contract from the `codehash` generated by `put_code`, optionally transferring some balance.   Creation is executed as follows:   - The destination address is computed based on the sender and hash of the code.  - The smart-contract account is created at the computed address.  - The `ctor_code` is executed in the context of the newly-created account. Buffer returned    after the execution is saved as the `code` of the account. That code will be invoked    upon any call received by this account.  - The contract is initialized.
-
-▸ **putCode**(gas_limit: `Compact<Gas>`, code: `Bytes`)
-- **summary**:   Stores the given binary Wasm code into the chain's storage and returns its `codehash`.  You can instantiate contracts only with stored code.
-
-▸ **updateSchedule**(schedule: `Schedule`)
-- **summary**:   Updates the schedule for metering contracts.   The schedule must have a greater version than the stored schedule.
-
-___
-
-
-### council
-
-▸ **execute**(proposal: `Proposal`)
-- **summary**:   Dispatch a proposal from a member using the `Member` origin.   Origin must be a member of the collective.
-
-▸ **propose**(threshold: `Compact<MemberCount>`, proposal: `Proposal`)
-- **summary**:   # <weight>  - Bounded storage reads and writes.  - Argument `threshold` has bearing on weight.  # </weight>
-
-▸ **setMembers**(new_members: `Vec<AccountId>`)
-- **summary**:   Set the collective's membership manually to `new_members`. Be nice to the chain and  provide it pre-sorted.   Requires root origin.
-
-▸ **vote**(proposal: `Hash`, index: `Compact<ProposalIndex>`, approve: `bool`)
-- **summary**:   # <weight>  - Bounded storage read and writes.  - Will be slightly heavier if the proposal is approved / disapproved after the vote.  # </weight>
-
-___
-
-
-### democracy
-
-▸ **cancelQueued**(when: `Compact<BlockNumber>`, which: `Compact<u32>`, what: `Compact<ReferendumIndex>`)
-- **summary**:   Cancel a proposal queued for enactment.
-
-▸ **cancelReferendum**(ref_index: `Compact<ReferendumIndex>`)
-- **summary**:   Remove a referendum.
-
-▸ **delegate**(to: `AccountId`, conviction: `Conviction`)
-- **summary**:   Delegate vote.   # <weight>  - One extra DB entry.  # </weight>
-
-▸ **emergencyCancel**(ref_index: `ReferendumIndex`)
-- **summary**:   Schedule an emergency cancellation of a referendum. Cannot happen twice to the same  referendum.
-
-▸ **externalPropose**(proposal: `Proposal`)
-- **summary**:   Schedule a referendum to be tabled once it is legal to schedule an external  referendum.
-
-▸ **externalProposeDefault**(proposal: `Proposal`)
-- **summary**:   Schedule a negative-turnout-bias referendum to be tabled next once it is legal to  schedule an external referendum.   Unlike `external_propose`, blacklisting has no effect on this and it may replace a  pre-scheduled `external_propose` call.
-
-▸ **externalProposeMajority**(proposal: `Proposal`)
-- **summary**:   Schedule a majority-carries referendum to be tabled next once it is legal to schedule  an external referendum.   Unlike `external_propose`, blacklisting has no effect on this and it may replace a  pre-scheduled `external_propose` call.
-
-▸ **fastTrack**(proposal_hash: `Hash`, voting_period: `BlockNumber`, delay: `BlockNumber`)
-- **summary**:   Schedule the currently externally-proposed majority-carries referendum to be tabled  immediately. If there is no externally-proposed referendum currently, or if there is one  but it is not a majority-carries referendum then it fails.   - `proposal_hash`: The hash of the current external proposal.  - `voting_period`: The period that is allowed for voting on this proposal.  - `delay`: The number of block after voting has ended in approval and this should be    enacted. Increased to `EmergencyVotingPeriod` if too low.
-
-▸ **propose**(proposal: `Proposal`, value: `Compact<BalanceOf>`)
-- **summary**:   Propose a sensitive action to be taken.   # <weight>  - O(1).  - Two DB changes, one DB entry.  # </weight>
-
-▸ **proxyVote**(ref_index: `Compact<ReferendumIndex>`, vote: `Vote`)
-- **summary**:   Vote in a referendum on behalf of a stash. If `vote.is_aye()`, the vote is to enact  the proposal;  otherwise it is a vote to keep the status quo.   # <weight>  - O(1).  - One DB change, one DB entry.  # </weight>
-
-▸ **removeProxy**(proxy: `AccountId`)
-- **summary**:   Clear the proxy. Called by the stash.   # <weight>  - One DB clear.  # </weight>
-
-▸ **resignProxy**()
-- **summary**:   Clear the proxy. Called by the proxy.   # <weight>  - One DB clear.  # </weight>
-
-▸ **second**(proposal: `Compact<PropIndex>`)
-- **summary**:   Propose a sensitive action to be taken.   # <weight>  - O(1).  - One DB entry.  # </weight>
-
-▸ **setProxy**(proxy: `AccountId`)
-- **summary**:   Specify a proxy. Called by the stash.   # <weight>  - One extra DB entry.  # </weight>
-
-▸ **undelegate**()
-- **summary**:   Undelegate vote.   # <weight>  - O(1).  # </weight>
-
-▸ **vetoExternal**(proposal_hash: `Hash`)
-- **summary**:   Veto and blacklist the external proposal hash.
-
-▸ **vote**(ref_index: `Compact<ReferendumIndex>`, vote: `Vote`)
-- **summary**:   Vote in a referendum. If `vote.is_aye()`, the vote is to enact the proposal;  otherwise it is a vote to keep the status quo.   # <weight>  - O(1).  - One DB change, one DB entry.  # </weight>
-
-___
-
-
-### elections
-
-▸ **presentWinner**(candidate: `Address`, total: `Compact<BalanceOf>`, index: `Compact<VoteIndex>`)
-- **summary**:   Claim that `signed` is one of the top Self::carry_count() + current_vote().1 candidates.  Only works if the `block_number >= current_vote().0` and `< current_vote().0 + presentation_duration()`  `signed` should have at least   # <weight>  - O(voters) compute.  - One DB change.  # </weight>
-
-▸ **proxySetApprovals**(votes: `Vec<bool>`, index: `Compact<VoteIndex>`, hint: `SetIndex`)
-- **summary**:   Set candidate approvals from a proxy. Approval slots stay valid as long as candidates in those slots  are registered.   # <weight>  - Same as `set_approvals` with one additional storage read.  # </weight>
-
-▸ **reapInactiveVoter**(reporter_index: `Compact<u32>`, who: `Address`, who_index: `Compact<u32>`, assumed_vote_index: `Compact<VoteIndex>`)
-- **summary**:   Remove a voter. For it not to be a bond-consuming no-op, all approved candidate indices  must now be either unregistered or registered to a candidate that registered the slot after  the voter gave their last approval set.   Both indices must be provided as explained in [`voter_at`] function.   May be called by anyone. Returns the voter deposit to `signed`.   # <weight>  - O(1).  - Two fewer DB entries, one DB change.  # </weight>
-
-▸ **removeMember**(who: `Address`)
-- **summary**:   Remove a particular member from the set. This is effective immediately.   Note: A tally should happen instantly (if not already in a presentation  period) to fill the seat if removal means that the desired members are not met.
-
-▸ **retractVoter**(index: `Compact<u32>`)
-- **summary**:   Remove a voter. All votes are cancelled and the voter deposit is returned.   The index must be provided as explained in [`voter_at`] function.   Also removes the lock on the balance of the voter. See [`do_set_approvals()`].   # <weight>  - O(1).  - Two fewer DB entries, one DB change.  # </weight>
-
-▸ **setApprovals**(votes: `Vec<bool>`, index: `Compact<VoteIndex>`, hint: `SetIndex`)
-- **summary**:   Set candidate approvals. Approval slots stay valid as long as candidates in those slots  are registered.   Locks the total balance of caller indefinitely.  Only [`retract_voter`] or [`reap_inactive_voter`] can unlock the balance.   `hint` argument is interpreted differently based on:  - if `origin` is setting approvals for the first time: The index will be checked  for being a valid _hole_ in the voter list.    - if the hint is correctly pointing to a hole, no fee is deducted from `origin`.    - Otherwise, the call will succeed but the index is ignored and simply a push to the last chunk    with free space happens. If the new push causes a new chunk to be created, a fee indicated by    [`VotingFee`] is deducted.  - if `origin` is already a voter: the index __must__ be valid and point to the correct  position of the `origin` in the current voters list.   Note that any trailing `false` votes in `votes` is ignored; In approval voting, not voting for a candidate  and voting false, are equal.   # <weight>  - O(1).  - Two extra DB entries, one DB change.  - Argument `votes` is limited in length to number of candidates.  # </weight>
-
-▸ **setDesiredSeats**(count: `Compact<u32>`)
-- **summary**:   Set the desired member count; if lower than the current count, then seats will not be up  election when they expire. If more, then a new vote will be started if one is not  already in progress.
-
-▸ **setPresentationDuration**(count: `Compact<BlockNumber>`)
-- **summary**:   Set the presentation duration. If there is currently a vote being presented for, will  invoke `finalize_vote`.
-
-▸ **setTermDuration**(count: `Compact<BlockNumber>`)
-- **summary**:   Set the presentation duration. If there is current a vote being presented for, will  invoke `finalize_vote`.
-
-▸ **submitCandidacy**(slot: `Compact<u32>`)
-- **summary**:   Submit oneself for candidacy.   Account must have enough transferrable funds in it to pay the bond.   NOTE: if `origin` has already assigned approvals via [`set_approvals`],  it will NOT have any usable funds to pass candidacy bond and must first retract.  Note that setting approvals will lock the entire balance of the voter until  retraction or being reported.   # <weight>  - Independent of input.  - Three DB changes.  # </weight>
-
-___
-
-
-### finalityTracker
-
-▸ **finalHint**(hint: `Compact<BlockNumber>`)
-- **summary**:   Hint that the author of this block thinks the best finalized  block is the given number.
-
-___
-
-
-### grandpa
-
-▸ **reportMisbehavior**(_report: `Bytes`)
-- **summary**:   Report some misbehavior.
-
-___
-
-
-### imOnline
-
-▸ **heartbeat**(heartbeat: `Heartbeat`, signature: `AuthoritySignature`)
-
-___
-
-
-### session
-
-▸ **setKeys**(keys: `Keys`, proof: `Bytes`)
-- **summary**:   Sets the session key(s) of the function caller to `key`.  Allows an account to set its session key prior to becoming a validator.  This doesn't take effect until the next session.   The dispatch origin of this function must be signed.   # <weight>  - O(log n) in number of accounts.  - One extra DB entry.  # </weight>
-
-___
-
-
-### staking
-
-▸ **bond**(controller: `Address`, value: `Compact<BalanceOf>`, payee: `RewardDestination`)
-- **summary**:   Take the origin account as a stash and lock up `value` of its balance. `controller` will  be the account that controls it.   `value` must be more than the `existential_deposit` defined in the Balances module.   The dispatch origin for this call must be _Signed_ by the stash account.   # <weight>  - Independent of the arguments. Moderate complexity.  - O(1).  - Three extra DB entries.   NOTE: Two of the storage writes (`Self::bonded`, `Self::payee`) are _never_ cleaned unless  the `origin` falls below _existential deposit_ and gets removed as dust.  # </weight>
-
-▸ **bondExtra**(max_additional: `Compact<BalanceOf>`)
-- **summary**:   Add some extra amount that have appeared in the stash `free_balance` into the balance up  for staking.   Use this if there are additional funds in your stash account that you wish to bond.  Unlike [`bond`] or [`unbond`] this function does not impose any limitation on the amount  that can be added.   The dispatch origin for this call must be _Signed_ by the stash, not the controller.   # <weight>  - Independent of the arguments. Insignificant complexity.  - O(1).  - One DB entry.  # </weight>
-
-▸ **chill**()
-- **summary**:   Declare no desire to either validate or nominate.   Effects will be felt at the beginning of the next era.   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   # <weight>  - Independent of the arguments. Insignificant complexity.  - Contains one read.  - Writes are limited to the `origin` account key.  # </weight>
-
-▸ **forceNewEra**()
-- **summary**:   Force there to be a new era at the end of the next session. After this, it will be  reset to normal (non-forced) behaviour.   # <weight>  - No arguments.  # </weight>
-
-▸ **forceNoEras**()
-- **summary**:   Force there to be no new eras indefinitely.   # <weight>  - No arguments.  # </weight>
-
-▸ **nominate**(targets: `Vec<Address>`)
-- **summary**:   Declare the desire to nominate `targets` for the origin controller.   Effects will be felt at the beginning of the next era.   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   # <weight>  - The transaction's complexity is proportional to the size of `targets`,  which is capped at `MAX_NOMINATIONS`.  - Both the reads and writes follow a similar pattern.  # </weight>
-
-▸ **setController**(controller: `Address`)
-- **summary**:   (Re-)set the controller of a stash.   Effects will be felt at the beginning of the next era.   The dispatch origin for this call must be _Signed_ by the stash, not the controller.   # <weight>  - Independent of the arguments. Insignificant complexity.  - Contains a limited number of reads.  - Writes are limited to the `origin` account key.  # </weight>
-
-▸ **setInvulnerables**(validators: `Vec<AccountId>`)
-- **summary**:   Set the validators who cannot be slashed (if any).
-
-▸ **setPayee**(payee: `RewardDestination`)
-- **summary**:   (Re-)set the payment target for a controller.   Effects will be felt at the beginning of the next era.   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   # <weight>  - Independent of the arguments. Insignificant complexity.  - Contains a limited number of reads.  - Writes are limited to the `origin` account key.  # </weight>
-
-▸ **setValidatorCount**(new: `Compact<u32>`)
-- **summary**:   The ideal number of validators.
-
-▸ **unbond**(value: `Compact<BalanceOf>`)
-- **summary**:   Schedule a portion of the stash to be unlocked ready for transfer out after the bond  period ends. If this leaves an amount actively bonded less than  T::Currency::existential_deposit(), then it is increased to the full amount.   Once the unlock period is done, you can call `withdraw_unbonded` to actually move  the funds out of management ready for transfer.   No more than a limited number of unlocking chunks (see `MAX_UNLOCKING_CHUNKS`)  can co-exists at the same time. In that case, [`Call::withdraw_unbonded`] need  to be called first to remove some of the chunks (if possible).   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   See also [`Call::withdraw_unbonded`].   # <weight>  - Independent of the arguments. Limited but potentially exploitable complexity.  - Contains a limited number of reads.  - Each call (requires the remainder of the bonded balance to be above `minimum_balance`)    will cause a new entry to be inserted into a vector (`Ledger.unlocking`) kept in storage.    The only way to clean the aforementioned storage item is also user-controlled via `withdraw_unbonded`.  - One DB entry.  </weight>
-
-▸ **validate**(prefs: `ValidatorPrefs`)
-- **summary**:   Declare the desire to validate for the origin controller.   Effects will be felt at the beginning of the next era.   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   # <weight>  - Independent of the arguments. Insignificant complexity.  - Contains a limited number of reads.  - Writes are limited to the `origin` account key.  # </weight>
-
-▸ **withdrawUnbonded**()
-- **summary**:   Remove any unlocked chunks from the `unlocking` queue from our management.   This essentially frees up that balance to be used by the stash account to do  whatever it wants.   The dispatch origin for this call must be _Signed_ by the controller, not the stash.   See also [`Call::unbond`].   # <weight>  - Could be dependent on the `origin` argument and how much `unlocking` chunks exist.   It implies `consolidate_unlocked` which loops over `Ledger.unlocking`, which is   indirectly user-controlled. See [`unbond`] for more detail.  - Contains a limited number of reads, yet the size of which could be large based on `ledger`.  - Writes are limited to the `origin` account key.  # </weight>
-
-___
-
-
-### sudo
-
-▸ **setKey**(new: `Address`)
-- **summary**:   Authenticates the current sudo key and sets the given AccountId (`new`) as the new sudo key.   The dispatch origin for this call must be _Signed_.   # <weight>  - O(1).  - Limited storage reads.  - One DB change.  # </weight>
-
-▸ **sudo**(proposal: `Proposal`)
-- **summary**:   Authenticates the sudo key and dispatches a function call with `Root` origin.   The dispatch origin for this call must be _Signed_.   # <weight>  - O(1).  - Limited storage reads.  - No DB writes.  # </weight>
-
-___
-
-
-### system
-
-▸ **fillBlock**()
-- **summary**:   A big dispatch that will disallow any other transaction to be included.
-
-▸ **killStorage**(keys: `Vec<Key>`)
-- **summary**:   Kill some items from storage.
-
-▸ **remark**(_remark: `Bytes`)
-- **summary**:   Make some on-chain remark.
-
-▸ **setCode**(new: `Bytes`)
-- **summary**:   Set the new code.
-
-▸ **setHeapPages**(pages: `u64`)
-- **summary**:   Set the number of pages in the WebAssembly environment's heap.
-
-▸ **setStorage**(items: `Vec<KeyValue>`)
-- **summary**:   Set some items of storage.
-
-___
-
-
-### technicalCommittee
-
-▸ **execute**(proposal: `Proposal`)
-- **summary**:   Dispatch a proposal from a member using the `Member` origin.   Origin must be a member of the collective.
-
-▸ **propose**(threshold: `Compact<MemberCount>`, proposal: `Proposal`)
-- **summary**:   # <weight>  - Bounded storage reads and writes.  - Argument `threshold` has bearing on weight.  # </weight>
-
-▸ **setMembers**(new_members: `Vec<AccountId>`)
-- **summary**:   Set the collective's membership manually to `new_members`. Be nice to the chain and  provide it pre-sorted.   Requires root origin.
-
-▸ **vote**(proposal: `Hash`, index: `Compact<ProposalIndex>`, approve: `bool`)
-- **summary**:   # <weight>  - Bounded storage read and writes.  - Will be slightly heavier if the proposal is approved / disapproved after the vote.  # </weight>
-
-___
-
-
-### technicalMembership
-
-▸ **addMember**(who: `AccountId`)
-- **summary**:   Add a member `who` to the set.   May only be called from `AddOrigin` or root.
-
-▸ **removeMember**(who: `AccountId`)
-- **summary**:   Remove a member `who` from the set.   May only be called from `RemoveOrigin` or root.
-
-▸ **resetMembers**(members: `Vec<AccountId>`)
-- **summary**:   Change the membership to a new set, disregarding the existing membership. Be nice and  pass `members` pre-sorted.   May only be called from `ResetOrigin` or root.
-
-▸ **swapMember**(remove: `AccountId`, add: `AccountId`)
-- **summary**:   Swap out one member `remove` for another `add`.   May only be called from `SwapOrigin` or root.
-
-___
-
-
-### timestamp
-
-▸ **set**(now: `Compact<Moment>`)
-- **summary**:   Set the current time.   This call should be invoked exactly once per block. It will panic at the finalization  phase, if this call hasn't been invoked by that time.   The timestamp should be greater than the previous one by the amount specified by  `MinimumPeriod`.   The dispatch origin for this call must be `Inherent`.
-
-___
-
-
-### treasury
-
-▸ **approveProposal**(proposal_id: `Compact<ProposalIndex>`)
-- **summary**:   Approve a proposal. At a later time, the proposal will be allocated to the beneficiary  and the original deposit will be returned.   # <weight>  - O(1).  - Limited storage reads.  - One DB change.  # </weight>
-
-▸ **proposeSpend**(value: `Compact<BalanceOf>`, beneficiary: `Address`)
-- **summary**:   Put forward a suggestion for spending. A deposit proportional to the value  is reserved and slashed if the proposal is rejected. It is returned once the  proposal is awarded.   # <weight>  - O(1).  - Limited storage reads.  - One DB change, one extra DB entry.  # </weight>
-
-▸ **rejectProposal**(proposal_id: `Compact<ProposalIndex>`)
-- **summary**:   Reject a proposed spend. The original deposit will be slashed.   # <weight>  - O(1).  - Limited storage reads.  - One DB clear.  # </weight>

docs/METHODS_STORAGE.md

@@ -1,544 +0,0 @@
-## Storage
-
-_The following sections contain Storage methods are part of the default Substrate runtime._
-- **[authorship](#authorship)**
-
-- **[babe](#babe)**
-
-- **[balances](#balances)**
-
-- **[contracts](#contracts)**
-
-- **[council](#council)**
-
-- **[democracy](#democracy)**
-
-- **[elections](#elections)**
-
-- **[grandpa](#grandpa)**
-
-- **[imOnline](#imOnline)**
-
-- **[indices](#indices)**
-
-- **[offences](#offences)**
-
-- **[session](#session)**
-
-- **[staking](#staking)**
-
-- **[sudo](#sudo)**
-
-- **[system](#system)**
-
-- **[technicalCommittee](#technicalCommittee)**
-
-- **[technicalMembership](#technicalMembership)**
-
-- **[timestamp](#timestamp)**
-
-- **[treasury](#treasury)**
-
-- **[substrate](#substrate)**
-
-
-___
-
-
-### authorship
-
-▸ **author**(): `Option<AccountId>`
-- **summary**:   Author of current block.
-
-▸ **didSetUncles**(): `bool`
-- **summary**:   Whether uncles were already set in this block.
-
-▸ **uncles**(): `Vec<UncleEntryItem>`
-- **summary**:   Uncles
-
-___
-
-
-### babe
-
-▸ **authorities**(): `Vec<(AuthorityId,BabeAuthorityWeight)>`
-- **summary**:   Current epoch authorities.
-
-▸ **currentSlot**(): `u64`
-- **summary**:   Current slot number.
-
-▸ **epochIndex**(): `u64`
-- **summary**:   Current epoch index.
-
-▸ **epochStartSlot**(): `u64`
-- **summary**:   Slot at which the current epoch started. It is possible that no  block was authored at the given slot and the epoch change was  signalled later than this.
-
-▸ **initialized**(): `Option<bool>`
-- **summary**:   Temporary value (cleared at block finalization) which is true  if per-block initialization has already been called for current block.
-
-▸ **nextRandomness**(): `[u8;32]`
-- **summary**:   Next epoch randomness.
-
-▸ **pendingSecondarySlotsChange**(): `Option<bool>`
-- **summary**:   Pending change to enable/disable secondary slots which will be  triggered at `current_epoch + 2`.
-
-▸ **randomness**(): `[u8;32]`
-- **summary**:   The epoch randomness for the *current* epoch.   # Security   This MUST NOT be used for gambling, as it can be influenced by a  malicious validator in the short term. It MAY be used in many  cryptographic protocols, however, so long as one remembers that this  (like everything else on-chain) it is public. For example, it can be  used where a number is needed that cannot have been chosen by an  adversary, for purposes such as public-coin zero-knowledge proofs.
-
-▸ **secondarySlots**(): `(bool,bool)`
-- **summary**:   Whether secondary slots are enabled in case the VRF-based slot is  empty for the current epoch and the next epoch, respectively.
-
-▸ **segmentIndex**(): `u32`
-- **summary**:   Randomness under construction.   We make a tradeoff between storage accesses and list length.  We store the under-construction randomness in segments of up to  `UNDER_CONSTRUCTION_SEGMENT_LENGTH`.   Once a segment reaches this length, we begin the next one.  We reset all segments and return to `0` at the beginning of every  epoch.
-
-▸ **underConstruction**(`u32`): `Vec<[u8;32]>`
-
-___
-
-
-### balances
-
-▸ **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`.
-
-▸ **locks**(`AccountId`): `Vec<BalanceLock>`
-- **summary**:   Any liquidity locks on some account balances.
-
-▸ **reservedBalance**(`AccountId`): `Balance`
-- **summary**:   The amount of the balance of a given account that is externally reserved; this can still get  slashed, but gets slashed last of all.   This balance is a 'reserve' balance that other subsystems use in order to set aside tokens  that are still 'owned' by the account holder, but which are suspendable.   When this balance falls below the value of `ExistentialDeposit`, then this 'reserve account'  is deleted: specifically, `ReservedBalance`.   `system::AccountNonce` is also deleted if `FreeBalance` is also zero (it also gets  collapsed to zero if it ever becomes less than `ExistentialDeposit`.)
-
-▸ **totalIssuance**(): `Balance`
-- **summary**:   The total units issued in the system.
-
-▸ **vesting**(`AccountId`): `Option<VestingSchedule>`
-- **summary**:   Information regarding the vesting of a given account.
-
-___
-
-
-### contracts
-
-▸ **accountCounter**(): `u64`
-- **summary**:   The subtrie counter.
-
-▸ **codeStorage**(`CodeHash`): `Option<PrefabWasmModule>`
-- **summary**:   A mapping between an original code hash and instrumented wasm code, ready for execution.
-
-▸ **contractInfoOf**(`AccountId`): `Option<ContractInfo>`
-- **summary**:   The code associated with a given account.
-
-▸ **currentSchedule**(): `Schedule`
-- **summary**:   Current cost schedule for contracts.
-
-▸ **gasPrice**(): `BalanceOf`
-- **summary**:   The price of one unit of gas.
-
-▸ **gasSpent**(): `Gas`
-- **summary**:   Gas spent so far in this block.
-
-▸ **pristineCode**(`CodeHash`): `Option<Bytes>`
-- **summary**:   A mapping from an original code hash to the original code, untouched by instrumentation.
-
-___
-
-
-### council
-
-▸ **members**(): `Vec<AccountId>`
-- **summary**:   The current members of the collective. This is stored sorted (just by value).
-
-▸ **proposalCount**(): `u32`
-- **summary**:   Proposals so far.
-
-▸ **proposalOf**(`Hash`): `Option<Proposal>`
-- **summary**:   Actual proposal for a given hash, if it's current.
-
-▸ **proposals**(): `Vec<Hash>`
-- **summary**:   The hashes of the active proposals.
-
-▸ **voting**(`Hash`): `Option<Votes>`
-- **summary**:   Votes on a given proposal, if it is ongoing.
-
-___
-
-
-### democracy
-
-▸ **blacklist**(`Hash`): `Option<(BlockNumber,Vec<AccountId>)>`
-- **summary**:   A record of who vetoed what. Maps proposal hash to a possible existent block number  (until when it may not be resubmitted) and who vetoed it.
-
-▸ **cancellations**(`Hash`): `bool`
-- **summary**:   Record of all proposals that have been subject to emergency cancellation.
-
-▸ **delegations**(`AccountId`): `((AccountId,Conviction), Linkage<AccountId>)`
-- **summary**:   Get the account (and lock periods) to which another account is delegating vote.
-
-▸ **depositOf**(`PropIndex`): `Option<(BalanceOf,Vec<AccountId>)>`
-- **summary**:   Those who have locked a deposit.
-
-▸ **dispatchQueue**(`BlockNumber`): `Vec<Option<(Proposal,ReferendumIndex)>>`
-- **summary**:   Queue of successful referenda to be dispatched.
-
-▸ **lastTabledWasExternal**(): `bool`
-- **summary**:   True if the last referendum tabled was submitted externally. False if it was a public  proposal.
-
-▸ **nextExternal**(): `Option<(Proposal,VoteThreshold)>`
-- **summary**:   The referendum to be tabled whenever it would be valid to table an external proposal.  This happens when a referendum needs to be tabled and one of two conditions are met:  - `LastTabledWasExternal` is `false`; or  - `PublicProps` is empty.
-
-▸ **nextTally**(): `ReferendumIndex`
-- **summary**:   The next referendum index that should be tallied.
-
-▸ **proxy**(`AccountId`): `Option<AccountId>`
-- **summary**:   Who is able to vote for whom. Value is the fund-holding account, key is the  vote-transaction-sending account.
-
-▸ **publicPropCount**(): `PropIndex`
-- **summary**:   The number of (public) proposals that have been made so far.
-
-▸ **publicProps**(): `Vec<(PropIndex,Proposal,AccountId)>`
-- **summary**:   The public proposals. Unsorted.
-
-▸ **referendumCount**(): `ReferendumIndex`
-- **summary**:   The next free referendum index, aka the number of referenda started so far.
-
-▸ **referendumInfoOf**(`ReferendumIndex`): `Option<ReferendumInfo>`
-- **summary**:   Information concerning any given referendum.
-
-▸ **voteOf**(`(ReferendumIndex,AccountId)`): `Vote`
-- **summary**:   Get the vote in a given referendum of a particular voter. The result is meaningful only  if `voters_for` includes the voter when called with the referendum (you'll get the  default `Vote` value otherwise). If you don't want to check `voters_for`, then you can  also check for simple existence with `VoteOf::exists` first.
-
-▸ **votersFor**(`ReferendumIndex`): `Vec<AccountId>`
-- **summary**:   Get the voters for the current proposal.
-
-___
-
-
-### elections
-
-▸ **approvalsOf**(`(AccountId,SetIndex)`): `Vec<ApprovalFlag>`
-- **summary**:   A list of votes for each voter. The votes are stored as numeric values and parsed in a bit-wise manner.   In order to get a human-readable representation (`Vec<bool>`), use [`all_approvals_of`].   Furthermore, each vector of scalars is chunked with the cap of `APPROVAL_SET_SIZE`.
-
-▸ **candidateCount**(): `u32`
-- **summary**:   Current number of active candidates
-
-▸ **candidates**(): `Vec<AccountId>`
-- **summary**:   The present candidate list.
-
-▸ **desiredSeats**(): `u32`
-- **summary**:   Number of accounts that should constitute the collective.
-
-▸ **leaderboard**(): `Option<Vec<(BalanceOf,AccountId)>>`
-- **summary**:   Get the leaderboard if we're in the presentation phase. The first element is the weight of each entry;  It may be the direct summed approval stakes, or a weighted version of it.
-
-▸ **members**(): `Vec<(AccountId,BlockNumber)>`
-- **summary**:   The current membership. When there's a vote going on, this should still be used for executive  matters. The block number (second element in the tuple) is the block that their position is  active until (calculated by the sum of the block number when the member was elected  and their term duration).
-
-▸ **nextFinalize**(): `Option<(BlockNumber,u32,Vec<AccountId>)>`
-- **summary**:   The accounts holding the seats that will become free on the next tally.
-
-▸ **nextVoterSet**(): `SetIndex`
-- **summary**:   the next free set to store a voter in. This will keep growing.
-
-▸ **presentationDuration**(): `BlockNumber`
-- **summary**:   How long to give each top candidate to present themselves after the vote ends.
-
-▸ **proxy**(`AccountId`): `Option<AccountId>`
-- **summary**:   Who is able to vote for whom. Value is the fund-holding account, key is the  vote-transaction-sending account.
-
-▸ **registerInfoOf**(`AccountId`): `Option<(VoteIndex,u32)>`
-- **summary**:   The vote index and list slot that the candidate `who` was registered or `None` if they are not  currently registered.
-
-▸ **termDuration**(): `BlockNumber`
-- **summary**:   How long each position is active for.
-
-▸ **voteCount**(): `VoteIndex`
-- **summary**:   The total number of vote rounds that have happened or are in progress.
-
-▸ **voterCount**(): `SetIndex`
-- **summary**:   Current number of Voters.
-
-▸ **voterInfoOf**(`AccountId`): `Option<VoterInfo>`
-- **summary**:   Basic information about a voter.
-
-▸ **voters**(`SetIndex`): `Vec<Option<AccountId>>`
-- **summary**:   The present voter list (chunked and capped at [`VOTER_SET_SIZE`]).
-
-___
-
-
-### grandpa
-
-▸ **authorities**(): `Vec<(AuthorityId,AuthorityWeight)>`
-- **summary**:   The current authority set.
-
-▸ **nextForced**(): `Option<BlockNumber>`
-- **summary**:   next block number where we can force a change.
-
-▸ **pendingChange**(): `Option<StoredPendingChange>`
-- **summary**:   Pending change: (signaled at, scheduled change).
-
-▸ **stalled**(): `Option<(BlockNumber,BlockNumber)>`
-- **summary**:   `true` if we are currently stalled.
-
-▸ **state**(): `StoredState`
-- **summary**:   State of the current authority set.
-
-___
-
-
-### imOnline
-
-▸ **gossipAt**(): `BlockNumber`
-- **summary**:   The block number when we should gossip.
-
-▸ **keys**(): `Vec<AuthorityId>`
-- **summary**:   The current set of keys that may issue a heartbeat.
-
-▸ **receivedHeartbeats**(`SessionIndex, AuthIndex`): `Bytes`
-- **summary**:   For each session index we keep a mapping of `AuthorityId`  to `offchain::OpaqueNetworkState`.
-
-___
-
-
-### indices
-
-▸ **enumSet**(`AccountIndex`): `Vec<AccountId>`
-- **summary**:   The enumeration sets.
-
-▸ **nextEnumSet**(): `AccountIndex`
-- **summary**:   The next free enumeration set.
-
-___
-
-
-### offences
-
-▸ **concurrentReportsIndex**(`Kind, OpaqueTimeSlot`): `Vec<ReportIdOf>`
-- **summary**:   A vector of reports of the same kind that happened at the same time slot.
-
-▸ **reports**(`ReportIdOf`): `Option<OffenceDetails>`
-- **summary**:   The primary structure that holds all offence records keyed by report identifiers.
-
-▸ **reportsByKindIndex**(`Kind`): `Bytes`
-- **summary**:   Enumerates all reports of a kind along with the time they happened.   All reports are sorted by the time of offence.   Note that the actual type of this mapping is `Vec<u8>`, this is because values of  different types are not supported at the moment so we are doing the manual serialization.
-
-___
-
-
-### session
-
-▸ **changed**(): `bool`
-- **summary**:   True if anything has changed in this session.
-
-▸ **currentIndex**(): `SessionIndex`
-- **summary**:   Current index of the session.
-
-▸ **keyOwner**(`Bytes, (KeyTypeId,Bytes)`): `Option<ValidatorId>`
-- **summary**:   The owner of a key. The second key is the `KeyTypeId` + the encoded key.   The first key is always `DEDUP_KEY_PREFIX` to have all the data in the same branch of  the trie. Having all data in the same branch should prevent slowing down other queries.
-
-▸ **nextKeys**(`Bytes, ValidatorId`): `Option<Keys>`
-- **summary**:   The next session keys for a validator.   The first key is always `DEDUP_KEY_PREFIX` to have all the data in the same branch of  the trie. Having all data in the same branch should prevent slowing down other queries.
-
-▸ **queuedChanged**(): `bool`
-- **summary**:   Queued keys changed.
-
-▸ **queuedKeys**(): `Vec<(ValidatorId,Keys)>`
-- **summary**:   The queued keys for the next session. When the next session begins, these keys  will be used to determine the validator's session keys.
-
-▸ **validators**(): `Vec<ValidatorId>`
-- **summary**:   The current set of validators.
-
-___
-
-
-### staking
-
-▸ **bonded**(`AccountId`): `Option<AccountId>`
-- **summary**:   Map from all locked "stash" accounts to the controller account.
-
-▸ **bondedEras**(): `Vec<(EraIndex,SessionIndex)>`
-- **summary**:   A mapping from still-bonded eras to the first session index of that era.
-
-▸ **currentElected**(): `Vec<AccountId>`
-- **summary**:   The currently elected validator set keyed by stash account ID.
-
-▸ **currentEra**(): `EraIndex`
-- **summary**:   The current era index.
-
-▸ **currentEraRewards**(): `EraRewards`
-- **summary**:   Rewards for the current era. Using indices of current elected set.
-
-▸ **currentEraStart**(): `MomentOf`
-- **summary**:   The start of the current era.
-
-▸ **currentEraStartSessionIndex**(): `SessionIndex`
-- **summary**:   The session index at which the current era started.
-
-▸ **eraSlashJournal**(`EraIndex`): `Vec<SlashJournalEntry>`
-- **summary**:   All slashes that have occurred in a given era.
-
-▸ **forceEra**(): `Forcing`
-- **summary**:   True if the next session change will be a new era regardless of index.
-
-▸ **invulnerables**(): `Vec<AccountId>`
-- **summary**:   Any validators that may never be slashed or forcibly kicked. It's a Vec since they're  easy to initialize and the performance hit is minimal (we expect no more than four  invulnerables) and restricted to testnets.
-
-▸ **ledger**(`AccountId`): `Option<StakingLedger>`
-- **summary**:   Map from all (unlocked) "controller" accounts to the info regarding the staking.
-
-▸ **minimumValidatorCount**(): `u32`
-- **summary**:   Minimum number of staking participants before emergency conditions are imposed.
-
-▸ **nominators**(`AccountId`): `(Vec<AccountId>, Linkage<AccountId>)`
-- **summary**:   The map from nominator stash key to the set of stash keys of all validators to nominate.
-
-▸ **payee**(`AccountId`): `RewardDestination`
-- **summary**:   Where the reward payment should be made. Keyed by stash.
-
-▸ **slashRewardFraction**(): `Perbill`
-- **summary**:   The percentage of the slash that is distributed to reporters.   The rest of the slashed value is handled by the `Slash`.
-
-▸ **slotStake**(): `BalanceOf`
-- **summary**:   The amount of balance actively at stake for each validator slot, currently.   This is used to derive rewards and punishments.
-
-▸ **stakers**(`AccountId`): `Exposure`
-- **summary**:   Nominators for a particular account that is in action right now. You can't iterate  through validators here, but you can find them in the Session module.   This is keyed by the stash account.
-
-▸ **validatorCount**(): `u32`
-- **summary**:   The ideal number of staking participants.
-
-▸ **validators**(`AccountId`): `(ValidatorPrefs, Linkage<AccountId>)`
-- **summary**:   The map from (wannabe) validator stash key to the preferences of that validator.
-
-___
-
-
-### sudo
-
-▸ **key**(): `AccountId`
-- **summary**:   The `AccountId` of the sudo key.
-
-___
-
-
-### system
-
-▸ **accountNonce**(`AccountId`): `Index`
-- **summary**:   Extrinsics nonce for accounts.
-
-▸ **allExtrinsicsLen**(): `Option<u32>`
-- **summary**:   Total length (in bytes) for all extrinsics put together, for the current block.
-
-▸ **allExtrinsicsWeight**(): `Option<Weight>`
-- **summary**:   Total weight for all extrinsics put together, for the current block.
-
-▸ **blockHash**(`BlockNumber`): `Hash`
-- **summary**:   Map of block numbers to block hashes.
-
-▸ **digest**(): `DigestOf`
-- **summary**:   Digest of the current block, also part of the block header.
-
-▸ **eventCount**(): `EventIndex`
-- **summary**:   The number of events in the `Events<T>` list.
-
-▸ **events**(): `Vec<EventRecord>`
-- **summary**:   Events deposited for the current block.
-
-▸ **eventTopics**(`Null, Hash`): `Vec<(BlockNumber,EventIndex)>`
-- **summary**:   Mapping between a topic (represented by T::Hash) and a vector of indexes  of events in the `<Events<T>>` list.   The first key serves no purpose. This field is declared as double_map just  for convenience of using `remove_prefix`.   All topic vectors have deterministic storage locations depending on the topic. This  allows light-clients to leverage the changes trie storage tracking mechanism and  in case of changes fetch the list of events of interest.   The value has the type `(T::BlockNumber, EventIndex)` because if we used only just  the `EventIndex` then in case if the topic has the same contents on the next block  no notification will be triggered thus the event might be lost.
-
-▸ **extrinsicCount**(): `Option<u32>`
-- **summary**:   Total extrinsics count for the current block.
-
-▸ **extrinsicData**(`u32`): `Bytes`
-- **summary**:   Extrinsics data for the current block (maps an extrinsic's index to its data).
-
-▸ **extrinsicsRoot**(): `Hash`
-- **summary**:   Extrinsics root of the current block, also part of the block header.
-
-▸ **nextWeightMultiplier**(): `WeightMultiplier`
-- **summary**:   The next weight multiplier. This should be updated at the end of each block based on the  saturation level (weight).
-
-▸ **number**(): `BlockNumber`
-- **summary**:   The current block number being processed. Set by `execute_block`.
-
-▸ **parentHash**(): `Hash`
-- **summary**:   Hash of the previous block.
-
-▸ **randomMaterial**(): `(i8,Vec<Hash>)`
-- **summary**:   Series of block headers from the last 81 blocks that acts as random seed material. This is arranged as a  ring buffer with the `i8` prefix being the index into the `Vec` of the oldest hash.
-
-___
-
-
-### technicalCommittee
-
-▸ **members**(): `Vec<AccountId>`
-- **summary**:   The current members of the collective. This is stored sorted (just by value).
-
-▸ **proposalCount**(): `u32`
-- **summary**:   Proposals so far.
-
-▸ **proposalOf**(`Hash`): `Option<Proposal>`
-- **summary**:   Actual proposal for a given hash, if it's current.
-
-▸ **proposals**(): `Vec<Hash>`
-- **summary**:   The hashes of the active proposals.
-
-▸ **voting**(`Hash`): `Option<Votes>`
-- **summary**:   Votes on a given proposal, if it is ongoing.
-
-___
-
-
-### technicalMembership
-
-▸ **members**(): `Vec<AccountId>`
-- **summary**:   The current membership, stored as an ordered Vec.
-
-___
-
-
-### timestamp
-
-▸ **didUpdate**(): `bool`
-- **summary**:   Did the timestamp get updated in this block?
-
-▸ **now**(): `Moment`
-- **summary**:   Current time for the current block.
-
-___
-
-
-### treasury
-
-▸ **approvals**(): `Vec<ProposalIndex>`
-- **summary**:   Proposal indices that have been approved but not yet awarded.
-
-▸ **proposalCount**(): `ProposalIndex`
-- **summary**:   Number of proposals that have been made.
-
-▸ **proposals**(`ProposalIndex`): `Option<TreasuryProposal>`
-- **summary**:   Proposals that have been made.
-
----
-
-### substrate
-
-_These are keys that are always available to the runtime implementation_
-
-▸ **changesTrieConfig**(): `u32`
-- **summary**: Changes trie configuration is stored under this key.
-
-▸ **childStorageKeyPrefix**(): `u32`
-- **summary**: Prefix of child storage keys.
-
-▸ **code**(): `Bytes`
-- **summary**: Wasm code of the runtime.
-
-▸ **extrinsicIndex**(): `u32`
-- **summary**: Current extrinsic index (u32) is stored under this key.
-
-▸ **heapPages**(): `u64`
-- **summary**: Number of wasm linear memory pages required for execution of the runtime.
-
----

docs/README.md

@@ -20,8 +20,8 @@ footer: Apache-2 Licensed | Copyright © 2017-2019 polkadot-js authors and contr
 
 The API provides application developers the ability to query a node and interact with the Polkadot or Substrate chains using Javascript. Here you will find documentation and examples to get you started.
 
-::: tip Examples
-In a rush and just want examples? [Jump right in](/examples/promise/) and get a handle on using the API in your projects.
+::: tip Getting started & Examples
+[Jump right in](/start/) and get an overview on using the API in your projects, from installation all the way through to making it do magic.  Already understand how things work and just want the examples? [The ApiPromise examples](/examples/promise/) provide some basic recipies.
 :::
 
 ## Available packages

docs/SUMMARY.md

@@ -1,3 +1,23 @@
+## Getting started
+
+- [Introduction](start/README.md)
+  - [Installation](start/install.md)
+  - [Basics](start/basics.md)
+  - [Creating](start/create.md)
+  - [Constant queries](start/api.consts.md)
+  - [State queries](start/api.query.md)
+  - [RPC queries](start/api.rpc.md)
+  - [State subscriptions](start/api.query.subs.md)
+  - [Multi state retrieval](start/api.query.multi.md)
+  - [State query utilities](start/api.query.other.md)
+  - [Transactions](start/api.tx.md)
+  - [Keyring](start/keyring.md)
+  - [Transaction subscriptions](start/api.tx.subs.md)
+  - [Complex transactions](start/api.tx.wrap.md)
+  - [Type basics](start/types.basics.md)
+  - [Type extension](start/types.extend.md)
+  - [TypeScript interfaces](start/typescript.md)
+
 ## Packages
 
 - [api](api/README.md)
@@ -10,13 +30,15 @@
 
 ## Interfaces
 
-- [RPC](METHODS_RPC.md)
-- [Constants (runtime)](METHODS_CONSTANTS.md)
-- [Chain state (runtime)](METHODS_STORAGE.md)
-- [Extrinsics (runtime)](METHODS_EXTRINSICS.md)
-- [Events (runtime)](METHODS_EVENTS.md)
+- [Substrate](substrate/README.md)
+  - [RPC](substrate/rpc.md)
+  - [Constants (runtime)](substrate/constants.md)
+  - [Chain state (runtime)](substrate/storage.md)
+  - [Extrinsics (runtime)](substrate/extrinsics.md)
+  - [Events (runtime)](substrate/events.md)
 
 ## Examples
+
 - [ApiPromise](examples/promise/README.md)
   - [Simple connect](examples/promise/01_simple_connect/README.md)
   - [Listen to blocks](examples/promise/02_listen_to_blocks/README.md)
@@ -24,7 +46,7 @@
   - [Unsubscribe from listening](examples/promise/04_unsubscribe/README.md)
   - [Read chain state](examples/promise/05_read_storage/README.md)
   - [Make a transfer](examples/promise/06_make_transfer/README.md)
-  - [Display system events](examples/promise/08_system_events/README.md)(
+  - [Display system events](examples/promise/08_system_events/README.md)
   - [Transaction with events](examples/promise/09_transfer_events/README.md)
   - [Upgrade via sudo](examples/promise/10_upgrade_chain/README.md)
 - [ApiRx](examples/rx/README.md)

docs/examples/promise/01_simple_connect/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Required imports
 const { ApiPromise, WsProvider } = require('@polkadot/api');

docs/examples/promise/02_listen_to_blocks/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');
@@ -8,13 +10,13 @@ async function main () {
   // the API has connected to the node and completed the initialisation process
   const api = await ApiPromise.create();
 
-  // we only display a couple, then unsubscribe
+  // We only display a couple, then unsubscribe
   let count = 0;
 
   // Subscribe to the new headers on-chain. The callback is fired when new headers
   // are found, the call itself returns a promise with a subscription that can be
   // used to unsubscribe from the newHead subscription
-  const unsubscribe = await api.rpc.chain.subscribeNewHead((header) => {
+  const unsubscribe = await api.rpc.chain.subscribeNewHeads((header) => {
     console.log(`Chain is at block: #${header.number}`);
 
     if (++count === 256) {

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

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');

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

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');

docs/examples/promise/04_unsubscribe/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');
@@ -6,8 +8,8 @@ async function main () {
   // Create a new instance of the api
   const api = await ApiPromise.create();
 
-  // Subscribe to chain updates and log the current block  number on update.
-  const unsubscribe = await api.rpc.chain.subscribeNewHead((header) => {
+  // Subscribe to chain updates and log the current block number on update.
+  const unsubscribe = await api.rpc.chain.subscribeNewHeads((header) => {
     console.log(`Chain is at block: #${header.number}`);
   });
 

docs/examples/promise/05_read_storage/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');

docs/examples/promise/05_read_storage_at/README.md

@@ -2,4 +2,4 @@
 
 In addition to querying the latest storage, you can make storage queries at a specific blockhash. Be aware that the node applies a pruning strategy and typically only keeps the last 256 blocks, unless run in archive mode.
 
-<<< @/docs/examples/promise/07_read_storage_at/index.js
+<<< @/docs/examples/promise/05_read_storage_at/index.js

docs/examples/promise/05_read_storage_at/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');
@@ -10,18 +12,18 @@ async function main () {
   // Create our API with a default connection to the local node
   const api = await ApiPromise.create();
 
-  // retrieve the last block header, extracting the hash and parentHash
+  // Retrieve the last block header, extracting the hash and parentHash
   const { hash, parentHash } = await api.rpc.chain.getHeader();
 
   console.log(`last header hash ${hash.toHex()}`);
 
-  // retrieve the balance at the preceding block for Alice. For at queries
+  // Retrieve the balance at the preceding block for Alice. For at queries
   // the format is always `.at(<blockhash>, ...params)`
   const balance = await api.query.balances.freeBalance.at(parentHash, ALICE);
 
   console.log(`Alice's balance at ${parentHash.toHex()} was ${balance}`);
 
-  // now perform a multi query, returning multiple balances at once
+  // Now perform a multi query, returning multiple balances at once
   const balances = await api.query.balances.freeBalance.multi([ALICE, BOB]);
 
   console.log(`Current balances for Alice and Bob are ${balances[0]} and ${balances[1]}`);

docs/examples/promise/06_make_transfer/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API, Keyring and some utility functions
 const { ApiPromise } = require('@polkadot/api');
@@ -12,7 +14,7 @@ async function main () {
   // Constuct the keying after the API (crypto has an async init)
   const keyring = new Keyring({ type: 'sr25519' });
 
-  // Add alice to our keyring with a hard-deived path (empty phrase, so uses dev)
+  // Add Alice to our keyring with a hard-deived path (empty phrase, so uses dev)
   const alice = keyring.addFromUri('//Alice');
 
   // Create a extrinsic, transferring 12345 units to Bob

docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API, Keyring and some utility functions
 const { ApiPromise } = require('@polkadot/api');
@@ -13,16 +15,16 @@ async function main () {
   // Constuct the keying after the API (crypto has an async init)
   const keyring = new Keyring({ type: 'sr25519' });
 
-  // Add alice to our keyring with a hard-derived path (empty phrase, so uses dev)
+  // Add Alice to our keyring with a hard-derived path (empty phrase, so uses dev)
   const alice = keyring.addFromUri('//Alice');
 
   // Get nonce for account
   const nonce = await api.query.system.accountNonce(alice.address);
 
-  // get current block
+  // Get current block
   const signedBlock = await api.rpc.chain.getBlock();
 
-  // get current block height and hash
+  // Get current block height and hash
   const currentHeight = signedBlock.block.header.number;
   const blockHash = signedBlock.block.header.hash;
 

docs/examples/promise/07_make_transfer_with_allowed_block_permissions_only/package.json

@@ -10,8 +10,7 @@
     "start": "node index.js"
   },
   "dependencies": {
-    "@polkadot/api": "0.80.1",
-    "@polkadot/keyring": "^0.93.1"
+    "@polkadot/api": "*"
   },
   "devDependencies": {
     "rimraf": "^2.6.2"

docs/examples/promise/08_system_events/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiPromise } = require('@polkadot/api');
@@ -6,21 +8,21 @@ async function main () {
   // Create our API with a default connection to the local node
   const api = await ApiPromise.create();
 
-  // subscribe to system events via storage
+  // Subscribe to system events via storage
   api.query.system.events((events) => {
     console.log(`\nReceived ${events.length} events:`);
 
-    // loop through the Vec<EventRecord>
+    // Loop through the Vec<EventRecord>
     events.forEach((record) => {
-      // extract the phase, event and the event types
+      // Extract the phase, event and the event types
       const { event, phase } = record;
       const types = event.typeDef;
 
-      // show what we are busy with
+      // Show what we are busy with
       console.log(`\t${event.section}:${event.method}:: (phase=${phase.toString()})`);
       console.log(`\t\t${event.meta.documentation.toString()}`);
 
-      // loop through each of the parameters, displaying the type and data
+      // Loop through each of the parameters, displaying the type and data
       event.data.forEach((data, index) => {
         console.log(`\t\t\t${types[index].type}: ${data.toString()}`);
       });

docs/examples/promise/09_transfer_events/index.js

@@ -1,14 +1,16 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API & Provider and some utility functions
 const { ApiPromise } = require('@polkadot/api');
 
-// import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+// Import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
 const testKeyring = require('@polkadot/keyring/testing');
 
-// utility function for random values
+// Utility function for random values
 const { randomAsU8a } = require('@polkadot/util-crypto');
 
-// some constants we are using in this sample
+// Some constants we are using in this sample
 const ALICE = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
 const AMOUNT = 10000;
 
@@ -16,18 +18,18 @@ async function main () {
   // Create the API and wait until ready
   const api = await ApiPromise.create();
 
-  // create an instance of our testing keyring
+  // Create an instance of our testing keyring
   // If you're using ES6 module imports instead of require, just change this line to:
   // const keyring = testKeyring();
   const keyring = testKeyring.default();
 
-  // get the nonce for the admin key
+  // Get the nonce for the admin key
   const nonce = await api.query.system.accountNonce(ALICE);
 
-  // find the actual keypair in the keyring
+  // Find the actual keypair in the keyring
   const alicePair = keyring.getPair(ALICE);
 
-  // create a new random recipient
+  // Create a new random recipient
   const recipient = keyring.addFromSeed(randomAsU8a(32)).address;
 
   console.log('Sending', AMOUNT, 'from', alicePair.address, 'to', recipient, 'with nonce', nonce.toString());
@@ -35,8 +37,7 @@ async function main () {
   // Do the transfer and track the actual status
   api.tx.balances
     .transfer(recipient, AMOUNT)
-    .sign(alicePair, { nonce })
-    .send(({ events = [], status }) => {
+    .signAndSend(alicePair, { nonce }, ({ events = [], status }) => {
       console.log('Transaction status:', status.type);
 
       if (status.isFinalized) {

docs/examples/promise/10_upgrade_chain/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API & Provider and some utility functions
 const { ApiPromise, WsProvider } = require('@polkadot/api');
@@ -14,22 +16,24 @@ async function main () {
   // Create the API and wait until ready (optional provider passed through)
   const api = await ApiPromise.create({ provider });
 
-  // retrieve the upgrade key from the chain state
+  // Retrieve the upgrade key from the chain state
   const adminId = await api.query.sudo.key();
 
-  // find the actual keypair in the keyring (if this is an changed value, the key
+  // Find the actual keypair in the keyring (if this is a changed value, the key
   // needs to be added to the keyring before - this assumes we have defaults, i.e.
   // Alice as the key - and this already exists on the test keyring)
   const keyring = testKeyring.default();
   const adminPair = keyring.getPair(adminId.toString());
 
-  // retrieve the runtime to upgrade to
+  // Retrieve the runtime to upgrade
   const code = fs.readFileSync('./test.wasm').toString('hex');
-  const proposal = api.tx.consensus.setCode(`0x${code}`);
+  const proposal = api.tx.system && api.tx.system.setCode
+    ? api.tx.system.setCode(`0x${code}`) // For newer versions of Substrate
+    : api.tx.consensus.setCode(`0x${code}`); // For previous versions
 
   console.log(`Upgrading from ${adminId}, ${code.length / 2} bytes`);
 
-  // preform the actual chain upgrade via the sudo module
+  // Perform the actual chain upgrade via the sudo module
   api.tx.sudo
     .sudo(proposal)
     .signAndSend(adminPair, ({ events = [], status }) => {

docs/examples/rx/01_simple_connect/index.js

@@ -1,10 +1,12 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Required imports
 const { zip } = require('rxjs');
 const { ApiRx } = require('@polkadot/api');
 const { WsProvider } = require('@polkadot/rpc-provider');
 
-function main () {
+async function main () {
   // Initialise the provider to connect to the local node
   const provider = new WsProvider('ws://127.0.0.1:9944');
 

docs/examples/rx/02_listen_to_blocks/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiRx } = require('@polkadot/api');
@@ -10,7 +12,7 @@ async function main () {
   new ApiRx().isReady
     .pipe(
       switchMap((api) =>
-        api.rpc.chain.subscribeNewHead()
+        api.rpc.chain.subscribeNewHeads()
       ))
     .subscribe((header) => {
       console.log(`Chain is at block: #${header.number}`);

docs/examples/rx/03_listen_to_balance_change/README.md

@@ -2,4 +2,4 @@
 
 This example shows how to instantiate a Polkadot API object and use it to connect to a node and retrieve balance updates.
 
-<<< @/docs/examples/rx/03_listent_to_balance_change/index.js
+<<< @/docs/examples/rx/03_listen_to_balance_change/index.js

docs/examples/rx/03_listen_to_balance_change/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API and operators from RxJs
 const { ApiRx } = require('@polkadot/api');

docs/examples/rx/04_unsubscribe/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiRx } = require('@polkadot/api');
@@ -5,11 +7,11 @@ const { switchMap } = require('rxjs/operators');
 
 async function main () {
   // Create a new instance of the api
-  // Subscribe to chain updates and log the current block  number on update.
+  // Subscribe to chain updates and log the current block number on update.
   const subscription = new ApiRx().isReady
     .pipe(
       switchMap((api) =>
-        api.rpc.chain.subscribeNewHead()
+        api.rpc.chain.subscribeNewHeads()
       ))
     .subscribe((header) => {
       console.log(`Chain is at block: #${header.number}`);

docs/examples/rx/05_read_storage/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API
 const { ApiRx } = require('@polkadot/api');

docs/examples/rx/06_make_transfer/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API, Keyring and some utility functions
 const { ApiRx } = require('@polkadot/api');
@@ -10,13 +12,13 @@ async function main () {
   const api = await ApiRx.create().toPromise();
 
   // Create an instance of the keyring
-  const keyring = new Keyring({ type: 's25519' });
+  const keyring = new Keyring({ type: 'sr25519' });
 
   // Add Alice to our keyring (with the known seed for the account)
-  const alice = keyring.addFomUri('//Alice');
+  const alice = keyring.addFromUri('//Alice');
 
-  //  Create a extrinsic, transferring 12345 units to Bob.
-  api.tx.balances
+  // Create a extrinsic, transferring 12345 units to Bob.
+  const subscription = api.tx.balances
     // create transfer
     .transfer(BOB, 12345)
     // Sign and send the transcation
@@ -25,10 +27,11 @@ async function main () {
     .subscribe(({ status }) => {
       if (status.isFinalized) {
         console.log(`Successful transfer of 12345 from Alice to Bob with hash ${status.asFinalized.toHex()}`);
+        subscription.unsubscribe();
       } else {
-        console.log(`Staus of transfer: ${status.type}`);
+        console.log(`Status of transfer: ${status.type}`);
       }
     });
 }
 
-main().catch(console.error).finally(() => process.exit());
+main().catch(console.error);

docs/examples/rx/08_system_events/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API and selected RxJs operators
 const { switchMap } = require('rxjs/operators');

docs/examples/rx/09_transfer_events/index.js

@@ -1,14 +1,16 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API and some utility functions
 const { ApiRx } = require('@polkadot/api');
 
-// import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+// Import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
 const testKeyring = require('@polkadot/keyring/testing');
 
-// utility function for random values
+// Utility function for random values
 const { randomAsU8a } = require('@polkadot/util-crypto');
 
-// some constants we are using in this sample
+// Some constants we are using in this sample
 const ALICE = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
 const AMOUNT = 10000;
 
@@ -16,21 +18,21 @@ async function main () {
   // Create our API with a connection to the node
   const api = await ApiRx.create().toPromise();
 
-  // create an instance of our testign keyring
+  // Create an instance of our testign keyring
   // If you're using ES6 module imports instead of require, just change this line to:
   // const keyring = testKeyring();
   const keyring = testKeyring.default();
 
-  // find the actual keypair in the keyring
+  // Find the actual keypair in the keyring
   const alicePair = keyring.getPair(ALICE);
 
-  // create a new random recipient
+  // Create a new random recipient
   const recipient = keyring.addFromSeed(randomAsU8a(32)).address;
 
   console.log('Sending', AMOUNT, 'from', alicePair.address, 'to', recipient);
 
-  // get the nonce for the admin key
-  //  Create a extrinsic, transferring 12345 units to Bob.
+  // Get the nonce for the admin key
+  // Create a extrinsic, transferring 12345 units to Bob.
   api.tx.balances
     // Do the transfer
     .transfer(recipient, AMOUNT)

docs/examples/rx/10_upgrade_chain/index.js

@@ -1,7 +1,9 @@
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/unbound-method */
 /* eslint-disable @typescript-eslint/no-var-requires */
 // Import the API & Provider and some utility functions
 const { ApiRx, WsProvider } = require('@polkadot/api');
-// import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
+// Import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
 const testKeyring = require('@polkadot/keyring/testing');
 const fs = require('fs');
 
@@ -12,27 +14,28 @@ async function main () {
   // Create the API and wait until ready (optional provider passed through)
   const api = await ApiRx.create({ provider }).toPromise();
 
-  // retrieve the upgrade key from the chain state
+  // Retrieve the upgrade key from the chain state
+  // TODO It seems like this promise doesn't resolve
   const adminId = await api.query.sudo.key().toPromise();
 
-  // find the actual keypair in the keyring (if this is an changed value, the key
+  // Find the actual keypair in the keyring (if this is an changed value, the key
   // needs to be added to the keyring before - this assumes we have defaults, i.e.
   // Alice as the key - and this already exists on the test keyring)
   const keyring = testKeyring.default();
   const adminPair = keyring.getPair(adminId.toString());
 
-  // retrieve the runtime to upgrade to
+  // Retrieve the runtime to upgrade to
   const code = fs.readFileSync('./test.wasm').toString('hex');
   const proposal = api.tx.consensus.setCode(`0x${code}`);
 
   console.log(`Upgrading chain runtime from ${adminId}`);
 
   api.tx.sudo
-    // preform the actual chain upgrade via the sudo module
+    // Perform the actual chain upgrade via the sudo module
     .sudo(proposal)
-    // sign and send the proposal
+    // Sign and send the proposal
     .signAndSend(adminPair)
-    // subscribe to overall result
+    // Subscribe to overall result
     .subscribe(({ events = [], status }) => {
       // Log transfer events
       console.log('Proposal status:', status.type);

docs/start/.TODOS.md

@@ -0,0 +1,5 @@
+... somewhere also need a signer injection section, something along the lines of the singlesigner or this https://github.com/polkadot-js/tools/blob/master/packages/signer-cli/src/cmdSubmit.ts#L12
+
+... DoubleMap & LinkedMap examples
+
+... api.derive

docs/start/FAQ.md

@@ -0,0 +1,35 @@
+# FAQ
+
+The list will be updated/expanded as questions come up, dealing with some common issues that API users find.
+
+## I am getting a "Unknown types found, no types for ..." error
+
+There are 2 causes for this, both related to the version of the API that you are using and the support of types. As explained in the elsewhere, types on Polkadot/Substrate are continuously evolving - the latest version of the API always tries to support types for the latest Polkadot networks, such as [Kusama](https://kusama.network/). So for Polkadot public chains, ensure that you are using the latest released API version.
+
+If however you are running against a master branch of either Polkadot or Substrate, you may well be better suited running [a beta version, tracking master](install.md#betas). If you are connected to a customized chain, you would rather want to [register the types](types.extend.md) either on your own, or via packages that the chain vendor provides.
+
+## I am getting a "Metadata:: failed on MagicNumber" error
+
+Update your version of the API to the [latest version](install.md). Like types, the [metadata interfaces](basics.md) are continuously evolving. For instance with the Polkadot Alexander network, only metadata v3 is available. By the time Kusama launched, this has been bumped to v7. As these versions are added to the Polkadot/Substrate codebase, they are added to the API.
+
+## I would like to sign transactions offline
+
+The API itself is independent on where the signature comes from and how it is injected. Additionally it implements a signer interface, that can be used for external signing - an example of this is the [polkadot-js/apps](https://github.com/polkadot-js/apps) support for signing via extensions and even the [polkadot-js/extension](https://github.com/polkadot-js/extension) support for tools such as the [Parity Signer](https://github.com/paritytech/parity-signer).
+
+As of this writing we don't have an explicit example of implementing the signer interface in these docs, although we do use one in [our tests](https://github.com/polkadot-js/api/blob/master/packages/api/test/util/SingleAccountSigner.ts). Additionally, the [polkadot-js/tools](https://github.com/polkadot-js/tools) has an implementation of [a very basic offline signer](https://github.com/polkadot-js/tools/tree/master/packages/signer-cli) where transactions are generated in one process and signatures in another non-connected process.
+
+## I would like to send a root transaction
+
+Some calls in Polkadot/Substrate can only be submitted as root, these are indicated by `ensure_root(origin)` in the Rust codebase. Root here does not refer to the actual account, i.e. `//Alice` on  a `--dev` chain, but rather that it cannot be submitted as a bare user transaction. This restriction applies to chain upgrades, changing balances or anything that modifies the state and/or chain operation.
+
+To submit these transactions, it needs to be send as a [wrapped transaction](api.tx.wrap.md#sudo-use) via either `sudo.sudo` (assuming you have access on your chain) or `democracy.proposal` (which would allow users of the chain to vote on it).
+
+## How do I call a function with a Tuple input
+
+Tuples, as defined in the Polkadot/Substrate types appear as `(TypeA, TypeB)`. For instance we may have an `(AccountId, u64)` input as defined in the metadata or as part of the user types. To specify a Tuple as an input, wrap it is an  array format, for instance to call `query.module.get((u32, u64))` where a `(u32, u64)` Tuple input is expected, you would do  `query.module.get([123, 456])`
+
+## How long do transactions live
+
+Polkadot/Substrate supports both immortal and mortal transactions. For immortal, this means that the transaction has an infinite lifetime, for mortals, the transactions expire after a defined period. By default the API sends mortal transactions when no explicit extrinsic era has been specified. This means that all transaction has a limited lifetime and will expire if not included in the period set.
+
+The length for this transaction validity is set to 50 blocks, which translates to 5 minutes assuming a default of 6 second blocktimes. (10 blocks per minute in this default configuration).

docs/start/README.md

@@ -0,0 +1,15 @@
+# Getting started
+
+These sections should provide you with all the information needed to install the `@polkadot/api` package, understand the structure of the interfaces and allow you to start using it. For existing users this really should be titled "Things I wish I knew before I started using the api" - it really aims to close the gap to allow anybody to get to grips with using the packages.
+
+## What this is not
+
+This is not line-by-line documentation of all the existing function calls available, nor it is tied to a specific chain. (Although the examples do refer to the base Polkadot & Substrate chains). There will be some things in the API that are probably not covered, which brings us to the next point...
+
+## Help us help others
+
+If you spot gaps in the information provided, or are uncertain about any specific area, please do [log an issue](https://github.com/polkadot-js/api/issues) or if you are that way inclined, make a pull-request. We really want to have good documentation in these areas and allow people to be productive right from the start.
+
+## Ready? Steady? Go!
+
+If you already have a good grasp on the API and are just looking for a specific answer, you may want to take a look at the [Frequently Asked Questions](FAQ.md). With all that said, let's get started... [What should be installed, and how should we do it?](install.md)

docs/start/api.consts.md

@@ -0,0 +1,34 @@
+# Runtime Constants
+
+Constant queries will introduce you to the concepts behind the types and the interaction of the API with those types. The same concepts are implemented in the remainder of the API - the runtime constants is just the simplest starting point.
+
+For some background: constants are values that are defined in the runtime and used as part of chain operations. These constants can be changed as part of an upgrade.
+
+```js
+// Initialize the API as per previous sections
+...
+
+// The length of an epoch (session) in Babe
+console.log(api.consts.babe.epochDuration.toNumber());
+
+// The amount required to create a new account
+console.log(api.consts.balances.creationFee.toNumber());
+
+// The amount required per byte on an extrinsic
+console.log(api.consts.balances.transactionByteFee.toNumber());
+```
+
+Since these are constants and defined by the metadata, it is not a call, but rather the values immediately available - as you'll see in subsequent sections, there is no need for `await` on these, it immediately returns the type and value for you to work with.
+
+## The API and types
+
+There is some magic applied by the API. For instance as the `createFee` result is returned, the API knows the expected type and makes a `Balance` object available, hence the `toNumber`. This result mapping is consistent in retrieving constants, making queries or even sending transactions:
+
+- when values are passed to the API, the API will convert whatever is provided into the correct type as required by the call
+- when a value is retrieved, the API will provide an object of the correct type that wraps this value
+
+From the last point, this means that a `Balance` will be returned as a number object extending [bn.js](https://github.com/indutny/bn.js/). In a later section we will go through a breakdown of all the commonly-used types and all [the basics available on types](types.basics.md).
+
+## Making queries
+
+In the next section we will take an initial dive into [chain state and state queries](api.query.md), allowing the use of the API to retrieve information contained in the chain state.

docs/start/api.query.md

@@ -0,0 +1,48 @@
+# State queries
+
+In previous sections, we initialized the API and retrieved runtime constants. This section will walk through the concepts behind making queries to the chain to retrieve current state. The `api.query.<module>.<method>` interfaces, as already described earlier, is populated from the metadata. The API uses the metadata information provided to construct queries based on the location and parameters provided to generate state keys, and then queries these via RPC.
+
+## Basic queries
+
+Let's dive right in, connect to a general chain and retrieve some information on the current state. Of interest may be retrieving the nonce of a particular account as well as the current balance, this can be achieved via -
+
+```js
+// Initialize the API as in previous sections
+...
+
+// The actual address that we will use
+const ADDR = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFabHE';
+
+// Retrieve the last timestamp
+const now = await api.query.timestamp.now();
+
+// Retrieve the account nonce via the system module
+const nonce = await api.query.system.accountNonce(ADDR);
+
+// Retrieve the account balance via the balances module
+const balance = await api.query.balances.freeBalance(ADDR);
+
+console.log(`${now}: balance of ${balance} and a nonce of ${nonce}`);
+```
+
+There have been some additions in the code above comparing with retrieving runtime constants. In these cases, since we are making a query to the actual chain, we use the `await` syntax to retrieve the information. Since the API is Promise-based, this means we can also rewrite the above to follow a Promise pattern,
+
+```js
+...
+// Retrieve last block timestamp, account nonce & balance
+const [now, nonce, balance] = await Promise.all([
+  api.query.timestamp.now(),
+  api.query.system.accountNonce(ADDR),
+  api.query.balances.freeBalance(ADDR)
+]);
+```
+
+## Parameters & return values
+
+As indicated in previous sections, any return value is always an object with a consistent interface that reflects the type being returned. In the above example, the timestamp is a `Moment` (a `u64` value), the nonce is an `Index` (a `u32` value) and the `Balance` is an underlying `u128`.
+
+Additionally we have provided some parameters for the query calls, specifically for the retrieval of the nonce and balance. It is important to note that the API will automatically convert any parameters into the correct type for encoding and making calls, in this case the `AccountId` parameter could be specified as a ss58 address (as it was), an actual `AccountId` (retrieved via another call) or just a plain `Uint8Array` (or even hex-string representation) for a publicKey.
+
+## Exploring RPCs
+
+Where all query functions use the underlying RPCs, together with metadata, to construct and retrieve information, the direct node RPCs can be seen as raw calls that enable these (slightly) higher-level operations. Next up we will take a dive into [making RPC calls via the API](api.rpc.md).

docs/start/api.query.multi.md

@@ -0,0 +1,60 @@
+# Multi queries
+
+In a number of applications, it is useful to monitor a number of like-queries at the same time. For instance, we may want to track the balances for a list of accounts we have. The `api.query` interfaces allows this via the `.multi` subscription call.
+
+## Multi queries, same type
+
+Where possible, the use of multi queries are encouraged since it tracks a number of state entries over a single RPC call, instead of making a call for each single item. In addition it allows you to have a single callback to track changes. For queries of the same type we can use `.multi`, for example to retrieve the balances of a number of accounts at once -
+
+```js
+...
+
+// Subscribe to balance changes for 2 accounts, ADDR1 & ADDR2 (already defined)
+const unsub = await api.query.balances.freeBalance.multi([ADDR1, ADDR2], (balances) => {
+  const [balance1, balance2] = balances;
+
+  console.log(`The balances are ${balance1} and ${balance2}`);
+});
+```
+
+A couple of items to note in the example above: we don't call `freeBalance` directly, but rather `freeBalance.multi`. We pass the addresses we want to query as an array, and the length thereof would depend on the number of addresses we want to query. As an extended example, we can track the balances of a list of validators,
+
+```js
+...
+
+// Retrieve a snapshot of the validators
+const validators = await api.query.session.validators();
+
+// Subscribe to the balances for these accounts
+const unsub = await api.query.balances.freeBalance.multi(validators, (balances) => {
+  console.log(`The balances are: ${balances}`);
+});
+```
+
+The above example does not subscribe to the validators explicitly, but only gets a snapshot and uses this into the future. It should be trivially extendable to subscribe to the validators, track which one have entered or left and then subscribe to balances as they change through the next blocks.
+
+## Multi queries, distinct types
+
+The previous `.multi` examples assumes that we do queries for the same types, i.e. we retrieve the balances for a number of accounts. However, there is also a need to retrieve various distinct types, as an example we would like to track the block timestamp in addition to the nonce and balance of a specific account. To cater for this, the api has a specific `api.queryMulti` interface that can be used to perform this query -
+
+```js
+...
+
+// Subscribe to the timestamp, our index and balance
+const unsub = await api.queryMulti([
+  api.query.timestamp.now,
+  [api.query.system.accountNonce, ADDR],
+  [api.query.balances.freeBalance, ADDR]
+], ([now, nonce, balance]) => {
+  console.log(`${now}: balance of ${balance} and a nonce of ${nonce}`);
+});
+```
+
+The above example certainly does not quite look as ergonomic and clean, but the API needs to understand (a) which are all the calls we need to make and (b) the calls and their params (if required). So breaking it down -
+
+- `api.query.timestamp.now` - the timestamp is passed naked without any params. Also note that we do not call it while passing, but rather only provides a reference to the function, i.e. we do not have the expected `()` at the end. (This could also be of the form `[api.query.timestamp.now]`, aligning with subsequent entries)
+- `[api.query.system.accountNonce, ADDR]` - the nonce query is passed as an array containing the function (once again naked), followed by the parameters that apply.
+
+## Rounding out queries
+
+To round out our query introduction, there are a [number of other utilities and calls available](api.query.other.md) that allows the `api.query` user to perform certain tasks, such as querying state at a specific block. These are covered in the next section.

docs/start/api.query.other.md

@@ -0,0 +1,76 @@
+# Query extras
+
+In previous sections we took a walk through queries, showing how to use one-shot queries, how to subscribe to results and how to combine multiple queries into one. This section will aim to extend that knowledge showing some other features and utilities that are available on the `api.query` interfaces.
+
+## State at a specific block
+
+Quite often is is useful (taking pruning into account, more on this later) to retrieve the state at a specific block. For instance we may wish to retrieve the current balance as well as the balance at a previous block for a specific account -
+
+```js
+...
+
+// Retrieve the current block header
+const lastHdr = await api.rpc.chain.getHeader();
+
+// Retrieve the balance at both the current and the parent hashes
+const [balanceNow, balancePrev] = await Promise.all([
+  api.query.balances.freeBalance.at(lastHdr.hash, ADDR),
+  api.query.balances.freeBalance.at(lastHdr.parentHash, ADDR)
+]);
+
+// Display the difference
+console.log(`The delta was ${balanceNow.sub(balancePrev)}`);
+```
+
+In the above example, we introduce the `.at(<hash>[, ...params])` query. For all `.at` queries, the first parameter is always the block hash at which we want to make the query, in our example we use both the last retrieved block and the parent thereof. The params are optional as per the type of query made, for instance to retrieve the timestamp for a previous block, it would be -
+
+```js
+...
+
+// Retrieve the timestamp for the previous block
+const momentPrev = await api.query.timestamp.now.at(lastHdr.parentHash);
+```
+
+The `.at` queries are all single-shot, i.e. there are no subscription option to these, since the state for a previous block should be static. (This is true to a certain extent, i.e. when blocks have been finalized).
+
+An additional point to take care of (briefly mentioned above), is state pruning. By default a Polkadot/Substrate node will only keep state for the last 256 blocks, unless it is explicitly run in archive mode. This means that querying state further back than the pruning period will result in an error returned from the Node. (Generally most public RPC nodes only run with default settings, which includes aggressive state pruning)
+
+## State entries
+
+In addition to using `api.query` to make actual on-chain queries, it can also be used to retrieve some information on the state entries. For instance to retrieve both the hash and size of an existing entry, we can make the following calls -
+
+```js
+...
+
+// Retrieve the hash & size of the entry as stored on-chain
+const [entryHash, entrySize] = await Promise.all([
+  api.query.balances.freeBalance.hash(ADDR),
+  api.query.balances.freeBalance.size(ADDR)
+]);
+
+// Output the info
+console.log(`The current size is ${entrySize} bytes with a hash of ${entryHash}`);
+```
+
+As per the previous examples, the params here apply explicitly to the actual needed values to identify an entry. As with `.at` queries, there are no subscription versions for these queries, rather they are seen as one-shot values at a specific point in time.
+
+## Entry metadata
+
+It has been explained that the `api.query` interfaces are decorated from the metadata. This also means that there is some information that we can gather from the entry, as decorated -
+
+```js
+// Extract the info
+const { meta, method, section } = api.query.balances.freeBalance;
+
+// Display some info on a specific entry
+console.log(`${section}.${method}: ${meta.documentation.join(' ')}`);
+console.log(`query key: ${api.query.balances.freeBalance.key(ADDR)}`);
+```
+
+The `section` & `method` is an indication of where it is exposed on the API. In addition the `meta` holds an array with the metadata documentation for the entry.
+
+The `key` endpoint requires some explanation. In the chain state, the key values (identified by the module, method & params) are hashed and this is used as a lookup. So underlying a single-shot query would utilize the `api.rpc.state.getStorage` entry, passing the output of `key` (which is a hashed representation of the values). Apart from the hashing, the API also takes care of type formatting, handling optional values and merging results across multiple subscriptions.
+
+## Let's transact already!
+
+At this point you are already burning to actually make some transactions. Making queries is cool, but just how do [you actually submit transactions on-chain](api.tx.md).

docs/start/api.query.subs.md

@@ -0,0 +1,37 @@
+# Query subscriptions
+
+Previously we explained the concepts between `api.query`. In this section we will expand on that knowledge to introduce subscriptions (akin to what we found in `api.rpc`) to stream results from the state, as it changes between blocks.
+
+## Subscriptions
+
+As in the case with `api.rpc` subscriptions, query subscriptions follow exactly the same form - an actual call is augmented with a callback to return the current state value that is updated as the underlying value changes. As an example, we can extend on what we had previously -
+
+```js
+...
+
+// Retrieve the current timestamp via subscription
+const unsub = await api.query.timestamp.now((moment) => {
+  console.log(`The last block has a timestamp of ${moment}`);
+});
+```
+
+The form is exactly the same as the subscriptions we have seen previously, instead of the `await` returning the actual once-off value, it returns a subscription `unsub()` function that can be used to stop the subscription and clear up any underlying RPC connections. The supplied callback will contain the value as it changes, streamed from the node.
+
+## Subscriptions with params
+
+If we had a query with parameters, i.e. where we wish to perform a query for a specific account, the form is exactly the same - the last parameter contains the actual callback, after all other parameters. To retrieve the balances for an account as it changes, we could do the following -
+
+```js
+...
+
+// Subscribe to balance changes for our account
+const unsub = await api.query.balances.freeBalance(ADDR, (balance) => {
+  console.log(`Your account balance is ${balance}`);
+});
+```
+
+By now this subscription form should be familiar to you, including the usage of `unsub`.
+
+## Multiple queries
+
+In most non-trivial applications, it is useful to optimize both our code in terms of callbacks as well as node resources, for instance by [performing multiple queries at once, over the same RPC call](api.query.multi.md).

docs/start/api.rpc.md

@@ -0,0 +1,70 @@
+# RPC queries
+
+The RPC calls provide the backbone for the transmission of data to and from the node. This means that all API endpoints such as `api.query`, `api.tx` or `api.derive` just wrap RPC calls, providing information in the encoded format as expected by the node.
+
+Since you are already familiar with the `api.query` interface, the `api.rpc` interface follows the same format, for instance -
+
+```js
+...
+
+// Retrieve the chain name
+const chain = await api.rpc.system.chain();
+
+// Retrieve the latest header
+const lastHeader = await api.rpc.chain.getHeader();
+
+// Log the information
+console.log(`${chain}: last block #${lastHeader.number} has hash ${lastHeader.hash}`);
+```
+
+In this example, you will see the same pattern as with queries: each result is a promise and a simple `await` makes the query and resolves with the result.
+
+## Subscriptions
+
+The RPCs lend themselves to using subscriptions, for instance in the above case you would assume that once connected, the chain won't change, however new blocks will come in at intervals and we probably want to keep track of those. We can adapt the previous example to start using subscriptions -
+
+```js
+...
+
+// Subscribe to the new headers
+await api.rpc.chain.subscribeNewHeads((lastHeader) => {
+  console.log(`${chain}: last block #${lastHeader.number} has hash ${lastHeader.hash}`);
+});
+```
+
+Since we are dealing with a subscription, we now pass a callback into the `subscribeNewHeads` function, and this will be triggered on each header, as they are imported. The same pattern would apply to each of the `api.rpc.subscribe*` functions - as a last parameter a callback is to be provided that streams the latest data, as it becomes available.
+
+In general, whenever we create a subscription, we would like to cleanup after ourselves and unsubscribe, so assuming we only want to log the first 10 headers, the above example can be adjusted in the following manner -
+
+```js
+...
+let count = 0;
+
+// Subscribe to the new headers
+const unsubHeads = await api.rpc.chain.subscribeNewHeads((lastHeader) => {
+  console.log(`${chain}: last block #${lastHeader.number} has hash ${lastHeader.hash}`);
+
+  if (++count === 10) {
+    unsubHeads();
+  }
+});
+```
+
+Unlike single-shot queries, for subscriptions we are `await`-ing a function, taking no parameters (that also returns nothing) that can be used to unsubscribe for the subscription and clear the underlying RPC connection. So in the above example we set `unsubHeads` and then call it when we wish to cancel the subscription.
+
+## Detour into derives
+
+The `api.derive` interfaces will be covered in a follow-up section, but since the above example deals with new head subscriptions, a quick detour is warranted. The derives are just helpers that define certain functions and combine results from multiple sources. For new headers, the following information is useful in certain scenarios -
+
+```js
+...
+const unsub = await api.derive.chain.subscribeNewHeads((lastHeader) => {
+  console.log(`#${lastHeader.number} was authored by ${lastHeader.author}`);
+});
+```
+
+In the above case the `subscribeNewHeads` derive augments the header retrieved with an `.author` getter. This is done by parsing the actual header and logs received and filling in the author from the `api.query.session.validators` call.
+
+## Extended Queries
+
+As a next step, now that we have understood subscription and RPC basics, we will circle back to the `api.query` interface, [extending our queries with subscriptions](api.query.subs.md).

docs/start/api.tx.md

@@ -0,0 +1,40 @@
+# Transactions
+
+Transaction endpoints are exposed, as determined by the metadata, on the `api.tx` endpoint. These allow you to submit transactions for inclusion in blocks, be it transfers, setting information or anything else your chain supports.
+
+## Simple transactions
+
+To start off, let's make a balance transfer from Alice to Bob.
+
+```js
+...
+
+// Sign and send a transfer from Alice to Bob
+const txHash = await api.tx.balances
+  .transfer(BOB, 12345)
+  .signAndSend(alice);
+
+// Show the hash
+console.log(`Submitted with hash ${txHash}`);
+```
+
+We have already become familiar with the `Promise` syntax that is used throughout the API, in this case it is no different. We construct a transaction by calling `balances.transfer(<accountId>, <value>)` with the required params and then as a next step we submit it to the node.
+
+As with all other API operations, the `to` params just needs to be "account-like" and the value params needs to be "number-like", the API will take care of encoding and conversion into the correct format.
+
+The result for this call (we will deal with subscriptions in a short while), is the transaction hash. This is a hash of the data and receiving this does not mean that transaction has been included, but rather only that it has been accepted for propagation by the node. (It can still fail on execution, we will handle this in some of our follow-up sections.)
+
+## Under the hood
+
+Despite the single-line format of `signAndSend`, there is a lot happening under the hood (and all of this can be manually provided) -
+
+- Based on the sender, the API will retrieve the `system.accountNonce` to determine the next nonce to use
+- The API will retrieve the current block hash and use it to create a mortal transaction, i.e. the transaction will only be valid for a limited number of blocks (by default this is 5 mins at 6s block times)
+- It will construct a payload and sign this, this includes the `genesisHash`, the `blockHash` for the start of the mortal era as well as the current chain `specVersion`
+- The transaction is submitted to the node
+
+As suggested, you can override all of this, i.e. by retrieving the nonce yourself and passing that as an option, i.e. `signAndSend(alice, { nonce: aliceNonce })`, this could be useful when manually tracking and submitting transactions in bulk.
+
+## Into the keyring we go
+
+With the examples above, the variable `alice` seems to have appeared from thin air. To understand how transactions are signed, we will take a [brief diversion into the keyring](keyring.md) before returning to our regularly scheduled program.

docs/start/api.tx.subs.md

@@ -0,0 +1,65 @@
+# Transaction subscriptions
+
+Previously we sent simple transactions using the `api.tx` endpoints, in this section we will extend that to monitor the actual transactions for inclusion and also extend the monitoring for transaction events.
+
+## Transaction inclusion
+
+To send a transaction and then waiting until it has been included in a block, we will use a subscription interface instead of just waiting for the transaction pool addition to yield the extrinsic hash. For the simplest form, we can do the following -
+
+```js
+...
+
+// Create alice (carry-over from the keyring section)
+const alice = keyring.addFromUri('//Alice');
+
+// Make a transfer from Alice to BOB, waiting for inclusion
+const unsub = await api.tx.balances
+  .transfer(BOB, 12345)
+  .signAndSend(alice, (result) => {
+    console.log(`Current status is ${result.status}`);
+
+    if (result.status.isFinalized) {
+      console.log(`Transaction included at blockHash ${result.status.asFinalized}`);
+      unsub();
+    }
+  });
+```
+
+As per all previous subscriptions, the transaction subscription returns in `unsub()` and the actual method has a subscription callback. The `result` object has 2 parts, `events` (to to covered in the next section) and the `status` enum.
+
+When the `status` enum is in `Finalized` state (checked via `isFinalized`), the underlying value contains the block hash of the block where the transaction has been included. This does not mean the block is finalized, but rather applies to the transaction state, as no further updates will be received for this subscription.
+
+## Transaction events
+
+Any transaction will emit events, as a bare minimum this will always be either a `system.ExtrinsicSuccess` or `system.ExtrinsicFailed` event for the specific transaction. These provide the overall execution result for the transaction, i.e. execution has succeeded or failed.
+
+Depending on the transaction sent, some other events may however be emitted, for instance for a `balances.transfer` this could include one or more of `Transfer`, `NewAccount` or `ReapedAccount`, as defined in the [substrate balances event defaults](../substrate/events.md#balances).
+
+To display or act on these events, we can do the following -
+
+```js
+...
+// Make a transfer from Alice to BOB, waiting for inclusion
+const unsub = await api.tx.balances
+  .transfer(BOB, 12345)
+  .signAndSend(alice, ({ events = [], status }) => {
+    console.log(`Current status is ${status.type}`);
+
+    if (status.isFinalized) {
+      console.log(`Transaction included at blockHash ${status.asFinalized}`);
+
+      // Loop through Vec<EventRecord> to display all events
+      events.forEach(({ phase, event: { data, method, section } }) => {
+        console.log(`\t' ${phase}: ${section}.${method}:: ${data}`);
+      });
+
+      unsub();
+    }
+  });
+```
+
+Be aware that when a transaction status is `isFinalized`, it means it is included, but it may still have failed - for instance if you try to send a larger amount that you have free, the transaction is included in a block, however from a end-user perspective the transaction failed since the transfer did not occur. In these cases a `system.ExtrinsicFailed` event will be available in the events array.
+
+## Complex transactions
+
+In many cases transactions can carry quite complex information, be it for passing objects or proposing changes. In the next section we will take a dive [into complex transactions, including those wrapped for sudo](api.tx.wrap.md).

docs/start/api.tx.wrap.md

@@ -0,0 +1,44 @@
+# Complex transactions
+
+Up till now we have focussed on the base operation of transactions. There are however some more complex operations that deserve some more information, for instance when doing either democracy proposals or executing sudo calls, in both these cases the transaction wraps a call or proposal to be evaluated.
+
+## Sudo use
+
+When running a development chain (Polkadot/Substrate with a `--dev` flag), or in certain testnets a sudo module is available - just like the sudo command found on some systems, it allows root-level access to perform actions. For instance, we can perform a `setBalance(<accountId>, <free>, <reserved>)` on an account -
+
+```js
+...
+// Get the current sudo key in the system
+const sudoKey = await api.query.sudo.key();
+
+// Lookup from keyring (assuming we have added all, on --dev this would be `//Alice`)
+const sudoPair = keyring.getPair(sudoKey);
+
+// Send the actual sudo transaction
+const unsub = await api.tx.sudo
+  .sudo(
+    api.tx.balances.setBalance(ADDR, 12345, 678)
+  )
+  .signAndSend(sudoPair, (result) => { ... });
+```
+
+The above is really quite straight-forward, the `sudo.sudo(<call>)` call takes 1 parameter, which is a `Call`. We construct this via the `api.tx` and pass it through. The only difference is that the nested call has no actual `.signAndSend` on it, rather it is only used as a container for data.
+
+Exactly the same would apply to the standard `democracy.propose(<proposal>, <value>)`, for instance we can just swap the above sudo wrapper with a proposal and add the correct fees for the proposal.
+
+## Complex types
+
+As indicated in previous sections (we will cover types in more detail next), the API will format the inputs into the actual type required for submission. For primitives such as numbers, this is quite understandable, but it is worth spending at least one example on cases where an object is provided as an input. For instance, making a call to validate -
+
+```js
+...
+const txHash = await api.tx.staking.validate({
+  validatorPayment: 12345
+});
+```
+
+In the above example, all we need to provide is a the fields for the `ValidatorPrefs` object. (Any fields not defined will be set to the default for that type, i.e. all zero). This object maps through to what is defined on the Polkadot/Substrate side, with the [@polkadot/types version](https://github.com/polkadot-js/api/blob/master/packages/types/src/interfaces/staking/definitions.ts) mapping all fields.
+
+## Understanding types
+
+As has been very apparent in all the preceding sections, the management of types is what allows the API to communicate with the node. Most values are in a [binary SCALE-encoded format](https://github.com/paritytech/parity-scale-codec) and it is the responsibility of the API is to encode and decode these. In the next section we will [take a look at what interfaces the API provides around types](types.basics.md).

docs/start/basics.md

@@ -0,0 +1,34 @@
+# Basics & Metadata
+
+One of the most important things to understand about the `@polkadot/api` is that most interfaces are actually generated automatically when it connects to a running node. This is quite a departure from other APIs in projects where the interfaces are static. While sounding quite scary, it actually is a powerful concept that exists in both Polkadot and Substrate chains, and allows the API to be used in environments where the chain is customized.
+
+To unpack this, we will start with the Metadata and explain what it actually provides, since it is critical for understanding how to interact with the API and any underlying chain.
+
+## Metadata
+
+When the API connects to a node, one of the first things it does is to retrieve the metadata. The metadata, effectively provides data in the form of `api.<type>.<module>.<section>` that fits into one of the following categories -
+
+- [consts](../substrate/constants.md) - All runtime constants, e.g. `api.consts.balances.creationFee`. These are not functions, rather accessing the endpoint immediately yields the result as defined.
+- [query](../substrate/storage.md) - All chain state, e.g. `api.query.balances.freeBalance(<accountId>)`.
+- [tx](../substrate/extrinsics.md) - All extrinsics, e.g. `api.tx.balances.transfer(<accountId>, <value>)`.
+
+Additionally the metadata also provides information on [events](../substrate/events.md), these are query-able via the `api.query.system.events()` interface and also appear on transactions... both these cases are detailed later.
+
+## Types
+
+The metadata defines the calls with all the type names used in the various interfaces. At the moment (this is undergoing investigations and could improve in future versions of metadata), this also means that the types between the API and the node need to be aligned. For instance, by default Substrate defines a `BlockNumber` type as a `u32` and the API follows the Substrate defaults - if a chain has a different definitions, the API needs to be aware of this so it can actually decode (and encode) the type.
+
+At this point just be aware of it, we will touch on types, custom chains and their impacts in a later section.
+
+## Chain Defaults
+
+In addition to the `api.[consts | query | tx]` detailed above, the API, upon connecting to a chain, fills in some information and makes it available directly on the API interface. These include -
+
+- `api.genesisHash` - The genesisHash of the connected chain
+- `api.runtimeMetadata` - The metadata as retrieved from the chain
+- `api.runtimeVersion` - The chain runtime version (including spec/impl. versions and types)
+- `api.libraryInfo` - The version of the API, i.e. `@polkadot/api v0.90.1`
+
+## Let's do something!
+
+Now that we have covered what the API actually exposes, it is time to [dive in and actually use what we installed earlier](create.md).

docs/start/create.md

@@ -0,0 +1,79 @@
+# Create an instance
+
+We have the API installed, we have an understanding of what will actually be exposed and how the API knows what to expose. So down the rabbit hole we go - let's create an actual API instance, and then take it from there -
+
+```js
+// Import
+import { ApiPromise, WsProvider } from '@polkadot/api';
+
+...
+// Construct
+const wsProvider = new WsProvider('wss://poc-3.polkadot.io');
+const api = await ApiPromise.create({ provider: wsProvider });
+
+// Do something
+console.log(api.genesisHash.toHex());
+```
+
+We will have some explanation on the ES2015 syntax used next, but just a small note on the above - where other code is included (or just some previous boilerplate is used), you will see `...` in most of the examples. This is not due to laziness, but rather just to keep things straight and to the point.
+
+## ES2015 Usage and examples
+
+Before we jump into an explanation of the above example, be aware that in all cases we are using ES2015, including using things like `async`/`await`, `import` and others. Depending on your environment, this may require some adjustments.
+
+While we are using the `await` naked in all examples (this removes boilerplate), it will need to be wrapped in an `async` block, for we could warp all samples inside a `async function main () { ... }` and then just call `main()`.
+
+In the case of Node.js you would change the `import` into `require`, i.e.
+
+```js
+// Import
+const { ApiPromise, WsProvider } = require('@polkadot/api');
+...
+```
+
+We are basing all our examples on the [ApiPromise](../examples/promise/README.md) version of the API, however there is also an RxJS version available. Since Promises are a part of the ES2015 specification, it covers the greater amount of use and is the one that will be used in 95% of the cases and should be familiar to 100% of all developers. However if you are in an environment where RxJs is recommended or your have a great affinity ot it, you could take a look at the [RxJS examples](../examples/rx/README.md) once you are familiar with the base concepts introduced here.
+
+For now... just ignore the various flavors and focus on understanding the concepts.
+
+## Providers
+
+Focusing on the construction, any API requires a provider and we create one via the `const wsProvider = new WsProvider(...)`. By default, if none is provided to the API it will construct a default `WsProvider` instance to connect to `ws://127.0.0.1:9944`.
+
+We generally recommend always specifying the endpoint since in most cases we want to connect to an external node and even for local nodes, it is always better being explicit, less magic that can make you wonder in the future.
+
+At this time the only provider type that is fully supported by the API is the WebSocket version. Polkadot/Substrate really comes alive with possibilities once you have access to bi-directional RPCs such as what WebSockets provide. (It is technically possible to have some limited capability via bare-HTTP, but at this point WebSockets is the only fully-operational and supported version - always remember that it is just "upgraded HTTP".)
+
+## API Instance
+
+The API creation is done via the `ApiPromise.create` interface which is a shortcut version for calling `new` and then waiting until the API is connected. Without the `async` syntax, this would be,
+
+```js
+ApiPromise
+  .create({ provider: wsProvider })
+  .then((api) =>
+    console.log(api.genesisHash.toHex())
+  );
+```
+
+In most cases we would suggest using the `.create` shortcut, which really just takes care of the following boilerplate that otherwise needs to be provided -
+
+```js
+// Create the instance
+const api = new ApiPromise({ provider: wsProvider });
+
+// Wait until we are ready and connected
+await api.isReady;
+
+// Do something
+console.log(api.genesisHash.toHex());
+```
+
+## Advanced creation
+
+There are more advanced cases where you would prefer to use the longer version, for instance: if you want to explicitly listen to events emitted, you probably want to attach to the API even before connecting to the chain. All API instances implement an `EventEmitter` interface, with `on` handlers, which emit `connected`, `disconnected`, `ready` and `error` events, allowing you to listen to events on the transport layer.
+
+In these cases, create via `new`, attach listeners and then wait for the `isReady`.
+
+## Do something
+
+Now that we have the API initialized, the next step would be to start using it to interact and extract data [starting with chain constants](api.consts.md).

docs/start/extrinsic.extend.md

@@ -0,0 +1,158 @@
+# Extending extrinsics
+
+On some chains, the need may arise to customize the extrinsic format. In this section we will explain what extrinsics and their payloads contain, explain how signed extensions work and provide a walk through of an advanced use-case where extrinsics are customized for a specific Substrate chain.
+
+## Extensions
+
+In Substrate (which forms the base of Polkadot and a number of custom chains), an extrinsic has a specific version, flag to indicating if it has been signed, the address, signature, extra data as well as the actual method with params. In addition, the signature is generated over the call and may include values that are not encoded into the final extrinsic.
+
+For instance, with version 3 extrinsics, the signature payload contains the runtime spec version as well as the `genesisHash` and `blockHash` (the latter being equivalent to the `genesisHash` in case of immortal transactions), however while these 3 fields are signed together with the method data, they do not actually appear in the extrinsic itself. Rather the chain executing the transaction will retrieve this information, add it to the method data and compare the signatures thereof.
+
+So in both the cases of the `genesisHash` and `specVersion`, if these do not match the signer version, the transaction won't be accepted - however the extrinsic doesn't explicitly carry this information in the data being transmitted, rather only implicitly as part of the signature. And it always forms part of the validation.
+
+## Default extrinsics
+
+With the above in-mind, the extrinsic format is explicitly defined as having the following structure in Substrate -
+
+```rust
+pub struct UncheckedExtrinsic<Address, Call, Signature, Extra>
+where Extra: SignedExtension
+{
+	pub signature: Option<(Address, Signature, Extra)>,
+	pub function: Call,
+}
+```
+
+The `Option` is here encoded such that is conveys both the extrinsic version `0x03` for Substrate 2.x chains (`0x01` for Substrate 1.x chains) as well as a high-bit that indicates if the transaction is signed or unsigned. (For unsigned the `signature` details therefore does not appear). The `SignedExtension` part defined both the data in the actual extrinsic as well as data, i.e. `AdditionalSigned`, that appears in the payload for the signature, but is not explicitly contained in the extrinsic.
+
+The default `SignedExtension` for Substrate 2.x with extrinsic version 3 is defined as follow -
+
+```rust
+pub type SignedExtra = (
+	system::CheckVersion<Runtime>,
+	system::CheckGenesis<Runtime>,
+	system::CheckEra<Runtime>,
+	system::CheckNonce<Runtime>,
+	system::CheckWeight<Runtime>,
+	balances::TakeFees<Runtime>,
+	contracts::CheckBlockGasLimit<Runtime>,
+);
+```
+
+Some of these are only checks, requiring no additional data in the payload or extrinsic itself, i.e. the contracts checks do exactly that. It only applies checks and invalidates when those checks are invalid. This is a powerful concept, for instance on the [initial Kusama chain this was used to limit the types of calls allowed](https://github.com/paritytech/polkadot/blob/f52c714ec3411eea58647d0f5176f4eb81660188/runtime/src/lib.rs#L117-L139).
+
+## Extension deep-dive
+
+For each of the default extensions, we will take a look through to understand the implications of the specific extension and how it relates to both the data contained in the extrinsic as well as the signature payload.
+
+- `system::CheckVersion` - This checks that the spec version matches between the extrinsic and the chain. It takes no parameters which means that these is no explicit data in the extrinsic format for this field, however it has `type AdditionalSigned = u32` which means that a `u32` containing the runtime spec version is part of the signature payload.
+
+- `system::CheckGenesis` - This checks that the `genesisHash` matches between extrinsic and chain. Like the previous check, no additional data is added to the extrinsic, however with `type AdditionalSigned = T::Hash`, the `genesisHash` is part of the signature payload.
+
+- `system::CheckEra` - This checks the era (mortal or immortal) for the transaction being sent. It checks both the `era: Era` as part of the actual extrinsic and the `blockHash` via the `type AdditionalSigned = T::Hash`. This means that the extrinsic era is both in the data being signed and the extrinsic itself, while the `blockHash` the era applies to is only available in the signature payload.
+
+- `system::CheckNonce` - This checks the nonce for the sending account. Unlike the preceding checks, it has no payload-specific data, however the `nonce: Compact<T::Index>` (`Index` is default `u32`) is applicable to both the extrinsic and, therefore, the actual signature payload as well.
+
+- `system::CheckWeight` - This checks the weight and length of the block and ensure that it does not exceed the limits. It does not have any specific data attached to either the extrinsic nor payload, but rather just does calculations based on the weights and type of transaction received.
+
+- `balances::TakeFees` - Consumes fees proportional to the length and weight of the transaction. It operates on the `fee: Compact<T::Balance>`, which means this value is included in both the extrinsic and subsequent payload being signed.
+
+- `contracts::CheckBlockGasLimit` - As explained briefly above, this extension does not add data to the extrinsic, or the signature payload, however it ensures that the transaction does not exceeds the block gas limit.
+
+## Extrinsic and signature payloads
+
+With the above extension, the following formats for the extrinsic and payloads are the outcome of the application of the signed extension. For the extrinsic the following data is [always encoded for v3 extrinsics](https://github.com/polkadot-js/api/blob/8b0ef159c05bcb5d9b664546d0e7289e79b5c9d5/packages/types/src/primitive/Extrinsic/v3/Extrinsic.ts#L27) -
+
+```js
+class ExtrinsicV3 extends Struct {
+ constructor (value) {
+  super({
+   signer: 'Address',
+   signature: 'Signature',
+   era: 'ExtrinsicEra', // extra via system::CheckEra
+   nonce: 'Compact<Index>', // extra via system::CheckNonce
+   tip: 'Compact<Balance>', // extra via balances::TakeFees
+   method: 'Call'
+  }, value);
+ }
+ ...
+```
+
+The signature payload will contain the same information as the extrinsic, with the following [additional information](https://github.com/polkadot-js/api/blob/8b0ef159c05bcb5d9b664546d0e7289e79b5c9d5/packages/types/src/primitive/Extrinsic/v3/ExtrinsicPayload.ts#L33) as expected by the `AdditionalSigned` portions of the extensions -
+
+```js
+class ExtrinsicPayloadV3 extends Struct {
+ constructor (value) {
+  super({
+   method: 'Bytes',
+   era: 'ExtrinsicEra', // extra via system::CheckEra
+   nonce: 'Compact<Index>', // extra via system::CheckNonce
+   tip: 'Compact<Balance>', // extra via balances::TakeFees
+   specVersion: 'u32', // additional via system::CheckVersion
+   genesisHash: 'Hash', // additional via system::CheckGenesis
+   blockHash: 'Hash' // additional via system::CheckEra
+  }, value);
+ }
+ ...
+```
+
+As per the above structures, it means that both the extrinsic sent on-chain as well as the data being signed to generate the signature is tied by the hip based on the logic the chain expects via `SignedExtension`. The API is only aware of the version of the extrinsic being used on-chain (it determines this on connection) and therefore only knows about the specific logic that has been coded for the extrinsic version.
+
+## Extending existing or implementing new
+
+When the API encodes or decodes an extrinsic, it uses the first `Option` byte to determine the version. Once it has this value, it will create a specific extrinsic via `createType('ExtrinsicV3', value)`. This means that at any point, you can supply your own version of either the `Extrinsic` or `ExtrinsicPayload` and you can do so via 2 avenues -
+
+- If you are extending/replacing the existing version, you can inject your own types for both `ExtrinsicV3` and `ExtrinsicV3Payload` (assuming you are replacing v3)
+
+- If you are adding a new version, you can add a handler for both `ExtrinsicUnknown` and `ExtrinsicPayloadUnknown`. These will be constructed when the version the API is aware of does not match with the on-chain version.
+
+While we will not provide a full example of all the code here, the above links will show the existing implementations. However, assuming we have a chain where neither the nonce or tip is applicable (or we just don't care) and we are ignoring the check to the runtime versioning.
+
+Additionally assuming that we have made the required `SignedExtension` updates by removing `system::CheckVersion`, `system::CheckNonce` and `balances::TakeFees`, we can do the following -
+
+```js
+...
+class OwnExtrinsic extends Struct {
+ constructor (value) {
+  super({
+   signer: 'Address',
+   signature: 'Signature',
+   era: 'ExtrinsicEra', // extra via system::CheckEra
+   method: 'Call'
+  }, value);
+ }
+ ...
+}
+
+class OwnExtrinsicPayload extends Struct {
+ constructor (value) {
+  super({
+   method: 'Bytes',
+   era: 'ExtrinsicEra', // extra via system::CheckEra
+   genesisHash: 'Hash', // additional via system::CheckGenesis
+   blockHash: 'Hash' // additional via system::CheckEra
+  }, value);
+ }
+ ...
+ // signing logic needs to be included, as per existing
+}
+...
+
+// inject our types at API construction
+const api = ApiPromise.create({
+ types: {
+  'ExtrinsicV3': OwnExtrinsic,
+  'ExtrinsicV3Payload': OwnExtrinsicPayload,
+ }
+})
+```
+
+The above example is certainly an advanced example, but it shows that all data types in the API can be adjusted and these adjustment can be provided to the API. In all cases, if you made updates to the formats and types of the actual runtime, you need to ensure that the API is aware of these changes.
+
+In the above example, should these updates only be made on the node side, without the required API adjustments, the API will generate invalid transactions for the node since it is unaware of the changes and adjusted formats. Making the adjustments on only one side will mean that the signature verification can fail and that the format will not be decodable via the node.
+
+(These extensions are not exposed via metadata at all, and would be quite difficult to do as well - since each of these have specific logic as well as data types assigned.)
+
+## Using with TypeScript
+
+The API is built with TypeScript (as are all projects in the [polkadot-js organization](https://github.com/polkadot-js/)) and as such allows developers using TS to have access to all the type interfaces defined on the chain, as well as having access to typings on interacting with the `api.*` namespaces. In the next section we will provide an overview of [what is available in terms of types and TypeScript](typescript.md).

docs/start/install.md

@@ -0,0 +1,27 @@
+# Installation
+
+Yes, it really is as simple as [installing from npm](https://www.npmjs.com/package/@polkadot/api), so we are not going to waste too much time with the bare basics, just install the API via
+
+`yarn add @polkadot/api`
+
+And it will be added and ready for use. The above will always install the latest stable release, which should allow you to connect to test networks and local nodes that are tracking versioned releases for [Polkadot](https://github.com/paritytech/polkadot) and [Substrate](https://github.com/paritytech/substrate).
+
+## Betas
+
+For users who have a slightly higher appetite for risk, or are using bleeding-edge master branches of either Polkadot/Substrate, we also publish a beta version as soon as anything is merged into the API master branch. This version really contains all the latest fixes and features and is the version we actually use inside the polkadot-js projects - eating our own dog food.
+
+To install a beta version, either to test or for support of a feature that is available in Substrate master (and has not yet made it to a stable api release), you can install it via the `@beta` tag, i.e.
+
+`yarn add @polkadot/api@beta`
+
+## Other dependencies
+
+In most cases, you don't need to do anything else apart from just installing `@polkadot/api` above. It has dependencies such as `@polkadot/types` which are installed automatically alongside. When using `yarn` the dependencies are installed, flattened, available for use and you will never run into issues with mismatched versions.
+
+This means that by simply installing `@polkadot/api`, you will have access to utilities (crypto and normal), types, providers and even higher-order (derived) API functions. (We will get to all of these in follow-up sections)
+
+If you do however decide to explicitly install other packages (even though they are dependencies), please make sure that the versions inside the api package always match with your versions, i.e. if you installed `@polkadot/api` `0.91.0-beta.22` and you have your own version of `@polkadot/types`, ensure that it is also `0.91.0-beta.22`.
+
+## API basics
+
+So we have it installed. Before we jump into actual real-world usage, [let's understand what the API gives us](basics.md).

docs/start/keyring.md

@@ -0,0 +1,119 @@
+# Keyring
+
+This section will give a quick introduction into the Keyring, including the addition of accounts, retrieving pairs and the signing of any data. Unlike the rest of the API, only the core concepts will be covered with the most-used-functions. However, what is covered is enough for 99.9 of the use-cases ... or rather, that is the aim.
+
+## Installation
+
+They [@polkadot/keyring](https://github.com/polkadot-js/common/tree/master/packages/keyring) keyring is included directly with the API as a dependency, so it is directly importable (since the 0.92 version) alongside the API.
+
+If you do opt to install it separately, ensure that the version of `@polkadot/util-crypto` that is included with the API matches with the version of `@polkadot/keyring` installed. So if the API depends on `util-crypto 1.4.1`, it would make sense to include `keyring 1.4.1` as the installed version. (This helps in making sure extra versions of the libraries are not included as duplicates, especially in the case where bundles are created. Additionally, this makes sure that weird side-effects in the WASM initialization is avoided.)
+
+## Creating a keyring instance
+
+Once installed, you can create an instance by just creating an instance of the `Keyring` class -
+
+```js
+// Import the keyring as required
+import { Keyring } from '@polkadot/api';
+
+// Initialize the API as we would normally do
+...
+
+// Create a keyring instance
+const keyring = new Keyring({ type: 'sr25519' });
+```
+
+In the above example, the import is self-explanatory. Upon creation we pass through a `type` which can have a value of either `ed25519` or `sr25519`, when not specified this would default to `ed25519`. This type parameter only applies to the default type of account created when no type is specified, it does not mean that the keyring can only store that type of account.
+
+So effectively, when creating an account and not specifying a type, it will be `sr25519` by default based on the above construction params, however we can also add an `ed25519` account and use it transparently in the same keyring.
+
+One "trick" that is done implicitly in the above sample is that that keyring is only initialized after the API. In the case of `sr25519` the keyring relies on a [WASM build](https://github.com/polkadot-js/wasm) of the [schnorrkel libraries](https://github.com/w3f/schnorrkel). Since the API inlitialization is already async, it initializes the WASM libraries are part of the setup.
+
+However, this initialization can also be done explicitly, mostly for more advances use-cases, or in cases where the API won't be attached until much later -
+
+```js
+// Crypto promise, package used by keyring internally
+import { cryptoWaitReady } from '@polkadot/util-crypto';
+
+// Wait for the promise to resolve, async WASM or `cryptoWaitReady().then(() => { ... })`
+await cryptoWaitReady();
+
+// Create a keyring instance
+const keyring = new Keyring({ type: 'sr25519' });
+```
+
+## Adding accounts
+
+The recommended catch-all approach to adding accounts is via `.addFromUri(<suri>, [meta], [type])` function, where only the `suri` param is required. For instance to add an account via mnemonic, you would do the following -
+
+```js
+...
+
+// Some mnemonic phrase
+const PHRASE = 'entire material egg meadow latin bargain dutch coral blood melt acoustic thought';
+
+// Add an account, straight mnemonic
+const newPair = keyring.addFromUri(PHRASE);
+
+// (Advanced) add an account with a derivation path (hard & soft)
+const newDeri = keyring.addFromUri(`${PHRASE}//hard-derived/soft-derived`);
+
+// (Advanced, development-only) add with an implied dev seed and hard derivation
+const alice = keyring.addFromUri('//Alice', { name: 'Alice default' });
+```
+
+The above additions cater for most of the use cases and aligns with the you would find in the Substrate `subkey`. Be very wary of the last "dev-seed" option, it is explicitly added for `subkey` compatibility and implies using the "known-everywhere" dev seed. It is however useful when running Polkadot/Substrate with a `--dev` flag.
+
+## Adding accounts with raw seeds
+
+Since mnemonics are recommended and the defacto standard for current Polkadot/Substrate generations, the only mentioned way of adding keys thus far has been via mnemonic. However, the `addFromUri` method on the keyring is intelligent enough to detect and add from inputs specified as mnemonics, hex seeds and string seeds (appropriately padded).
+
+With the above in mind, we could extend our examples above for custom raw seed. For instance to add both a hex and string seed, we can follow the following approach -
+
+```js
+...
+// add a hex seed, 32-characters in length
+const hexPair = keyring.addFromUri('0x1234567890123456789012345678901234567890123456789012345678901234');
+
+// add a string seed, internally this is padded with ' ' to 32-bytes in length
+const strPair = keyring.addFromUri('Janice');
+```
+
+You could extend derivation from these specified seeds with derivation paths if applicable, i.e. `Janice//hard` will perform a hard derivation with the path `hard` on the pair that is generated from the `Janice` seed. As far as possible, try to stick with mnemonics in your applications, unless you have a good reason to not do so. Humans are generally bad at generating their own entropy and mnemonics has additional properties such as built-in checksums.
+
+## Working with pairs
+
+In the previous examples we added a pair to the keyring (and we actually immediately got access to the pair). From this pair there is some information we can retrieve -
+
+```js
+...
+
+// Add our Alice dev account
+const alice = keyring.addFromUri('//Alice', { name: 'Alice default' });
+
+// Log some info
+console.log(`${alice.meta.name}: has address ${alice.address} with publicKey [${alice.publicKey}]`);
+```
+
+Additionally you can sign and verify using the pairs. This is the same internally to the API when constructing transactions -
+
+```js
+// Some helper functions used here
+import { stringToU8a, u8aToHex } from '@polkadot/util';
+
+...
+
+// Convert message, sign and then verify
+const message = stringToU8a('this is our message');
+const signature = alice.sign(message);
+const isValid = alice.verify(message, signature);
+
+// Log info
+console.log(`The signature ${u8aToHex(signature)}, is ${isValid ? '' : 'in'}valid`);
+```
+
+This covers the keyring basics, however there are two additional functions here of interest, `keyring.getPairs()` to retrieve a list of all pairs in the keyring and `keyring.getPair(<address or publicKey>)` to retrieve a pair where we have an identifier.
+
+## Back to transactions
+
+Now that we have short introduction to the keyring, we can move back to API transactions and find out [how to subscribe and track events](api.tx.subs.md), taking our management of transactions to the next level.

docs/start/types.basics.md

@@ -0,0 +1,84 @@
+# Type basics
+
+We've touched upon types in most previous sections, i.e. that these are driven by metadata and that they are created and converted to/from automatically by the API. Since they appear in all results, we will divert a bit from the regularly scheduled program in explaining the API interfaces to giving some info on the base types.
+
+## Everything is a type
+
+Just to re-iterate from the above. Everything returned by the API is a type and has a consistent interface. This means that a `Vec<u32>` (an array of `u32` values) as well as a `Struct` (an pre-defined object) or an `Enum` has the same consistent base interface. Specific types types will have values, based on the type - decorated and available.
+
+As a minimum, anything returned by the API, be it a `Vec<...>`, `Option<...>`, `Struct` or any normal type will always have the following methods -
+
+- `.eq(<other value>)` - checks for equality against the other value. In all cases, it will accept "like" values, i.e. in the case of a number you can pass a primitive (such as `1`), a hex value (such as `0x01`) or even an `Unit8Array`
+- `toHex()` - returns a hex-base representation of the value, always prefixed by `0x`
+- `toJSON()` - returns a JSON-like representation of the value, this is generally used when calling `JSON.stringify(...)` on the value
+- `toString()` - returns a string representation, in some cases this performs additional encoding, i.e. for `Address`, `AccountId` and `AccountIndex` it will encode to the ss58 address
+- `.toU8a()` - returns a `Uint8Array` representation of the encoded value (generally exactly as passed to the node, where values are SCALE encoded)
+
+Additionally, the following getters and utilities are available -
+
+- `.isEmpty` - `true` if the value is an all-empty value, i.e. `0` in for numbers, all-zero for Arrays (or anything `Uint8Array`), `false` is non-zero
+- `.hash` - a `Hash` (once again with all the methods above) that is a `blake2-256` representation of the contained value
+
+## Comparing types
+
+To reiterate the above API, the `.eq` method is the preferred means of comparing base types, rather than the JavaScript equality operator (`===`).
+
+For example:
+
+```js
+const { metadata } = await api.rpc.state.getMetadata();
+const modules = metadata.asV3.modules;
+
+// This will not work, because `name` is an instance of `Text`, not a string
+// const system = modules.find(m => m.name === 'system');
+
+// This will work, because `Text.eq()` can compare against a string
+const system = modules.find(m => m.name.eq('system'));
+```
+
+## Working with numbers
+
+All numbers wrap and extend an instance of [bn.js](https://github.com/indutny/bn.js/). This means that in addition to the interfaces defined above, they have some additional methods -
+
+- `.toNumber()` - a JS number (limited to 2^53 - 1). This does mean that for large values, e.g. `Balance` (a `u128` extension), this can cause overflows
+- `.add(...)`, `.sub(...)`, ... - all the base methods available on the `BN` object
+
+In cases where a `Compact` is returned, i.e. `Compact<Balance>`, the value is wrapped. This object should be `.unwrap()`-ed first to gain access to the underlying `Balance` object.
+
+## Working with structures
+
+All structures, a wrapping of an object containing a number of member variables, is an implementation of a standard JS `Map` object, so all the functions available on a `Map` such as `.entries()` are available. Additionally it is decorated with actual getters for the fields.
+
+As an example, a `Header` will have getters for the `.parentHash`, `.number`, `.stateRoot`, `.extrinsicsRoot` and `.digest` fields. The same applies for all structures, as they are returned, each member will have an associated getter.
+
+Be aware that in the JS version naming defaults to `camelCase` where names of fields in Substrate defaults to `snake_case`. (Each version aligning with conventions in the respective languages)
+
+## Working with enums
+
+Each enum has additional getters which are injected based on the fields wrapped. These take the form of `.is<Name>` and `.as<Name>` to allow you to check is the enum is a certain value or to retrieve the underlying value as a specific type.
+
+As a real-world example, when an extrinsic is applied, the `Phase` enum has one of two states, `ApplyExtrinsic(u32)` or `Finalization`. In this case `.isApplyExtrinsic` would be `true` when an extrinsic is being applied, and `.asApplyExtrinsic` would return the value as a `u32` (which is the index of the extrinsic in the block, as it is being applied). When `isisApplyExtrinsic` is `false` and `asApplyExtrinsic` is called, the getter will throw.
+
+## Working with Option&lt;Type&gt;
+
+An `Option<Type>` attempts to mimic the Rust approach of having `None` and `Some` available. This means the following getters & methods are available on an `Option` -
+
+- `.isNone` - is `true` if no underlying values is wrapped, effectively the same as `.isEmpty`
+- `.isSome` - this is `true` is a value is wrapped, i.e. if a `Option<u32>` has an actual underlying `u32`
+- `.unwrap()` - when `isSome`, this will return the wrapped value, i.e. for `Option<u32>`, this would return the `u32`. When the value is `isNone`, this call will throw an exception.
+- `.unwrapOr(<default value>)` - this extends `unwrap()`, returning the wrapped value when `isSome` and in the case of `isNone` it will return the `<default value>` passed.
+
+## Working with Tuples
+
+A tuple is defined in the form of `(u32, AccountId)`. To access the individual values, you can access t via the index, i.e.
+
+```js
+// Assuming a tuple defined as `(32, AccountId)`
+const [count, accountId] = tuple;
+
+console.log(`${accountId} has ${count.toNumber()} values`);
+```
+
+## Extending types
+
+For customized chains, the need exists to register types so the API is aware of how to decode values for those types. The next section will provide a [walk-through for the definition of custom types](types.extend.md) allowing the definition or re-definition of any type the API is aware of.

docs/start/types.extend.md

@@ -0,0 +1,142 @@
+# Extending types
+
+Circling back to metadata, by default the metadata information (at this point in time), only returns the type names as they apply to any section, be it a call, event or query. As an example, this means that transfers are defined as `balances.transfer(AccountId, Balance)` with no details as to the mapping of the `Balance` type to a `u128`. (The underlying Polkadot/Substrate default)
+
+Therefore to cater for all types, a mapping in done on the [@polkadot/types library](https://github.com/polkadot-js/api/tree/master/packages/types/src/interfaces) to define each of the types and align with their underlying structures as it maps to a default Polkadot or Substrate chain.
+
+Additionally, the API contains some logic for chain type detection, for instance in the case of Substrate 1.x based chains, it will define `BlockNumber` & `Index` (nonce) as a `u64`, while for current-generation chains, these will be defined as `u32`. Some of the work in maintaining the API for Polkadot/Substrate is the addition of types as they appear and gets used in the Rust codebase.
+
+There is a the [recommendation](install.md#betas) to use a `@polkadot/api@beta` should you wish to track the master branches of Polkadot or Substrate, since master changes for the addition of new types do not make it into a stable release immediately.
+
+## Extension
+
+As a blockchain toolkit, Substrate makes it easy to add your own modules and types. In most non-trivial implementations, this would mean that developers are adding specific types for their implementation as well. The API will get to know the names of these types via the metadata, however it won't understand what they are, which means it cannot encode or decode them.
+
+To close this gap, the API allows for the injection of types, i.e. you can explicitly define (or override) types for the node/chain you are connecting to. In the simplest example, assuming you have a chain where your `Balance` type is a `u64` (as opposed to the default `u128`), you need to let the API know -
+
+```js
+...
+const api = await ApiPromise.create({
+  provider: wsProvider,
+  types: {
+    Balance: 'u64'
+  }
+});
+```
+
+The above introduces the `types` registry, effectively allowing overrides and the definition of new types. The override above would mean that immediately the API will treat all occurrences of `Balance` not as the default, but rather as the defined size.
+
+## User-defined types
+
+Registration also applies to any type that can be found on a specific chain, i.e. we can add any types that is available on a specific node -
+
+```js
+...
+const api = await ApiPromise.create({
+  ...,
+  types: {
+    TransactionInput: {
+      parentOutput: 'Hash',
+      signature: 'Signature'
+    },
+    TransactionOutput: {
+      value: 'u128',
+      pubkey: 'Hash',
+      sale: 'u32'
+    },
+    Transaction: {
+      inputs: 'Vec<TransactionInput>',
+      outputs: 'Vec<TransactionOutput>'
+    }
+  }
+})
+```
+
+The example above defines non-primitive types (as found in the specific implementation) as structures. Additionally it also shows the user-defined types can depend on other user-defined types with `Transaction` referencing both `TransactionInput` and `TransactionOutput`. Here you can reference any known types, i.e. in the above we have referenced primitives such as `u32` and `Signature` (itself an alias for `H512`).
+
+One form of types that appear regularly is enums, these can be defined as follow -
+
+```js
+...
+const api = await ApiPromise.create({
+  ...,
+  types: {
+    CLikeEnum: {
+      _enum: ['One', 'Two', 'Three']
+    },
+    TypedEnum: {
+      _enum: {
+        One: 'Compact<u32>',
+        Two: 'u64',
+        Three: 'Option<Balance>',
+        Four: null
+      }
+    }
+  }
+});
+```
+
+As seen in these examples, types are built up in terms of primitives and aligns with the Rust-type definition model with `Compact`, `Option` and `Vec`.
+
+## Node and chain-specific types
+
+There are cases where a single API object can be used to connect to different types of nodes or chains, each including their own specific types. For these cases the `typesChain` and `typesSpec` injectors are made available.
+
+As a real-world example, the [polkadot-js/apps UI](https://github.com/polkadot-js/apps) can connect to a variety of chains. To support [Edgeware](https://edgewa.re/) by default, the following node-type (`specName` as per the runtime version) overrides are made -
+
+```js
+import { IdentityTypes } from 'edgeware-node-types/dist/identity';
+import { SignalingTypes } from 'edgeware-node-types/dist/signaling';
+import { VotingTypes } from 'edgeware-node-types/dist/voting';
+
+...
+const api = await ApiPromise.create({
+  ...,
+  typesSpec: {
+    edgeware: {
+      ...IdentityTypes,
+      ...SignalingTypes,
+      ...VotingTypes
+    }
+  }
+});
+```
+
+In the same way `typesChain` can be used to match on the actual chain name, i.e. for a chain such as Kusama, the following overrides can be made (as per example only - Kusama uses the Polkadot defaults, so no overrides are needed) -
+
+```js
+...
+const api = await ApiPromise.create({
+  ...,
+  typesChain: {
+    'Kusama CC1': {
+      BlockNumber: 'u32',
+      Index: 'u32'
+    }
+  }
+});
+```
+
+The `types`, `typesChain` and `typesSpec` overrides are all optional and all are applied, as applicable to a specific connection. From the options `types` are registered first, followed by `typesSpec` for node-specific overrides and finally `typesChain` for chain-specific overrides. The would mean is you have the following (contrived) example,
+
+```js
+...
+const api = await ApiPromise.create({
+  ...,
+  types: {
+    Balance: 'u32',
+  }
+  typesChain: {
+    Balance: 'u128'
+  },
+  typesSpec: {
+    Balance: 'u64',
+  }
+});
+```
+
+`Balance` would be defined as an `u128` at the end. Effectively based on the flow it is first registered as a `u32`, then overridden as a `u64` and finally overridden once more as a `u128` by the chain types.
+
+## Extending extrinsics
+
+On customized chains, it is possible to [extend the format of the extrinsics and extrinsic payload as customized on the chain](extrinsic.extend.md), next up we will look at this advanced use-case.

docs/start/typescript.md

@@ -0,0 +1,56 @@
+# TypeScript interfaces
+
+The API is written in TypeScript, and as such definitions for all actual exposed interfaces are available. In general terms, care has been taken to expose types via a `@polkadot/<package>/types` interface, for instance the `ApiOptions` type which is passed through on the `.create` interface is available under `@polkadot/api/types`.
+
+## RPC interfaces
+
+Before getting to the "hard things", i.e. methods as decorated based on metadata interfaces, let's take a look at more "static" interfaces such as RPC. (Be aware though that these can be customized on a per-chain basis as well - for now this functionality is not reflected in the API itself).
+
+```js
+import { Header } from '@polkadot/types/interfaces';
+
+...
+const firstHead = api.rpc.chain.getHeader();
+
+api.rpc.chain.subscribeNewHeads((lastHead: Header): void => {
+  console.log('current header:', JSON.stringify(lastHead));
+});
+```
+
+In the above example a couple of things are introduced - most of the chain definitions (the default types for both Polkadot & Substrate) can be imported as interfaces from the `@polkadot/types/interfaces` endpoint. These are not classes (since they are [generated from definitions](https://github.com/polkadot-js/api/tree/master/packages/types/src/interfaces)) but rather a combination of TypeScript `interfaces` (where structures are involved) and `type`, i.e. `type Balance = u128`.
+
+In the subscription example, we explicitly define `lastHead: Header`, although the same definition is missing for `firstHead`. However, in both these cases the definitions for the `api.rpc` sections are such that TypeScript understands that `firstHead` and `lastHead` are of type `Header`. The `: Header` here is rather for our own understanding (and could be needed based on your eslint/tslint config).
+
+As indicated, most of the Polkadot/Substrate default types are available via `types/interfaces`. However, for primitives types where there is an actual implementation, these are made available via `@polkadot/types` directly. For instance, `import { u32 } from '@polkadot/types` is valid in this context.
+
+## Metadata injected
+
+For any interface injected by metadata, the types are not available by default (although it may be in the future for default interfaces), but rather what the API understands is that all results need to comply to the `Codec` interface. (The base of all our types)
+
+However, to make this sane from a developer perspective the injected methods are generic, effectively making the following possible -
+
+```js
+import { Balance, Index } from '@polkadot/types/interfaces';
+
+...
+const nonce = await api.query.system.accountNonce<Index>(ADDR);
+const balance = await api.query.balances.freeBalance<Balance>(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.
+
+## Future work
+
+As of this writing, there are still some gray areas to type detection, specifically around the following interfaces -
+
+- `.at` & `.multi` on `api.query` does not (yet) have a `<TypeOverride>` interface. This means `as <TypeOverride>` casts are presently needed for these results
+- `api.queryMulti` does not (yet) allow you to provide a hint to the types returned, this ties to the previous point
+
+In addition to expanding the type coverage, we wish to make the actual generation script for the types from `@polkadot/types/interfaces` available in 2 ways -
+
+- allowing you to point to a folder of types and auto-generate the TypeScript typings from those. (Which is akin to what we do internally). This would allow a reduction in type classes explicitly written and injected.
+- once the metadata itself supports full type definitions, the script can be used to generate interface definitions specifically tailored for a chain
+
+## And that's a wrap
+
+This brings us to the end of our overview and jump through the API. While the documentation is still very much and ever evolving item, we can encourage you to try out what you have learned with some [examples](../examples). As we [indicated right at the start of this journey](README.md#help-us-help-others), if there are areas for improvement, let us know.

docs/substrate/README.md

@@ -0,0 +1,3 @@
+# Substrate
+
+As part of a running node, some information is exposed as part of the metadata.

docs/substrate/constants.md

@@ -0,0 +1,225 @@
+## Constants
+
+The following sections contain the module constants, also known as parameter types. These can only be changed as part of a runtime upgrade. On the api, these are exposed via `api.consts.<module>.<method>`. 
+
+(NOTE: These were generated from a static/snapshot view of a recent Substrate master node. Some items may not be available in older nodes, or in any customized implementations.)
+- **[babe](#babe)**
+
+- **[balances](#balances)**
+
+- **[contracts](#contracts)**
+
+- **[democracy](#democracy)**
+
+- **[elections](#elections)**
+
+- **[finalityTracker](#finalityTracker)**
+
+- **[session](#session)**
+
+- **[staking](#staking)**
+
+- **[timestamp](#timestamp)**
+
+- **[treasury](#treasury)**
+
+
+___
+
+
+### babe
+
+▸ **epochDuration**: `u64`
+- **summary**: The number of **slots** that an epoch takes. We couple sessions to epochs, i.e. we start a new session once the new epoch begins.
+
+▸ **expectedBlockTime**: `Moment`
+- **summary**: The expected average block time at which BABE should be creating blocks. Since BABE is probabilistic it is not trivial to figure out what the expected average block time should be based on the slot duration and the security parameter `c` (where `1 - c` represents the probability of a slot being empty).
+
+___
+
+
+### balances
+
+▸ **creationFee**: `Balance`
+- **summary**: The fee required to create an account.
+
+▸ **existentialDeposit**: `Balance`
+- **summary**: The minimum amount required to keep an account open.
+
+▸ **transactionBaseFee**: `Balance`
+- **summary**: The fee to be paid for making a transaction; the base.
+
+▸ **transactionByteFee**: `Balance`
+- **summary**: The fee to be paid for making a transaction; the per-byte portion.
+
+▸ **transferFee**: `Balance`
+- **summary**: The fee required to make a transfer.
+
+___
+
+
+### contracts
+
+▸ **blockGasLimit**: `Gas`
+- **summary**: The maximum amount of gas that could be expended per block. A reasonable default value is 10_000_000.
+
+▸ **callBaseFee**: `Gas`
+- **summary**: The base fee charged for calling into a contract. A reasonable default value is 135.
+
+▸ **contractFee**: `BalanceOf`
+- **summary**: The fee required to instantiate a contract instance. A reasonable default value is 21.
+
+▸ **creationFee**: `BalanceOf`
+- **summary**: The fee required to create an account.
+
+▸ **instantiateBaseFee**: `Gas`
+- **summary**: The base fee charged for instantiating a contract. A reasonable default value is 175.
+
+▸ **maxDepth**: `u32`
+- **summary**: The maximum nesting level of a call/instantiate stack. A reasonable default value is 100.
+
+▸ **maxValueSize**: `u32`
+- **summary**: The maximum size of a storage value in bytes. A reasonable default is 16 KiB.
+
+▸ **rentByteFee**: `BalanceOf`
+- **summary**: Price of a byte of storage per one block interval. Should be greater than 0.
+
+▸ **rentDepositOffset**: `BalanceOf`
+- **summary**: The amount of funds a contract should deposit in order to offset the cost of one byte.  Let's suppose the deposit is 1,000 BU (balance units)/byte and the rent is 1 BU/byte/day, then a contract with 1,000,000 BU that uses 1,000 bytes of storage would pay no rent. But if the balance reduced to 500,000 BU and the storage stayed the same at 1,000, then it would pay 500 BU/day.
+
+▸ **signedClaimHandicap**: `BlockNumber`
+- **summary**: Number of block delay an extrinsic claim surcharge has.  When claim surcharge is called by an extrinsic the rent is checked for current_block - delay
+
+▸ **storageSizeOffset**: `u32`
+- **summary**: Size of a contract at the time of instantiaion. This is a simple way to ensure that empty contracts eventually gets deleted.
+
+▸ **surchargeReward**: `BalanceOf`
+- **summary**: Reward that is received by the party whose touch has led to removal of a contract.
+
+▸ **tombstoneDeposit**: `BalanceOf`
+- **summary**: The minimum amount required to generate a tombstone.
+
+▸ **transactionBaseFee**: `BalanceOf`
+- **summary**: The fee to be paid for making a transaction; the base.
+
+▸ **transactionByteFee**: `BalanceOf`
+- **summary**: The fee to be paid for making a transaction; the per-byte portion.
+
+▸ **transferFee**: `BalanceOf`
+- **summary**: The fee required to make a transfer.
+
+___
+
+
+### democracy
+
+▸ **cooloffPeriod**: `BlockNumber`
+- **summary**: Period in blocks where an external proposal may not be re-submitted after being vetoed.
+
+▸ **emergencyVotingPeriod**: `BlockNumber`
+- **summary**: Minimum voting period allowed for an emergency referendum.
+
+▸ **enactmentPeriod**: `BlockNumber`
+- **summary**: The minimum period of locking and the period between a proposal being approved and enacted.  It should generally be a little more than the unstake period to ensure that voting stakers have an opportunity to remove themselves from the system in the case where they are on the losing side of a vote.
+
+▸ **launchPeriod**: `BlockNumber`
+- **summary**: How often (in blocks) new public referenda are launched.
+
+▸ **minimumDeposit**: `BalanceOf`
+- **summary**: The minimum amount to be used as a deposit for a public referendum proposal.
+
+▸ **votingPeriod**: `BlockNumber`
+- **summary**: How often (in blocks) to check for new votes.
+
+___
+
+
+### elections
+
+▸ **approvalSetSize**: `u32`
+- **summary**: The chunk size of the approval vector.
+
+▸ **candidacyBond**: `BalanceOf`
+- **summary**: How much should be locked up in order to submit one's candidacy. A reasonable default value is 9.
+
+▸ **carryCount**: `u32`
+- **summary**: How many runners-up should have their approvals persist until the next vote. A reasonable default value is 2.
+
+▸ **decayRatio**: `u32`
+- **summary**: Decay factor of weight when being accumulated. It should typically be set to __at least__ `membership_size -1` to keep the collective secure. When set to `N`, it indicates `(1/N)^t` of staked is decayed at weight increment step `t`. 0 will result in no weight being added at all (normal approval voting). A reasonable default value is 24.
+
+▸ **inactiveGracePeriod**: `VoteIndex`
+- **summary**: How many vote indices need to go by after a target voter's last vote before they can be reaped if their approvals are moot. A reasonable default value is 1.
+
+▸ **minimumVotingLock**: `BalanceOf`
+- **summary**: Minimum about that can be used as the locked value for voting.
+
+▸ **presentSlashPerVoter**: `BalanceOf`
+- **summary**: The punishment, per voter, if you provide an invalid presentation. A reasonable default value is 1.
+
+▸ **voterSetSize**: `u32`
+- **summary**: The chunk size of the voter vector.
+
+▸ **votingBond**: `BalanceOf`
+- **summary**: How much should be locked up in order to be able to submit votes.
+
+▸ **votingFee**: `BalanceOf`
+- **summary**: The amount of fee paid upon each vote submission, unless if they submit a _hole_ index and replace it.
+
+▸ **votingPeriod**: `BlockNumber`
+- **summary**: How often (in blocks) to check for new votes. A reasonable default value is 1000.
+
+___
+
+
+### finalityTracker
+
+▸ **reportLatency**: `BlockNumber`
+- **summary**: The delay after which point things become suspicious. Default is 1000.
+
+▸ **windowSize**: `BlockNumber`
+- **summary**: The number of recent samples to keep from this chain. Default is 101.
+
+___
+
+
+### session
+
+▸ **dedupKeyPrefix**: `Bytes`
+- **summary**: Used as first key for `NextKeys` and `KeyOwner` to put all the data into the same branch of the trie.
+
+___
+
+
+### staking
+
+▸ **bondingDuration**: `EraIndex`
+- **summary**: Number of eras that staked funds must remain bonded for.
+
+▸ **sessionsPerEra**: `SessionIndex`
+- **summary**: Number of sessions per era.
+
+___
+
+
+### timestamp
+
+▸ **minimumPeriod**: `Moment`
+- **summary**: The minimum period between blocks. Beware that this is different to the *expected* period that the block production apparatus provides. Your chosen consensus system will generally work with this to determine a sensible block time. e.g. For Aura, it will be double this period on default settings.
+
+___
+
+
+### treasury
+
+▸ **burn**: `Permill`
+- **summary**: Percentage of spare funds (if any) that are burnt per spend period.
+
+▸ **proposalBond**: `Permill`
+- **summary**: Fraction of a proposal's value that should be bonded in order to place the proposal. An accepted proposal gets these back. A rejected proposal does not.
+
+▸ **proposalBondMinimum**: `BalanceOf`
+- **summary**: Minimum amount of funds that should be placed in a deposit for making a proposal.
+
+▸ **spendPeriod**: `BlockNumber`
+- **summary**: Period between successive spends.

docs/substrate/events.md

@@ -0,0 +1,298 @@
+## Events
+
+Events are emitted for certain operations on the runtime. The following sections describe the events that are part of the default Substrate runtime. 
+
+(NOTE: These were generated from a static/snapshot view of a recent Substrate master node. Some items may not be available in older nodes, or in any customized implementations.)
+- **[balances](#balances)**
+
+- **[contracts](#contracts)**
+
+- **[council](#council)**
+
+- **[democracy](#democracy)**
+
+- **[elections](#elections)**
+
+- **[grandpa](#grandpa)**
+
+- **[imOnline](#imOnline)**
+
+- **[indices](#indices)**
+
+- **[offences](#offences)**
+
+- **[session](#session)**
+
+- **[staking](#staking)**
+
+- **[sudo](#sudo)**
+
+- **[system](#system)**
+
+- **[technicalCommittee](#technicalCommittee)**
+
+- **[technicalMembership](#technicalMembership)**
+
+- **[treasury](#treasury)**
+
+- **[utility](#utility)**
+
+
+___
+
+
+### balances
+
+▸ **NewAccount**(`AccountId`, `Balance`)
+- **summary**: A new account was created.
+
+▸ **ReapedAccount**(`AccountId`)
+- **summary**: An account was reaped.
+
+▸ **Transfer**(`AccountId`, `AccountId`, `Balance`, `Balance`)
+- **summary**: Transfer succeeded (from, to, value, fees).
+
+___
+
+
+### contracts
+
+▸ **CodeStored**(`Hash`)
+- **summary**: Code with the specified hash has been stored.
+
+▸ **Contract**(`AccountId`, `Bytes`)
+- **summary**: An event from contract of account.
+
+▸ **Dispatched**(`AccountId`, `bool`)
+- **summary**: A call was dispatched from the given account. The bool signals whether it was successful execution or not.
+
+▸ **Instantiated**(`AccountId`, `AccountId`)
+- **summary**: Contract deployed by address at the specified address.
+
+▸ **ScheduleUpdated**(`u32`)
+- **summary**: Triggered when the current schedule is updated.
+
+▸ **Transfer**(`AccountId`, `AccountId`, `Balance`)
+- **summary**: Transfer happened `from` to `to` with given `value` as part of a `call` or `instantiate`.
+
+___
+
+
+### council
+
+▸ **Approved**(`Hash`)
+- **summary**: A motion was approved by the required threshold.
+
+▸ **Disapproved**(`Hash`)
+- **summary**: A motion was not approved by the required threshold.
+
+▸ **Executed**(`Hash`, `bool`)
+- **summary**: A motion was executed; `bool` is true if returned without error.
+
+▸ **MemberExecuted**(`Hash`, `bool`)
+- **summary**: A single member did some action; `bool` is true if returned without error.
+
+▸ **Proposed**(`AccountId`, `ProposalIndex`, `Hash`, `MemberCount`)
+- **summary**: A motion (given hash) has been proposed (by given account) with a threshold (given `MemberCount`).
+
+▸ **Voted**(`AccountId`, `Hash`, `bool`, `MemberCount`, `MemberCount`)
+- **summary**: A motion (given hash) has been voted on by given account, leaving a tally (yes votes and no votes given respectively as `MemberCount`).
+
+___
+
+
+### democracy
+
+▸ **Cancelled**(`ReferendumIndex`)
+
+▸ **Delegated**(`AccountId`, `AccountId`)
+
+▸ **Executed**(`ReferendumIndex`, `bool`)
+
+▸ **ExternalTabled**()
+
+▸ **NotPassed**(`ReferendumIndex`)
+
+▸ **Passed**(`ReferendumIndex`)
+
+▸ **Proposed**(`PropIndex`, `Balance`)
+
+▸ **Started**(`ReferendumIndex`, `VoteThreshold`)
+
+▸ **Tabled**(`PropIndex`, `Balance`, `Vec<AccountId>`)
+
+▸ **Undelegated**(`AccountId`)
+
+▸ **Vetoed**(`AccountId`, `Hash`, `BlockNumber`)
+
+___
+
+
+### elections
+
+▸ **BadReaperSlashed**(`AccountId`)
+- **summary**: slashed reaper
+
+▸ **TallyFinalized**(`Vec<AccountId>`, `Vec<AccountId>`)
+- **summary**: A tally (for approval votes of seat(s)) has ended (with one or more new members).
+
+▸ **TallyStarted**(`u32`)
+- **summary**: A tally (for approval votes of seat(s)) has started.
+
+▸ **VoterReaped**(`AccountId`, `AccountId`)
+- **summary**: reaped voter, reaper
+
+___
+
+
+### grandpa
+
+▸ **NewAuthorities**(`Vec<(AuthorityId,AuthorityWeight)>`)
+- **summary**: New authority set has been applied.
+
+▸ **Paused**()
+- **summary**: Current authority set has been paused.
+
+▸ **Resumed**()
+- **summary**: Current authority set has been resumed.
+
+___
+
+
+### imOnline
+
+▸ **HeartbeatReceived**(`AuthorityId`)
+- **summary**: A new heartbeat was received from `AuthorityId`
+
+___
+
+
+### indices
+
+▸ **NewAccountIndex**(`AccountId`, `AccountIndex`)
+- **summary**: A new account index was assigned.  This event is not triggered when an existing index is reassigned to another `AccountId`.
+
+___
+
+
+### offences
+
+▸ **Offence**(`Kind`, `OpaqueTimeSlot`)
+- **summary**: There is an offence reported of the given `kind` happened at the `session_index` and (kind-specific) time slot. This event is not deposited for duplicate slashes.
+
+___
+
+
+### session
+
+▸ **NewSession**(`SessionIndex`)
+- **summary**: New session has happened. Note that the argument is the session index, not the block number as the type might suggest.
+
+___
+
+
+### staking
+
+▸ **OldSlashingReportDiscarded**(`SessionIndex`)
+- **summary**: An old slashing report from a prior era was discarded because it could not be processed.
+
+▸ **Reward**(`Balance`)
+- **summary**: All validators have been rewarded by the given balance.
+
+▸ **Slash**(`AccountId`, `Balance`)
+- **summary**: One validator (and its nominators) has been slashed by the given amount.
+
+___
+
+
+### sudo
+
+▸ **KeyChanged**(`AccountId`)
+- **summary**: The sudoer just switched identity; the old key is supplied.
+
+▸ **Sudid**(`bool`)
+- **summary**: A sudo just took place.
+
+▸ **SudoAsDone**(`bool`)
+- **summary**: A sudo just took place.
+
+___
+
+
+### system
+
+▸ **ExtrinsicFailed**(`DispatchError`)
+- **summary**: An extrinsic failed.
+
+▸ **ExtrinsicSuccess**()
+- **summary**: An extrinsic completed successfully.
+
+___
+
+
+### technicalCommittee
+
+▸ **Approved**(`Hash`)
+- **summary**: A motion was approved by the required threshold.
+
+▸ **Disapproved**(`Hash`)
+- **summary**: A motion was not approved by the required threshold.
+
+▸ **Executed**(`Hash`, `bool`)
+- **summary**: A motion was executed; `bool` is true if returned without error.
+
+▸ **MemberExecuted**(`Hash`, `bool`)
+- **summary**: A single member did some action; `bool` is true if returned without error.
+
+▸ **Proposed**(`AccountId`, `ProposalIndex`, `Hash`, `MemberCount`)
+- **summary**: A motion (given hash) has been proposed (by given account) with a threshold (given `MemberCount`).
+
+▸ **Voted**(`AccountId`, `Hash`, `bool`, `MemberCount`, `MemberCount`)
+- **summary**: A motion (given hash) has been voted on by given account, leaving a tally (yes votes and no votes given respectively as `MemberCount`).
+
+___
+
+
+### technicalMembership
+
+▸ **Dummy**(`PhantomData`)
+- **summary**: Phantom member, never used.
+
+▸ **MemberAdded**()
+- **summary**: The given member was added; see the transaction for who.
+
+▸ **MemberRemoved**()
+- **summary**: The given member was removed; see the transaction for who.
+
+▸ **MembersReset**()
+- **summary**: The membership was reset; see the transaction for who the new set is.
+
+▸ **MembersSwapped**()
+- **summary**: Two members were swapped; see the transaction for who.
+
+___
+
+
+### treasury
+
+▸ **Awarded**(`ProposalIndex`, `Balance`, `AccountId`)
+- **summary**: Some funds have been allocated.
+
+▸ **Burnt**(`Balance`)
+- **summary**: Some of our funds have been burnt.
+
+▸ **Proposed**(`ProposalIndex`)
+- **summary**: New proposal.
+
+▸ **Rollover**(`Balance`)
+- **summary**: Spending has finished; this is the amount that rolls over until next spend.
+
+▸ **Spending**(`Balance`)
+- **summary**: We have ended a spend period and will now allocate funds.
+
+___
+
+
+### utility
+
+▸ **BatchExecuted**(`Vec<DispatchResult>`)

docs/substrate/extrinsics.md

@@ -0,0 +1,370 @@
+## Extrinsics
+
+The following sections contain Extrinsics methods are part of the default Substrate runtime. On the api, these are exposed via `api.tx.<module>.<method>`. 
+
+(NOTE: These were generated from a static/snapshot view of a recent Substrate master node. Some items may not be available in older nodes, or in any customized implementations.)
+- **[authorship](#authorship)**
+
+- **[balances](#balances)**
+
+- **[contracts](#contracts)**
+
+- **[council](#council)**
+
+- **[democracy](#democracy)**
+
+- **[elections](#elections)**
+
+- **[finalityTracker](#finalityTracker)**
+
+- **[grandpa](#grandpa)**
+
+- **[imOnline](#imOnline)**
+
+- **[session](#session)**
+
+- **[staking](#staking)**
+
+- **[sudo](#sudo)**
+
+- **[system](#system)**
+
+- **[technicalCommittee](#technicalCommittee)**
+
+- **[technicalMembership](#technicalMembership)**
+
+- **[timestamp](#timestamp)**
+
+- **[treasury](#treasury)**
+
+- **[utility](#utility)**
+
+
+___
+
+
+### authorship
+
+▸ **setUncles**(new_uncles: `Vec<Header>`)
+- **summary**: Provide a set of uncles.
+
+___
+
+
+### balances
+
+▸ **forceTransfer**(source: `Address`, dest: `Address`, value: `Compact<Balance>`)
+- **summary**: Exactly as `transfer`, except the origin must be root and the source account may be specified.
+
+▸ **setBalance**(who: `Address`, new_free: `Compact<Balance>`, new_reserved: `Compact<Balance>`)
+- **summary**: Set the balances of a given account.  This will alter `FreeBalance` and `ReservedBalance` in storage. it will also decrease the total issuance of the system (`TotalIssuance`). If the new free or reserved balance is below the existential deposit, it will reset the account nonce (`system::AccountNonce`).  The dispatch origin for this call is `root`.  # <weight> - Independent of the arguments. - Contains a limited number of reads and writes. # </weight>
+
+▸ **transfer**(dest: `Address`, value: `Compact<Balance>`)
+- **summary**: Transfer some liquid free balance to another account.  `transfer` will set the `FreeBalance` of the sender and receiver. It will decrease the total issuance of the system by the `TransferFee`. If the sender's account is below the existential deposit as a result of the transfer, the account will be reaped.  The dispatch origin for this call must be `Signed` by the transactor.  # <weight> - Dependent on arguments but not critical, given proper implementations for input config types. See related functions below. - It contains a limited number of reads and writes internally and no complex computation.  Related functions:  - `ensure_can_withdraw` is always called internally but has a bounded complexity. - Transferring balances to accounts that did not exist before will cause `T::OnNewAccount::on_new_account` to be called. - Removing enough funds from an account will trigger `T::DustRemoval::on_unbalanced` and `T::OnFreeBalanceZero::on_free_balance_zero`.  # </weight>
+
+___
+
+
+### contracts
+
+▸ **call**(dest: `Address`, value: `Compact<BalanceOf>`, gas_limit: `Compact<Gas>`, data: `Bytes`)
+- **summary**: Makes a call to an account, optionally transferring some balance.  * If the account is a smart-contract account, the associated code will be executed and any value will be transferred. * If the account is a regular account, any value will be transferred. * If no account exists and the call value is not less than `existential_deposit`, a regular account will be created and any value will be transferred.
+
+▸ **claimSurcharge**(dest: `AccountId`, aux_sender: `Option<AccountId>`)
+- **summary**: Allows block producers to claim a small reward for evicting a contract. If a block producer fails to do so, a regular users will be allowed to claim the reward.  If contract is not evicted as a result of this call, no actions are taken and the sender is not eligible for the reward.
+
+▸ **instantiate**(endowment: `Compact<BalanceOf>`, gas_limit: `Compact<Gas>`, code_hash: `CodeHash`, data: `Bytes`)
+- **summary**: Instantiates a new contract from the `codehash` generated by `put_code`, optionally transferring some balance.  Instantiation is executed as follows:  - The destination address is computed based on the sender and hash of the code. - The smart-contract account is created at the computed address. - The `ctor_code` is executed in the context of the newly-created account. Buffer returned after the execution is saved as the `code` of the account. That code will be invoked upon any call received by this account. - The contract is initialized.
+
+▸ **putCode**(gas_limit: `Compact<Gas>`, code: `Bytes`)
+- **summary**: Stores the given binary Wasm code into the chain's storage and returns its `codehash`. You can instantiate contracts only with stored code.
+
+▸ **updateSchedule**(schedule: `Schedule`)
+- **summary**: Updates the schedule for metering contracts.  The schedule must have a greater version than the stored schedule.
+
+___
+
+
+### council
+
+▸ **execute**(proposal: `Proposal`)
+- **summary**: Dispatch a proposal from a member using the `Member` origin.  Origin must be a member of the collective.
+
+▸ **propose**(threshold: `Compact<MemberCount>`, proposal: `Proposal`)
+- **summary**: # <weight> - Bounded storage reads and writes. - Argument `threshold` has bearing on weight. # </weight>
+
+▸ **setMembers**(new_members: `Vec<AccountId>`)
+- **summary**: Set the collective's membership manually to `new_members`. Be nice to the chain and provide it pre-sorted.  Requires root origin.
+
+▸ **vote**(proposal: `Hash`, index: `Compact<ProposalIndex>`, approve: `bool`)
+- **summary**: # <weight> - Bounded storage read and writes. - Will be slightly heavier if the proposal is approved / disapproved after the vote. # </weight>
+
+___
+
+
+### democracy
+
+▸ **cancelQueued**(when: `Compact<BlockNumber>`, which: `Compact<u32>`, what: `Compact<ReferendumIndex>`)
+- **summary**: Cancel a proposal queued for enactment.
+
+▸ **cancelReferendum**(ref_index: `Compact<ReferendumIndex>`)
+- **summary**: Remove a referendum.
+
+▸ **delegate**(to: `AccountId`, conviction: `Conviction`)
+- **summary**: Delegate vote.  # <weight> - One extra DB entry. # </weight>
+
+▸ **emergencyCancel**(ref_index: `ReferendumIndex`)
+- **summary**: Schedule an emergency cancellation of a referendum. Cannot happen twice to the same referendum.
+
+▸ **externalPropose**(proposal: `Proposal`)
+- **summary**: Schedule a referendum to be tabled once it is legal to schedule an external referendum.
+
+▸ **externalProposeDefault**(proposal: `Proposal`)
+- **summary**: Schedule a negative-turnout-bias referendum to be tabled next once it is legal to schedule an external referendum.  Unlike `external_propose`, blacklisting has no effect on this and it may replace a pre-scheduled `external_propose` call.
+
+▸ **externalProposeMajority**(proposal: `Proposal`)
+- **summary**: Schedule a majority-carries referendum to be tabled next once it is legal to schedule an external referendum.  Unlike `external_propose`, blacklisting has no effect on this and it may replace a pre-scheduled `external_propose` call.
+
+▸ **fastTrack**(proposal_hash: `Hash`, voting_period: `BlockNumber`, delay: `BlockNumber`)
+- **summary**: Schedule the currently externally-proposed majority-carries referendum to be tabled immediately. If there is no externally-proposed referendum currently, or if there is one but it is not a majority-carries referendum then it fails.  - `proposal_hash`: The hash of the current external proposal. - `voting_period`: The period that is allowed for voting on this proposal. - `delay`: The number of block after voting has ended in approval and this should be enacted. Increased to `EmergencyVotingPeriod` if too low.
+
+▸ **propose**(proposal: `Proposal`, value: `Compact<BalanceOf>`)
+- **summary**: Propose a sensitive action to be taken.  # <weight> - O(1). - Two DB changes, one DB entry. # </weight>
+
+▸ **proxyVote**(ref_index: `Compact<ReferendumIndex>`, vote: `Vote`)
+- **summary**: Vote in a referendum on behalf of a stash. If `vote.is_aye()`, the vote is to enact the proposal;  otherwise it is a vote to keep the status quo.  # <weight> - O(1). - One DB change, one DB entry. # </weight>
+
+▸ **removeProxy**(proxy: `AccountId`)
+- **summary**: Clear the proxy. Called by the stash.  # <weight> - One DB clear. # </weight>
+
+▸ **resignProxy**()
+- **summary**: Clear the proxy. Called by the proxy.  # <weight> - One DB clear. # </weight>
+
+▸ **second**(proposal: `Compact<PropIndex>`)
+- **summary**: Propose a sensitive action to be taken.  # <weight> - O(1). - One DB entry. # </weight>
+
+▸ **setProxy**(proxy: `AccountId`)
+- **summary**: Specify a proxy. Called by the stash.  # <weight> - One extra DB entry. # </weight>
+
+▸ **undelegate**()
+- **summary**: Undelegate vote.  # <weight> - O(1). # </weight>
+
+▸ **vetoExternal**(proposal_hash: `Hash`)
+- **summary**: Veto and blacklist the external proposal hash.
+
+▸ **vote**(ref_index: `Compact<ReferendumIndex>`, vote: `Vote`)
+- **summary**: Vote in a referendum. If `vote.is_aye()`, the vote is to enact the proposal; otherwise it is a vote to keep the status quo.  # <weight> - O(1). - One DB change, one DB entry. # </weight>
+
+___
+
+
+### elections
+
+▸ **presentWinner**(candidate: `Address`, total: `Compact<BalanceOf>`, index: `Compact<VoteIndex>`)
+- **summary**: Claim that `candidate` is one of the top `carry_count + desired_seats` candidates. Only works iff the presentation period is active. `candidate` should have at least collected some non-zero `total` votes and `origin` must have enough funds to pay for a potential slash.  # <weight> - O(voters) compute. - One DB change. # </weight>
+
+▸ **proxySetApprovals**(votes: `Vec<bool>`, index: `Compact<VoteIndex>`, hint: `SetIndex`, value: `Compact<BalanceOf>`)
+- **summary**: Set candidate approvals from a proxy. Approval slots stay valid as long as candidates in those slots are registered.  # <weight> - Same as `set_approvals` with one additional storage read. # </weight>
+
+▸ **reapInactiveVoter**(reporter_index: `Compact<u32>`, who: `Address`, who_index: `Compact<u32>`, assumed_vote_index: `Compact<VoteIndex>`)
+- **summary**: Remove a voter. For it not to be a bond-consuming no-op, all approved candidate indices must now be either unregistered or registered to a candidate that registered the slot after the voter gave their last approval set.  Both indices must be provided as explained in [`voter_at`] function.  May be called by anyone. Returns the voter deposit to `signed`.  # <weight> - O(1). - Two fewer DB entries, one DB change. # </weight>
+
+▸ **removeMember**(who: `Address`)
+- **summary**: Remove a particular member from the set. This is effective immediately.  Note: A tally should happen instantly (if not already in a presentation period) to fill the seat if removal means that the desired members are not met.
+
+▸ **retractVoter**(index: `Compact<u32>`)
+- **summary**: Remove a voter. All votes are cancelled and the voter deposit is returned.  The index must be provided as explained in [`voter_at`] function.  Also removes the lock on the balance of the voter. See [`do_set_approvals()`].  # <weight> - O(1). - Two fewer DB entries, one DB change. # </weight>
+
+▸ **setApprovals**(votes: `Vec<bool>`, index: `Compact<VoteIndex>`, hint: `SetIndex`, value: `Compact<BalanceOf>`)
+- **summary**: Set candidate approvals. Approval slots stay valid as long as candidates in those slots are registered.  Locks `value` from the balance of `origin` indefinitely. Only [`retract_voter`] or [`reap_inactive_voter`] can unlock the balance.  `hint` argument is interpreted differently based on: - if `origin` is setting approvals for the first time: The index will be checked for being a valid _hole_ in the voter list. - if the hint is correctly pointing to a hole, no fee is deducted from `origin`. - Otherwise, the call will succeed but the index is ignored and simply a push to the last chunk with free space happens. If the new push causes a new chunk to be created, a fee indicated by [`VotingFee`] is deducted. - if `origin` is already a voter: the index __must__ be valid and point to the correct position of the `origin` in the current voters list.  Note that any trailing `false` votes in `votes` is ignored; In approval voting, not voting for a candidate and voting false, are equal.  # <weight> - O(1). - Two extra DB entries, one DB change. - Argument `votes` is limited in length to number of candidates. # </weight>
+
+▸ **setDesiredSeats**(count: `Compact<u32>`)
+- **summary**: Set the desired member count; if lower than the current count, then seats will not be up election when they expire. If more, then a new vote will be started if one is not already in progress.
+
+▸ **setPresentationDuration**(count: `Compact<BlockNumber>`)
+- **summary**: Set the presentation duration. If there is currently a vote being presented for, will invoke `finalize_vote`.
+
+▸ **setTermDuration**(count: `Compact<BlockNumber>`)
+- **summary**: Set the presentation duration. If there is current a vote being presented for, will invoke `finalize_vote`.
+
+▸ **submitCandidacy**(slot: `Compact<u32>`)
+- **summary**: Submit oneself for candidacy.  Account must have enough transferrable funds in it to pay the bond.  NOTE: if `origin` has already assigned approvals via [`set_approvals`], it will NOT have any usable funds to pass candidacy bond and must first retract. Note that setting approvals will lock the entire balance of the voter until retraction or being reported.  # <weight> - Independent of input. - Three DB changes. # </weight>
+
+___
+
+
+### finalityTracker
+
+▸ **finalHint**(hint: `Compact<BlockNumber>`)
+- **summary**: Hint that the author of this block thinks the best finalized block is the given number.
+
+___
+
+
+### grandpa
+
+▸ **reportMisbehavior**(_report: `Bytes`)
+- **summary**: Report some misbehavior.
+
+___
+
+
+### imOnline
+
+▸ **heartbeat**(heartbeat: `Heartbeat`, signature: `Signature`)
+
+___
+
+
+### session
+
+▸ **setKeys**(keys: `Keys`, proof: `Bytes`)
+- **summary**: Sets the session key(s) of the function caller to `key`. Allows an account to set its session key prior to becoming a validator. This doesn't take effect until the next session.  The dispatch origin of this function must be signed.  # <weight> - O(log n) in number of accounts. - One extra DB entry. # </weight>
+
+___
+
+
+### staking
+
+▸ **bond**(controller: `Address`, value: `Compact<BalanceOf>`, payee: `RewardDestination`)
+- **summary**: Take the origin account as a stash and lock up `value` of its balance. `controller` will be the account that controls it.  `value` must be more than the `minimum_balance` specified by `T::Currency`.  The dispatch origin for this call must be _Signed_ by the stash account.  # <weight> - Independent of the arguments. Moderate complexity. - O(1). - Three extra DB entries.  NOTE: Two of the storage writes (`Self::bonded`, `Self::payee`) are _never_ cleaned unless the `origin` falls below _existential deposit_ and gets removed as dust. # </weight>
+
+▸ **bondExtra**(max_additional: `Compact<BalanceOf>`)
+- **summary**: Add some extra amount that have appeared in the stash `free_balance` into the balance up for staking.  Use this if there are additional funds in your stash account that you wish to bond. Unlike [`bond`] or [`unbond`] this function does not impose any limitation on the amount that can be added.  The dispatch origin for this call must be _Signed_ by the stash, not the controller.  # <weight> - Independent of the arguments. Insignificant complexity. - O(1). - One DB entry. # </weight>
+
+▸ **chill**()
+- **summary**: Declare no desire to either validate or nominate.  Effects will be felt at the beginning of the next era.  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  # <weight> - Independent of the arguments. Insignificant complexity. - Contains one read. - Writes are limited to the `origin` account key. # </weight>
+
+▸ **forceNewEra**()
+- **summary**: Force there to be a new era at the end of the next session. After this, it will be reset to normal (non-forced) behaviour.  # <weight> - No arguments. # </weight>
+
+▸ **forceNoEras**()
+- **summary**: Force there to be no new eras indefinitely.  # <weight> - No arguments. # </weight>
+
+▸ **nominate**(targets: `Vec<Address>`)
+- **summary**: Declare the desire to nominate `targets` for the origin controller.  Effects will be felt at the beginning of the next era.  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  # <weight> - The transaction's complexity is proportional to the size of `targets`, which is capped at `MAX_NOMINATIONS`. - Both the reads and writes follow a similar pattern. # </weight>
+
+▸ **setController**(controller: `Address`)
+- **summary**: (Re-)set the controller of a stash.  Effects will be felt at the beginning of the next era.  The dispatch origin for this call must be _Signed_ by the stash, not the controller.  # <weight> - Independent of the arguments. Insignificant complexity. - Contains a limited number of reads. - Writes are limited to the `origin` account key. # </weight>
+
+▸ **setInvulnerables**(validators: `Vec<AccountId>`)
+- **summary**: Set the validators who cannot be slashed (if any).
+
+▸ **setPayee**(payee: `RewardDestination`)
+- **summary**: (Re-)set the payment target for a controller.  Effects will be felt at the beginning of the next era.  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  # <weight> - Independent of the arguments. Insignificant complexity. - Contains a limited number of reads. - Writes are limited to the `origin` account key. # </weight>
+
+▸ **setValidatorCount**(new: `Compact<u32>`)
+- **summary**: The ideal number of validators.
+
+▸ **unbond**(value: `Compact<BalanceOf>`)
+- **summary**: Schedule a portion of the stash to be unlocked ready for transfer out after the bond period ends. If this leaves an amount actively bonded less than T::Currency::minimum_balance(), then it is increased to the full amount.  Once the unlock period is done, you can call `withdraw_unbonded` to actually move the funds out of management ready for transfer.  No more than a limited number of unlocking chunks (see `MAX_UNLOCKING_CHUNKS`) can co-exists at the same time. In that case, [`Call::withdraw_unbonded`] need to be called first to remove some of the chunks (if possible).  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  See also [`Call::withdraw_unbonded`].  # <weight> - Independent of the arguments. Limited but potentially exploitable complexity. - Contains a limited number of reads. - Each call (requires the remainder of the bonded balance to be above `minimum_balance`) will cause a new entry to be inserted into a vector (`Ledger.unlocking`) kept in storage. The only way to clean the aforementioned storage item is also user-controlled via `withdraw_unbonded`. - One DB entry. </weight>
+
+▸ **validate**(prefs: `ValidatorPrefs`)
+- **summary**: Declare the desire to validate for the origin controller.  Effects will be felt at the beginning of the next era.  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  # <weight> - Independent of the arguments. Insignificant complexity. - Contains a limited number of reads. - Writes are limited to the `origin` account key. # </weight>
+
+▸ **withdrawUnbonded**()
+- **summary**: Remove any unlocked chunks from the `unlocking` queue from our management.  This essentially frees up that balance to be used by the stash account to do whatever it wants.  The dispatch origin for this call must be _Signed_ by the controller, not the stash.  See also [`Call::unbond`].  # <weight> - Could be dependent on the `origin` argument and how much `unlocking` chunks exist. It implies `consolidate_unlocked` which loops over `Ledger.unlocking`, which is indirectly user-controlled. See [`unbond`] for more detail. - Contains a limited number of reads, yet the size of which could be large based on `ledger`. - Writes are limited to the `origin` account key. # </weight>
+
+___
+
+
+### sudo
+
+▸ **setKey**(new: `Address`)
+- **summary**: Authenticates the current sudo key and sets the given AccountId (`new`) as the new sudo key.  The dispatch origin for this call must be _Signed_.  # <weight> - O(1). - Limited storage reads. - One DB change. # </weight>
+
+▸ **sudo**(proposal: `Proposal`)
+- **summary**: Authenticates the sudo key and dispatches a function call with `Root` origin.  The dispatch origin for this call must be _Signed_.  # <weight> - O(1). - Limited storage reads. - One DB write (event). - Unknown weight of derivative `proposal` execution. # </weight>
+
+▸ **sudoAs**(who: `Address`, proposal: `Proposal`)
+- **summary**: Authenticates the sudo key and dispatches a function call with `Signed` origin from a given account.  The dispatch origin for this call must be _Signed_.  # <weight> - O(1). - Limited storage reads. - One DB write (event). - Unknown weight of derivative `proposal` execution. # </weight>
+
+___
+
+
+### system
+
+▸ **fillBlock**()
+- **summary**: A big dispatch that will disallow any other transaction to be included.
+
+▸ **killPrefix**(prefix: `Key`)
+- **summary**: Kill all storage items with a key that starts with the given prefix.
+
+▸ **killStorage**(keys: `Vec<Key>`)
+- **summary**: Kill some items from storage.
+
+▸ **remark**(_remark: `Bytes`)
+- **summary**: Make some on-chain remark.
+
+▸ **setCode**(new: `Bytes`)
+- **summary**: Set the new code.
+
+▸ **setHeapPages**(pages: `u64`)
+- **summary**: Set the number of pages in the WebAssembly environment's heap.
+
+▸ **setStorage**(items: `Vec<KeyValue>`)
+- **summary**: Set some items of storage.
+
+___
+
+
+### technicalCommittee
+
+▸ **execute**(proposal: `Proposal`)
+- **summary**: Dispatch a proposal from a member using the `Member` origin.  Origin must be a member of the collective.
+
+▸ **propose**(threshold: `Compact<MemberCount>`, proposal: `Proposal`)
+- **summary**: # <weight> - Bounded storage reads and writes. - Argument `threshold` has bearing on weight. # </weight>
+
+▸ **setMembers**(new_members: `Vec<AccountId>`)
+- **summary**: Set the collective's membership manually to `new_members`. Be nice to the chain and provide it pre-sorted.  Requires root origin.
+
+▸ **vote**(proposal: `Hash`, index: `Compact<ProposalIndex>`, approve: `bool`)
+- **summary**: # <weight> - Bounded storage read and writes. - Will be slightly heavier if the proposal is approved / disapproved after the vote. # </weight>
+
+___
+
+
+### technicalMembership
+
+▸ **addMember**(who: `AccountId`)
+- **summary**: Add a member `who` to the set.  May only be called from `AddOrigin` or root.
+
+▸ **removeMember**(who: `AccountId`)
+- **summary**: Remove a member `who` from the set.  May only be called from `RemoveOrigin` or root.
+
+▸ **resetMembers**(members: `Vec<AccountId>`)
+- **summary**: Change the membership to a new set, disregarding the existing membership. Be nice and pass `members` pre-sorted.  May only be called from `ResetOrigin` or root.
+
+▸ **swapMember**(remove: `AccountId`, add: `AccountId`)
+- **summary**: Swap out one member `remove` for another `add`.  May only be called from `SwapOrigin` or root.
+
+___
+
+
+### timestamp
+
+▸ **set**(now: `Compact<Moment>`)
+- **summary**: Set the current time.  This call should be invoked exactly once per block. It will panic at the finalization phase, if this call hasn't been invoked by that time.  The timestamp should be greater than the previous one by the amount specified by `MinimumPeriod`.  The dispatch origin for this call must be `Inherent`.
+
+___
+
+
+### treasury
+
+▸ **approveProposal**(proposal_id: `Compact<ProposalIndex>`)
+- **summary**: Approve a proposal. At a later time, the proposal will be allocated to the beneficiary and the original deposit will be returned.  # <weight> - O(1). - Limited storage reads. - One DB change. # </weight>
+
+▸ **proposeSpend**(value: `Compact<BalanceOf>`, beneficiary: `Address`)
+- **summary**: Put forward a suggestion for spending. A deposit proportional to the value is reserved and slashed if the proposal is rejected. It is returned once the proposal is awarded.  # <weight> - O(1). - Limited storage reads. - One DB change, one extra DB entry. # </weight>
+
+▸ **rejectProposal**(proposal_id: `Compact<ProposalIndex>`)
+- **summary**: Reject a proposed spend. The original deposit will be slashed.  # <weight> - O(1). - Limited storage reads. - One DB clear. # </weight>
+
+___
+
+
+### utility
+
+▸ **batch**(calls: `Vec<Call>`)
+- **summary**: Send a batch of dispatch calls (only root).

docs/substrate/rpc.md

@@ -1,10 +1,17 @@
 ## JSON-RPC
 
-_The following sections contain RPC methods that are Remote Calls available by default and allow you to interact with the actual node, query, and submit. The RPCs are provided by Substrate itself._
+The following sections contain RPC methods that are Remote Calls available by default and allow you to interact with the actual node, query, and submit.
+
+- **[account](#account)**
+
 - **[author](#author)**
 
 - **[chain](#chain)**
 
+- **[contracts](#contracts)**
+
+- **[rpc](#rpc)**
+
 - **[state](#state)**
 
 - **[system](#system)**
@@ -13,11 +20,21 @@ _The following sections contain RPC methods that are Remote Calls available by d
 ___
 
 
+### account
+
+_(Optional) Methods that retrieves account-specific information_
+
+▸ **nextIndex**(accountId: `AccountId`): `Index`
+- **summary**: Retrieves the next accountIndex as available on the node
+
+___
+
+
 ### author
 
 _Authoring of network items_
 
-▸ **insertKey**(keyType: `Text`, suri: `Text`, maybePublic?: `Bytes`): `Bytes`
+▸ **insertKey**(keyType: `Text`, suri: `Text`, publicKey: `Bytes`): `Bytes`
 - **summary**: Insert a key into the keystore.
 
 ▸ **pendingExtrinsics**(): `Vec<Extrinsic>`
@@ -54,17 +71,31 @@ _Retrieval of chain data_
 ▸ **getHeader**(hash?: `Hash`): `Header`
 - **summary**: Retrieves the header for a specific block
 
-▸ **getRuntimeVersion**(hash?: `Hash`): `RuntimeVersion`
-- **summary**: Get the runtime version (alias of state_getRuntimeVersion)
-
 ▸ **subscribeFinalizedHeads**(): `Header`
 - **summary**: Retrieves the best finalized header via subscription
 
 ▸ **subscribeNewHeads**(): `Header`
 - **summary**: Retrieves the best header via subscription
 
-▸ **subscribeRuntimeVersion**(): `RuntimeVersion`
-- **summary**: Retrieves the runtime version via subscription
+___
+
+
+### contracts
+
+_(Optional) Methods that performs actions on contracts_
+
+▸ **call**(callRequest: `ContractCallRequest`, at?: `Hash`): `ContractExecResult`
+- **summary**: Executes a call to a contract
+
+___
+
+
+### rpc
+
+_Retrieves information about the RPC endpoints_
+
+▸ **methods**(): `RpcMethods`
+- **summary**: Retrieves the list of RPC methods that are exposed by the node
 
 ___
 
@@ -109,6 +140,9 @@ _Query of state_
 ▸ **queryStorage**(keys: `Vec<StorageKey>`, startBlock: `Hash`, block?: `Hash`): `Vec<StorageChangeSet>`
 - **summary**: Query historical storage entries (by key) starting from a start block
 
+▸ **subscribeRuntimeVersion**(): `RuntimeVersion`
+- **summary**: Retrieves the runtime version via subscription
+
 ▸ **subscribeStorage**(keys: `Vec<StorageKey>`): `StorageChangeSet`
 - **summary**: Subscribes to storage changes for the provided keys
 

docs/substrate/storage.md

@@ -0,0 +1,545 @@
+## Storage
+
+The following sections contain Storage methods are part of the default Substrate runtime. On the api, these are exposed via `api.query.<module>.<method>`. 
+
+(NOTE: These were generated from a static/snapshot view of a recent Substrate master node. Some items may not be available in older nodes, or in any customized implementations.)
+- **[authorship](#authorship)**
+
+- **[babe](#babe)**
+
+- **[balances](#balances)**
+
+- **[contracts](#contracts)**
+
+- **[council](#council)**
+
+- **[democracy](#democracy)**
+
+- **[elections](#elections)**
+
+- **[grandpa](#grandpa)**
+
+- **[imOnline](#imOnline)**
+
+- **[indices](#indices)**
+
+- **[offences](#offences)**
+
+- **[session](#session)**
+
+- **[staking](#staking)**
+
+- **[sudo](#sudo)**
+
+- **[system](#system)**
+
+- **[technicalCommittee](#technicalCommittee)**
+
+- **[technicalMembership](#technicalMembership)**
+
+- **[timestamp](#timestamp)**
+
+- **[treasury](#treasury)**
+
+- **[substrate](#substrate)**
+
+
+___
+
+
+### authorship
+
+▸ **author**(): `Option<AccountId>`
+- **summary**: Author of current block.
+
+▸ **didSetUncles**(): `bool`
+- **summary**: Whether uncles were already set in this block.
+
+▸ **uncles**(): `Vec<UncleEntryItem>`
+- **summary**: Uncles
+
+___
+
+
+### babe
+
+▸ **authorities**(): `Vec<(AuthorityId,BabeAuthorityWeight)>`
+- **summary**: Current epoch authorities.
+
+▸ **currentSlot**(): `u64`
+- **summary**: Current slot number.
+
+▸ **epochIndex**(): `u64`
+- **summary**: Current epoch index.
+
+▸ **genesisSlot**(): `u64`
+- **summary**: The slot at which the first epoch actually started. This is 0 until the first block of the chain.
+
+▸ **initialized**(): `Option<MaybeVrf>`
+- **summary**: Temporary value (cleared at block finalization) which is `Some` if per-block initialization has already been called for current block.
+
+▸ **nextRandomness**(): `[u8;32]`
+- **summary**: Next epoch randomness.
+
+▸ **randomness**(): `[u8;32]`
+- **summary**: The epoch randomness for the *current* epoch.  # Security  This MUST NOT be used for gambling, as it can be influenced by a malicious validator in the short term. It MAY be used in many cryptographic protocols, however, so long as one remembers that this (like everything else on-chain) it is public. For example, it can be used where a number is needed that cannot have been chosen by an adversary, for purposes such as public-coin zero-knowledge proofs.
+
+▸ **segmentIndex**(): `u32`
+- **summary**: Randomness under construction.  We make a tradeoff between storage accesses and list length. We store the under-construction randomness in segments of up to `UNDER_CONSTRUCTION_SEGMENT_LENGTH`.  Once a segment reaches this length, we begin the next one. We reset all segments and return to `0` at the beginning of every epoch.
+
+▸ **underConstruction**(`u32`): `Vec<[u8;32]>`
+
+___
+
+
+### balances
+
+▸ **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`.
+
+▸ **locks**(`AccountId`): `Vec<BalanceLock>`
+- **summary**: Any liquidity locks on some account balances.
+
+▸ **reservedBalance**(`AccountId`): `Balance`
+- **summary**: The amount of the balance of a given account that is externally reserved; this can still get slashed, but gets slashed last of all.  This balance is a 'reserve' balance that other subsystems use in order to set aside tokens that are still 'owned' by the account holder, but which are suspendable.  When this balance falls below the value of `ExistentialDeposit`, then this 'reserve account' is deleted: specifically, `ReservedBalance`.  `system::AccountNonce` is also deleted if `FreeBalance` is also zero (it also gets collapsed to zero if it ever becomes less than `ExistentialDeposit`.)
+
+▸ **totalIssuance**(): `Balance`
+- **summary**: The total units issued in the system.
+
+▸ **vesting**(`AccountId`): `Option<VestingSchedule>`
+- **summary**: Information regarding the vesting of a given account.
+
+___
+
+
+### contracts
+
+▸ **accountCounter**(): `u64`
+- **summary**: The subtrie counter.
+
+▸ **codeStorage**(`CodeHash`): `Option<PrefabWasmModule>`
+- **summary**: A mapping between an original code hash and instrumented wasm code, ready for execution.
+
+▸ **contractInfoOf**(`AccountId`): `Option<ContractInfo>`
+- **summary**: The code associated with a given account.
+
+▸ **currentSchedule**(): `Schedule`
+- **summary**: Current cost schedule for contracts.
+
+▸ **gasPrice**(): `BalanceOf`
+- **summary**: The price of one unit of gas.
+
+▸ **gasSpent**(): `Gas`
+- **summary**: Gas spent so far in this block.
+
+▸ **pristineCode**(`CodeHash`): `Option<Bytes>`
+- **summary**: A mapping from an original code hash to the original code, untouched by instrumentation.
+
+___
+
+
+### council
+
+▸ **members**(): `Vec<AccountId>`
+- **summary**: The current members of the collective. This is stored sorted (just by value).
+
+▸ **proposalCount**(): `u32`
+- **summary**: Proposals so far.
+
+▸ **proposalOf**(`Hash`): `Option<Proposal>`
+- **summary**: Actual proposal for a given hash, if it's current.
+
+▸ **proposals**(): `Vec<Hash>`
+- **summary**: The hashes of the active proposals.
+
+▸ **voting**(`Hash`): `Option<Votes>`
+- **summary**: Votes on a given proposal, if it is ongoing.
+
+___
+
+
+### democracy
+
+▸ **blacklist**(`Hash`): `Option<(BlockNumber,Vec<AccountId>)>`
+- **summary**: A record of who vetoed what. Maps proposal hash to a possible existent block number (until when it may not be resubmitted) and who vetoed it.
+
+▸ **cancellations**(`Hash`): `bool`
+- **summary**: Record of all proposals that have been subject to emergency cancellation.
+
+▸ **delegations**(`AccountId`): `((AccountId,Conviction), Linkage<AccountId>)`
+- **summary**: Get the account (and lock periods) to which another account is delegating vote.
+
+▸ **depositOf**(`PropIndex`): `Option<(BalanceOf,Vec<AccountId>)>`
+- **summary**: Those who have locked a deposit.
+
+▸ **dispatchQueue**(`BlockNumber`): `Vec<Option<(Proposal,ReferendumIndex)>>`
+- **summary**: Queue of successful referenda to be dispatched.
+
+▸ **lastTabledWasExternal**(): `bool`
+- **summary**: True if the last referendum tabled was submitted externally. False if it was a public proposal.
+
+▸ **nextExternal**(): `Option<(Proposal,VoteThreshold)>`
+- **summary**: The referendum to be tabled whenever it would be valid to table an external proposal. This happens when a referendum needs to be tabled and one of two conditions are met: - `LastTabledWasExternal` is `false`; or - `PublicProps` is empty.
+
+▸ **nextTally**(): `ReferendumIndex`
+- **summary**: The next referendum index that should be tallied.
+
+▸ **proxy**(`AccountId`): `Option<AccountId>`
+- **summary**: Who is able to vote for whom. Value is the fund-holding account, key is the vote-transaction-sending account.
+
+▸ **publicPropCount**(): `PropIndex`
+- **summary**: The number of (public) proposals that have been made so far.
+
+▸ **publicProps**(): `Vec<(PropIndex,Proposal,AccountId)>`
+- **summary**: The public proposals. Unsorted.
+
+▸ **referendumCount**(): `ReferendumIndex`
+- **summary**: The next free referendum index, aka the number of referenda started so far.
+
+▸ **referendumInfoOf**(`ReferendumIndex`): `Option<ReferendumInfo>`
+- **summary**: Information concerning any given referendum.
+
+▸ **voteOf**(`(ReferendumIndex,AccountId)`): `Vote`
+- **summary**: Get the vote in a given referendum of a particular voter. The result is meaningful only if `voters_for` includes the voter when called with the referendum (you'll get the default `Vote` value otherwise). If you don't want to check `voters_for`, then you can also check for simple existence with `VoteOf::exists` first.
+
+▸ **votersFor**(`ReferendumIndex`): `Vec<AccountId>`
+- **summary**: Get the voters for the current proposal.
+
+___
+
+
+### elections
+
+▸ **approvalsOf**(`(AccountId,SetIndex)`): `Vec<ApprovalFlag>`
+
+▸ **candidateCount**(): `u32`
+- **summary**: Current number of active candidates
+
+▸ **candidates**(): `Vec<AccountId>`
+- **summary**: The present candidate list.
+
+▸ **desiredSeats**(): `u32`
+- **summary**: Number of accounts that should constitute the collective.
+
+▸ **leaderboard**(): `Option<Vec<(BalanceOf,AccountId)>>`
+- **summary**: Get the leaderboard if we're in the presentation phase. The first element is the weight of each entry; It may be the direct summed approval stakes, or a weighted version of it. Sorted from low to high.
+
+▸ **members**(): `Vec<(AccountId,BlockNumber)>`
+- **summary**: The current membership. When there's a vote going on, this should still be used for executive matters. The block number (second element in the tuple) is the block that their position is active until (calculated by the sum of the block number when the member was elected and their term duration).
+
+▸ **nextFinalize**(): `Option<(BlockNumber,u32,Vec<AccountId>)>`
+- **summary**: The accounts holding the seats that will become free on the next tally.
+
+▸ **nextVoterSet**(): `SetIndex`
+- **summary**: the next free set to store a voter in. This will keep growing.
+
+▸ **presentationDuration**(): `BlockNumber`
+- **summary**: How long to give each top candidate to present themselves after the vote ends.
+
+▸ **proxy**(`AccountId`): `Option<AccountId>`
+- **summary**: Who is able to vote for whom. Value is the fund-holding account, key is the vote-transaction-sending account.
+
+▸ **registerInfoOf**(`AccountId`): `Option<(VoteIndex,u32)>`
+- **summary**: The vote index and list slot that the candidate `who` was registered or `None` if they are not currently registered.
+
+▸ **termDuration**(): `BlockNumber`
+- **summary**: How long each position is active for.
+
+▸ **voteCount**(): `VoteIndex`
+- **summary**: The total number of vote rounds that have happened or are in progress.
+
+▸ **voterCount**(): `SetIndex`
+- **summary**: Current number of Voters.
+
+▸ **voterInfoOf**(`AccountId`): `Option<VoterInfo>`
+- **summary**: Basic information about a voter.
+
+▸ **voters**(`SetIndex`): `Vec<Option<AccountId>>`
+- **summary**: The present voter list (chunked and capped at [`VOTER_SET_SIZE`]).
+
+___
+
+
+### grandpa
+
+▸ **authorities**(): `Vec<(AuthorityId,AuthorityWeight)>`
+- **summary**: The current authority set.
+
+▸ **currentSetId**(): `SetId`
+- **summary**: The number of changes (both in terms of keys and underlying economic responsibilities) in the "set" of Grandpa validators from genesis.
+
+▸ **nextForced**(): `Option<BlockNumber>`
+- **summary**: next block number where we can force a change.
+
+▸ **pendingChange**(): `Option<StoredPendingChange>`
+- **summary**: Pending change: (signaled at, scheduled change).
+
+▸ **setIdSession**(`SetId`): `Option<SessionIndex>`
+- **summary**: A mapping from grandpa set ID to the index of the *most recent* session for which its members were responsible.
+
+▸ **stalled**(): `Option<(BlockNumber,BlockNumber)>`
+- **summary**: `true` if we are currently stalled.
+
+▸ **state**(): `StoredState`
+- **summary**: State of the current authority set.
+
+___
+
+
+### imOnline
+
+▸ **gossipAt**(): `BlockNumber`
+- **summary**: The block number when we should gossip.
+
+▸ **keys**(): `Vec<AuthorityId>`
+- **summary**: The current set of keys that may issue a heartbeat.
+
+▸ **receivedHeartbeats**(`SessionIndex, AuthIndex`): `Bytes`
+- **summary**: For each session index we keep a mapping of `AuthorityId` to `offchain::OpaqueNetworkState`.
+
+___
+
+
+### indices
+
+▸ **enumSet**(`AccountIndex`): `Vec<AccountId>`
+- **summary**: The enumeration sets.
+
+▸ **nextEnumSet**(): `AccountIndex`
+- **summary**: The next free enumeration set.
+
+___
+
+
+### offences
+
+▸ **concurrentReportsIndex**(`Kind, OpaqueTimeSlot`): `Vec<ReportIdOf>`
+- **summary**: A vector of reports of the same kind that happened at the same time slot.
+
+▸ **reports**(`ReportIdOf`): `Option<OffenceDetails>`
+- **summary**: The primary structure that holds all offence records keyed by report identifiers.
+
+▸ **reportsByKindIndex**(`Kind`): `Bytes`
+- **summary**: Enumerates all reports of a kind along with the time they happened.  All reports are sorted by the time of offence.  Note that the actual type of this mapping is `Vec<u8>`, this is because values of different types are not supported at the moment so we are doing the manual serialization.
+
+___
+
+
+### session
+
+▸ **currentIndex**(): `SessionIndex`
+- **summary**: Current index of the session.
+
+▸ **disabledValidators**(): `Vec<u32>`
+- **summary**: Indices of disabled validators.  The set is cleared when `on_session_ending` returns a new set of identities.
+
+▸ **keyOwner**(`Bytes, (KeyTypeId,Bytes)`): `Option<ValidatorId>`
+- **summary**: The owner of a key. The second key is the `KeyTypeId` + the encoded key.  The first key is always `DEDUP_KEY_PREFIX` to have all the data in the same branch of the trie. Having all data in the same branch should prevent slowing down other queries.
+
+▸ **nextKeys**(`Bytes, ValidatorId`): `Option<Keys>`
+- **summary**: The next session keys for a validator.  The first key is always `DEDUP_KEY_PREFIX` to have all the data in the same branch of the trie. Having all data in the same branch should prevent slowing down other queries.
+
+▸ **queuedChanged**(): `bool`
+- **summary**: True if the underlying economic identities or weighting behind the validators has changed in the queued validator set.
+
+▸ **queuedKeys**(): `Vec<(ValidatorId,Keys)>`
+- **summary**: The queued keys for the next session. When the next session begins, these keys will be used to determine the validator's session keys.
+
+▸ **validators**(): `Vec<ValidatorId>`
+- **summary**: The current set of validators.
+
+___
+
+
+### staking
+
+▸ **bonded**(`AccountId`): `Option<AccountId>`
+- **summary**: Map from all locked "stash" accounts to the controller account.
+
+▸ **bondedEras**(): `Vec<(EraIndex,SessionIndex)>`
+- **summary**: A mapping from still-bonded eras to the first session index of that era.
+
+▸ **currentElected**(): `Vec<AccountId>`
+- **summary**: The currently elected validator set keyed by stash account ID.
+
+▸ **currentEra**(): `EraIndex`
+- **summary**: The current era index.
+
+▸ **currentEraPointsEarned**(): `EraPoints`
+- **summary**: Rewards for the current era. Using indices of current elected set.
+
+▸ **currentEraStart**(): `MomentOf`
+- **summary**: The start of the current era.
+
+▸ **currentEraStartSessionIndex**(): `SessionIndex`
+- **summary**: The session index at which the current era started.
+
+▸ **eraSlashJournal**(`EraIndex`): `Vec<SlashJournalEntry>`
+- **summary**: All slashes that have occurred in a given era.
+
+▸ **forceEra**(): `Forcing`
+- **summary**: True if the next session change will be a new era regardless of index.
+
+▸ **invulnerables**(): `Vec<AccountId>`
+- **summary**: Any validators that may never be slashed or forcibly kicked. It's a Vec since they're easy to initialize and the performance hit is minimal (we expect no more than four invulnerables) and restricted to testnets.
+
+▸ **ledger**(`AccountId`): `Option<StakingLedger>`
+- **summary**: Map from all (unlocked) "controller" accounts to the info regarding the staking.
+
+▸ **minimumValidatorCount**(): `u32`
+- **summary**: Minimum number of staking participants before emergency conditions are imposed.
+
+▸ **nominators**(`AccountId`): `(Vec<AccountId>, Linkage<AccountId>)`
+- **summary**: The map from nominator stash key to the set of stash keys of all validators to nominate.
+
+▸ **payee**(`AccountId`): `RewardDestination`
+- **summary**: Where the reward payment should be made. Keyed by stash.
+
+▸ **slashRewardFraction**(): `Perbill`
+- **summary**: The percentage of the slash that is distributed to reporters.  The rest of the slashed value is handled by the `Slash`.
+
+▸ **slotStake**(): `BalanceOf`
+- **summary**: The amount of balance actively at stake for each validator slot, currently.  This is used to derive rewards and punishments.
+
+▸ **stakers**(`AccountId`): `Exposure`
+- **summary**: Nominators for a particular account that is in action right now. You can't iterate through validators here, but you can find them in the Session module.  This is keyed by the stash account.
+
+▸ **validatorCount**(): `u32`
+- **summary**: The ideal number of staking participants.
+
+▸ **validators**(`AccountId`): `(ValidatorPrefs, Linkage<AccountId>)`
+- **summary**: The map from (wannabe) validator stash key to the preferences of that validator.
+
+___
+
+
+### sudo
+
+▸ **key**(): `AccountId`
+- **summary**: The `AccountId` of the sudo key.
+
+___
+
+
+### system
+
+▸ **accountNonce**(`AccountId`): `Index`
+- **summary**: Extrinsics nonce for accounts.
+
+▸ **allExtrinsicsLen**(): `Option<u32>`
+- **summary**: Total length (in bytes) for all extrinsics put together, for the current block.
+
+▸ **allExtrinsicsWeight**(): `Option<Weight>`
+- **summary**: Total weight for all extrinsics put together, for the current block.
+
+▸ **blockHash**(`BlockNumber`): `Hash`
+- **summary**: Map of block numbers to block hashes.
+
+▸ **digest**(): `DigestOf`
+- **summary**: Digest of the current block, also part of the block header.
+
+▸ **eventCount**(): `EventIndex`
+- **summary**: The number of events in the `Events<T>` list.
+
+▸ **events**(): `Vec<EventRecord>`
+- **summary**: Events deposited for the current block.
+
+▸ **eventTopics**(`Null, Hash`): `Vec<(BlockNumber,EventIndex)>`
+- **summary**: Mapping between a topic (represented by T::Hash) and a vector of indexes of events in the `<Events<T>>` list.  The first key serves no purpose. This field is declared as double_map just for convenience of using `remove_prefix`.  All topic vectors have deterministic storage locations depending on the topic. This allows light-clients to leverage the changes trie storage tracking mechanism and in case of changes fetch the list of events of interest.  The value has the type `(T::BlockNumber, EventIndex)` because if we used only just the `EventIndex` then in case if the topic has the same contents on the next block no notification will be triggered thus the event might be lost.
+
+▸ **extrinsicCount**(): `Option<u32>`
+- **summary**: Total extrinsics count for the current block.
+
+▸ **extrinsicData**(`u32`): `Bytes`
+- **summary**: Extrinsics data for the current block (maps an extrinsic's index to its data).
+
+▸ **extrinsicsRoot**(): `Hash`
+- **summary**: Extrinsics root of the current block, also part of the block header.
+
+▸ **nextWeightMultiplier**(): `WeightMultiplier`
+- **summary**: The next weight multiplier. This should be updated at the end of each block based on the saturation level (weight).
+
+▸ **number**(): `BlockNumber`
+- **summary**: The current block number being processed. Set by `execute_block`.
+
+▸ **parentHash**(): `Hash`
+- **summary**: Hash of the previous block.
+
+▸ **randomMaterial**(): `(i8,Vec<Hash>)`
+- **summary**: Series of block headers from the last 81 blocks that acts as random seed material. This is arranged as a ring buffer with the `i8` prefix being the index into the `Vec` of the oldest hash.
+
+___
+
+
+### technicalCommittee
+
+▸ **members**(): `Vec<AccountId>`
+- **summary**: The current members of the collective. This is stored sorted (just by value).
+
+▸ **proposalCount**(): `u32`
+- **summary**: Proposals so far.
+
+▸ **proposalOf**(`Hash`): `Option<Proposal>`
+- **summary**: Actual proposal for a given hash, if it's current.
+
+▸ **proposals**(): `Vec<Hash>`
+- **summary**: The hashes of the active proposals.
+
+▸ **voting**(`Hash`): `Option<Votes>`
+- **summary**: Votes on a given proposal, if it is ongoing.
+
+___
+
+
+### technicalMembership
+
+▸ **members**(): `Vec<AccountId>`
+- **summary**: The current membership, stored as an ordered Vec.
+
+___
+
+
+### timestamp
+
+▸ **didUpdate**(): `bool`
+- **summary**: Did the timestamp get updated in this block?
+
+▸ **now**(): `Moment`
+- **summary**: Current time for the current block.
+
+___
+
+
+### treasury
+
+▸ **approvals**(): `Vec<ProposalIndex>`
+- **summary**: Proposal indices that have been approved but not yet awarded.
+
+▸ **proposalCount**(): `ProposalIndex`
+- **summary**: Number of proposals that have been made.
+
+▸ **proposals**(`ProposalIndex`): `Option<TreasuryProposal>`
+- **summary**: Proposals that have been made.
+
+---
+
+### substrate
+
+_These are keys that are always available to the runtime implementation_
+
+▸ **changesTrieConfig**(): `u32`
+- **summary**: Changes trie configuration is stored under this key.
+
+▸ **childStorageKeyPrefix**(): `u32`
+- **summary**: Prefix of child storage keys.
+
+▸ **code**(): `Bytes`
+- **summary**: Wasm code of the runtime.
+
+▸ **extrinsicIndex**(): `u32`
+- **summary**: Current extrinsic index (u32) is stored under this key.
+
+▸ **heapPages**(): `u64`
+- **summary**: Number of wasm linear memory pages required for execution of the runtime.
+
+---

jest.config.js

@@ -6,8 +6,8 @@ module.exports = Object.assign({}, config, {
   moduleNameMapper: {
     '@polkadot/api-contract(.*)$': '<rootDir>/packages/api-contract/src/$1',
     '@polkadot/api-derive(.*)$': '<rootDir>/packages/api-derive/src/$1',
-    '@polkadot/api-metadata(.*)$': '<rootDir>/packages/api-metadata/src/$1',
     '@polkadot/api(.*)$': '<rootDir>/packages/api/src/$1',
+    '@polkadot/metadata(.*)$': '<rootDir>/packages/metadata/src/$1',
     '@polkadot/rpc-(core|provider)(.*)$': '<rootDir>/packages/rpc-$1/src/$2',
     '@polkadot/jsonrpc(.*)$': '<rootDir>/packages/type-jsonrpc/src/$1',
     '@polkadot/types(.*)$': '<rootDir>/packages/types/src/$1'
@@ -16,7 +16,7 @@ module.exports = Object.assign({}, config, {
     '<rootDir>/packages/api/build',
     '<rootDir>/packages/api-derive/build',
     '<rootDir>/packages/api-contract/build',
-    '<rootDir>/packages/api-metadata/build',
+    '<rootDir>/packages/metadata/build',
     '<rootDir>/packages/rpc-core/build',
     '<rootDir>/packages/rpc-provider/build',
     '<rootDir>/packages/type-jsonrpc/build',

lerna.json

@@ -9,5 +9,5 @@
   "packages": [
     "packages/*"
   ],
-  "version": "0.90.1"
+  "version": "0.100.1"
 }

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.90.1",
+  "version": "0.100.1",
   "private": true,
   "engines": {
     "yarn": "^1.10.1"
@@ -9,14 +9,14 @@
   ],
   "resolutions": {
     "babel-core": "^7.0.0-bridge.0",
-    "typescript": "^3.5.3"
+    "typescript": "^3.7.4"
   },
   "scripts": {
-    "build": "yarn build:interfaces && polkadot-dev-build-ts && yarn run build:methodsdoc && polkadot-dev-build-docs",
-    "build:htmldoc": "yarn clean && typedoc --theme default --out docs/html",
+    "build": "yarn build:interfaces && polkadot-dev-build-ts",
     "build:interfaces": "node packages/types/src/scripts/interfacesTsWrapper.js",
-    "build:methodsdoc": "node packages/types/src/scripts/MetadataMdWrapper.js",
-    "check": "yarn lint",
+    "circular": "madge --circular --extensions ts ./",
+    "docs": "node packages/types/src/scripts/MetadataMdWrapper.js && polkadot-dev-build-docs",
+    "chain:info": "node packages/types/src/scripts/extractChainWrapper.js",
     "lint": "eslint --ext .js,.jsx,.ts,.tsx . && tsc --noEmit --pretty",
     "clean": "polkadot-dev-clean-build",
     "postinstall": "polkadot-dev-yarn-only",
@@ -29,11 +29,10 @@
     "test:watch": "jest --coverage --watch"
   },
   "devDependencies": {
-    "@babel/core": "^7.5.5",
-    "@babel/register": "^7.5.5",
-    "@babel/runtime": "^7.5.5",
-    "@polkadot/dev": "^0.31.0-beta.3",
-    "@polkadot/ts": "^0.1.64",
-    "gh-pages": "^2.1.1"
+    "@babel/core": "^7.7.7",
+    "@babel/register": "^7.7.7",
+    "@babel/runtime": "^7.7.7",
+    "@polkadot/dev": "^0.32.14",
+    "@polkadot/ts": "^0.1.90"
   }
 }

packages/api-contract/README.md

@@ -3,9 +3,12 @@
 Interfaces to allow for the encoding and decoding of Substrate contract ABIs.
 
 ```js
+import {ApiPromise, WsProvider } from '@polkadot/api';
 import { Abi } from '@polkadot/api-contract';
 
-const abi = new Abi(<...JSON ABI...>);
+const wsProvider = new WsProvider(<...Node Url...>);
+const api = await ApiPromise.create({ provider: wsProvider });
+const abi = new Abi(api.registry, <...JSON ABI...>);
 
 api.tx.contracts
   .call(<contract addr>, <value>, <max gas>, abi.messages.<method name>(<...params...>))

packages/api-contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polkadot/api-contract",
-  "version": "0.90.1",
+  "version": "0.100.1",
   "description": "Interfaces for interacting with contracts and contract ABIs",
   "main": "index.js",
   "keywords": [
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/polkadot-js/api/tree/master/packages/api-contract#readme",
   "dependencies": {
-    "@babel/runtime": "^7.5.5",
-    "@polkadot/types": "^0.90.1"
+    "@babel/runtime": "^7.7.7",
+    "@polkadot/types": "^0.100.1"
   }
 }

packages/api-contract/src/Abi.spec.ts

@@ -1,119 +1,25 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
 // This software may be modified and distributed under the terms
 // of the Apache-2.0 license. See the LICENSE file for details.
 
-import { ContractABIArg } from './types';
-
-import typesAbi from '../test/abi/types.json';
-import erc20Abi from '../test/contracts/Erc20.json';
+import { TypeRegistry } from '@polkadot/types';
 
+import incrementerAbi from '../test/contracts/incrementer.json';
 import { Abi } from '.';
 
 describe('Abi', (): void => {
-  describe('types encoding', (): void => {
-    let abi: Abi;
+  const registry = new TypeRegistry();
 
-    beforeAll((): void => {
-      abi = new Abi(typesAbi);
-    });
-
-    function check (method: string, args: ContractABIArg[], type: string | null): void {
-      const fn = abi.messages[method];
-
-      expect(fn.args).toEqual(args);
-      expect(fn.type).toEqual(type);
-    }
-
-    it('has the primitive method with args & return', (): void => {
-      check(
-        'primitive',
-        [
-          { name: 'bool', type: 'bool' },
-          { name: 'u32', type: 'u32' }
-        ],
-        'bool'
-      );
-    });
-
-    it('has the vector method with args & return', (): void => {
-      check(
-        'vector',
-        [
-          { name: 'vecU8', type: 'Vec<u8>' },
-          { name: 'vecU32', type: 'Vec<u32>' }
-        ],
-        'Vec<bool>'
-      );
-    });
-
-    it('has the vector_fixed method with args & return', (): void => {
-      check(
-        'vectorFixed',
-        [
-          { name: 'vecU8Length32', type: '[u8;32]' }
-        ],
-        '[u32;8]'
-      );
-    });
-
-    it('has the option method with args & return', (): void => {
-      check(
-        'option',
-        [
-          { name: 'optionU32', type: 'Option<u32>' }
-        ],
-        'Option<bool>'
-      );
-    });
-
-    it('has the result method with return (empty)', (): void => {
-      check(
-        'result',
-        [],
-        '()'
-      );
-    });
-
-    it('allows for nested args', (): void => {
-      check(
-        'nested',
-        [
-          { name: 'optionVec', type: 'Option<Vec<u32>>' }
-        ],
-        'Vec<(u32,u64)>'
-      );
-    });
-
-    describe('messages', (): void => {
-      it('fails when invalid args are supplied', (): void => {
-        expect(
-          (): Uint8Array => abi.messages.primitive(false)
-        ).toThrow(/Expected 2 arguments to contract messages.primitive, found 1/);
-      });
-
-      it('encodes primitives correctly', (): void => {
-        expect(
-          abi.messages.primitive(true, 0x12345678)
-        ).toEqual(new Uint8Array([
-          9 << 2, // total length (4 + 1 + 4)
-          0x67, 0x2b, 0, 0, // 11111 -> hex (LE)
-          1, // true
-          0x78, 0x56, 0x34, 0x12 // u32
-        ]));
-      });
-    });
-  });
-
-  describe('erc20', (): void => {
+  describe('incrementer', (): void => {
     let abi: Abi;
 
     beforeEach((): void => {
-      abi = new Abi(erc20Abi);
+      abi = new Abi(registry, incrementerAbi);
     });
 
     it('has the attached methods', (): void => {
-      expect(Object.keys(abi.messages)).toEqual(
-        ['totalSupply', 'balanceOf', 'allowance', 'transfer', 'approve', 'transferFrom']
+      expect(Object.values(abi.abi.contract.messages).map(({ name }): string => name)).toEqual(
+        ['inc', 'get', 'compare']
       );
     });
   });

packages/api-contract/src/Abi.ts

@@ -1,31 +1,48 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
 // This software may be modified and distributed under the terms
 // of the Apache-2.0 license. See the LICENSE file for details.
 
-import { ContractABI, ContractABIFn, InterfaceAbi, AbiMessages } from './types';
+import { Registry } from '@polkadot/types/types';
+import { AbiConstructors, AbiMessages, ContractABI, ContractABIPre, ContractABIFn, InterfaceAbi } from './types';
 
 import { stringCamelCase } from '@polkadot/util';
 
-import { createMethod } from './method';
-import { validateAbi } from './validation';
+import ContractRegistry from './ContractRegistry';
 
-export default class ContractAbi implements InterfaceAbi {
+export default class ContractAbi extends ContractRegistry implements InterfaceAbi {
   public readonly abi: ContractABI;
 
-  public readonly deploy: ContractABIFn;
+  public readonly constructors: AbiConstructors;
 
-  public readonly messages: AbiMessages = {};
+  public readonly messages: AbiMessages;
 
-  public constructor (abi: ContractABI) {
-    validateAbi(abi);
+  constructor (registry: Registry, abi: ContractABIPre) {
+    super(registry, abi);
+    [this.abi, this.constructors, this.messages] = this.decodeAbi(abi);
+  }
 
-    this.abi = abi;
-    this.deploy = createMethod('deploy', abi.deploy);
+  private decodeAbi (abiPre: ContractABIPre): [ContractABI, ContractABIFn[], AbiMessages] {
+    this.validateAbi(abiPre);
 
-    abi.messages.forEach((method): void => {
-      const name = stringCamelCase(method.name);
+    const abi = this.convertAbi(abiPre);
+    const constructors = abi.contract.constructors.map(
+      (constructor, index): ContractABIFn => {
+        return this.createMessage(`constructor ${index}`, constructor);
+      }
+    );
 
-      this.messages[name] = createMethod(`messages.${name}`, method);
-    });
+    const messages: AbiMessages = abi.contract.messages.reduce(
+      (result: AbiMessages, message): AbiMessages => {
+        const name = stringCamelCase(message.name);
+
+        return {
+          ...result,
+          [name]: this.createMessage(`messages.${name}`, message)
+        };
+      },
+      {}
+    );
+
+    return [abi, constructors, messages];
   }
 }

packages/api-contract/src/ContractRegistry.ts

@@ -0,0 +1,221 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { CodecArg, Constructor, Registry, TypeDef } from '@polkadot/types/types';
+import { ContractABIArgBasePre, ContractABIContract, ContractABIContractPre, ContractABIEvent, ContractABIEventPre, ContractABIFn, ContractABIFnArg, ContractABIMessage, ContractABIMessageBase, ContractABIMessagePre, ContractABI, ContractABIMessageCommon, ContractABIPre, ContractABIRange, ContractABIRangePre, ContractABIStorage, ContractABIStorageLayout, ContractABIStorageLayoutPre, ContractABIStoragePre, ContractABIStorageStruct, ContractABIStorageStructPre, ContractABITypePre } from './types';
+
+import { Compact, u32, createClass, createType, encodeType } from '@polkadot/types';
+import { assert, hexToU8a, isNumber, isString, isNull, isObject, isUndefined, stringCamelCase, isHex, hexToNumber } from '@polkadot/util';
+
+import MetaRegistry from './MetaRegistry';
+
+// parse a selector, this can be a number (older) or of [<hex>, <hex>, ...]. However,
+// just catch everything (since this is now non-standard for u32 anyway)
+function parseSelector (registry: Registry, fnname: string, input: ContractABIMessageCommon['selector']): u32 {
+  if (isNumber(input)) {
+    return createType(registry, 'u32', input);
+  } else if (isHex(input)) {
+    return createType(registry, 'u32', hexToU8a(input));
+  } else if (typeof input === 'string') {
+    try {
+      const array = JSON.parse(input);
+
+      assert(array.length === 4, `${fnname}: Invalid selector length`);
+
+      return createType(registry, 'u32', Uint8Array.from(
+        // the as number[] is here to pacify TS, it doesn't quite know how to handle the cb
+        (array as number[]).map((value: string | number): number =>
+          isHex(value)
+            ? hexToNumber(value.toString())
+            : value
+        )
+      ));
+    } catch (e) {
+      console.error(e);
+    }
+  }
+
+  throw new Error(`${fnname}: Unable to parse selector`);
+}
+
+function createArgClass (registry: Registry, args: ContractABIFnArg[], baseDef: Record<string, string>): Constructor {
+  return createClass(
+    registry,
+    JSON.stringify(
+      args.reduce((base: Record<string, any>, { name, type }): Record<string, any> => {
+        base[name] = type.displayName || encodeType(type);
+
+        return base;
+      }, baseDef)
+    )
+  );
+}
+
+export default class ContractRegistry extends MetaRegistry {
+  // Contract ABI helpers
+  public validateArgs (name: string, args: ContractABIArgBasePre[]): void {
+    assert(Array.isArray(args), `Expected 'args' to exist on ${name}`);
+
+    args.forEach((arg): void => {
+      const unknownKeys = Object.keys(arg).filter((key): boolean => !['name', 'type'].includes(key));
+
+      assert(unknownKeys.length === 0, `Unknown keys ${unknownKeys.join(', ')} found in ABI args for ${name}`);
+      assert(isNumber(arg.name) && isString(this.stringAt(arg.name)), `${name} args should have valid name `);
+      assert(isNumber(arg.type.ty) && isObject(this.typeDefAt(arg.type.ty)), `${name} args should have valid type`);
+    });
+  }
+
+  public validateConstructors ({ contract: { constructors } }: ContractABIPre): void {
+    constructors.forEach((constructor: ContractABIMessagePre, index): void => {
+      const unknownKeys = Object.keys(constructor).filter((key): boolean => !['args', 'docs', 'name', 'selector'].includes(key));
+
+      assert(unknownKeys.length === 0, `Unknown keys ${unknownKeys.join(', ')} found in ABI constructor`);
+
+      this.validateArgs(`constructor ${index}`, constructor.args);
+    });
+  }
+
+  public validateMessages ({ contract: { messages } }: ContractABIPre): void {
+    messages.forEach((message): void => {
+      const unknownKeys = Object.keys(message).filter((key): boolean => !['args', 'docs', 'mutates', 'name', 'selector', 'return_type'].includes(key));
+      const fnname = `messages.${message.name}`;
+
+      assert(unknownKeys.length === 0, `Unknown keys ${unknownKeys.join(', ')} found in ABI args for messages.${message.name}`);
+
+      const { name, selector, return_type: returnType } = message;
+
+      assert(isNumber(name) && isString(this.stringAt(name)), `Expected name for ${fnname}`);
+      assert(isNull(returnType) || (isNumber(returnType.ty) && isObject(this.typeDefAt(returnType.ty))), `Expected return_type for ${fnname}`);
+
+      parseSelector(this.registry, fnname, selector);
+      this.validateArgs(fnname, message.args);
+    });
+  }
+
+  public validateAbi (abi: ContractABIPre): void {
+    const unknownKeys = Object.keys(abi.contract).filter((key): boolean => !['constructors', 'docs', 'events', 'messages', 'name'].includes(key));
+
+    assert(unknownKeys.length === 0, `Unknown fields ${unknownKeys.join(', ')} found in ABI`);
+
+    const { contract: { constructors, messages, name } } = abi;
+
+    assert(constructors && messages && isString(this.stringAt(name)), 'ABI should have constructors, messages & name sections');
+
+    this.validateConstructors(abi);
+    this.validateMessages(abi);
+  }
+
+  public createMessage (name: string, message: Partial<ContractABIMessage> & ContractABIMessageBase): ContractABIFn {
+    const args = message.args.map(({ name, type }): ContractABIFnArg => {
+      assert(isObject(type), `Invalid type at index ${type}`);
+      return {
+        name: stringCamelCase(name),
+        type
+      };
+    });
+    const Clazz = createArgClass(this.registry, args, isUndefined(message.selector) ? {} : { __selector: 'u32' });
+    const baseStruct: { [index: string]: any } = { __selector: isUndefined(message.selector) ? undefined : parseSelector(this.registry, name, message.selector) };
+    const encoder = (...params: CodecArg[]): Uint8Array => {
+      assert(params.length === args.length, `Expected ${args.length} arguments to contract ${name}, found ${params.length}`);
+
+      const u8a = new Clazz(
+        this.registry,
+        args.reduce((mapped, { name }, index): Record<string, CodecArg> => {
+          mapped[name] = params[index];
+
+          return mapped;
+        }, { ...baseStruct })
+      ).toU8a();
+
+      return Compact.addLengthPrefix(u8a);
+    };
+
+    const fn = (encoder as ContractABIFn);
+
+    fn.args = args;
+    fn.isConstant = !(message.mutates || false);
+    fn.type = message.returnType || null;
+    return fn;
+  }
+
+  public convertAbi ({ contract, storage }: ContractABIPre): ContractABI {
+    return {
+      contract: this.convertContract(contract),
+      storage: this.convertStorage(storage)
+    };
+  }
+
+  public convertArgs (args: ContractABIArgBasePre[]): any[] {
+    return args.map(({ name, type, ...arg }) => ({ ...arg, name: this.stringAt(name), type: this.convertType(type) }));
+  }
+
+  public convertType ({ ty, display_name: displayNameIndices }: ContractABITypePre): TypeDef {
+    const displayName = this.stringsAt(displayNameIndices).join('::');
+    return this.typeDefAt(ty, { displayName });
+  }
+
+  public convertContract ({ constructors, messages, name, events, ...contract }: ContractABIContractPre): ContractABIContract {
+    return {
+      constructors: this.convertConstructors(constructors),
+      messages: messages.map(message => this.convertMessage(message)),
+      name: this.stringAt(name),
+      ...(events
+        ? { events: events.map(event => this.convertEvent(event)) }
+        : {}),
+      ...contract
+    };
+  }
+
+  public convertConstructors (constructors: ContractABIMessagePre[]): ContractABIMessage[] {
+    return constructors.map(
+      (constructor: ContractABIMessagePre): ContractABIMessage => {
+        return this.convertMessage(constructor);
+      }
+    );
+  }
+
+  public convertMessage ({ args, name, return_type: returnType, ...message }: ContractABIMessagePre): ContractABIMessage {
+    return {
+      ...message,
+      args: this.convertArgs(args),
+      name: this.stringAt(name),
+      returnType: returnType ? this.convertType(returnType) : null
+    };
+  }
+
+  public convertEvent ({ args }: ContractABIEventPre): ContractABIEvent {
+    return {
+      args: this.convertArgs(args)
+    };
+  }
+
+  public convertStorage (storage: ContractABIStoragePre): ContractABIStorage {
+    return this.convertStorageStruct(storage);
+  }
+
+  public convertStorageLayout (storageLayout: ContractABIStorageLayoutPre): ContractABIStorageLayout {
+    if ((storageLayout as ContractABIStorageStructPre)['struct.type']) {
+      return this.convertStorageStruct(storageLayout as ContractABIStorageStructPre);
+    } else {
+      return this.convertStorageRange(storageLayout as ContractABIRangePre);
+    }
+  }
+
+  public convertStorageStruct ({ 'struct.type': structType, 'struct.fields': structFields }: ContractABIStorageStructPre): ContractABIStorageStruct {
+    return {
+      'struct.type': this.typeDefAt(structType),
+      'struct.fields': structFields.map(({ name, layout }) => ({
+        name: this.stringAt(name),
+        layout: this.convertStorageLayout(layout)
+      }))
+    };
+  }
+
+  public convertStorageRange ({ 'range.elem_type': type, ...range }: ContractABIRangePre): ContractABIRange {
+    return {
+      ...range,
+      'range.elem_type': this.typeDefAt(type)
+    };
+  }
+}

packages/api-contract/src/MetaRegistry.spec.ts

@@ -0,0 +1,42 @@
+// Copyright 2017-2020 @polkadot/types authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { TypeRegistry } from '@polkadot/types';
+
+import MetaRegistry from './MetaRegistry';
+
+import erc20Abi from '../test/contracts/Erc20.json';
+import erc20Cmp from '../test/compare/erc20.test.json';
+import sharedVecAbi from '../test/contracts/SharedVecV2.json';
+import sharedVecCmp from '../test/compare/shared-vec.test.json';
+import test001Abi from '../test/abi/test001.json';
+import test001Cmp from '../test/compare/test001.cmp.json';
+
+function compare (meta: MetaRegistry, other: any): void {
+  try {
+    expect(meta.typeDefs).toEqual(other);
+  } catch (error) {
+    console.error(JSON.stringify(meta.typeDefs));
+
+    throw error;
+  }
+}
+
+describe('MetaRegistry', (): void => {
+  const registry = new TypeRegistry();
+
+  describe('construction', (): void => {
+    it('initializes from a contract ABI (ERC20)', (): void => {
+      compare(new MetaRegistry(registry, erc20Abi), erc20Cmp);
+    });
+
+    it('initializes from a contract ABI (SharedVec)', (): void => {
+      compare(new MetaRegistry(registry, sharedVecAbi), sharedVecCmp);
+    });
+
+    it('initializes from a contract ABI (Other, test001)', (): void => {
+      compare(new MetaRegistry(registry, test001Abi), test001Cmp);
+    });
+  });
+});

packages/api-contract/src/MetaRegistry.ts

@@ -0,0 +1,351 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { MetaRegistryItem, MetaRegistryJson, MetaTypeDefClikeEnum, MetaType, MetaTypeDefEnum, MetaTypeDefEnumVariant, MetaTypeDefEnumVariantStruct, MetaTypeDefEnumVariantTupleStruct, MetaTypeDefEnumVariantUnit, MetaTypeDefStruct, MetaTypeDefStructField, MetaTypeDefTupleStruct, MetaTypeDefUnion, MetaTypeIdCustom, MetaTypeIdVec, MetaTypeIdVecFixed, MetaTypeInfo, Registry, StringIndex, TypeDef, TypeDefInfo, TypeIndex } from '@polkadot/types/types';
+
+import { assert } from '@polkadot/util';
+import { displayType, withTypeString } from '@polkadot/types';
+
+const builtinMap: [(id: any) => boolean, MetaTypeInfo][] = [
+  [(id: any): boolean => typeof id === 'string', MetaTypeInfo.BuiltinPlain],
+  [(id: any): boolean => Array.isArray(id), MetaTypeInfo.BuiltinTuple],
+  [(id: any): boolean => !!(id['array.type']), MetaTypeInfo.BuiltinVecFixed],
+  [(id: any): boolean => !!(id['slice.type']), MetaTypeInfo.BuiltinVec]
+];
+
+const typeMap: [string, MetaTypeInfo][] = [
+  ['enum.variants', MetaTypeInfo.Enum],
+  ['clike_enum.variants', MetaTypeInfo.ClikeEnum],
+  ['struct.fields', MetaTypeInfo.Struct],
+  ['tuple_struct.types', MetaTypeInfo.TupleStruct]
+];
+
+function detectedType ({ def, id }: MetaType): MetaTypeInfo {
+  assert(!(def as MetaTypeDefUnion)['union.fields'], 'Invalid union type definition found');
+
+  const lookup = def === 'builtin'
+    ? builtinMap.find(([test]): boolean => test(id))
+    : typeMap.find(([test]): boolean => !!(def as any)[test]);
+
+  return lookup
+    ? lookup[1]
+    : MetaTypeInfo.Null;
+}
+
+class MetadataRegistryLookup {
+  public readonly registry: Registry;
+
+  protected _strings: string[] = [];
+
+  protected _types: MetaType[] = [];
+
+  public typeDefs: TypeDef[] = [];
+
+  constructor (registry: Registry, { registry: { strings, types } }: MetaRegistryJson) {
+    this.registry = registry;
+    this._strings = strings;
+    this._types = types;
+  }
+
+  protected hasItemAt (index: number, variant: MetaRegistryItem): boolean {
+    switch (variant) {
+      case MetaRegistryItem.String:
+        return this._strings && !!this._strings[index - 1];
+      case MetaRegistryItem.Type:
+        return this._types && !!this._types[index - 1];
+      case MetaRegistryItem.TypeDef:
+        return this.typeDefs && !!this.typeDefs[index - 1];
+    }
+  }
+
+  protected itemAt (index: number, variant: MetaRegistryItem): any {
+    assert(this.hasItemAt(index, variant), `MetaRegistry: Invalid ${variant} index ${index} found in metadata`);
+
+    switch (variant) {
+      case MetaRegistryItem.String:
+        return this._strings[index - 1];
+      case MetaRegistryItem.Type:
+        return this._types[index - 1];
+      case MetaRegistryItem.TypeDef:
+        return this.typeDefs[index - 1];
+    }
+  }
+
+  protected itemsAt (indices: number[], variant: MetaRegistryItem): any[] {
+    return indices.map((index: number): string => this.itemAt(index, variant));
+  }
+
+  protected stringAt (index: StringIndex): string {
+    return this.itemAt(index, MetaRegistryItem.String);
+  }
+
+  public stringsAt (indices: StringIndex[]): string[] {
+    return this.itemsAt(indices, MetaRegistryItem.String);
+  }
+
+  public typeAt (index: TypeIndex): MetaType {
+    return this.itemAt(index, MetaRegistryItem.Type);
+  }
+
+  public typesAt (indices: TypeIndex[]): MetaType[] {
+    return this.itemsAt(indices, MetaRegistryItem.Type);
+  }
+
+  public hasTypeDefAt (index: TypeIndex): boolean {
+    return this.hasItemAt(index, MetaRegistryItem.TypeDef);
+  }
+
+  public typeDefAt (index: TypeIndex, extra: Pick<TypeDef, never> = {}): TypeDef {
+    return {
+      ...this.itemAt(index, MetaRegistryItem.TypeDef),
+      ...extra
+    };
+  }
+}
+
+export default class MetaRegistry extends MetadataRegistryLookup {
+  constructor (registry: Registry, json: MetaRegistryJson) {
+    super(registry, json);
+
+    // Generate TypeDefs for each provided registry type
+    this._types.forEach((_, index: number): void => this.setTypeDefAtIndex(index + 1));
+  }
+
+  public setTypeDefAtIndex (typeIndex: TypeIndex): void {
+    this.typeDefs[typeIndex - 1] = this.typeDefFromMetaType(this.typeAt(typeIndex), typeIndex);
+  }
+
+  private typeDefIdFields ({ id }: MetaType): Pick<TypeDef, never> {
+    const { 'custom.name': nameIndex, 'custom.namespace': namespaceIndices, 'custom.params': paramsIndices } = id as MetaTypeIdCustom;
+
+    if (!nameIndex) {
+      return {};
+    }
+
+    return {
+      name: this.stringAt(nameIndex),
+      ...(namespaceIndices && namespaceIndices.length
+        ? { namespace: this.stringsAt(namespaceIndices).join('::') }
+        : {}
+      ),
+      ...(paramsIndices && paramsIndices.length
+        ? { params: this.typesAt(paramsIndices).map((type): TypeDef => this.typeDefFromMetaType(type)) }
+        : {}
+      )
+    };
+  }
+
+  private typeDefDefFields (metaType: MetaType, typeIndex?: TypeIndex): Pick<TypeDef, never> {
+    let typeDef;
+
+    switch (detectedType(metaType)) {
+      case MetaTypeInfo.BuiltinPlain:
+        typeDef = this.typeDefForBuiltinPlain(metaType.id as string);
+        break;
+      case MetaTypeInfo.BuiltinTuple:
+        typeDef = this.typeDefForBuiltinTuple(metaType.id as TypeIndex[]);
+        break;
+      case MetaTypeInfo.BuiltinVec:
+        typeDef = this.typeDefForBuiltinVec(metaType.id as MetaTypeIdVec, typeIndex);
+        break;
+      case MetaTypeInfo.BuiltinVecFixed:
+        typeDef = this.typeDefForBuiltinVecFixed(metaType.id as MetaTypeIdVecFixed, typeIndex);
+        break;
+      case MetaTypeInfo.Enum:
+        typeDef = this.typeDefForEnum(metaType.def as MetaTypeDefEnum, metaType.id as MetaTypeIdCustom, typeIndex);
+        break;
+      case MetaTypeInfo.ClikeEnum:
+        typeDef = this.typeDefForClikeEnum(metaType.def as MetaTypeDefClikeEnum);
+        break;
+      case MetaTypeInfo.Struct:
+        typeDef = this.typeDefForStruct(metaType.def as MetaTypeDefStruct);
+        break;
+      case MetaTypeInfo.TupleStruct:
+        typeDef = this.typeDefForTupleStruct(metaType.def as MetaTypeDefTupleStruct);
+        break;
+      case MetaTypeInfo.Null:
+      default:
+        throw new Error(`Invalid type detected at index ${typeIndex}`);
+    }
+
+    return typeDef;
+  }
+
+  public typeDefFromMetaType (metaType: MetaType, typeIndex?: TypeIndex): TypeDef {
+    return withTypeString({
+      info: TypeDefInfo.Null,
+      type: '',
+      ...this.typeDefDefFields(metaType, typeIndex),
+      ...this.typeDefIdFields(metaType)
+    }) as TypeDef;
+  }
+
+  public typeDefFromMetaTypeAt (typeIndex: TypeIndex): TypeDef {
+    if (!this.hasTypeDefAt(typeIndex)) {
+      this.setTypeDefAtIndex(typeIndex);
+    }
+
+    return this.typeDefAt(typeIndex);
+  }
+
+  private typeDefForEnumVariant (variant: MetaTypeDefEnumVariant): Pick<TypeDef, any> {
+    const { 'unit_variant.name': unitNameIndex } = variant as MetaTypeDefEnumVariantUnit;
+
+    if (unitNameIndex) {
+      return {
+        info: TypeDefInfo.Plain,
+        name: this.stringAt(unitNameIndex),
+        type: 'Null'
+      };
+    }
+
+    const { 'tuple_struct_variant.name': tupleStructVariantNameIndex } = variant as MetaTypeDefEnumVariantTupleStruct;
+
+    if (tupleStructVariantNameIndex) {
+      return this.typeDefForTupleStruct(variant as MetaTypeDefEnumVariantTupleStruct);
+    }
+
+    const { 'struct_variant.name': structVariantNameIndex } = variant as MetaTypeDefEnumVariantStruct;
+
+    if (structVariantNameIndex) {
+      return this.typeDefForStruct(variant as MetaTypeDefEnumVariantStruct);
+    }
+
+    return {
+      info: TypeDefInfo.Null,
+      type: 'Null'
+    };
+  }
+
+  private typeDefForBuiltinPlain (id: string): Pick<TypeDef, never> {
+    return {
+      info: TypeDefInfo.Plain,
+      type: id
+    };
+  }
+
+  private typeDefForBuiltinTuple (id: TypeIndex[]): Pick<TypeDef, never> {
+    const sub = id.map((tupleTypeIndex: number): TypeDef => this.typeDefFromMetaTypeAt(tupleTypeIndex));
+
+    return {
+      info: TypeDefInfo.Tuple,
+      sub
+    };
+  }
+
+  private typeDefForBuiltinVec (id: MetaTypeIdVec, typeIndex?: TypeIndex): Pick<TypeDef, never> {
+    const { 'slice.type': vecTypeIndex } = id;
+
+    assert(!typeIndex || vecTypeIndex !== typeIndex, `MetaRegistry: self-referencing registry type at index ${typeIndex}`);
+
+    const type = displayType(this.typeDefFromMetaTypeAt(vecTypeIndex));
+    assert(type && type.length > 0, `MetaRegistry: Invalid builtin Vec type found at index ${typeIndex}`);
+
+    return {
+      info: TypeDefInfo.Vec,
+      type: `Vec<${type}>`,
+      sub: this.typeDefFromMetaTypeAt(vecTypeIndex)
+    };
+  }
+
+  private typeDefForBuiltinVecFixed (id: MetaTypeIdVecFixed, typeIndex?: TypeIndex): Pick<TypeDef, never> {
+    const { 'array.type': vecTypeIndex, 'array.len': vecLength } = id;
+
+    assert(!vecLength || vecLength <= 256, 'MetaRegistry: Only support for [Type; <length>], where length <= 256');
+    assert(!typeIndex || vecTypeIndex !== typeIndex, `MetaRegistry: self-referencing registry type at index ${typeIndex}`);
+
+    const type = displayType(this.typeDefFromMetaTypeAt(vecTypeIndex));
+    assert(type && type.length > 0, `MetaRegistry: Invalid vector type found at index ${typeIndex}`);
+
+    return {
+      info: TypeDefInfo.VecFixed,
+      ext: { length: vecLength, type },
+      type: `[${type};${vecLength}]`,
+      sub: this.typeDefFromMetaTypeAt(vecTypeIndex)
+    };
+  }
+
+  private typeDefForEnum (def: MetaTypeDefEnum, id: MetaTypeIdCustom, typeIndex?: TypeIndex): Pick<TypeDef, any> {
+    const name = id && this.stringAt(id['custom.name']);
+
+    switch (name) {
+      case 'Option':
+        return this.typeDefForOption(id, typeIndex);
+      case 'Result':
+        return this.typeDefForResult(id, typeIndex);
+      default: {
+        const sub = def['enum.variants'].map(variant => this.typeDefForEnumVariant(variant));
+
+        return {
+          info: TypeDefInfo.Enum,
+          sub
+        };
+      }
+    }
+  }
+
+  private typeDefForClikeEnum (def: MetaTypeDefClikeEnum): Pick<TypeDef, never> {
+    return {
+      info: TypeDefInfo.Enum,
+      sub: def['clike_enum.variants'].map(({ name: nameIndex, discriminant }): TypeDef => ({
+        ext: { discriminant },
+        info: TypeDefInfo.Plain,
+        name: this.stringAt(nameIndex),
+        type: 'Null'
+      }))
+    };
+  }
+
+  public typeDefForOption (id: MetaTypeIdCustom, typeIndex?: TypeIndex): Pick<TypeDef, any> {
+    assert(id['custom.params'] && id['custom.params'][0], `Invalid Option type defined at index ${typeIndex}`);
+
+    return {
+      info: TypeDefInfo.Option,
+      sub: this.typeDefFromMetaTypeAt(id['custom.params']![0])
+    };
+  }
+
+  public typeDefForResult (id: MetaTypeIdCustom, typeIndex?: TypeIndex): Pick<TypeDef, any> {
+    assert(id['custom.params'] && id['custom.params'][0] && id['custom.params'][1], `Invalid Result type defined at index ${typeIndex}`);
+
+    return {
+      info: TypeDefInfo.Result,
+      sub: id['custom.params']!.map((typeIndex): TypeDef => this.typeDefFromMetaTypeAt(typeIndex))
+    };
+  }
+
+  public typeDefForStruct (def: MetaTypeDefStruct | MetaTypeDefEnumVariantStruct): Pick<TypeDef, any> {
+    const structFields = (def as MetaTypeDefStruct)['struct.fields'] || (def as MetaTypeDefEnumVariantStruct)['struct_variant.fields'];
+    const structNameIndex = (def as MetaTypeDefEnumVariantStruct)['struct_variant.name'];
+
+    return withTypeString({
+      info: TypeDefInfo.Struct,
+      ...(structNameIndex
+        ? { name: this.stringAt(structNameIndex) }
+        : {}
+      ),
+      sub: structFields.map((field: MetaTypeDefStructField): TypeDef => ({
+        ...this.typeDefFromMetaTypeAt(field.type),
+        name: this.stringAt(field.name)
+      }))
+    });
+  }
+
+  private typeDefForTupleStruct (def: MetaTypeDefTupleStruct | MetaTypeDefEnumVariantTupleStruct): Pick<TypeDef, any> {
+    const tupleStructTypes = (def as MetaTypeDefTupleStruct)['tuple_struct.types'] || (def as MetaTypeDefEnumVariantTupleStruct)['tuple_struct_variant.types'];
+    const tupleStructNameIndex = (def as MetaTypeDefEnumVariantTupleStruct)['tuple_struct_variant.name'];
+
+    return withTypeString({
+      info: TypeDefInfo.Tuple,
+      ...(tupleStructNameIndex
+        ? { name: this.stringAt(tupleStructNameIndex) }
+        : {}
+      ),
+      sub: tupleStructTypes.map((fieldIndex: number, index: number): TypeDef => ({
+        ...this.typeDefFromMetaTypeAt(fieldIndex),
+        index
+      }))
+    });
+  }
+}

packages/api-contract/src/RxBase.ts

@@ -1,31 +0,0 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
-// This software may be modified and distributed under the terms
-// of the Apache-2.0 license. See the LICENSE file for details.
-
-import { SubmittableModuleExtrinsics } from '@polkadot/api/types';
-import { ApiObject, ContractABI, ContractBase } from './types';
-
-import { assert } from '@polkadot/util';
-
-import Abi from './Abi';
-
-// NOTE Experimental, POC, bound to change
-export default abstract class RxBase implements ContractBase<'rxjs'> {
-  public readonly abi: Abi;
-
-  public readonly api: ApiObject<'rxjs'>;
-
-  public readonly apiContracts: SubmittableModuleExtrinsics<'rxjs'>;
-
-  public constructor (api: ApiObject<'rxjs'>, abi: ContractABI | Abi) {
-    this.abi = abi instanceof Abi
-      ? abi
-      : new Abi(abi);
-    this.api = api;
-
-    // cater for substrate 2.x & 1.x (in order)
-    this.apiContracts = api.tx.contracts || api.tx.contract;
-
-    assert(this.apiContracts && this.apiContracts.putCode, `You need to connect to a node with the contracts module, the metadata does not enable api.tx.contracts on this instance`);
-  }
-}

packages/api-contract/src/RxBlueprint.ts

@@ -1,70 +0,0 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
-// This software may be modified and distributed under the terms
-// of the Apache-2.0 license. See the LICENSE file for details.
-
-import { ISubmittableResult, SubmittableResult } from '@polkadot/api/SubmittableExtrinsic';
-import { AccountId, Address, Hash } from '@polkadot/types/interfaces';
-import { IKeyringPair } from '@polkadot/types/types';
-import { ContractABI } from './types';
-
-import BN from 'bn.js';
-import { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-import { ApiRx } from '@polkadot/api';
-import { createType } from '@polkadot/types';
-
-import Abi from './Abi';
-import RxBase from './RxBase';
-import RxContract from './RxContract';
-
-type BlueprintCreateResultSubscription = Observable<BlueprintCreateResult>;
-
-export interface BlueprintCreate {
-  signAndSend (account: IKeyringPair | string | AccountId | Address): BlueprintCreateResultSubscription;
-}
-
-class BlueprintCreateResult extends SubmittableResult {
-  public readonly contract?: RxContract;
-
-  public constructor (result: ISubmittableResult, contract?: RxContract) {
-    super(result);
-
-    this.contract = contract;
-  }
-}
-
-// NOTE Experimental, POC, bound to change
-export default class Blueprint extends RxBase {
-  public readonly codeHash: Hash;
-
-  public constructor (api: ApiRx, abi: ContractABI | Abi, codeHash: string | Hash) {
-    super(api, abi);
-
-    this.codeHash = createType('Hash', codeHash);
-  }
-
-  public deployContract (endowment: number | BN, maxGas: number | BN, ...params: any[]): BlueprintCreate {
-    const signAndSend = (account: IKeyringPair | string | AccountId | Address): BlueprintCreateResultSubscription => {
-      return this.apiContracts
-        .create(endowment, maxGas, this.codeHash, this.abi.deploy(...params))
-        .signAndSend(account)
-        .pipe(map(this.createResult));
-    };
-
-    return { signAndSend };
-  }
-
-  private createResult = (result: SubmittableResult): BlueprintCreateResult => {
-    let contract: RxContract | undefined;
-
-    if (result.isFinalized) {
-      const record = result.findRecord('contract', 'Instantiated');
-
-      if (record) {
-        contract = new RxContract(this.api, this.abi, record.event.data[1] as Address);
-      }
-    }
-
-    return new BlueprintCreateResult(result, contract);
-  }
-}

packages/api-contract/src/RxCode.ts

@@ -1,83 +0,0 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
-// This software may be modified and distributed under the terms
-// of the Apache-2.0 license. See the LICENSE file for details.
-
-import { ISubmittableResult, SubmittableResult } from '@polkadot/api/SubmittableExtrinsic';
-import { AccountId, Address, Hash } from '@polkadot/types/interfaces';
-import { IKeyringPair } from '@polkadot/types/types';
-import { ContractABI } from './types';
-
-import BN from 'bn.js';
-import { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-import { ApiRx } from '@polkadot/api';
-import { compactAddLength, u8aToU8a } from '@polkadot/util';
-
-import Abi from './Abi';
-import RxBase from './RxBase';
-import RxBlueprint from './RxBlueprint';
-
-// Ok, tried, failed, eventually ... well, we are only trying with RxJs as a
-// start, so take a big fat shortcut with this version, real intended version
-// follows this and is commented out
-type CodePutCodeResultSubscription = Observable<CodePutCodeResult>;
-// type ICodePutCodeResultSubscription<ApiType> =
-//   ApiType extends 'rxjs'
-//     ? Observable<CodePutCodeResult>
-//     : Promise<() => void>;
-
-// unlike the ISubmittableExtrinsic, it doesn't extend IExtrinsic and only
-// implements one var iant of signAndSend - this is purely done to see what
-// is hanging where, with the bare-mainimum from a simplicity perspective
-// Very obvious is that it supports only 1 version of signAndSend
-// (we need to revisit this, but probably ok for initial?)
-// eslint-disable-next-line @typescript-eslint/interface-name-prefix
-export interface CodePutCode {
-  signAndSend (account: IKeyringPair | string | AccountId | Address): CodePutCodeResultSubscription;
-}
-
-class CodePutCodeResult extends SubmittableResult {
-  public readonly blueprint?: RxBlueprint;
-
-  public constructor (result: ISubmittableResult, blueprint?: RxBlueprint) {
-    super(result);
-
-    this.blueprint = blueprint;
-  }
-}
-
-// NOTE Experimental, POC, bound to change
-export default class RxCode extends RxBase {
-  public readonly code: Uint8Array;
-
-  public constructor (api: ApiRx, abi: ContractABI | Abi, wasm: string | Uint8Array) {
-    super(api, abi);
-
-    this.code = u8aToU8a(wasm);
-  }
-
-  public createBlueprint (maxGas: number | BN): CodePutCode {
-    const signAndSend = (account: IKeyringPair | string | AccountId | Address): CodePutCodeResultSubscription => {
-      return this.apiContracts
-        .putCode(maxGas, compactAddLength(this.code))
-        .signAndSend(account)
-        .pipe(map(this.createResult));
-    };
-
-    return { signAndSend };
-  }
-
-  private createResult = (result: ISubmittableResult): CodePutCodeResult => {
-    let blueprint: RxBlueprint | undefined;
-
-    if (result.isFinalized) {
-      const record = result.findRecord('contract', 'CodeStored');
-
-      if (record) {
-        blueprint = new RxBlueprint(this.api, this.abi, record.event.data[0] as Hash);
-      }
-    }
-
-    return new CodePutCodeResult(result, blueprint);
-  }
-}

packages/api-contract/src/RxContract.ts

@@ -1,42 +0,0 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
-// This software may be modified and distributed under the terms
-// of the Apache-2.0 license. See the LICENSE file for details.
-
-import { AccountId, Address } from '@polkadot/types/interfaces';
-import { IKeyringPair } from '@polkadot/types/types';
-import { ContractABI, ContractABIFn, InterfaceContract, InterfaceContractCalls } from './types';
-
-import BN from 'bn.js';
-import { Observable } from 'rxjs';
-import { ApiRx } from '@polkadot/api';
-import { SubmittableResult } from '@polkadot/api/SubmittableExtrinsic';
-import { createType } from '@polkadot/types';
-import Abi from './Abi';
-import RxBase from './RxBase';
-
-export type ContractCallResultSubscription = Observable<SubmittableResult>;
-
-export interface ContractCall {
-  signAndSend (account: IKeyringPair | string | AccountId | Address): ContractCallResultSubscription;
-}
-
-type CallResult = (value: BN | number, maxGas: BN | number, ...params: any[]) => ContractCall;
-
-// NOTE Experimental, POC, bound to change
-export default class RxContract extends RxBase implements InterfaceContract {
-  public readonly address: Address;
-
-  public readonly calls: InterfaceContractCalls = {};
-
-  public constructor (api: ApiRx, abi: ContractABI | Abi, address: string | AccountId | Address) {
-    super(api, abi);
-
-    this.address = createType('Address', address);
-
-    Object.entries(abi.messages).forEach(([name]): void => {
-      this.calls[name] = (fn: ContractABIFn): CallResult =>
-        (value: BN | number, maxGas: BN | number, ...params: any[]): ContractCall =>
-          this.apiContracts.call(this.address, value, maxGas, fn(...params));
-    });
-  }
-}

packages/api-contract/src/base/Blueprint.ts

@@ -0,0 +1,75 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ApiTypes, DecorateMethod, SubmittableResultImpl } from '@polkadot/api/types';
+import { AccountId, Address, Hash } from '@polkadot/types/interfaces';
+import { IKeyringPair } from '@polkadot/types/types';
+import { ApiObject, ContractABIPre } from '../types';
+
+import BN from 'bn.js';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { SubmittableResult } from '@polkadot/api';
+import { createType } from '@polkadot/types';
+import { assert } from '@polkadot/util';
+
+import Abi from '../Abi';
+import Contract from './Contract';
+import { BaseWithTx } from './util';
+
+type BlueprintCreateResultSubscription<ApiType extends ApiTypes> = Observable<BlueprintCreateResult<ApiType>>;
+
+export interface BlueprintCreate<ApiType extends ApiTypes> {
+  signAndSend (account: IKeyringPair | string | AccountId | Address): BlueprintCreateResultSubscription<ApiType>;
+}
+
+class BlueprintCreateResult<ApiType extends ApiTypes> extends SubmittableResult {
+  public readonly contract?: Contract<ApiType>;
+
+  constructor (result: SubmittableResultImpl, contract?: Contract<ApiType>) {
+    super(result);
+
+    this.contract = contract;
+  }
+}
+
+// NOTE Experimental, POC, bound to change
+export default class Blueprint<ApiType extends ApiTypes> extends BaseWithTx<ApiType> {
+  public readonly codeHash: Hash;
+
+  constructor (api: ApiObject<ApiType>, abi: ContractABIPre | Abi, decorateMethod: DecorateMethod<ApiType>, codeHash: string | Hash) {
+    super(api, abi, decorateMethod);
+
+    this.codeHash = createType(this.registry, 'Hash', codeHash);
+  }
+
+  public deployContract (constructorIndex = 0, endowment: number | BN, maxGas: number | BN, ...params: any[]): BlueprintCreate<ApiType> {
+    assert(!!this.abi.constructors[constructorIndex], `Specified constructor index ${constructorIndex} does not exist`);
+
+    return {
+      signAndSend: this.decorateMethod(
+        (account: IKeyringPair | string | AccountId | Address): BlueprintCreateResultSubscription<ApiType> => {
+          return this.apiContracts
+            .create(endowment, maxGas, this.codeHash, this.abi.constructors[constructorIndex](...params))
+            .signAndSend(account)
+            .pipe(map(this.createResult));
+        }
+      )
+    };
+  }
+
+  private createResult = (result: SubmittableResult): BlueprintCreateResult<ApiType> => {
+    let contract: Contract<ApiType> | undefined;
+
+    if (result.isFinalized) {
+      const record = result.findRecord('contract', 'Instantiated');
+
+      if (record) {
+        contract = new Contract<ApiType>(this.api, this.abi, this.decorateMethod, record.event.data[1] as Address);
+      }
+    }
+
+    return new BlueprintCreateResult(result, contract);
+  }
+}

packages/api-contract/src/base/Code.ts

@@ -0,0 +1,71 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ApiTypes, DecorateMethod, SubmittableResultImpl } from '@polkadot/api/types';
+import { AccountId, Address, Hash } from '@polkadot/types/interfaces';
+import { IKeyringPair } from '@polkadot/types/types';
+import { ApiObject, ContractABIPre } from '../types';
+
+import BN from 'bn.js';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { SubmittableResult } from '@polkadot/api';
+import { compactAddLength, u8aToU8a } from '@polkadot/util';
+
+import Abi from '../Abi';
+import Blueprint from './Blueprint';
+import { BaseWithTx } from './util';
+
+type CodePutCodeResultSubscription<ApiType extends ApiTypes> = Observable<CodePutCodeResult<ApiType>>;
+
+// eslint-disable-next-line @typescript-eslint/interface-name-prefix
+export interface CodePutCode<ApiType extends ApiTypes> {
+  signAndSend (account: IKeyringPair | string | AccountId | Address): CodePutCodeResultSubscription<ApiType>;
+}
+
+class CodePutCodeResult<ApiType extends ApiTypes> extends SubmittableResult {
+  public readonly blueprint?: Blueprint<ApiType>;
+
+  constructor (result: SubmittableResultImpl, blueprint?: Blueprint<ApiType>) {
+    super(result);
+
+    this.blueprint = blueprint;
+  }
+}
+
+// NOTE Experimental, POC, bound to change
+export default class Code<ApiType extends ApiTypes> extends BaseWithTx<ApiType> {
+  public readonly code: Uint8Array;
+
+  constructor (api: ApiObject<ApiType>, abi: ContractABIPre | Abi, decorateMethod: DecorateMethod<ApiType>, wasm: string | Uint8Array) {
+    super(api, abi, decorateMethod);
+
+    this.code = u8aToU8a(wasm);
+  }
+
+  public createBlueprint = (maxGas: number | BN): CodePutCode<ApiType> => {
+    return {
+      signAndSend: this.decorateMethod(
+        (account: IKeyringPair | string | AccountId | Address): CodePutCodeResultSubscription<ApiType> => this.apiContracts
+          .putCode(maxGas, compactAddLength(this.code))
+          .signAndSend(account)
+          .pipe(map(this.createResult))
+      )
+    };
+  }
+
+  private createResult = (result: SubmittableResultImpl): CodePutCodeResult<ApiType> => {
+    let blueprint: Blueprint<ApiType> | undefined;
+
+    if (result.isFinalized) {
+      const record = result.findRecord('contract', 'CodeStored');
+
+      if (record) {
+        blueprint = new Blueprint<ApiType>(this.api, this.abi, this.decorateMethod, record.event.data[0] as Hash);
+      }
+    }
+
+    return new CodePutCodeResult(result, blueprint);
+  }
+}

packages/api-contract/src/base/Contract.ts

@@ -0,0 +1,97 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ApiTypes, DecorateMethod, ObsInnerType } from '@polkadot/api/types';
+import { AccountId, Address, ContractExecResult } from '@polkadot/types/interfaces';
+import { Codec, IKeyringPair } from '@polkadot/types/types';
+import { ApiObject, ContractABIMessage, ContractABIPre, ContractCallOutcome } from '../types';
+
+import BN from 'bn.js';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { SubmittableResult } from '@polkadot/api';
+import { createType } from '@polkadot/types';
+import Abi from '../Abi';
+import { formatData } from '../util';
+import { BaseWithTxAndRpcCall } from './util';
+
+type ContractCallTypes = 'tx' | 'rpc';
+
+type ContractCallResultSubscription<ApiType extends ApiTypes, CallType extends ContractCallTypes> = ApiType extends 'rxjs'
+  ? Observable<ContractCallResult<CallType>>
+  : Promise<ObsInnerType<ContractCallResult<CallType>>>;
+
+// eslint-disable-next-line @typescript-eslint/interface-name-prefix
+export interface ContractCall<ApiType extends ApiTypes, CallType extends ContractCallTypes> {
+  send (account: IKeyringPair | string | AccountId | Address): ContractCallResultSubscription<ApiType, CallType>;
+}
+
+export type ContractCallResult<CallType extends ContractCallTypes> = CallType extends 'rpc'
+  ? Observable<ContractCallOutcome>
+  : Observable<SubmittableResult>;
+
+export default class Contract<ApiType extends ApiTypes> extends BaseWithTxAndRpcCall<ApiType> {
+  public readonly address: Address;
+
+  public call (as: 'rpc', message: string, value: BN | number, gasLimit: BN | number, ...params: any[]): ContractCall<ApiType, 'rpc'>;
+  public call (as: 'tx', message: string, value: BN | number, gasLimit: BN | number, ...params: any[]): ContractCall<ApiType, 'tx'>;
+  public call<CallType extends ContractCallTypes> (as: CallType, message: string, value: BN | number, gasLimit: BN | number, ...params: any[]): ContractCall<ApiType, CallType> {
+    const { fn, def } = this.getMessage(message);
+
+    return {
+      send: this.decorateMethod(
+        as === 'rpc' && this.hasRpcContractsCall
+          ? (account: IKeyringPair | string | AccountId | Address): ContractCallResult<'rpc'> => {
+            return this.rpcContractsCall(
+              createType(this.registry, 'ContractCallRequest', {
+                origin: account,
+                dest: this.address.toString(),
+                value,
+                gasLimit,
+                inputData: fn(...params)
+              })
+            )
+              .pipe(
+                map((result: ContractExecResult): ContractCallOutcome =>
+                  this.createOutcome(result, createType(this.registry, 'AccountId', account), def, params)
+                )
+              );
+          }
+          : (account: IKeyringPair | string | AccountId | Address): ContractCallResult<'tx'> => {
+            return this.apiContracts
+              .call(this.address, value, gasLimit, fn(...params))
+              .signAndSend(account);
+          }
+      )
+    };
+  }
+
+  private createOutcome (result: ContractExecResult, origin: AccountId, message: ContractABIMessage, params: any[]): ContractCallOutcome {
+    let output: Codec | null = null;
+
+    if (result.isSuccess) {
+      const { data } = result.asSuccess;
+
+      output = message.returnType
+        ? formatData(this.registry, data, message.returnType)
+        : createType(this.registry, 'Raw', data);
+    }
+
+    return {
+      time: Date.now(),
+      message,
+      origin,
+      params,
+      result,
+      isSuccess: result.isSuccess,
+      output
+    };
+  }
+
+  constructor (api: ApiObject<ApiType>, abi: ContractABIPre | Abi, decorateMethod: DecorateMethod<ApiType>, address: string | AccountId | Address) {
+    super(api, abi, decorateMethod);
+
+    this.address = createType(this.registry, 'Address', address);
+  }
+}

packages/api-contract/src/base/index.ts

@@ -0,0 +1,7 @@
+// Copyright 2017-2020 @polkadot/api authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+export { default as Blueprint } from './Blueprint';
+export { default as Code } from './Code';
+export { default as Contract } from './Contract';

packages/api-contract/src/base/util.ts

@@ -0,0 +1,78 @@
+// Copyright 2017-2020 @polkadot/api authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ApiTypes, DecorateMethod, DecoratedRpc, SubmittableModuleExtrinsics } from '@polkadot/api/types';
+import { ApiObject, ContractABIMessage, ContractABIPre, ContractBase, ContractMessage } from '../types';
+import { RpcInterface } from '@polkadot/rpc-core/jsonrpc.types';
+import { Registry } from '@polkadot/types/types';
+
+import { assert, isFunction, stringCamelCase } from '@polkadot/util';
+import Abi from '../Abi';
+
+export abstract class Base<ApiType extends ApiTypes> implements ContractBase<ApiType> {
+  public readonly abi: Abi;
+
+  public readonly api: ApiObject<ApiType>;
+
+  public readonly decorateMethod: DecorateMethod<ApiType>;
+
+  public readonly registry: Registry;
+
+  constructor (api: ApiObject<ApiType>, abi: ContractABIPre | Abi, decorateMethod: DecorateMethod<ApiType>) {
+    this.abi = abi instanceof Abi
+      ? abi
+      : new Abi(api.registry, abi);
+    this.registry = api.registry;
+    this.api = api;
+    this.decorateMethod = decorateMethod;
+  }
+
+  public get messages (): ContractMessage[] {
+    return this.abi.abi.contract.messages
+      .map(
+        (def: ContractABIMessage, index): ContractMessage => ({
+          index,
+          def,
+          fn: this.abi.messages[def.name] || this.abi.messages[stringCamelCase(name)]
+        })
+      );
+  }
+
+  public getMessage (nameOrIndex?: string | number): ContractMessage {
+    const index = nameOrIndex
+      ? typeof nameOrIndex === 'number'
+        ? nameOrIndex
+        : this.abi.abi.contract.messages.findIndex((message): boolean => nameOrIndex === message.name || nameOrIndex === stringCamelCase(message.name))
+      : 0;
+    const def = this.abi.abi.contract.messages[index];
+    assert(!!def, `Attempted to access a contract message that does not exist: ${typeof nameOrIndex === 'number' ? `index ${nameOrIndex}` : nameOrIndex}`);
+
+    const fn = this.abi.messages[def.name] || this.abi.messages[stringCamelCase(def.name)];
+    return { index, def, fn };
+  }
+}
+
+export abstract class BaseWithTx<ApiType extends ApiTypes> extends Base<ApiType> {
+  protected get apiContracts (): SubmittableModuleExtrinsics<'rxjs'> {
+    return this.api.rx.tx.contracts;
+  }
+
+  constructor (api: ApiObject<ApiType>, abi: ContractABIPre | Abi, decorateMethod: DecorateMethod<ApiType>) {
+    super(api, abi, decorateMethod);
+
+    assert(this.api.rx.tx.contracts && this.api.rx.tx.contracts.putCode, 'You need to connect to a node with the contracts module, the metadata does not enable api.tx.contracts on this instance');
+  }
+}
+
+export abstract class BaseWithTxAndRpcCall<ApiType extends ApiTypes> extends BaseWithTx<ApiType> {
+  public get hasRpcContractsCall (): boolean {
+    return isFunction(this.api.rx.rpc.contracts?.call);
+  }
+
+  protected get rpcContractsCall (): DecoratedRpc<'rxjs', RpcInterface>['contracts']['call'] {
+    assert(this.hasRpcContractsCall, 'You need to connect to a node with the contracts.call RPC method.');
+
+    return this.api.rx.rpc.contracts.call;
+  }
+}

packages/api-contract/src/index.ts

@@ -1,8 +1,7 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
 // This software may be modified and distributed under the terms
 // of the Apache-2.0 license. See the LICENSE file for details.
 
 export { default as Abi } from './Abi';
-export { default as RxBlueprint } from './RxBlueprint';
-export { default as RxCode } from './RxCode';
-export { default as RxContract } from './RxContract';
+export * from './rx';
+export * from './promise';

packages/api-contract/src/method.ts

@@ -1,69 +0,0 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
-// This software may be modified and distributed under the terms
-// of the Apache-2.0 license. See the LICENSE file for details.
-
-import { CodecArg, Constructor } from '@polkadot/types/types';
-import { ContractABIFn, ContractABIFnArg, ContractABIMethod, ContractABIMethodBase, ContractABITypes } from './types';
-
-import { Compact, createClass } from '@polkadot/types';
-import { assert, isString, isUndefined, stringCamelCase } from '@polkadot/util';
-
-export function typeToString (type: ContractABITypes): string {
-  if (isString(type)) {
-    return type;
-  } else if (Array.isArray(type)) {
-    return `(${type.map((type): string => typeToString(type)).join(',')})`;
-  } else if (type['Option<T>']) {
-    return `Option<${typeToString(type['Option<T>'].T)}>`;
-  } else if (type['Result<T,E>']) {
-    return `()`; // Result is not supported, but only applicable for returns
-  } else if (type['Vec<T>']) {
-    return `Vec<${typeToString(type['Vec<T>'].T)}>`;
-  } else if (type['[T;n]']) {
-    return `[${typeToString(type['[T;n]'].T)};${type['[T;n]'].n}]`;
-  }
-
-  throw new Error(`Unknown type specified ${JSON.stringify(type)}`);
-}
-
-export function createArgClass (args: ContractABIFnArg[], baseDef: Record<string, string>): Constructor {
-  return createClass(
-    JSON.stringify(
-      args.reduce((base: Record<string, any>, { name, type }): Record<string, any> => {
-        base[name] = type;
-
-        return base;
-      }, baseDef)
-    )
-  );
-}
-
-export function createMethod (name: string, method: Partial<ContractABIMethod> & ContractABIMethodBase): ContractABIFn {
-  const args: ContractABIFnArg[] = method.args.map(({ name, type }): ContractABIFnArg => ({
-    name: stringCamelCase(name),
-    type: typeToString(type)
-  }));
-  const Clazz = createArgClass(args, isUndefined(method.selector) ? {} : { __selector: 'u32' });
-  const baseStruct: { [index: string]: any } = { __selector: method.selector };
-  const encoder = (...params: CodecArg[]): Uint8Array => {
-    assert(params.length === args.length, `Expected ${args.length} arguments to contract ${name}, found ${params.length}`);
-
-    const u8a = new Clazz(
-      args.reduce((mapped, { name }, index): Record<string, CodecArg> => {
-        mapped[name] = params[index];
-
-        return mapped;
-      }, { ...baseStruct })
-    ).toU8a();
-
-    return Compact.addLengthPrefix(u8a);
-  };
-
-  const fn = (encoder as ContractABIFn);
-
-  fn.args = args;
-  fn.isConstant = !(method.mutates || false);
-  fn.type = method.return_type ? typeToString(method.return_type) : null;
-
-  return fn;
-}

packages/api-contract/src/promise/PromiseBlueprint.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { Hash } from '@polkadot/types/interfaces';
+import { ContractABIPre } from '../types';
+
+import { ApiPromise } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/promise';
+
+import Abi from '../Abi';
+import Blueprint from '../base/Blueprint';
+
+export default class PromiseBlueprint extends Blueprint<'promise'> {
+  constructor (api: ApiPromise, abi: ContractABIPre | Abi, codeHash: string | Hash) {
+    super(api, abi, decorateMethod, codeHash);
+  }
+}

packages/api-contract/src/promise/PromiseCode.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ContractABIPre } from '../types';
+
+import { ApiPromise } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/promise';
+
+import Abi from '../Abi';
+import Code from '../base/Code';
+
+export default class PromiseCode extends Code<'promise'> {
+  constructor (api: ApiPromise, abi: ContractABIPre | Abi, wasm: string | Uint8Array) {
+    super(api, abi, decorateMethod, wasm);
+  }
+}

packages/api-contract/src/promise/PromiseContract.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { AccountId } from '@polkadot/types/interfaces';
+import { ContractABIPre } from '../types';
+
+import { ApiPromise } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/promise';
+
+import Abi from '../Abi';
+import Contract from '../base/Contract';
+
+export default class PromiseContract extends Contract<'promise'> {
+  constructor (api: ApiPromise, abi: ContractABIPre | Abi, address: string | AccountId) {
+    super(api, abi, decorateMethod, address);
+  }
+}

packages/api-contract/src/promise/index.ts

@@ -0,0 +1,7 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+export { default as PromiseBlueprint } from './PromiseBlueprint';
+export { default as PromiseCode } from './PromiseCode';
+export { default as PromiseContract } from './PromiseContract';

packages/api-contract/src/rx/RxBlueprint.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { Hash } from '@polkadot/types/interfaces';
+import { ContractABIPre } from '../types';
+
+import { ApiRx } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/rx';
+
+import Abi from '../Abi';
+import Blueprint from '../base/Blueprint';
+
+export default class RxBlueprint extends Blueprint<'rxjs'> {
+  constructor (api: ApiRx, abi: ContractABIPre | Abi, codeHash: string | Hash) {
+    super(api, abi, decorateMethod, codeHash);
+  }
+}

packages/api-contract/src/rx/RxCode.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { ContractABIPre } from '../types';
+
+import { ApiRx } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/rx';
+
+import Abi from '../Abi';
+import Code from '../base/Code';
+
+export default class RxCode extends Code<'rxjs'> {
+  constructor (api: ApiRx, abi: ContractABIPre | Abi, wasm: string | Uint8Array) {
+    super(api, abi, decorateMethod, wasm);
+  }
+}

packages/api-contract/src/rx/RxContract.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+import { AccountId } from '@polkadot/types/interfaces';
+import { ContractABIPre } from '../types';
+
+import { ApiRx } from '@polkadot/api';
+import { decorateMethod } from '@polkadot/api/rx';
+
+import Abi from '../Abi';
+import Contract from '../base/Contract';
+
+export default class RxContract extends Contract<'rxjs'> {
+  constructor (api: ApiRx, abi: ContractABIPre | Abi, address: string | AccountId) {
+    super(api, abi, decorateMethod, address);
+  }
+}

packages/api-contract/src/rx/index.ts

@@ -0,0 +1,7 @@
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
+// This software may be modified and distributed under the terms
+// of the Apache-2.0 license. See the LICENSE file for details.
+
+export { default as RxBlueprint } from './RxBlueprint';
+export { default as RxCode } from './RxCode';
+export { default as RxContract } from './RxContract';

packages/api-contract/src/types.ts

@@ -1,87 +1,192 @@
-// Copyright 2017-2019 @polkadot/api-contract authors & contributors
+// Copyright 2017-2020 @polkadot/api-contract authors & contributors
 // This software may be modified and distributed under the terms
 // of the Apache-2.0 license. See the LICENSE file for details.
 
-import { SubmittableModuleExtrinsics } from '@polkadot/api/types';
-import { Address } from '@polkadot/types/interfaces';
-import { CodecArg } from '@polkadot/types/types';
+import { ApiTypes, DecorateMethod } from '@polkadot/api/types';
+import { AccountId, Address, ContractExecResult } from '@polkadot/types/interfaces';
+import { Codec, CodecArg } from '@polkadot/types/types';
+import { MetaRegistryJson, StringIndex, TypeIndex, TypeDef } from '@polkadot/types/codec/create/types';
 
+// import { Observable } from 'rxjs';
 import { ApiPromise, ApiRx } from '@polkadot/api';
 
-export type ApiObject<ApiType> = ApiType extends 'rxjs'
+export type ApiObject<ApiType extends ApiTypes> = ApiType extends 'rxjs'
   ? ApiRx
   : ApiPromise;
 
-export interface ContractABITypesStruct {
-  'Option<T>'?: {
-    T: ContractABITypes;
-  };
-  'Result<T,E>'?: {
-    T: ContractABITypes;
-    E: ContractABITypes;
-  };
-  'Vec<T>'?: {
-    T: ContractABITypes;
-  };
-  '[T;n]'?: {
-    T: ContractABITypes;
-    n: number;
-  };
+export interface ContractBase<ApiType extends ApiTypes> {
+  readonly abi: InterfaceAbi;
+  readonly api: ApiObject<ApiType>;
+  readonly decorateMethod: DecorateMethod<ApiType>;
+  getMessage: (name: string) => ContractMessage;
+  messages: ContractMessage[];
 }
 
-export type ContractABITypes = string | ContractABITypesStruct | (string | ContractABITypesStruct)[];
+export interface ContractABITypePre {
+  ty: TypeIndex;
+  display_name: StringIndex[];
+}
 
-export interface ContractABIArg {
+export interface ContractABIArgBasePre {
+  name: StringIndex;
+  type: ContractABITypePre;
+}
+
+export interface ContractABIArgBase {
   name: string;
-  type: ContractABITypes;
+  type: TypeDef;
 }
 
-export interface ContractABIMethodBase {
-  args: ContractABIArg[];
+export type ContractABIMessageArgPre = ContractABIArgBasePre;
+
+export type ContractABIMessageArg = ContractABIArgBase;
+
+export interface ContractABIMessageBase {
+  args: ContractABIMessageArg[];
 }
 
-export interface ContractABIMethod extends ContractABIMethodBase {
+export interface ContractABIMessageBasePre {
+  args: ContractABIMessageArgPre[];
+}
+
+export interface ContractABIMessageCommon {
+  docs?: ContractABIDocs;
   mutates?: boolean;
+  selector: string | number;
+}
+
+export interface ContractABIMessagePre extends ContractABIMessageCommon, ContractABIMessageBasePre {
+  name: StringIndex;
+  return_type: ContractABITypePre | null;
+}
+
+export interface ContractABIMessage extends ContractABIMessageCommon {
+  args: ContractABIMessageArg[];
   name: string;
-  selector: number;
-  return_type: ContractABITypes | null;
+  returnType: TypeDef | null;
+}
+
+export interface ContractABIContractCommon {
+  docs?: ContractABIDocs;
+}
+
+export interface ContractABIContractPre extends ContractABIContractCommon {
+  constructors: ContractABIMessagePre[];
+  messages: ContractABIMessagePre[];
+  name: StringIndex;
+  events?: ContractABIEventPre[];
+  docs?: ContractABIDocs;
+}
+
+export interface ContractABIContract extends ContractABIContractCommon {
+  constructors: ContractABIMessage[];
+  messages: ContractABIMessage[];
+  name: string;
+  events?: ContractABIEvent[];
+  docs?: ContractABIDocs;
+}
+
+export interface ContractABIPre extends MetaRegistryJson {
+  storage: ContractABIStoragePre;
+  contract: ContractABIContractPre;
 }
 
 export interface ContractABI {
-  deploy: ContractABIMethodBase;
-  messages: ContractABIMethod[];
-  name: string;
+  storage: ContractABIStorage;
+  contract: ContractABIContract;
 }
 
 export interface ContractABIFnArg {
   name: string;
-  type: string;
+  type: TypeDef;
 }
 
 export interface ContractABIMeta {
   args: ContractABIFnArg[];
   isConstant: boolean;
-  type: string | null;
+  type: TypeDef | null;
 }
 
 export interface ContractABIFn extends ContractABIMeta {
   (...args: CodecArg[]): Uint8Array;
 }
 
+export interface ContractABIEventArgBase {
+  indexed: boolean;
+}
+
+export interface ContractABIEventArgPre extends ContractABIArgBasePre, ContractABIEventArgBase {}
+
+export interface ContractABIEventArg extends ContractABIArgBase, ContractABIEventArgBase {}
+
+export type ContractABIDocs = string[];
+
+export interface ContractABIEventPre {
+  args: ContractABIEventArgPre[];
+}
+
+export interface ContractABIEvent {
+  args: ContractABIEventArg[];
+}
+
+export interface ContractABIRangeBase {
+  // can be number[] (old) or hex (new)
+  'range.offset': number[] | string;
+  'range.len': number;
+}
+
+export interface ContractABIRangePre extends ContractABIRangeBase {
+  'range.elem_type': TypeIndex;
+}
+
+export interface ContractABIRange extends ContractABIRangeBase {
+  'range.elem_type': TypeDef;
+}
+
+export type ContractABIStorageLayoutPre = ContractABIStorageStructPre | ContractABIRangePre;
+
+export type ContractABIStorageLayout = ContractABIStorageStruct | ContractABIRange;
+
+export interface ContractABIStorageStructFieldPre {
+  name: StringIndex;
+  layout: ContractABIStorageLayoutPre;
+}
+
+export interface ContractABIStorageStructField {
+  name: string;
+  layout: ContractABIStorageLayout;
+}
+
+export interface ContractABIStorageStructPre {
+  'struct.type': TypeIndex;
+  'struct.fields': ContractABIStorageStructFieldPre[];
+}
+
+export interface ContractABIStorageStruct {
+  'struct.type': TypeDef;
+  'struct.fields': ContractABIStorageStructField[];
+}
+
+export type ContractABIStoragePre = ContractABIStorageStructPre;
+
+export type ContractABIStorage = ContractABIStorageStruct;
+
+export interface ContractMessage {
+  index: number;
+  fn: ContractABIFn;
+  def: ContractABIMessage;
+}
+
+export type AbiConstructors = ContractABIFn[];
+
 export type AbiMessages = Record<string, ContractABIFn>;
 
 export interface InterfaceAbi {
   readonly abi: ContractABI;
-  readonly deploy: ContractABIFn;
+  readonly constructors: AbiConstructors;
   readonly messages: AbiMessages;
 }
 
-export interface ContractBase<ApiType> {
-  readonly abi: InterfaceAbi;
-  readonly api: ApiObject<ApiType>;
-  readonly apiContracts: SubmittableModuleExtrinsics<ApiType>;
-}
-
 export interface InterfaceContractCalls {
   [index: string]: Function;
 }
@@ -90,3 +195,13 @@ export interface InterfaceContract {
   readonly address: Address;
   readonly calls: InterfaceContractCalls;
 }
+
+export interface ContractCallOutcome {
+  time: number;
+  result: ContractExecResult;
+  origin: AccountId;
+  output: Codec | null;
+  params: any[];
+  isSuccess: boolean;
+  message: ContractABIMessage;
+}