How to transfer tokens

Step by step instructions how to transfer tokens by using features provided by Etherscan and BlockScout

The instructions below use the Etherscan UI and the Blockscout UI to demonstrate the token transfer process.

There is an OMNIBRIDGE UI now available which calls the methods of the multi-token mediators contracts described below.

General Case: ERC20 Token Transfer

The general case describes a "pure" ERC20 token. For tokens compatible with ERC677 and ERC827 token standards the steps may be simplified - see the separate section below.

Ethereum -> xDai Chain

The steps below assume:

  1. The account performing the actions owns some amount of an ERC20 token on Ethereum.

  2. The account is funded with some ether to cover gas fees.

  3. The MetaMask/NiftyWallet must be unlocked and rights to access the account must be granted for Etherscan.

For demonstration purposes we transfer Sai tokens.

Step 1: Approve the mediator contract to transfer tokens

The mediator contract uses transferFrom functionality of the ERC20 token contract to lock the tokens; it must be explicitly approved to perform this operation.

First, connect to the Web3 provider (MetaMask/NiftyWallet). Next, click on Write Contract and go to the approve method. Enter the following:

  • guy (address) field: the mediator contract address on Ethereum (0x88ad09518695c6c3712AC10a214bE5109a655671)

  • wad (uint256): the amount of tokens to transfer in wei

Press the "Write" button to send the transaction.

The MetaMask/NiftyWallet window will appear. Gas price can be adjusted to speed up transaction verification. After the transaction is confirmed in MetaMask/NiftyWallet, it is necessary to wait for verification by the block miners. Depending on the gas price specified and traffic congestion it can take several seconds to several minutes.

Step 2: Initiate the transfer request

Copy the contract address before proceeding.

Next, open the mediator contract (0x88ad09518695c6c3712AC10a214bE5109a655671) in Etherscan.

The mediator contract is a proxy contract; Click contract then click the "Write as Proxy" tab.

Since you are opening a new contract in Etherscan, you will connect to the Web3 provider (MetaMask/NiftyWallet) again. Then, in the relayTokens method enter the token contract address and the amount of tokens to transfer.

Press the "Write" button to send the transaction.

The MetaMask/NiftyWallet will appear and the gas price can be adjusted to speed up the transaction verification. Once the transaction is confirmed in the MetaMask/NiftyWallet, wait for the block miners to verify. Depending on the gas price specified and traffic congestion it could take from several seconds to several minutes.

Once the transaction is included in a block, the Arbitrary Message Bridge validators will wait for 8 additional blocks. Then, they will send confirmations to the xDai chain to invoke the multi-token mediator contract and complete the tokens transfer.

You can monitor the confirmation and AMB request execution with the AMB Live Monitoring tool: https://alm-xdai.herokuapp.com/. Specify the hash (tx id) of the transaction used to call relayTokens in the ALM entry page to check the status of the AMB request initiated by this transaction in real time

The ALM entry page with the transaction id specifed
The example of ALM response in case of successful execution of the AMB request

If the AMB request is executed successfully:

  • If token has not been transferred with AMB before: If this is the first transaction for this particular token using the AMB, a new ERC677 token contract will be deployed to the xDai chain. The token contract will be initialized with the same symbol and decimals as for the original token on Ethereum. The name of the new token will be extended with the letters "on xDai" (e.g. "Dai Stablecoin v1.0 on xDai"). At the end, the requested amount of tokens will be minted and sent to the account that called relayTokens.

  • If token has been previously transferred with AMB: If If the ERC677 token has already been registered by the mediator for the original ERC20 token, deployment of the contract will be skipped but the requested amount of tokens will be minted and sent to the account that called relayTokens.

Once the process is complete and indexed by BlockScout, it is possible to find the token contract on the xDai chain (in the current example, Sai tokens has the symbol "DAI", that's why it is being used to discover the new token contract).

The link available on the token name will lead to the token view in BlockScout:

In token view you can see that the amount of tokens transferred from Ethereum was minted successfully (the sender is the address 0x0000000...000000).

This view also informs the viewer that the token is bridged and provides a link to view the original token.

At this point, the token can be added to MetaMask/NiftyWallet and operations (like transferring tokens, sending to other contracts etc) are available for use.

xDai Chain -> Ethereum

The steps below assume that the account performing the actions is funded with some xDai to cover gas fees.

Also, the MetaMask/NiftyWallet must be unlocked and rights to access the account must be granted for BlockScout.

Make sure that the token contract is verified in BlockScout. Token contracts deployed as part of the multi-token mediator operations are not verified automatically, so if the token does not allow read and write in the block explorer, follow the steps to verify the contract before starting.

Step 1: transferAndCall method to transfer tokens

The token contract deployed by the mutli-token mediator supports the ERC677 standard, so instead of calling approve and relayTokens, a single method transferAndCall can be used to transfer tokens to the mediator contract and notify it regarding this action at the same time.

Go to the "Write Proxy" tab of the token contract in BlockScout:

In the transferAndCall method enter the multi-token mediator contract address on the xDai chain (0xf6A78083ca3e2a662D6dd1703c939c8aCE2e268d), amount of tokens to transfer, and "0x" in the _data field. Press Write to send the transaction.

The MetaMask/NiftyWallet window will appear. Gas price should be 1 GWei, adjust if needed. Once the transaction is confirmed in the MetaMask/NiftyWallet, wait for verification by the xDai chain validators. This is typically completed in a few seconds.

Once the transaction is included in a block, the Arbitrary Message Bridge validators will wait for one more block. After that, they will collect confirmations in the xDai chain and transfer them to Ethereum. The transaction sent by a validator to Ethereum will execute the request to unlock the tokens.

You can monitor this process using the AMB Live Monitoring tool: https://alm-xdai.herokuapp.com/. Specify the hash (tx id) of the transaction used to call transferAndCall in the ALM entry page and it will check the status of the AMB request initiated by this transaction in real time:

The requested amount of tokens - reduced by the fee amount - will be unlocked on Ethereum.

Simplification for ERC677/ERC827 tokens

If the token on Ethereum is ERC677 or ERC827 compatible it is possible to omit the approve method call and only call the transferAndCall method in the token contract.

Below is example with the STAKE token contract:

Click Write Contract and specify the multi-token mediator contract address on Ethereum (0x88ad09518695c6c3712AC10a214bE5109a655671)as the recipient of the tokens, the amount of tokens in wei the "value" field, and 0x in the "data" field. Click Write to execute.

Simplification for token transfers from the xDai side

Do Not Use the transfer method to send tokens to the multi-token mediator on Ethereum. It will lead to loss of tokens.

The token contact deployed on the xDai chain is a customized version of ERC677 standard. It contains the changes that allow calling the transfer method to withdraw tokens from the xDai chain instead of transferAndCall. So, it is enough to specify the multi-token mediator contract address on the xDai chain (0xf6A78083ca3e2a662D6dd1703c939c8aCE2e268d) as the recipient and amount of tokens to initiate request to transfer tokens back to Ethereum.

The method described above works only for tokens deployed by the multi-token mediator in the xDai chain.