Integrate a Light Client Node
Demonstrates how you can connect to Substrate-based blockchains using Substrate Connect in a browser.
Last updated
Demonstrates how you can connect to Substrate-based blockchains using Substrate Connect in a browser.
Last updated
As you learned in , light client nodes provide secure and decentralized access to blockchain data with minimal hardware and software requirements.
This tutorial demonstrates how you can connect to any Substrate-based blockchain using a light client. To illustrate this, you'll learn how to connect your application to the . Statemint is a system parachain that is connected to Polkadot and has a publicly-accessible chain specification file.
Before you begin, verify the following:
You have a code editor set up for working with Javascript and Typescript.
You have the installed.
By completing this tutorial, you will accomplish the following objectives:
Connect to the Polkadot relay chain using the Substrate Connect Javascript library.
Learn how to specify a custom chain specification file for Substrate Connect to use.
Connect to a parachain associated with the custom chain specification.
Before the light client can connect to a network, you must have a web application that specifies the network the light client should connect to, the nodes for it to communicate with, and the consensus-critical state it must have at genesis. This information is available in the file for the network.
Substrate Connect is preconfigured to recognize several chains that are defined in the enumeration list. These well-known chains are:
Polkadot identified as polkadot
Kusama identified as ksmcc3
Rococo identified as rococo_v2_2
Westend identified as westend2
To connect to one of these chains:
Open a new terminal shell on your computer.
Create a web application to use Substrate Connect by cloning the empty-webapp
template with the following command:
Change to the empty-webapp
directory by running the following command:
Install Substrate Connect by running the following command:
Install dependencies from the Polkadot-JS RPC provider by running the following command:
Install dependencies from the Polkadot-JS API by running the following command:
After you install these dependencies, you can use them in the sample application.
Open the empty-webapp/index.ts
file in your preferred code editor.
Copy and paste the following application code to create a Substrate Connect instance with substrate-connect
as the provider that connects to the Polkadot relay chain using the polkadot
chain specification file.
In this sample application code, creating a Substrate Connect instance is similar to how you create a WebSocket instance using the Polkadot-JS API. With the Polkadot-JS API only, you would create an instance like this:
For Substrate Connect, you replace the WebSocket (WsProvider
) provider with the Substrate Connect (ScProvider
) provider, and, instead of a WebSocket URL client address, you specify the chain specification for the network to connect to (WellKnownChain.polkadot
).
Install any remaining dependencies by running the following command:
Start the web application by running the following command:
If there are compiler errors when you start the local server, you might be missing a dependency not accounted for by the current yarn
configuration. If a dependency is missing, you can add the package by running a command similar to the following:
Verify the browser opens the URL http://localhost:3001/
.
Open the browser console for your browser.
How you navigate to and open the browser console varies depending on the browser and operating system you use. For example, on Chrome, select More Tools, Developer Tools, then click Console.
Verify the smoldot
process is initialized, followed by the hashes of the incoming blocks from Polkadot.
For example, the console should display log entries similar to the following:
Stop the smoldot
light client node by pressing Control-c.
Connecting to a custom chain specification or a publicly-accessible parachain is similar to connecting to one of the well-known chains. The primary difference in the code is that you must explicitly identify the chain specification for Substrate Connect to use.
To connect to Statemint:
Open the index.ts
file in your code editor.
Replace the contents with the following code.
As you can see, this code has a few important differences.
The statemint.json
chain specification file is imported into the jsonParachainSpec
object.
The chain specification is converted to a JSON-encoded string and stored in the parachainSpec
variable, so that it can be exchanged with the web server.
The ScProvider
provider is created for the polkadot
relay chain but is used as a parameter for creating and connecting to the parachain provider.
Substrate Connect requires this information to determine the relay chain that the parachain communicates with.
Start the web application by running the following command:
Verify the browser opens the URL http://localhost:3001/
.
Open the browser console for your browser.
Verify the smoldot
process is initialized, followed by the hashes of the incoming blocks from Polkadot.
For example, the console should display log entries similar to the following:
This simple web application only connects to Polkadot to retrieve block hashes. The primary purpose of this application is to demonstrate connecting to the chain without using a centralized entry point to the network, such as the URL for a specific RPC node. However, you could extend this application to do a lot more, because—after you replace WsProvider
with ScProvider
—you can write code for your application simply by using the existing .
Download the custom chain specification file from the .
Copy the downloaded chain specification to the empty-webapp
directory you created in .
Congratulations, you've created a simple web application that connects to Statemint and Polkadot using an in-browser light client. Have a look at to learn how to add connections to more chains from the same application.