web3-plugin-polkadot

This is a web3.js plugin for communicating with Polkadot, Kusama, and Substrate nodes.

Project name: web3-plugin-polkadot

Project creation date: 8 Dec 2023

Introduction

As web3.js v4.x supports plugins, this library will utilize that to build a plugin for Polkadot RPC providers. This plugin would allow users to execute calls like web3.substrate.namespace.RPC and similar commands for Polkadot RPCs. And later it would offer the additional functionalities related to accounts & contracts that differ from Ethereum.

Why to build

There are 3 key benefits of this approach:

Development experience and learning curve

Developers who already use web3.js would quickly start working with Polkadot and Substrate with fewer things to read and learn. All they need to do is provide the web3.js library with a link to a Polkadot, Kusama, or a Substrate provider, register the new plugin, and then start working just like they used to. There will be slight differences that they'll have to adjust for. And a good progressive effort would be spent to reduce the differences to the minimum.

Code portability

Code that already exists for Ethereum DApps that uses web3.js, could be relatively-easily adapted to work with Polkadot and Substrate. Users would only have to make a few changes to their current code. For example, the code used to catch exceptions that indicate an unresponsive provider won't need to be changed. This also means developers may use the same code base for both Ethereum-based networks and Substrate, with just a bit of custom handling.

Diversity

It is good to provide the developers with an additional alternative to polkadot{.js}. So, developers can pick the library that they feel more comfortable working with.

Methodology

This plugin uses web3.js processing and logic; But, with the types from @polkadot/types in addition to types generated by @polkadot/typegen. Using those types keeps things smooth when communicating with RPC endpoints. In addition to keeping the available documentation available for those types mostly useful, instead of inventing new types. On the other hand, having the execution inside web3.js allows for having the benefits listed above in Why to build section.

TypeScript Intellisense

Trying to provide the developer with the best experience. The TypeScript Intellisense works in editors like vscode. The RPCs are accessible with the convention: web3.polka.<network>.<namespace>.<method>. And the supported network nodes are currently: polkadot, kusama and substrate.

For example, here is how the namespaces that categorize the RPC endpoints are listed inside polkadot network namespace:

And here is how the RPC methods that is inside a specific namespace, would be listed:

Picking or hovering over a specific method like getBlock would show its parameters and return type:

Showing only the supported methods

Some of the RPC methods are not supported on all networks. The plugin takes this into consideration when showing the list of methods inside each namespace.

For example, here is how web3.polka.substrate.beefy would like like:

And, in contrast, here is how web3.polka.polkadot.beefy would look like:

Sample plugin usage by the users

To check things fast, clone this repo, and go to test folder, update or keep the code, and then run yarn && yarn test in the terminal.

However, here is how you my use the plugin package inside your project:

At your typescript project run: yarn add web3 @conx3/web3-plugin-polkadot @polkadot/typegen

After that, use the following code to check the plugin:

import { Web3 } from 'web3';
import { PolkadotPlugin } from '@conx3/web3-plugin-polkadot';

// the following shows how to use the plugin
// you can call any rpc method using the convention: web3.polka.<network>.<namespace>.<method>
async function main() {
  const web3 = new Web3('wss://rpc.polkadot.io');
  web3.registerPlugin(new PolkadotPlugin());
  // to get the last block from Polkadot network
  const polkadotBlockData = await web3.polka.polkadot.chain.getBlock();

  // call web3 methods as usual. Like updating the provider to Kusama network:
  web3.provider = 'wss://kusama-rpc.polkadot.io';
  // to get the last block from Kusama network
  const kusamaBlockData = await web3.polka.kusama.chain.getBlock();

  // Updating the provider to a local substrate node for example:
  web3.provider = 'ws://127.0.0.1:9944/';
  // to get the last block from a Substrate network
  const substrateBlockData = await web3.polka.substrate.chain.getBlock();

  console.log('polkadot block header stateRoot:', polkadotBlockData.block.header.stateRoot);
  console.log('kusama block header stateRoot:', kusamaBlockData.block.header.stateRoot);
  console.log('substrate block header stateRoot:', substrateBlockData.block.header.stateRoot);

  // stateRoot is something like: 0xa18402bc3a2249d6af8e2ad6241e5b1b60360abd1b4e2c7c733c8c980331d278

  // if you want to log the full response
  console.log(JSON.stringify(substrateBlockData, null, 2));
  // {
  //   "jsonrpc": "2.0",
  //   "result": {
  //     "block": {
  //       "header": {
  //         "parentHash": "0x205d46cdcd9db4f795067718ef73292ab065aa08cec1ad6788b2c24028b160ea",
  //         "number": "0x6cc7",
  //         "stateRoot": "0xa18402bc3a2249d6af8e2ad6241e5b1b60360abd1b4e2c7c733c8c980331d278",
  //         "extrinsicsRoot": "0x345fc26b56a2a682a52ab5860b18df0a1698b0a6ac0cadd9bcba713d1a6f54d0",
  //         "digest": {
  //           "logs": [
  //             "0x0661757261203b5ee81000000000",
  //             "0x05617572610101187f7e10b05cd255b4ab0d3894b2c3c15bc4294a4124a7188981e3833af3440ae4322bec54ff65cb561e9fdfb4d02a5496fc64ea5991fcd4d42b43c48cd2588d"
  //           ]
  //         }
  //       },
  //       "extrinsics": [
  //         "0x280401000bd08620468c01"
  //       ]
  //     },
  //     "justifications": null
  //   },
  //   "id": 43
  // }
}
main();

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

When contributing, please make sure to update tests as appropriate.

Hints:

• Types were generated by following the steps at: https://polkadot.js.org/docs/api/examples/promise/typegen/.
• And a local substrate node can be run following the steps at: https://docs.substrate.io/quick-start/start-a-node/

License

MIT