rmrk-team/substra-hooks

Substrate Polkadot.js React Hooks

Deprecated

SubstraHooks Core

SubstraHooks is a collection of useful react hooks that work with polkadot.js on Substrate blockchains

inspired by useDApp

Usage

Add it to your project:

yarn add @substra-hooks/core @polkadot/api @polkadot/extension-dapp

Use it in your React app:

import React from 'react'
import { SubstraHooksProvider } from '@substra-hooks/core';

export enum NETWORKS {
    kusama = 'kusama',
    statemine = 'statemine',
}

const apiProviderConfig = {
    [NETWORKS.kusama]: {
        id: NETWORKS.kusama,
        wsProviderUrl: 'wss://kusama-rpc.polkadot.io',
    },
    [NETWORKS.statemine]: {
        id: NETWORKS.statemine,
        wsProviderUrl: 'wss://statemine-rpc.polkadot.io',
    },
}

// Wrap everything in <SubstraHooksProvider />
export default () => (
    <SubstraHooksProvider apiProviderConfig={apiProviderConfig} defaultApiProviderId={NETWORKS.kusama}>
        <App />
    </SubstraHooksProvider>
)

// App.tsx
import React from 'react'
import { useAccountBalance, useSystemProperties, useAssetBalance } from '@substra-hooks/core'

const App = () => {
    const { accounts, w3enable, w3Enabled } = usePolkadotExtension();
    const balancePayload = useAccountBalance(accounts?.[0]?.address || '');
    const assetPayload = useAssetBalance(accounts?.[0]?.address || '', 8, NETWORKS.statemine);
    const systemProperties = useSystemProperties()

    console.log('systemProperties', systemProperties)

    useEffect(() => {
        if (!w3Enabled) {
            w3enable();
        }
    }, [w3Enabled])

    console.log('accounts', accounts)
    console.log('balanceFormatted', accounts?.[5]?.address || '', balanceFormatted);
    console.log('assetPayload', assetPayload);

    return (
        <>
          <div>Balance: {balancePayload?.balance.formatted}</div>
          <div>Locked Balance: {balancePayload && balancePayload?.locked?.formatted}</div>
          <div>Reserved Balance: {balancePayload?.reserved?.formatted}</div>
          <div>Total Balance: {balancePayload?.total?.formatted}</div>
        </>
    )
}

If your app is using SSR (i.e. next.js) then you need to dynamically import Provider with no SSR, create your own local Provider first

import { ReactNode } from 'react';
import { SubstraHooksProvider } from '@substra-hooks/core';

interface ISubstraHooksProviderProps {
    apiProviderConfig: ApiProviderConfig;
    children: ReactNode;
}


const SubstraHooksProviderSSR = ({ apiProviderConfig, children }: ISubstraHooksProviderProps) => {
    return (
        <SubstraHooksProvider
            apiProviderConfig={apiProviderConfig}
            defaultApiProviderId={NETWORKS.kusama}>
            {children}
        </SubstraHooksProvider>
    );
};

export default SubstraHooksProviderSSR;

const SubstraHooksProviderSSR = dynamic(() => import('./substra-hook-provider'), {
  ssr: false,
});

const MyApp = ({ Component, pageProps }: AppProps) => {

  return (
      <SubstraHooksProviderSSR wsProviderUrl="wss://kusama-rpc.polkadot.io">
          <Component {...pageProps} />
      </SubstraHooksProviderSSR>
  );
};

export default MyApp;

API

Providers

SubstraHooksProvider

Main Provider that includes ExtensionProvider

ExtensionProvider

Provider that mainly deals with polkadot browser extension

Hooks

useApiProvider

Returns polkadot.js ApiPromise. Returns default ApiPromise as defined by defaultApiProviderId on SubstraHooksProvider, additional argument can be passed to return different ApiPromise from default one

const polkadotStatemineApi = useApiProvider('statemine');

useSystemProperties

Returns parsed results of polkadotApi.rpc.system.properties API in following format.

{
    tokenDecimals: number;
    tokenSymbol: string;
    ss58Format: number;
}

Returns system properties fetched from the chain connected by your default api provider, additional argument can be passed to return different system properties from different node

const systemProperties = useSystemProperties()

useAccountBalance

Returns token balance of given address from the default node.

const { balanceFormatted, balanceRaw } = useAccountBalance(userEncodedAddress);

useAssetBalance

Returns balance of specified asset id for given address from the default node.

const { balanceFormatted, balanceRaw } = useAssetBalance(
    userEncodedAddress,
    ASSET_ID,
    'statemine',
);

useEncodedAddress

Returns substrate address in a format of ss58Format of your default chain node

const ownerAddressEncoded = useEncodedAddress(owner);

usePolkadotExtension

import {useEffect} from "react";
...
const { w3Enabled, w3enable, accounts } = usePolkadotExtension();

const initialise = () => {
    if (!w3Enabled) {
        w3enable();
    }
};

useEffect(() => {
    if (!w3Enabled) {
        initialise();
    }
}, [w3Enabled])

console.log(accounts);

substra-hooks's Issues

Add build status to README

Add a hook to retrieve timestamp by block number

if one RPC config fails to fetch then none are saved in the context api

If you pass multiple RPC configs and one of them fails then none are saved as apiProvider context

Add polkadot identity hook

We have some code snippets for this, need to cleanup and add here

Add contribution guide

Look at https://github.com/EthWorks/useDApp/tree/master/packages/core#contributing for inspiration

expand extension hooks

For the extension hook, it would be great if extension hook would return methods to set and get your active account. This would save selected account object to reducer/context and then be able to return selected account.

Additionally maybe it's good idea to be able to pass callback or your own storage provider for persistent storage so address stays on refresh (maybe use zustand for this)

Add eslint and linting script

And make sure eslint and jest unit test yarn scripts are run during github actions

Example here https://github.com/EthWorks/useDApp/blob/master/.github/workflows/CI.yml

Remove api-augment

This is fine for Kusama / Polkadot chains but custom chains implement own type-gen and augmentation which makes substra-hooks incompatible.

Proposal to remove this line from bundled core:

substra-hooks/packages/core/src/index.ts

Line 1 in affafc3

import "@polkadot/api-augment";

So it is up to the upstream clients to augment types.