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:
- add network info to
status-im.constants - add chain id and name to
status-im.utils.ethereum.core - add native currency info to
status-im.utils.ethereum.tokens - add native currency icon to
resources/images/tokens/NETWORK/0-native.png - 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 currencysymbol- internal symbol key, alwaysETHfor native currenciessymbol-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.xDAIrepresents 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.
), here: