Module @substrate/connect - v2.1.3

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

An NPM package that offers an innovative way to interact with Substrate-based blockchains directly in your browser.

npm GPL-3.0-or-later



The primary implementation of the light-client provider for any Substrate-based chain.

Using @substrate/connect for library authors

The connect package searches for a light client provider via the discovery protocol. If none is found, it will initiate a smoldot instance in the user's browser tab.

Example Usage

To connect to a well-known chain ('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":[]}',
)

To connect to a custom Substrate chain using its 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":[]}',
)

Connecting to a Parachain

To connect to a parachain, first instantiate the relay chain it is connected to, then instantiate the parachain on the same relay chain. The following example connects to a parachain on 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":[]}',
)

PolkadotJs Example

yarn add @polkadot/rpc-provider
yarn add @polkadot/api

import { ScProvider } from "@polkadot/rpc-provider/substrate-connect"
import * as Sc from "@substrate/connect"
import { ApiPromise } from "@polkadot/api"

// Connect to polkadot relay chain
const provider = new ScProvider(Sc, Sc.WellKnownChain.polkadot)
await provider.connect()
const api = await ApiPromise.create({ provider })

// Connect to parachain
const provider2 = new ScProvider(Sc, Sc.WellKnownChain.people, provider)
await provider2.connect()
const api2 = await ApiPromise.create({ provider })

Scripts

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

Index

Namespaces

WellKnownChain

Classes

AlreadyDestroyedError CrashError JsonRpcDisabledError QueueFullError

Interfaces

Chain Config EmbeddedNodeConfig ScClient

Type Aliases

AddChain AddChainOptions AddWellKnownChain WellKnownChain

Variables

WellKnownChain

Functions

createScClient

Settings

Member Visibility

On This Page

Adding parachainsResources sharingWell-known chainsUsage with a worker
MMNEPVFCICPMFPCPTTAAATR