Bridging ERC-20 from Ethereum to Polygon PoS

The Polygon PoS mainnet is an L2 commit chain to the Ethereum mainnet.

Bridging your existing Ethereum smart contract to the Polygon PoS commit chain allows network users to move their assets based on your contract between an Ethereum network and a Polygon PoS commit chain.

In this tutorial, you will:

• Deploy an ERC-20 smart contract on the Ethereum Goerli testnet.
• Deploy a compatible smart contract on the Polygon PoS Mumbai testnet.
• Map the Ethereum smart contract to the Polygon PoS smart contract.

Prerequisites

• Chainstack account to deploy an Ethereum node and a Polygon PoS node.
• Truffle Suite (opens new window) to create and deploy contracts.
• OpenZeppelin Contracts (opens new window) to use the audited ERC-20 libraries (opens new window) to create your ERC-20 contract.

Overview

To get from zero to a deployed ERC-20 contract on the Ethereum Goerli testnet and bridge it to the Polygon PoS Mumbai testnet, do the following:

1. With Chainstack, create a public chain project.
2. With Chainstack, join the Ethereum Goerli testnet.
3. In the same project, join the Polygon PoS Mumbai testnet.
4. With Chainstack, access your Ethereum node and Polygon PoS node endpoints.
5. With OpenZeppelin, create an ERC-20 contract.
6. With Truffle, compile and deploy the contract through your Ethereum node.
7. With Truffle, compile and deploy a Polygon PoS contract through your Polygon PoS node.
8. Submit a mapping request to bridge the deployed Ethereum contract to the deployed Polygon PoS contract.

Step-by-step

Create a public chain project

See Create a project.

Join the Ethereum Goerli testnet and the Polygon PoS Mumbai testnet

See Join a public network.

Get your Ethereum node and Polygon PoS node access and credentials

See View node access and credentials.

Install OpenZeppelin Contracts

See OpenZeppelin Contracts (opens new window).

Install Truffle Suite

See Truffle Suite: Installation (opens new window).

Create the root Ethereum ERC-20 contract

1. On your machine, in the contract directory, initialize Truffle:

truffle init

This will generate the Truffle boilerplate structure:

.
├── contracts
│   └── Migrations.sol
├── migrations
│   └── 1_initial_migration.js
├── test
└── truffle-config.js

2. Go to the contracts directory. In the directory, create your ERC-20 contract: myL2token.sol.

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract myL2token is ERC20 {
    constructor(uint256 initialSupply) ERC20("myL2token", "ML2T") {
        _mint(msg.sender, initialSupply);
    }
}

This is a standard OpenZeppelin ERC-20 preset contract (opens new window).

3. Create 2_deploy_contracts.js in the migrations directory.

var myL2token = artifacts.require("./myL2token.sol");

module.exports = function(deployer) {
  deployer.deploy(myL2token, 100000000000000000000);
};

This will create the instructions for Truffle to deploy the contract with the supply of 100 18-decimal ML2T tokens.

Compile and deploy the root Ethereum ERC-20 contract

1. Install HDWalletProvider.

HDWalletProvider (opens new window) is Truffle's separate npm package used to sign transactions.

Run:

npm install @truffle/hdwallet-provider

2. Edit truffle-config.js to add:

• HDWalletProvider
• Your Ethereum node access and credentials
• Your Ethereum account that you will use to deploy the contract

const HDWalletProvider = require("@truffle/hdwallet-provider");
const private_key = 'PRIVATE_KEY';

module.exports = {
 networks: {
    goerli: {
        provider: () => new HDWalletProvider(private_key, "ENDPOINT"),
        network_id: 5
    }
   },

 compilers: {
    solc: {
    version: "0.8.1",
    }
  }
};

where

• goerli — any network name that you will pass to the truffle migrate --network command.
• HDWalletProvider — Truffle's custom provider to sign transactions.
• PRIVATE_KEY — the private key of your Ethereum account that will deploy the contract.
• ENDPOINT — your Ethereum node endpoint. The format is https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d. See also View node access and credentials and Tools.
• network_id — the network ID of the Ethereum Goerli testnet: 5.
• solc — the Solidity compiler version that Truffle must use.

3. Run:

truffle migrate --network goerli

This will engage 2_deploy_contracts.js and deploy the contract to the Ethereum Goerli testnet as specified in truffle-config.js.

Verify your root Ethereum ERC-20 contract on Etherscan

Once your contract is deployed, you can view it online at Etherscan (opens new window).

Before you submit a mapping request to bridge your root Ethereum ERC-20 contract to the Polygon PoS commit chain, you must verify the contract on Etherscan.

1. Flatten your contract code

Since your ERC-20 contract uses imported OpenZeppelin libraries, you must put all the imports into one .sol file to make Etherscan be able to verify it.

Install Truffle Flattener (opens new window).

In the contracts directory, run:

npx truffle-flattener myL2token.sol > flatmyL2token.sol

2. Clean up the licensing information.

The flattened contract will have the same licensing note imported from each of the files. Multiple licensing notes in one file break the Etherscan verification, so you have to leave one licensing note for the entirety of the flattened contract.

The easiest way to clean up is to search for the SPDX mentions in the file and remove all of them except for the very first one.

3. Verify the deployed contract on Etherscan

At this point you have your flattened and cleaned up contract ready for the Etherscan verification.

