@polkadot/api -> dedot

dedot is inspired by @polkadot/api, so both are sharing some common patterns and api styling (eg: api syntax api.<type>.<module>.<section>). Although we have experimented some other different api stylings but to our findings and development experience, we find that the api style of @polkadot/api is very intuiative and easy to use. We decide the use a similar api styling with @polkadot/api, this also helps the migration from @polkadot/api to dedot easier & faster.

While the api style are similar, but there're also some differences you might need to be aware of when switching to use dedot.

Initialize clients

• @polkadot/api

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await ApiPromise.create({ provider });

• dedot

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

const provider = new WsProvider('wss://rpc.polkadot.io');
const client = await DedotClient.new<PolkadotApi>(provider); // or DedotClient.create(...) if you prefer

// OR if you want to put additional api options when initialize the client
const client = await DedotClient.new<PolkadotApi>({ provider, cacheMetadata: true });

1. dedot only supports provider can make subscription request (e.g: via WebSocket or light client).

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

3. WsProvider from dedot and @polkadot/api are different, they cannot be used interchangeable.

Type system

Unlike @polkadot/api where data are wrapped inside a codec types, so we always need to unwrap the data before using it (e.g: via .unwrap(), .toNumber(), .toString(), .toJSON() ...). dedot leverages the native TypeScript type system to represent scale-codec types, so you can use the data directly without extra handling/unwrapping.

More information on how Dedot lerverage Typescript type system to represent scale-codec (Rust) data types can be found here.

Below is a few examples showing the differences between dedot & @polkadot/api when accessing the on-chain data/information.

Example 1:

const runtimeVersion = client.consts.system.version;

// @polkadot/api
const specName: string = runtimeVersion.toJSON().specName; // OR runtimeVersion.specName.toString()

// dedot
const specName: string = runtimeVersion.specName;

Example 2:

const balance = await client.query.system.account(<address>);

// @polkadot/api
const freeBalance: bigint = balance.data.free.toBigInt();

// dedot
const freeBalance: bigint = balance.data.free;

Example 3:

// @polkadot/api
const proposalBondMaximum: bigint | undefined = client.consts.treasury.proposalBondMaximum.unwrapOr(undefined)?.toBigInt();

// dedot
const proposalBondMaximum: bigint | undefined = client.consts.treasury.proposalBondMaximum;