@polkadot/api/rx

Overview

name: ApiRx

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.

see: ApiPromise

Usage

Making rpc calls -

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.subscribeNewHead().subscribe((header) => {
  console.log(`Chain is at #${header.blockNumber}`);
});

Subscribing to chain state -

import { combineLatest } from 'rxjs';
import { ApiRx } from '@polkadot/api';
import { WsProvider } from '@polkadot/rpc-provider';

// last block timestamp
let last = 0;

// initialise a provider with a specific endpoint
const provider = new WsProvider('wss://example.com:9944')

// initialise via isReady & new with specific provider
new ApiRx(provider)
  .isReady
  .pipe(
    switchMap((api) =>
      combineLatest([
        api.query.timestamp.blockPeriod(),
        api.query.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)`);
  });

Submitting a transaction -

import ApiRx from '@polkadot/api/rx';

// get api via Promise
const api = await ApiRx.create().toPromise();

// retrieve nonce for the account
api.query.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}`);
  });

Hierarchy

ApiBase<RpcRx, QueryableStorage, SubmittableExtrinsics>

↳ ApiRx

Implements

• ApiBaseInterface<RpcRx, QueryableStorage, SubmittableExtrinsics>
• ApiRxInterface

Constructors

constructor

⊕ new ApiRx(options?: ApiOptions | ProviderInterface): ApiRx

Overrides ApiBase.constructor

Defined in rx/index.ts:145

description: Create an instance of the ApiRx class

example:

import Api from '@polkadot/api/rx';

new Api().isReady.subscribe((api) => {
  api.rpc.subscribeNewHead().subscribe((header) => {
    console.log(`new block #${header.blockNumber.toNumber()}`);
  });
});

Parameters:

Returns: ApiRx

Accessors

derive

getderive(): Derive

Defined in rx/index.ts:181

Returns: Derive

genesisHash

getgenesisHash(): Hash

Inherited from ApiBase.genesisHash

Defined in Base.ts:77

description: Contains the genesis Hash of the attached chain. Apart from being useful to determine the actual chain, it can also be used to sign immortal transactions.

Returns: Hash

hasSubscriptions

gethasSubscriptions(): boolean

Inherited from ApiBase.hasSubscriptions

Defined in Base.ts:86

description: true when subscriptions are supported

Returns: boolean

isConnected

getisConnected(): Observable<boolean>

Defined in rx/index.ts:188

description: Observable that carries the connected state for the provider. Results in a boolean flag that is true/false based on the connectivity.

Returns: Observable<boolean>

isReady

getisReady(): Observable<ApiRx>

Defined in rx/index.ts:195

description: Observable that returns the first time we are connected and loaded

Returns: Observable<ApiRx>

query

getquery(): QueryableStorage

Inherited from ApiBase.query

Defined in Base.ts:122

description: Contains all the chain state modules and their subsequent methods in the API. These are attached dynamically from the runtime metadata.

All calls inside the namespace, is denoted by section.method and may take an optional query parameter. As an example, api.query.timestamp.now() (current block timestamp) does not take parameters, while api.query.system.accountNonce(<accountId>) (retrieving the associated nonce for an account), takes the AccountId as a parameter.

example:

api.query.balances.freeBalance(<accountId>, (balance) => {
  console.log('new balance', balance);
});

Returns: QueryableStorage

rpc

getrpc(): RpcRx

Inherited from ApiBase.rpc

Defined in Base.ts:142

description: Contains all the raw rpc sections and their subsequent methods in the API as defined by the jsonrpc interface definitions. Unlike the dynamic api.query and api.tx sections, these methods are fixed (although extensible with node upgrades) and not determined by the runtime.

RPC endpoints available here allow for the query of chain, node and system information, in addition to providing interfaces for the raw queries of state (usine known keys) and the submission of transactions.

example:

api.rpc.chain.subscribeNewHead((header) => {
  console.log('new header', header);
});

Returns: RpcRx

runtimeMetadata

getruntimeMetadata(): Metadata

Inherited from ApiBase.runtimeMetadata

Defined in Base.ts:93

description: Yields the current attached runtime metadata. Generally this is only used to construct extrinsics & storage, but is useful for current runtime inspection.

Returns: Metadata

runtimeVersion

getruntimeVersion(): RuntimeVersion

Inherited from ApiBase.runtimeVersion

Defined in Base.ts:102

description: Contains the version information for the current runtime.

Returns: RuntimeVersion

tx

gettx(): SubmittableExtrinsics

Inherited from ApiBase.tx

Defined in Base.ts:161

description: Contains all the extrinsic modules and their subsequent methods in the API. It allows for the construction of transactions and the submission thereof. These are attached dynamically from the runtime metadata.

example:

api.tx.balances
  .transfer(<recipientId>, <balance>)
  .sign(<keyPair>, <accountNonce>, <blockHash (optional)>)
  .send((status) => {
    console.log('tx status', status);
  });

Returns: SubmittableExtrinsics

Methods

on

▸ on(type: ApiInterface$Events, handler: function): this

Inherited from ApiBase.on

Defined in Base.ts:186

description: Attach an eventemitter handler to listen to a specific event

example:

api.on('connected', () => {
  console.log('API has been connected to the endpoint');
});

api.on('disconnected', () => {
  console.log('API has been disconnected from the endpoint');
});

Parameters:

Returns: this

once

▸ once(type: ApiInterface$Events, handler: function): this

Inherited from ApiBase.once

Defined in Base.ts:211

description: Attach an one-time eventemitter handler to listen to a specific event

example:

api.once('connected', () => {
  console.log('API has been connected to the endpoint');
});

api.once('disconnected', () => {
  console.log('API has been disconnected from the endpoint');
});

Parameters:

Returns: this

<Static> create

▸ create(options?: ApiOptions | ProviderInterface): Observable<ApiRx>

Defined in rx/index.ts:143

description: Creates an ApiRx instance using the supplied provider. Returns an Observable containing the actual Api instance.

example:

import Api from '@polkadot/api/rx';

Api.create().subscribe((api) => {
  api.query.timestamp.now.subscribe((timestamp) => {
    console.log(`lastest block timestamp ${timestamp}`);
  });
});

Parameters:

Returns: Observable<ApiRx>