Skip to main content

ETH Deposit and Withdraw Guide

Check out the latest Matic.js documentation on ETH.

Quick Summary​

This section of the docs deals with how to deposit and withdraw ERC20 tokens on the Polygon network. Common functions exist between the ETH, ERC20, ERC721 and ERC1155 sections of the docs with variances in the naming and implementation patterns as befitting the standards. The most important prerequisite to using this section of the docs is mapping your assets, so please submit your mapping request here.

Introduction​

This guide uses the Polygon Testnet (Mumbai) which in itself is mapped to the Goerli Network to demonstrate asset transfer between the two blockchains. It's important to note that for the purposes of this tutorial, you should use a proxy address whenever is possible. This is because while the implementation contract address is liable to change when a new update is added to the contract code, the proxy never changes and it redirects all the incoming calls to the latest implementation. In essence, if you use the proxy address, you won't need to worry about any changes happening on the implementation contract before you're ready.

For example, please use the RootChainManagerProxy address for interactions instead of the RootChainManager address. Deployment details like the PoS contract addresses, ABI, and Test Token Addresses can be found here.

Mapping your assets is a necessary step for integrating the PoS bridge on your application so if you haven't done it, please submit a mapping request here. For the purposes of this tutorial, the team has deployed test tokens and mapped them to the PoS bridge. Request the asset you want to use on the faucet and if the test tokens are unavailable, reach out to the team on Discord. We'll make sure to reply you immediately.

In the upcoming tutorial, every step will be explained in detail along with a few code snippets. However, you can always refer to this repository which will have all the example source code that can help you to integrate and understand the working of PoS bridge.

High Level Flow​

Deposit ETH -

  1. Make depositEtherFor call on RootChainManager and send the required ether.

Withdraw ETH -

  1. Burn tokens on Polygon chain.
  2. Call exit function on RootChainManager to submit proof of burn transaction. This call can be made after checkpoint is submitted for the block containing burn transaction.

Steps​

Deposit​

ETH can be deposited to the Polygon chain by calling depositEtherFor on the RootChainManager contract. The Polygon PoS client exposes the depositEther method to make this call.

const result = await posClient.depositEther(<amount>);
const txHash = await result.getTransactionHash();
const txReceipt = await result.getReceipt();
note

Deposits from Ethereum to Polygon happen using the State Sync Mechanism and this takes about 22-30 minutes. After waiting for this time interval, it is recommended to check the balance using the web3.js/matic.js library or using Metamask. The explorer will show the balance only if at least one asset transfer has happened on the child chain. This link explains how to track deposit events.

Burn​

ETH is deposited as an ERC20 token on the Polygon chain. Withdrawing follows the same process as withdrawing ERC20 tokens.

To burn the tokens and engage the withdrawal process, call the withdraw function of the MaticWETH contract. Since Ether is an ERC20 token on the Polygon chain, you need to initiate the ERC20 token from the Polygon PoS client and then call the withdrawStart() method to start the burn process.

const erc20Token = posClient.erc20(<token address>);

// start withdraw process for 100 amount
const result = await erc20Token.withdrawStart(100);

const txHash = await result.getTransactionHash();

const txReceipt = await result.getReceipt();

Store the transaction hash for this call and use it while generating burn proof.

Exit​

Once the checkpoint has been submitted for the block containing the burn transaction, the user should call the exit function of RootChainManager contract and submit the proof of burn. Upon submitting valid proof tokens are transferred to the user. Polygon POS client erc20 exposes withdrawExit method to make this call. This function can be called only after the checkpoint is included in the main chain. The checkpoint inclusion can be tracked by following this guide.

// token address can be null for native tokens like ethereum or matic
const erc20RootToken = posClient.erc20(<token address>, true);

const result = await erc20Token.withdrawExit(<burn tx hash>);

const txHash = await result.getTransactionHash();

const txReceipt = await result.getReceipt();