Setup Guide
Hello! 👋 This document will guide you through the process of setting up your xERC20 token with Connext.
Let’s assume the following information about your token before we begin:
- 1.Your token is already deployed to a “home” chain. The implementation here doesn’t matter.
- 2.If your token is deployed to other chains, it has a owner-controlled mint/burn interface or is upgradeable.
💡 The below sections specifically focus on testnet deployment. See Mainnet Deployment for mainnet-specific information.
The first thing you will need to do is deploy a representation of your token to each chain that you want to support with the following properties:
- MUST support a standard mint/burn interface.
- MUST give Connext’s contracts the rights to mint/burn the token.
- SHOULD be an upgradeable implementation so you can mi}grate to the full xERC20 standard in the future (which supports fungibility with canonical bridges).
After deployment, your token representations need to be allowlisted in Connext before the protocol can know to mint/burn them across chains. This process involves submitting two PRs:
- 1.
- For each chain in the mappings that your token is deployed to, add an object that looks like the following, keyed by your token address. Note that the
mainnetEquivalentfield refers to your asset’s address on Ethereum L1 - this is used to retrieve oracle pricing data in the cases where it is relevant. If your token is not deployed to Ethereum L1, feel free to leave this field blank.
"0xc234A67a4F840E61adE794be47de455361b52413": {"name": "Dai Stablecoin","symbol": "DAI","mainnetEquivalent": "0x6B175474E89094C44Da98b954EedeAC495271d0F","decimals": 18}, - 2.
- Each representation is indexed by domain (a Connext-specific identifier per chain that exists for forward compatibility with non-evm chains). You can find a list of domains here.
{name: "WMATIC",canonical: {domain: "9991",address: "0x9c3c9283d3e44854697cd22d3faa240cfb032889",decimals: 18,},representations: {"1735356532": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},"1735353714": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},"9991": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},/// ARBITRUM-GOERLI"1734439522": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},/// ZKSYNC-TEST"2053862260": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},/// CONSENSYS-ZKEVM-TEST"1668247156": {local: "0xcAA61BCAe7D37Fe9C33c0D8671448254eef44D63",adopted: "0xcAA61BCAe7D37Fe9C33c0D8671448254eef44D63",},/// POLYGON-ZKEVM-TEST"1887071092": {local: "0x0000000000000000000000000000000000000000",adopted: "0x0000000000000000000000000000000000000000",},},
📌 Please reference the ChainData PR in your PR to our allowlisting scripts to make it easier for the reviewer!
Once this is done, the Connext Labs team will review your PRs to sanity check deployment details. Once your PR is approved, your tokens will be whitelisted and transferrable across chains!
To make it easier to test and track your token transfers, we recommend adding your token to ConnextScan (the Connext network explorer) and the Connext Bridge. You’ll need to submit two more PRs for this:
- 1.
- As an example:
{"id": "tkn","symbol": "TKN","name": "TKN","image": "/logos/assets/tkn.png","is_stablecoin": true,"contracts": [{"contract_address": "0x16F63C5036d3F48A239358656a8f123eCE85789C","chain_id": 5,"decimals": 18,"symbol": "TKN"},{"contract_address": "0x3Db593146464816F10d4eBA4743C76A5A4D08425","chain_id": 420,"decimals": 18,"symbol": "TKN"}],"color": "#000000"}, - 2.
- As an example:
{"id": "tkn","symbol": "TKN","name": "TKN","image": "/logos/assets/tkn.png","is_stablecoin": true,"contracts": [{"contract_address": "0x16F63C5036d3F48A239358656a8f123eCE85789C","chain_id": 5,"decimals": 18,"symbol": "TKN"},{"contract_address": "0x3Db593146464816F10d4eBA4743C76A5A4D08425","chain_id": 420,"decimals": 18,"symbol": "TKN"}],"color": "#000000","group": "other_tokens"},
And that’s it! Once these PRs are merged, you should see your token appear on https://testnet.connextscan.io and https://testnet.bridge.connext.network.
At this point, your token should be transferrable across chains with no added fees or slippage. However, because of how Connext’s model works, these transfers will happen in large batches through Ethereum L1 roughly once every 2-3 hours.
If your usecase requires fast (i.e. <2 minute) transfers across chains, you will need some routers in our network to supply some liquidity to execute transactions immediately on behalf of users.
- 1.For testnet. This is pretty easy to set up:
- Mint or faucet your tokens to your address on each supported chain.
- Navigate to a router’s page on Connextscan - we recommend the Connext Labs router here as other routers may have inconsistent uptime.
- Click
Manage Router - Add liquidity on each chain
Untitled - 2.For mainnet. Please reach out to the Connext team and we can help work through options here with our router partners.
Getting set up on mainnet is largely the same as the testnet process. You’ll need to submit PRs to the following files instead of the testnet ones:
Last modified 2mo ago