Connect to network

After setting up your project & installing dedot packages, let's connect to the network to make some on-chain interactions. You can connect to the network using a WebSocket (wss://) connection or via light client (smoldot).

Initializing DedotClient and interact with Polkadot network

WebSocket

import { DedotClient, WsProvider } from 'dedot';
import type { PolkadotApi } from '@dedot/chaintypes';

// Initialize providers & clients
const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await DedotClient.new<PolkadotApi>(provider);

// Call rpc `state_getMetadata` to fetch raw scale-encoded metadata and decode it.
const metadata = await client.rpc.state_getMetadata();
console.log('Metadata:', metadata);

// Query on-chain storage
const balance = await client.query.system.account(<address>);
console.log('Balance:', balance);

// Subscribe to on-chain storage changes
const unsub = await client.query.system.number((blockNumber) => {
  console.log(`Current block number: ${blockNumber}`);
});

// Get pallet constants
const ss58Prefix = client.consts.system.ss58Prefix;
console.log('Polkadot ss58Prefix:', ss58Prefix);

// Call runtime api
const pendingRewards = await client.call.nominationPoolsApi.pendingRewards(<address>)
console.log('Pending rewards:', pendingRewards);

// Unsubcribe to storage changes & disconnect from the network
// await unsub();
// await client.disconnect();

Smoldot

Preparing a chainSpec.json file for the network that you want to connect to, you can find the chain spec for well-known chains by installing @substrate/connect-known-chains package.

npm i @substrate/connect-known-chains # or via yarn, pnpm

Next, initialize SmoldotProvider and DedotClient instances to connect to network

import { DedotClient, SmoldotProvider } from 'dedot';
import type { PolkadotApi } from '@dedot/chaintypes';
import { start } from 'dedot/smoldot';

// import `polkadot` chain spec to connect to Polkadot
import { polkadot } from '@substrate/connect-known-chains'

// Start smoldot instance & initialize a chain
const smoldot = start();
const chain = await smoldot.addChain({ chainSpec: polkadot });

// Initialize providers & clients
const provider = new SmoldotProvider(chain);
const client = await DedotClient.new<PolkadotApi>(provider);

// Call rpc `state_getMetadata` to fetch raw scale-encoded metadata and decode it.
const metadata = await client.rpc.state_getMetadata();
console.log('Metadata:', metadata);

// Query on-chain storage
const balance = await client.query.system.account(<address>);
console.log('Balance:', balance);


// Subscribe to on-chain storage changes
const unsub = await client.query.system.number((blockNumber) => {
  console.log(`Current block number: ${blockNumber}`);
});

// Get pallet constants
const ss58Prefix = client.consts.system.ss58Prefix;
console.log('Polkadot ss58Prefix:', ss58Prefix);

// Call runtime api
const pendingRewards = await client.call.nominationPoolsApi.pendingRewards(<address>)
console.log('Pending rewards:', pendingRewards);

// await unsub();
// await client.disconnect();

Smoldot (via WebWorker)

Preparing a chainSpec.json file for the network that you want to connect to, you can find the chain spec for well-known chains by installing @substrate/connect-known-chains package.

npm i @substrate/connect-known-chains # or via yarn, pnpm

Start a smoldot client within a WebWorker, then initialize SmoldotProvider & DedotClient to connect to the network

import { DedotClient, SmoldotProvider } from 'dedot';
import { startWithWorker } from 'dedot/smoldot/with-worker';

// Import & initialize the smoldot worker
import SmoldotWorker from 'dedot/smoldot/worker?worker';

// Or initialize it the Worker constructor
// const SmoldotWorker = new Worker(
//   new URL('dedot/smoldot/worker', import.meta.url),
//   { type: 'module' }
// )

// Start smoldot instance within a WebWorker
const smoldot = startWithWorker(new SmoldotWorker());

// Dynamically import Polkadot chain spec
const { chainSpec } = await import('@substrate/connect-known-chains/polkadot');

// Initialize a chain
const chain = smoldot.addChain({ chainSpec });

// Initialize provider & client
const provider = new SmoldotProvider(chain);
const client = await DedotClient.new<PolkadotApi>(provider);

// Call rpc `state_getMetadata` to fetch raw scale-encoded metadata and decode it.
const metadata = await client.rpc.state_getMetadata();
console.log('Metadata:', metadata);

// Query on-chain storage
const balance = await client.query.system.account(<address>);
console.log('Balance:', balance);


