Custom Chains

In this tutorial, we will go through the steps of connecting to a custom Chain, that's not listed as part of known Chains.

Prerequisites

The tutorial assumes the user has already started with the basics of useDApp.

See the Getting Started guide if you are a new user.

Motivation

The typical use of useDApp is to connect to a well known chain, such as Ethereum Mainnet or xDai chain.

However if your use case is to connect to a lesser known chain, or a custom one created by your team, this tutorial uncovers the steps required to connect useDApp to any chain.

As a first step, see if your chain is not already listed in the list of known Chains.

Create the custom chain object

The first step is to create a Chain configuration object with all the required information regarding the custom chain.

Example

tutorial-chain.ts

import { Chain } from '@usedapp/core'

export const TutorialChain: Chain = {
  chainId: 99999,
  chainName: 'TutorialChain',
  isTestChain: false,
  isLocalChain: false,
  multicallAddress: '0x0000000000000000000000000000000000000000',
  getExplorerAddressLink: (address: string) => `https://tutorialchain.etherscan.io/address/${address}`,
  getExplorerTransactionLink: (transactionHash: string) => `https://tutorialchain.etherscan.io/tx/${transactionHash}`,
  // Optional parameters:
  rpcUrl: 'https://rpc.tutorialchain.io',
  blockExplorerUrl: 'https://tutorialchain.etherscan.io',
  nativeCurrency: {
    name: 'TutorialCoin',
    symbol: 'TUT',
    decimals: 18,
  }
}
// IMPORTANT: Fill that object with your own data.

Explanation

Field	Meaning
chainId	The ID of the chain. Every chain has a unique chainId
chainName	The name of the chain
isTestChain	Whether the chain is a testnet, such as Kovan or Ropsten
isLocalChain	Whether the chain is a development chain running on localhost
multicallAddress	An address of the Multicall contract on the chain
getExplorerAddressLink	A function to construct a link to a blockchain explorer, based on an ethereum address
getExplorerTransactionLink	A function to construct a link to a blockchain explorer, based on a transaction hash
rpcUrl	(Optional) an RPC url. At least one is required if you want your app to be able to add new networks to Metamask
blockExplorerUrl	(Optional) a block explorer address, optional for adding the network to Metamask
nativeCurrency	(Optional) native currency, optional for adding the network to Metamask (otherwise it will refault to ETH). Please refer to Metamask docs or the example above

multicallAddress

Multicall aggregates results from multiple contract constant function calls.

It is required for useDApp to operate.

If there is no known Multicall contract deployed on your custom chain, it needs to be deployed and address configured as multicallAddress. For deployment, Mars deployment tool can be used.

If the chain is a local development chain, the Multicall contract is automatically deployed for you by useDApp.

Include your custom chain in Config

With the custom chain config created and saved in tutorial-chain.ts file, you can include it in useDApp Config object that was introduced in the Getting Started example.

The new Config object with your custom chain will be passed into the <DAppProvider> component.

  import {
    Mainnet,
    DAppProvider,
    useEtherBalance,
    useEthers,
    Config,
+   DEFAULT_SUPPORTED_CHAINS,
  } from '@usedapp/core'
  import { formatEther } from '@ethersproject/units'

  import App from 'App'
+ import { TutorialChain } from './tutorial-chain'

  const config: Config = {
-     readOnlyChainId: Mainnet.chainId,
+     readOnlyChainId: TutorialChain.chainId,
    readOnlyUrls: {
      [Mainnet.chainId]: 'https://mainnet.infura.io/v3/62687d1a985d4508b2b7a24827551934',
+     [TutorialChain.chainId]: '<url of the custom chain>',
    },
+   networks: [...DEFAULT_SUPPORTED_CHAINS, TutorialChain],
  }

  ReactDOM.render(
    <React.StrictMode>
      <DAppProvider config={config}>
        <App />
      </DAppProvider>
    </React.StrictMode>,
    document.getElementById('root')
  )

You're fully setup - now in the <App> component, you can use the functionality provided by useDApp to access your TutorialChain.

Send a PR to useDApp (optional)

If you want to add your custom chain to the list of known chains, you can send a PR to the useDApp repository. In your PR, please make sure to include the following changes:

• Add file describing your chain to the packages/core/src/model/chain directory. Please name the file <chainName>.ts. For example, if your chain is called TutorialChain, the file name should be tutorial-chain.ts. The file should export one object that implements the Chain interface. The example chain object is provided in the first step of this tutorial.
• Next please make sure to import and reexport the added file from packages/core/src/model/chain/index.ts file.
• Add your chain to the DEFAULT_SUPPORTED_CHAINS array in packages/core/src/constants/chainId.ts file.

When submitting a PR, please make sure to include the short description and motivation of the changes.

This step is optional - Send a PR with your custom chain if you think other users will benefit from it.

Example PR

• ThunderCore chain

Summary

In this tutorial, we went through the steps required for using useDApp with a custom chain that is not included by default.

We created the custom chain object which includes all the required information about the chain.

Next, we included the custom chain in useDApp config and optionally created a PR for useDApp to include the custom chain in the set of default chains.