@substrate/connect

What is @substrate/connect?

@substrate/connect is a JavaScript library that provides a way to connect to Substrate-based blockchain nodes. It offers a convenient API to interact with the blockchain, manage connections, and handle different types of network environments.

What are @substrate/connect's main functionalities?

Connecting to a Substrate Node

This feature allows you to establish a connection to a Substrate-based blockchain node using a WebSocket endpoint. The code sample demonstrates how to connect to a Polkadot node.

const { connect } = require('@substrate/connect');

async function main() {
  const api = await connect('wss://rpc.polkadot.io');
  console.log('Connected to the node');
}

main();

Handling Different Network Environments

This feature provides the ability to specify the network environment when connecting to a node. The code sample shows how to connect to the Polkadot network specifically.

const { connect } = require('@substrate/connect');

async function main() {
  const api = await connect('wss://rpc.polkadot.io', { network: 'polkadot' });
  console.log('Connected to the Polkadot network');
}

main();

Interacting with Blockchain Data

This feature allows you to interact with blockchain data once connected. The code sample demonstrates how to retrieve and log the name of the blockchain you are connected to.

const { connect } = require('@substrate/connect');

async function main() {
  const api = await connect('wss://rpc.polkadot.io');
  const chain = await api.rpc.system.chain();
  console.log(`You are connected to chain ${chain}`);
}

main();

Other packages similar to @substrate/connect

@polkadot/api

@polkadot/api is a library for interacting with Polkadot and Substrate-based blockchains. It provides a comprehensive API for querying blockchain data, submitting transactions, and managing accounts. Compared to @substrate/connect, @polkadot/api offers more extensive functionality for interacting with the blockchain, but @substrate/connect focuses on simplifying the connection process.

ethers

ethers is a library for interacting with the Ethereum blockchain. It provides utilities for connecting to Ethereum nodes, managing wallets, and interacting with smart contracts. While it is specific to Ethereum, it offers similar functionalities in terms of node connection and blockchain interaction as @substrate/connect does for Substrate-based blockchains.

README

@substrate/connect

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

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