Bridge rootchain-originated assets

[Stefan-Ethernal]

How I can bridge rootchain-originated assets on the Supernets?

[Stefan-Ethernal]

The following paragraphs explain how bridging from a rootchain to a child chain is done when a token originates from a rootchain (namely its supply is controlled over there: minting and burning). Given example explains how ERC20 tokens are bridged from a rootchain to a child chain, but workflow is similar to any other asset type (ERC721 or ERC1155). The only difference is that bridge deposit-erc721 or bridge deposit-erc1155 commands are used for depositing and bridge withdraw-erc721 or bridge withdraw-erc1155 are used for withdrawals.

Preconditions

1. token pre-exists on the rootchain,
2. sender has enough balance of that token that is about to be bridged,
3. at least single validator on an Edge chain is running in a relayer mode.

Deposit workflow

1. Deposit the tokens on the rootchain. It can be accomplished by running the following command

polygon-edge bridge deposit-erc20 \
	--sender-key <SENDER_PRIVATE_KEY> \
	--amounts <AMOUNT_IN_WEIS> \
	--receivers <RECEIVER_ADDRESS> \
	--root-token <ROOTCHAIN_ERC20_TOKEN> \
	--root-predicate <ROOT_ERC20_PREDICATE_ADDRESS> \
	--json-rpc <ROOTCHAIN_JSON_RPC_URL>

ROOTCHAIN_ERC20_TOKEN=address of an ERC20 token from a rootchain
ROOT_ERC20_PREDICATE_ADDRESS=erc20PredicateAddress from the genesis.json

There is an optional flag, called minter-key and it represents private key of account that has minter role assigned to the given ERC20 token. In case it is provided, before making deposit, token is being minted to the sender-key account, so that it make sure there are enough tokens to bridge.

Output of this command should be similar to this:

[DEPOSIT ERC 20]
Sender                  = 0x1FC1411A3Bd09E63d4A306FD1EB838bA457ddA13
Receivers               = 0xa0a946357221A7bf0195B0AE7dD07E2f58a3e8F6, 0xCEc294745471879704fF36C200df3737eD12633d, 0x67d61bF84a2898D98CBb4398AFddBD9E6469c67D, 0x297D8df540e3fd00148Fe83277501359A135dEA5, 0xaadac13B5eff2124Cf2d095e997F4992E1b44AB3
Amounts                 = 100, 100, 100, 100, 100
Inclusion Block Numbers = 192, 192, 192, 192, 192
Child Token Address     = 0x2f3A59d07f279Fb97feeAa7A7C1A90b6688F6dB0

It is important to mention that Child Token Address represents the address of the child token on the child chain and it is important to remember it because of withdrawal. It is going to be printed out for any token, except the native one (in case we are running a setup where the Edge chain native token is indeed some ERC20 rootchain token).

2. Wait for the bridge transaction to be settled on the child chain. After a couple of sprint blocks (sprint is equal to 5 blocks by default), bridge deposit transaction should be settled on the child chain and balances on the child token address should be updated accordingly.

The following image illustrates the deposit workflow.

Withdrawal workflow

1. Withdraw the tokens from the child chain is accomplished by running the following CLI command:

polygon-edge bridge withdraw-erc20 \
	--sender-key <SENDER_PRIVATE_KEY> \
	--receivers <RECEIVER_ADDRESS> \
	--amounts <AMOUNT_IN_WEIS> \
	--child-predicate 0x0000000000000000000000000000000000001004 \
	--child-token <CHILD_TOKEN_ADDRESS> \
	--json-rpc <CHILD_CHAIN_JSON_RPC_URL> \

Note that the child-predicate flag can be omitted as ChildERC20Predicate is deployed to 0x0000000000000000000000000000000000001004 by default in the genesis time.

The output of withdrawal command is as following:

[WITHDRAW ERC 20]
Sender                  = 0xa0a946357221A7bf0195B0AE7dD07E2f58a3e8F6
Receivers               = 0xa0a946357221A7bf0195B0AE7dD07E2f58a3e8F6
Amounts                 = 100
Exit Event IDs          = 6
Inclusion Block Numbers = 187

The most important parameter here is Exit Event IDs, as it is necessary for the final step, when withdrawal transaction is being finalized on a rootchain.

2. Wait for at least one epoch for checkpoint to be submitted to a rootchain. Checkpoint, among the other, contains withdrawal data. Checkpoints are regularly sent by the validators to a rootchain every 30 minutes and/or epoch-ending block.

3. Send exit transaction. It represents bridge withdrawal transaction finalization and can be accomplished by running the following CLI command

polygon-edge bridge exit \
    --sender-key <SENDER_PRIVATE_KEY> \
    --exit-helper <EXIT_HELPER> \
    --exit-id <EXIT_EVENT_ID> \
    --root-json-rpc <ROOTCHAIN_JSON_RPC_URL> \
    --child-json-rpc <CHILD_CHAIN_JSON_RPC_URL>

EXIT_HELPER=address of ExitHelper contract deployed on a rootchain. It can be found from the exitHelperAddress field in the genesis.json.
EXIT_EVENT_ID=id of exit event. It was the output of the bridge withdraw-erc20 command, namely when the withdrawal was initiated on a child chain.

The following image illustrates the withdrawal workflow.