1. Go to Etherscan (opens new window).
2. Find your deployed contract. The address of your contract should have been printed by Truffle at the end of the deployment in the contract address field.
3. On the contract page on Etherscan, click Contract > Verify and Publish.
4. In Compiler Type, select Solidity (Single file).
5. In Compiler Version, select v0.8.1. This is the version this tutorial used to compile the contract.
6. In Open Source License Type, select MIT License (MIT).
7. Click Continue.
8. Keep the Optimization option set to No as Truffle does not use optimization by default.
9. Paste the entirety of your flattened .sol contract in the Enter the Solidity Contract Code below field.
10. Click Verify and Publish.

Etherscan will take a few seconds to complie your contract, verify, and publish it.

Create the child Polygon PoS ERC-20 contract

1. Go to the contracts directory. In the directory, put the default child ERC-20 contract (opens new window) provided by Polygon.

2. Create 2_deploy_contracts.js in the migrations directory.

var ChildERC20 = artifacts.require("./ChildERC20.sol");

module.exports = function(deployer) {
  deployer.deploy(ChildERC20, 'myL2tokenChild', 'ML2T', 18, '0x2e5e27d50EFa501D90Ad3638ff8441a0C0C0d75e');
};

where

• myL2tokenChild — the name of your ERC-20 token.
• ML2T — the symbol of your ERC-20 token.
• 18 — the default decimals number as used by the OpenZeppelin ERC-20 preset contract (opens new window).
• 0x2e5e27d50EFa501D90Ad3638ff8441a0C0C0d75e — the ChildChainManager (opens new window) address on the Polygon PoS Mumbai testnet. For the ChildChainManager contract addresses, see the addresses provided by Polygon:
  • Testnet addresses (opens new window)
  • Mainnet addresses (opens new window)

Compile and deploy the child Polygon PoS ERC-20 contract

Clean up the environment by moving myL2token.sol and flatmyL2token.sol to a backup directory so that Truffle does not pick them up for deployment.

1. Edit truffle-config.js to change to:

• Your Polygon PoS node access and credentials
• Your Polygon PoS account that you will use to deploy the contract
• The Solidity compiler version used by the default child ERC-20 contract template (opens new window) provided by Polygon

const HDWalletProvider = require("@truffle/hdwallet-provider");
const private_key = 'PRIVATE_KEY';

module.exports = {
 networks: {
    mumbai: {
        provider: () => new HDWalletProvider(private_key, "ENDPOINT"),
        network_id: 80001
    }
   },

 compilers: {
    solc: {
    version: "0.6.6",
    }
  }
};

where

• mumbai — any network name that you will pass to the truffle migrate --network command.
• HDWalletProvider — Truffle's custom provider to sign transactions.
• PRIVATE_KEY — the private key of your Polygon PoS account that will deploy the contract.
• ENDPOINT — your Polygon PoS node endpoint. The format is https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d. See also View node access and credentials and Tools.
• network_id — the network ID of the Polygon PoS network: testnet is 80001, mainnet is 137,
• solc — the Solidity compiler version that Truffle must use. OpenZeppelin contracts have a higher version Solidity compiler requirement than the default Truffle installation, hence you must provide a specific compiler version.

2. Run:

truffle migrate --network mumbai

Verify your child Polygon PoS ERC-20 contract on the Polygon PoS explorer

Once your contract is deployed, you can view it online at the Polygon PoS Mumbai explorer (opens new window).

1. Go to the Polygon PoS Mumbai explorer (opens new window).
2. Find your deployed contract. The address of your contract should have been printed by Truffle at the end of the deployment in the contract address field.
3. On the contract page on the explorer, click Contract > Verify and Publish.
4. In Compiler Type, select Solidity (Single file).
5. In Compiler Version, select v0.6.6. This is the compiler version the default child contract uses as provided by Polygon.
6. In Open Source License Type, select MIT License (MIT).
7. Click Continue.
8. Keep the Optimization option set to No as Truffle does not use optimization by default.
9. Paste the entirety of your ChildERC20.sol contract in the Enter the Solidity Contract Code below field.
10. Click Verify and Publish.

ABI data

If on the verification attempt you get a message that the explorer cannot get the ABI data for the contract verification, do the following:

1. Go to the online ABI encoding service (opens new window).
2. In the service, provide the ChildERC20.json (opens new window) ABI data as ([abi]) .
3. Click Parse.
4. Put your constructor data by adding arguments with the data type:
   • name_: myL2tokenChild
   • symbol_: ML2T
   • decimals_: 18
   • childChainManager: 0x2e5e27d50EFa501D90Ad3638ff8441a0C0C0d75e
5. Copy the encoded data.
6. Paste the encoded data in the ABI constructor arguments field on the explorer.

The explorer will take a few seconds to compile your contract, verify, and publish it.

Map your Ethereum ERC-20 contract to the Polygon PoS contract

1. Go go the token mapper (opens new window).
2. Select ERC20 and Goerli Testnet - Mumbai Testnet.
3. Provide the address of your contract on the Ethereum Goerli testnet and on the Polygon PoS Mumbai testnet.
4. Provide an email address to be notified of when the mapping is done.
5. Click Submit.

Bridge the mapped token

When your token is mapped, bridge your token from Ethereum to Polygon and back:

• Polygon Mumbai testnet bridge (opens new window)
• Polygon mainnet bridge (opens new window)

Conclusion

This tutorial guided you through the basics of bridging an ERC-20 contract from the Ethereum Goerli testnet to the Polygon Mumbai testnet.

The same instructions will work for the Ethereum mainnet and the Polygon mainnet.

Polygon PoS has public L2 contract templates and a network of deployed contracts monitored by Heimdall nodes, all of which makes it easy to bridge assets from the Ethereum mainnet to the Polygon PoS commit chain.

See also

• Operations: Polygon PoS