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.
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.
The steps below assume:
The account performing the actions owns some amount of an ERC20 token on Ethereum.
The account is funded with some ether to cover gas fees.
The MetaMask/NiftyWallet must be unlocked and rights to access the account must be granted for Etherscan.
For demonstration purposes we transfer Sai 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 (
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.
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
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
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
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
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.
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.
The token contract deployed by the mutli-token mediator supports the ERC677 standard, so instead of calling
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.
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.
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.