Dev Tutorial - How To Add New Network


#1

This doc lists and explains all the steps needed to add a new network to Status (e.g. side chain or a test network).

Inclusion of POA Network and xDAI Chain was the feature that led to this document, so I’ll use them as an example throughout this doc.

Overview:

  1. add network info to status-im.constants
  2. add chain id and name to status-im.utils.ethereum.core
  3. add native currency info to status-im.utils.ethereum.tokens
  4. add native currency icon to resources/images/tokens/NETWORK/0-native.png
  5. add a migration to add new networks to existing accounts upon upgrade

Detailed walkthrough:

1. add network info to status-im.constants

Add a new entry to the map with all the networks. The key should be string representation of internal network id, e.g. “xdai_rpc”. The value should be network configuration object, e.g.:

{:id     "xdai_rpc",
 :name   "xDai Chain",
 :config {:NetworkId      (ethereum/chain-keyword->chain-id :xdai)
          :DataDir        "/ethereum/xdai_rpc"
          :UpstreamConfig {:Enabled true
                           :URL     "https://dai.poa.network"}}}

By convention, we’re using _rpc suffix for all networks that access their blockchain data via upstream RPC. For full or LES access, we should omit this suffix, e.g just "mainnet" as opposed to "mainnet_rpc". This only applies to network identifier - chain identifier should not contain any suffixes.

2. add chain id and name to status-im.utils.ethereum.core

There is a mapping between internal (as keywords) and numerical chain ids in this namespace. Add the new network info as per this example:

(def chains
  {:mainnet {:id 1 :name "Mainnet"}
   :testnet {:id 3 :name "Ropsten"}
   :rinkeby {:id 4 :name "Rinkeby"}
   :xdai    {:id 100 :name "xDai"}
   :poa     {:id 99 :name "POA"}})

Internal keyword id is arbitrary and you can choose whatever makes sense. On the other hand, numerical id should be the same as the one actually used by the chain in question. You can check the value by calling web3.version.getNetwork() - if incorrect id has been configured, there will be an error during Ethereum node initialization (right after login).

3. add native currency info to status-im.utils.ethereum.tokens

If native currency has a name and symbol other than Ether and ETH, then this needs to be set up. E.g. xDAI Chain native currency is called xDAI, so we set that up by adding a new entry to the native currency map, where chain id is the key and the following is value:

{:name            "xDAI"
 :symbol          :ETH
 :symbol-display  :xDAI
 :symbol-exchange :DAI
 :decimals        18}
  • name - full display name of the given currency
  • symbol - internal symbol key, always ETH for native currencies
  • symbol-display - the value of symbol as it is displayed in Wallet screens, chat messages, etc.
  • symbol-exchange - the symbol used as the ticker on exchange services to represent the given currency, e.g. xDAI represents the native currency of xDAI Chain, however it is listed as DAI on cryptocompare.

4. add native currency icon to resources/images/tokens/NETWORK/0-native.png

If native currency icon is different that the default Ether icon, then the resource file needs to be added to the project. Since there is only one native currency per chain, the file name will always be 0-native.png - it only needs to be located in the correct directory for that chain.

5. add a migration to add new networks to existing accounts upon upgrade

Correction - we’ll change the model in such a way to remove the need for this migration. See #6491

So, that’s it. If you have any questions or remarks, please comment. Hopefully, we’ll simplify this process soon enough.


#2

Great tutorial, rough around the edges but this makes it easy to see what needs to improve. Kudos @goranjovic for sharing this knowledge openly in this format!


#3

Sounds like it would be a great fit for our documentation website?
Or is there something to discuss about that?


#4

@julien I’d like all docs like this to get a chance to go through a discussion before they get to the much more static doc site. It makes sense to do that on discuss.

Btw, where on https://docs.status.im/ could we keep docs like this one? Not sure I see the right category.


#5

Cc @cryptowanderer or @rachel for category handling, I was wondering myself for another piece of knowledge to drop :slight_smile:


#6

Hi @goranjovic - PLEASE can we get this in the docs? :heart:

You can put it in the build_status folder and I will make a new section in the sidebar called Adapt Status and we can put procedural stuff and organisational knowledge like this into there.


#7

Docs added, along with @yenda’s docs for add default chats (which he never got to :stuck_out_tongue_winking_eye:), here: https://github.com/status-im/status.im/commit/9fea1c50ff08053b012b419a586087687904b7c5

Ping @rachel for comment on this new doc as it is something which I think we could push harder (plus your general feedback/edits would be much appreciated :heart:) https://status.im/developer_tools/enable_chat.html


#8

Awesome stuff, cheers @cryptowanderer

From my end, I’ll try to simplify this process. How do we update the docs after, just push to that repo?


#9

Just read: https://github.com/status-im/status.im/blob/develop/README.md

and make sure you commit to develop not master.