API documentation (#253)
* Remove badges from READMEs (used inside docs) * Expand intro * Intro and examples for ApiRx * examples -> examples-rpc * Update intros with expanded example * Don't nest subscriptions
This commit is contained in:
Jaco Greeff
+8
-8
@@ -13,11 +13,11 @@
|
||||
|
||||
## Examples
|
||||
|
||||
- [Overview](examples/README.md)
|
||||
- [Simple connect](examples/01_simple_connect/README.md)
|
||||
- [Listen to blocks](examples/02_listen_to_blocks/README.md)
|
||||
- [Listen to balance change](examples/03_listen_to_balance_change/README.md)
|
||||
- [Generate Accounts](examples/04_generate_account/README.md)
|
||||
- [Read Storage](examples/05_read_storage/README.md)
|
||||
- [Craft Extrinsic](examples/06_craft_extrinsic/README.md)
|
||||
- [Transfer DOTs](examples/07_transfer_dots/README.md)
|
||||
- [RPC](examples-rpc/README.md)
|
||||
- [Simple connect](examples-rpc/01_simple_connect/README.md)
|
||||
- [Listen to blocks](examples-rpc/02_listen_to_blocks/README.md)
|
||||
- [Listen to balance change](examples-rpc/03_listen_to_balance_change/README.md)
|
||||
- [Generate Accounts](examples-rpc/04_generate_account/README.md)
|
||||
- [Read Storage](examples-rpc/05_read_storage/README.md)
|
||||
- [Craft Extrinsic](examples-rpc/06_craft_extrinsic/README.md)
|
||||
- [Transfer DOTs](examples-rpc/07_transfer_dots/README.md)
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/api-observable)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/api-observable)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/api-observable#info=devDependencies)
|
||||
|
||||
# @polkadot/api
|
||||
|
||||
An Observable wrapper around [@polkadot/rpc-core](../rpc-core).
|
||||
|
||||
+38
-28
@@ -1,18 +1,23 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/api)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/api)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/api#info=devDependencies)
|
||||
|
||||
# @polkadot/api
|
||||
|
||||
An RxJs wrapper around [@polkadot/rpc-core](../rpc-core).
|
||||
The Polkadot-JS API provides easy-to-use wrappers around JSONRPC calls that flow from an application to a node. It handles all the encoding and decoding or parameters, provides access to RPC functions and allows for the query of chain state and the submission of transactions.
|
||||
|
||||
# Usage
|
||||
The API wrappers provide a standard interface for use -
|
||||
|
||||
- A static `.create(<optional WsProvider>)` that returns an API istance when connected, decorated and ready-to use
|
||||
- The above is just a wrapper for `new Api(<optional WsProvider>) `, exposing the `isReady` getter
|
||||
- `api.rpc.*` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
|
||||
- `api.st.*` provides access to chain state queries. These are dynamically populated based on what the runtime provides
|
||||
- `api.tx.*` provides the ability to create transaction, like chain state, this list is populated from a runtime query
|
||||
|
||||
## API Selection
|
||||
|
||||
There are two flavours of the API provided, one allowing a standard interface via JavaScript Promises and the second provides an Observable wrapper using [RxJS](https://github.com/ReactiveX/rxjs). Depending on your use-case and familiarity, you can choose either (or even both) for your application.
|
||||
|
||||
- [ApiPromise](promise/) All interface calls returns Promises, including the static `.create(...)`. Additionally any subscription method use standard JavaScript `(error, value) => {}` callbacks.
|
||||
- [ApiRx](rx/) All interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
|
||||
|
||||
## Installation & import
|
||||
|
||||
Installation -
|
||||
|
||||
@@ -20,14 +25,26 @@ Installation -
|
||||
npm install --save @polkadot/api/rx
|
||||
```
|
||||
|
||||
Making rpc calls -
|
||||
Subscribing to blocks via Promise-based API -
|
||||
|
||||
```javascript
|
||||
import ApiRx from '@polkadot/api/rx';
|
||||
// alternatively
|
||||
// import { ApiRx } from '@polkadot/api';
|
||||
import { ApiPromise } from '@polkadot/api';
|
||||
|
||||
// initialise via Promise & static create
|
||||
// initialise via static create
|
||||
const api = await ApiPromise.create();
|
||||
|
||||
// make a call to retrieve the current network head
|
||||
api.rpc.chain.newHead((error, header) => {
|
||||
console.log(`Chain is at #${header.blockNumber}`);
|
||||
});
|
||||
```
|
||||
|
||||
Subscribing to blocks via RxJS-based API -
|
||||
|
||||
```javascript
|
||||
import { ApiRx } from '@polkadot/api';
|
||||
|
||||
// initialise via static create
|
||||
const api = await ApiRx.create().toPromise();
|
||||
|
||||
// make a call to retrieve the current network head
|
||||
@@ -36,16 +53,9 @@ api.rpc.chain.newHead().subscribe((header) => {
|
||||
});
|
||||
```
|
||||
|
||||
Subscribing to chain state -
|
||||
## Users
|
||||
|
||||
```javascript
|
||||
import Api from '@polkadot/api';
|
||||
Some of the users of the API (let us know if you are missing from the list), include -
|
||||
|
||||
// initialise via isReady & new
|
||||
new Api().isReady.subscribe((api) => {
|
||||
// make a call to retrieve the current network head
|
||||
api.st.timestamp.now().subscribe((timestamp) => {
|
||||
console.log(`Current block timestamp ${timestamp}`);
|
||||
});
|
||||
});
|
||||
```
|
||||
- [Polkadot-JS UI](https://github.com/polkadot-js/apps) A user-interface that allows you to make transactions, query the network or participate in actions on the network such as referendums and staking
|
||||
- [Polkabot](https://gitlab.com/Polkabot) Polkabot is a Matrix chatbot that keeps an eye on the Polkadot network. You can see Polkabot in action in https://matrix.to/#/#polkadot-network-status:matrix.org
|
||||
|
||||
@@ -9,11 +9,86 @@ import Rpc from '@polkadot/rpc-core/index';
|
||||
import { Extrinsics, ExtrinsicFunction } from '@polkadot/extrinsics/types';
|
||||
import { Storage } from '@polkadot/storage/types';
|
||||
import { Base } from '@polkadot/types/codec';
|
||||
import isFunction from '@polkadot/util/is/function';
|
||||
|
||||
import ApiBase from '../Base';
|
||||
import SubmittableExtrinsic from './SubmittableExtrinsic';
|
||||
import { StorageFunction } from '@polkadot/types/StorageKey';
|
||||
|
||||
/**
|
||||
* @description
|
||||
* ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Polkadot network. As a full Promise-based, all interface calls return Promises, including the static `.create(...)`. Subscription calls utilise standard JavaScript-convention `(error, value)` callbacks.
|
||||
*
|
||||
* The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of athe subscription-based features of Polkadot (and Substrate) clients.
|
||||
*
|
||||
* @example
|
||||
* <BR>
|
||||
*
|
||||
* Making rpc calls -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import ApiPromise from '@polkadot/api/promise';
|
||||
*
|
||||
* // initialise via static create
|
||||
* const api = await ApiPromise.create();
|
||||
*
|
||||
* // make a subscription to the network head
|
||||
* api.rpc.chain.newHead((error, header) => {
|
||||
* console.log(`Chain is at #${header.blockNumber}`);
|
||||
* });
|
||||
* ```
|
||||
* <BR>
|
||||
*
|
||||
* Subscribing to chain state -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import { ApiPromise } from '@polkadot/api';
|
||||
* import WsProvider from '@polkadot/rpc-provider/ws';
|
||||
*
|
||||
* // initialise via isReady & new with specific non-local endpoint
|
||||
* const api = await new ApiPromise(new WsProvider('wss://example.com:9944')).isReady;
|
||||
*
|
||||
* // retrieve the block target time
|
||||
* const blockPeriod = await api.st.timestamp.blockPeriod().toNumber();
|
||||
* let last = 0;
|
||||
*
|
||||
* // subscribe to the current block timestamp, updates automatically
|
||||
* api.st.timestamp.now((error, timestamp) => {
|
||||
* const elapsed = last
|
||||
* ? `, ${timestamp.toNumber() - last}s since last`
|
||||
* : '';
|
||||
*
|
||||
* last = timestamp.toNumber();
|
||||
* console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
|
||||
* });
|
||||
* ```
|
||||
* <BR>
|
||||
*
|
||||
* Submitting a transaction -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import ApiPromise from '@polkadot/api/promise';
|
||||
*
|
||||
* ApiPromise.create().then((api) => {
|
||||
* const nonce = await api.st.system.accountNonce(keyring.alice.address());
|
||||
*
|
||||
* api.tx.balances
|
||||
* // create transfer
|
||||
* transfer(keyring.bob.address(), 12345)
|
||||
* // sign the transcation
|
||||
* .sign(keyring.alice, nonce)
|
||||
* // send the transaction
|
||||
* .send()
|
||||
* // retrieve the overall result
|
||||
* .then((hash) => {
|
||||
* console.log(`submitted with hash ${hash}`);
|
||||
* });
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, SubmittableExtrinsics> implements ApiPromiseInterface {
|
||||
private _isReady: Promise<ApiPromise>;
|
||||
|
||||
@@ -109,8 +184,16 @@ export default class ApiPromise extends ApiBase<Rpc, QueryableStorage, Submittab
|
||||
}
|
||||
|
||||
private decorateStorageEntry (method: StorageFunction): QueryableStorageFunction {
|
||||
const decorated: any = (arg: any): Promise<Base | null | undefined> =>
|
||||
this.rpc.state.getStorage([method, arg]);
|
||||
const decorated: any = (...args: Array<any>): Promise<Base | null | undefined> => {
|
||||
if (args.length === 0 || !isFunction(args[args.length - 1])) {
|
||||
return this.rpc.state.getStorage([method, args[0]]);
|
||||
}
|
||||
|
||||
return this.rpc.state.storage(
|
||||
[[method, args.length === 1 ? undefined : args[0]]],
|
||||
args[args.length - 1]
|
||||
);
|
||||
};
|
||||
|
||||
return this.decorateFunctionMeta(method, decorated) as QueryableStorageFunction;
|
||||
}
|
||||
|
||||
@@ -20,6 +20,92 @@ import { StorageFunction } from '@polkadot/types/StorageKey';
|
||||
|
||||
const l = logger('api-rx');
|
||||
|
||||
/**
|
||||
* @description
|
||||
* ApiRx is a powerfull RxJS Observable wrapper around the RPC and interfaces on the Polkadot network. As a full Observable API, all interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
|
||||
*
|
||||
* The API is well suited to real-time applications where the latest state is needed, unlocking the subscription-based features of Polkadot (and Substrate) clients. Some familiarity with RxJS is a requirement to use the API, however just understanding `.subscribe` and `.pipe` on Observables will unlock full-scale use thereof.
|
||||
*
|
||||
* @example
|
||||
* <BR>
|
||||
*
|
||||
* Making rpc calls -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import ApiRx from '@polkadot/api/rx';
|
||||
*
|
||||
* // initialise via Promise & static create
|
||||
* const api = await ApiRx.create().toPromise();
|
||||
*
|
||||
* // make a call to retrieve the current network head
|
||||
* api.rpc.chain.newHead().subscribe((header) => {
|
||||
* console.log(`Chain is at #${header.blockNumber}`);
|
||||
* });
|
||||
* ```
|
||||
* <BR>
|
||||
*
|
||||
* Subscribing to chain state -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import { ApiRx } from '@polkadot/api';
|
||||
* import WsProvider from '@polkadot/rpc-provider/ws';
|
||||
* import { combineLatest } from 'rxjs';
|
||||
*
|
||||
* let last = 0;
|
||||
*
|
||||
* // initialise via isReady & new with specific non-local endpoint
|
||||
* new ApiRx(new WsProvider('wss://example.com:9944'))
|
||||
* .isReady
|
||||
* .pipe(
|
||||
* switchMap((api) =>
|
||||
* combineLatest([
|
||||
* api.st.timestamp.blockPeriod(),
|
||||
* api.st.timestamp.now()
|
||||
* ])
|
||||
* )
|
||||
* .subscribe(([blockPeriod, timestamp]) => {
|
||||
* const elapsed = last
|
||||
* ? `, ${timestamp.toNumber() - last}s since last`
|
||||
* : '';
|
||||
*
|
||||
* last = timestamp.toNumber();
|
||||
* console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
|
||||
* });
|
||||
* ```
|
||||
* <BR>
|
||||
*
|
||||
* Submitting a transaction -
|
||||
* <BR>
|
||||
*
|
||||
* ```javascript
|
||||
* import ApiRx from '@polkadot/api/rx';
|
||||
*
|
||||
* // get api via Promise
|
||||
* const api = await ApiRx.create().toPromise();
|
||||
*
|
||||
* // retrieve nonce for the account
|
||||
* api.st.system
|
||||
* .accountNonce(keyring.alice.address())
|
||||
* .pipe(
|
||||
* // pipe nonce into transfer
|
||||
* switchMap((nonce) =>
|
||||
* api.tx.balances
|
||||
* // create transfer
|
||||
* .transfer(keyring.bob.address(), 12345)
|
||||
* // sign the transcation
|
||||
* .sign(keyring.alice, nonce)
|
||||
* // send the transaction
|
||||
* .send()
|
||||
* )
|
||||
* )
|
||||
* // subscribe to overall result
|
||||
* .subscribe((hash) => {
|
||||
* console.log(`submitted with hash ${hash}`);
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export default class ApiRx extends ApiBase<RpcRx, QueryableStorage, SubmittableExtrinsics> implements ApiRxInterface {
|
||||
private _isReady: Observable<ApiRx>;
|
||||
|
||||
@@ -33,7 +119,7 @@ export default class ApiRx extends ApiBase<RpcRx, QueryableStorage, SubmittableE
|
||||
* import Api from '@polkadot/api/rx';
|
||||
*
|
||||
* Api.create().subscribe((api) => {
|
||||
* api.st.timestamp.now((timestamp) => {
|
||||
* api.st.timestamp.now.subscribe((timestamp) => {
|
||||
* console.log(`lastest block timestamp ${timestamp}`);
|
||||
* });
|
||||
* });
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/api)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=package/rpc-core)
|
||||
[](https://david-dm.org/polkadot-js/api?path=package/rpc-core#info=devDependencies)
|
||||
|
||||
# @polkadot/rpc-core
|
||||
|
||||
This library provides a clean wrapper around all the methods exposed by a Polkadot network client.
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/rpc-provider)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/rpc-provider)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/rpc-provider#info=devDependencies)
|
||||
|
||||
# @polkadot/rpc-provider
|
||||
|
||||
Generic transport providers to handle the transport of method calls to and from Polkadot clients from applications interacting with it. Generally, unless you are operating at a low-level and taking care of encoding and decoding of parameters/results, it won't be directly used. API interfaces building on top these providers can support various transports with the same underlying interfaces.
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/rpc-rx)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/rpc-rx)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/rpc-rx#info=devDependencies)
|
||||
|
||||
# @polkadot/rpc-rx
|
||||
|
||||
An RxJs wrapper around the [@polkadot/rpc-core](../rpc-core).
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/jsonrpc)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/type-jsonrpc)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/type-jsonrpc#info=devDependencies)
|
||||
|
||||
# @polkadot/jsonrpc
|
||||
|
||||
A definition of all the methods exposed in a general Polkadot client application. These are used not only to provide a comprehensive code-generated document of the available methods, but are also used in the API to auto-generate endpoints with the required type-checking.
|
||||
|
||||
@@ -1,13 +1,3 @@
|
||||
[](https://polkadot.js.org)
|
||||
|
||||
[](https://github.com/Flet/semistandard)
|
||||
[](https://www.npmjs.com/package/@polkadot/storage)
|
||||
[](https://travis-ci.org/polkadot-js/api)
|
||||
[](https://codeclimate.com/github/polkadot-js/api/maintainability)
|
||||
[](https://coveralls.io/github/polkadot-js/api?branch=master)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/type-storage)
|
||||
[](https://david-dm.org/polkadot-js/api?path=packages/type-storage#info=devDependencies)
|
||||
|
||||
# @polkadot/storage
|
||||
|
||||
An base interface to the storage layer
|
||||
|
||||
+2
-1
@@ -3,9 +3,10 @@ module.exports = {
|
||||
exclude: [],
|
||||
excludeExternals: true,
|
||||
excludeNotExported: true,
|
||||
excludeProtected: true,
|
||||
excludePrivate: true,
|
||||
hideGenerator: true,
|
||||
includeDeclarations: true,
|
||||
includeDeclarations: false,
|
||||
out: 'docs',
|
||||
module: 'commonjs',
|
||||
moduleResolution: 'node',
|
||||
|
||||
Reference in New Issue
Block a user