// Subscribe to on-chain storage changes
const unsub = await client.query.system.number((blockNumber) => {
  console.log(`Current block number: ${blockNumber}`);
});

// Get pallet constants
const ss58Prefix = client.consts.system.ss58Prefix;
console.log('Polkadot ss58Prefix:', ss58Prefix);

// Call runtime api
const pendingRewards = await client.call.nominationPoolsApi.pendingRewards(<address>)
console.log('Pending rewards:', pendingRewards);

// await unsub();
// await client.disconnect();

Note, for instruction on how to connect to a parachain, check out this example on Dedot repository.

Pick ChainApi interface for the network you're working with

We recommend specifying the ChainApi interface (e.g: PolkadotApi in the example above) of the chain that you want to interact with. This enable Types & APIs suggestion/autocompletion for that particular chain (via IntelliSense). If you don't specify a ChainApi interface, the default SubstrateApi interface will be used.

import { DedotClient, WsProvider } from 'dedot';
import type { PolkadotApi, KusamaApi, MoonbeamApi, AstarApi } from '@dedot/chaintypes';

const polkadotClient = await DedotClient.new<PolkadotApi>(new WsProvider('wss://rpc.polkadot.io'));
const kusamaClient = await DedotClient.new<KusamaApi>(new WsProvider('wss://kusama-rpc.polkadot.io'));
const moonbeamClient = await DedotClient.new<MoonbeamApi>(new WsProvider('wss://wss.api.moonbeam.network'));
const astarClient = await DedotClient.new<AstarApi>(new WsProvider('wss://rpc.astar.network'));
const genericClient = await DedotClient.new(new WsProvider('ws://localhost:9944'));

If you don't find the ChainApi for the network that you're working with in the list, you generate the ChainApi (Types & APIs) for it using dedot cli.

# Generate ChainApi interface for Polkadot network via rpc endpoint: wss://rpc.polkadot.io
npx dedot chaintypes -w wss://rpc.polkadot.io

Or open a pull request to add your favorite Substrate-based network to the @dedot/chaintypes repo.

Caching metadata

In the bootstrapping/intialization process, clients have to download metadata from the network to prepare for on-chain interactions. Downloading a big metadata blob can take a large amount of time, depending on the JSON-RPC server that dapps are connecting to, it might potentially take longer if the connection is via a light client. For example, downloading Polkadot metadata (~500 kB) can take up to 500ms or ~1s or even longer depends on the network conditions.

Clients have an option to cache the downloaded metadata and using it again next time the dapp is loaded without having to download again. By default, Dedot save the cached metadata to localStorage in browser environment.

Enable caching metadata when initialize Dedot's clients:

import { DedotClient, WsProvider } from 'dedot';
import type { PolkadotApi } from '@dedot/chaintypes';

// Initialize providers & clients
const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await DedotClient.new<PolkadotApi>({ provider, cacheMetadata: true });

Add a custom caching storage?

You can also add a custom cache storage for different environments:

import { DedotClient, WsProvider } from 'dedot';
import type { PolkadotApi } from '@dedot/chaintypes';
import type { IStorage } from '@dedot/storage';

// Implement CustomStorage
class CustomStorage implements IStorage {
   // implementation details
}

// Initialize providers & clients
const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await DedotClient.new<PolkadotApi>({ 
   provider, 
   cacheMetadata: true,
   cacheStorage: new CustomStorage()
});

Dedot supports CommonJS

Dedot supports CommonJS, so you can use require to import primitives & APIs.

const { DedotClient, WsProvider } = require('dedot');

const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await DedotClient.new(provider);

Using LegacyClient to connect via legacy JSON-RPC APIs

If the JSON-RPC server doesn't support new JSON-RPC APIs yet, you can connect to the network using the LegacyClient which build on top of the legacy JSON-RPC APIs.

import { LegacyClient, WsProvider } from 'dedot';

const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await LegacyClient.new(provider);

When to use DedotClient or LegacyClient?

The new JSON-RPC APIs are not well implemented/unstable for RPC Nodes using Polkadot-SDK version < 1.11.0, so one should connect to the network using LegacyClient in such cases. For nodes using Polkadot-SDK version >= 1.11.0, it's recommended to use DedotClient to connect to the network.

You can easily check the current node's implementation version by calling RPC system_version

const version = await client.rpc.system_version();

It's recommended to use DedotClient for better performance when you connect to the network using smoldot light client via SmoldotProvider.