Module @substrate/connect - v0.8.10

The substrate-connect package makes it possible to connect to Substrate-compatible blockchains with a light client.

Connecting to a chain is done in two steps:

  1. Call createScClient, which gives you a so-called client.
  2. Call addChain or addWellKnownChain on this client.

Note that this library is a low-level library where you directly send JSON-RPC requests and receive responses.

Adding parachains

Connecting to a parachain is done by obtaining a relay chain instance and then calling addChain.

const client = createScClient();
const relayChain = await client.addChain(relayChainSpec);
const parachain = await relayChain.addChain(parachainSpec);

While this will not work, and an exception will be thrown when adding the parachain:

await createScClient().addChain(relayChainSpec);
await createScClient().addChain(parachainSpec);

Resources sharing

While calling createScClient multiple times leads to a different observable behaviour when it comes to parachains (see previous section), internally resources are shared between all the clients.

In order words, it is not a problem to do this:

const relayChainSpec = ...;
const chain1 = await createScClient().addChain(relayChainSpec);
const chain2 = await createScClient().addChain(relayChainSpec);

From an API perspective, chain1 and chain2 should be treated as two completely separate connections to the same chain. Internally, however, only one "actual" connection to that chain will exist.

This means that there is no problem in calling createScClient from within a library for example.

Well-known chains

This package contains a list of so-called WellKnownChains. This is a list of popular chains that users are likely to connect to. Instead of calling addChain with a chain specification, one can call addWellKnownChain, passing only the name of a well-known chain as parameter.

Using WellKnownChains doesn't provide any benefit when the substrate-connect extension is not installed.

If, however, the substrate-connect extension is installed, using addWellKnownChain has several benefits:

  • The web page that uses substrate-connect doesn't need to download the chain specification of a well-known chain from the web server, as this chain specification is already known by the extension.
  • The extension starts connect to well-known chains when the browser initializes, meaning that when addWellKnownChain is called, it is likely that the chain in question has already been fully synchronized.
  • Furthermore, the extension stores the state of all the well-known chains in the browser's local storage. This leads to a very quick initialization time.

Usage with a worker

By default, when the substrate-connect extension is not installed, createScClient will run the smoldot light client entirely in the current thread. This can cause performance issues if other CPU-heavy operations are done in that thread.

In order to help with this, it possible to run the smoldot light client in a worker. To do so, you must provide a workerFactory to createScClient and setup the worker to import @substrate/connect/worker.

For example

// worker.mjs
import "@substrate/connect/worker"

// main.mjs
import { createScClient } from "@substrate/connect"
createScClient({
  embeddedNodeConfig: {
    workerFactory: () => new Worker("./worker.mjs"),
  },
})

@substrate/connect

Using @substrate/connect for library authors

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

import { createScClient, WellKnownChain } from '@substrate/connect';

const scClient = createScClient();
const chain = await scClient.addWellKnownChain(
  WellKnownChain.westend2,
  function jsonRpcCallback(response) {
    console.log("response", response);
  }
);

chain.sendJsonRpc(
  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
);

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

import { createScClient } from '@substrate/connect';
import myJsonChainSpec from './mySubstrateChainSpec.json';

const myChainSpec = JSON.stringify(myJsonChainSpec);

const scClient = createScClient();
const chain = await scClient.addChain(
  myChainSpec,
  function jsonRpcCallback(response) {
    console.log("response", response);
  }
);

chain.sendJsonRpc(
  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
);

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 relay chain. The following example connects to a parachain of the Westend test network:

import { createScClient, WellKnownChain } from '@substrate/connect';
import jsonParachainSpec from './myParaChainSpec.json';

const parachainSpec = JSON.stringify(jsonParachainSpec);

const scClient = createScClient();
const relayChain = await scClient.addWellKnownChain(WellKnownChain.westend2)
const parachain = await relayChain.addChain(
  parachainSpec,
  function jsonRpcCallback(response) {
    console.log("response", response);
  }
);

parachain.sendJsonRpc(
  '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}'
);

Scripts

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

Index

Enumerations

WellKnownChain

Classes

AlreadyDestroyedError CrashError JsonRpcDisabledError

Interfaces

Chain Config EmbeddedNodeConfig ScClient

Type Aliases

AddChain AddWellKnownChain JsonRpcCallback

Functions

createScClient

Settings

Member Visibility

Theme

On This Page

Adding parachainsResources sharingWell-known chainsUsage with a worker@substrate/connect

Generated using TypeDoc