@substrate/connect

Using @substrate/connect through the PolkadotJS RPC Provider

The recommended way to use @substrate/connect is to use PolkadotJS, which provides a higher-level API built on top of it. Unless you are writting your own library, you probably want to use the PolkadotJS RPC provider.

Provide a well-known chain name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_2'):

Note these names are the "real" names of the chains rather than the friendly names (e.g. "kusama" or "rococo"). 'ksmcc3' is the name for kusama. This matters for chains which have been hard forked. I.e. rococo - "rococo_v2" and "rococo_v2_2" are two completely unrelated chains.

1import { ApiPromise } from "@polkadot/api";
2import {
3  ScProvider
4} from "@polkadot/rpc-provider";
5import * as Sc from "@substrate/connect";
6
7const provider = new ScProvider(Sc, Sc.WellKnownChain.polkadot);
8await provider.connect();
9const polkadotApi = await ApiPromise.create({ provider });
10await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => {
11  console.log(lastHeader.number.toString());
12});

...or provide your custom Substrate chain's specification:

1import { ApiPromise } from "@polkadot/api";
2import { ScProvider } from "@polkadot/rpc-provider/substrate-connect";
3import * as Sc from "@substrate/connect";
4
5import myJsonSubstrateChainSpec from './mySubstrateChainSpec.json';
6
7const mySubstrateChainSpec = JSON.stringify(myJsonSubstrateChainSpec);
8const provider = new ScProvider(Sc, mySubstrateChainSpec);
9
10await provider.connect();
11
12const polkadotApi = await ApiPromise.create({ provider });
13await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => {
14  console.log(lastHeader.number.toString());
15});

In order to connect to a parachain, you must first instantiate the ScProvider corresponding to the relay chain, then pass this ScProvider as the second argument of the constructor of the parachain ScProvider. The following example connects to a parachain of the Westend test network:

1import { ApiPromise } from "@polkadot/api";
2import {
3  ScProvider
4} from "@polkadot/rpc-provider";
5import * as Sc from "@substrate/connect";
6
7import jsonParachainSpec from './myParaChainSpec.json';
8
9const parachainSpec = JSON.stringify(jsonParachainSpec);
10
11const relayProvider = new ScProvider(Sc, Sc.WellKnownChain.westend2);
12const provider = new ScProvider(Sc, parachainSpec, relayProvider);
13
14await provider.connect();
15
16const polkadotApi = await ApiPromise.create({ provider });
17await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => {
18  console.log(lastHeader.number.toString());
19});

Using @substrate/connect for library authors

Provide a well-known chain name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_2'):

1import { createScClient, WellKnownChain } from '@substrate/connect';
2
3const scClient = createScClient();
4const chain = await scClient.addWellKnownChain(
5  WellKnownChain.westend2,
6  function jsonRpcCallback(response) {
7    console.log("response", response);
8  }
9);
10
11chain.sendJsonRpc(
12  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
13);

...or provide your custom substrate chain's name and chainspec:

1import { createScClient } from '@substrate/connect';
2import myJsonChainSpec from './mySubstrateChainSpec.json';
3
4const myChainSpec = JSON.stringify(myJsonChainSpec);
5
6const scClient = createScClient();
7const chain = await scClient.addChain(
8  myChainSpec,
9  function jsonRpcCallback(response) {
10    console.log("response", response);
11  }
12);
13
14chain.sendJsonRpc(
15  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
16);

In order to connect to a parachain, you must first instantiate the relay chain this parachain is connected to, then instantiate the parachain on the same ScClient. The following example connects to a parachain of the Westend test network:

1import { createScClient, WellKnownChain } from '@substrate/connect';
2import jsonParachainSpec from './myParaChainSpec.json';
3
4const parachainSpec = JSON.stringify(jsonParachainSpec);
5
6const scClient = createScClient();
7await scClient.addWellKnownChain(WellKnownChain.westend2)
8const parachain = await scClient.addChain(
9  parachainSpec,
10  function jsonRpcCallback(response) {
11    console.log("response", response);
12  }
13);
14
15parachain.sendJsonRpc(
16  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
17);

Scripts

• yarn test to run the unit tests
• yarn build to build @substrate-connect
• yarn lint to run linter for @substrate-connect