ERC1155 Deposit and Withdraw Guide

Quick Summary

This section of the docs deals with how to deposit and withdraw ERC1155 tokens on the Polygon network. Again, large parts of the documentation here are very much the same as the ETH, ERC20 and ERC721 sections of the docs, and this is because these standards are the same in some respects and divergent in others. The most notable difference is that ERC1155 tokens support non-fungible tokens (NFTs), but are faster and more efficient to use in batch token transfers.

Introduction

Because we will be firing off transactions, this tutorial uses the Polygon Testnet(Mumbai) which is mapped to the Goerli Network. For the purpose of this tutorial, we have already deployed the Test tokens and mapped them on the PoS bridge. You can request the asset from the faucet and if they aren't available, please reach out to us on discord and we'll get back to 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 ERC1155

  • Approve the ERC1155PredicateProxy contract to spend the tokens that are to be deposited.
  • Make the depositFor call on the RootChainManager contract on Ethereum.

Withdraw ERC1155

  • Burn your token on the Polygon chain. This involves sending your token to a bogus address so the token is no longer usable.

  • Call the exit function and make sure to submit the transaction proof of burn hash. This call is to be made after the checkpoint is submitted for the block containing burn transaction

Details and an Explanation of Terms

There are four major steps to this section: the Approve flow, the Deposit flow, the Burn flow, and the Exit flow. Let's explore them, shall we?

Approve

The ERC1155PredicateProxy contract is the beginning of the ERC20 deposit process. Approving this contract is important because it's what is responsible for locking our tokens by transferring the tokens to itself. It then goes on to call the transferFrom function. To facilitate this flow, the Polygon PoS client exposes the approveERC1155ForDeposit method to make this call.

This is what the approveERC1155ForDeposit method looks like:

await maticPOSClient.approveERC1155ForDeposit(rootToken, { from });

Deposit

Deposit can be done by calling depositFor on RootChainManager contract. Note that token needs to be mapped and approved for transfer beforehand. Once tokens are transferred deposit proceeds using StateSync mechanism. Matic POS client exposes depositSingleERC1155ForUser & depositBatchERC1155ForUser method to make this call.

These are what the depositSingleERC1155ForUser and depositBatchERC1155ForUser methods looks like.

await maticPOSClient.depositSingleERC1155ForUser(
rootToken,
from,
tokenId,
amount,
{ from, gasPrice: "10000000000" }
);
await maticPOSClient.depositBatchERC1155ForUser(
rootToken,
from,
[...tokenId],
[...amount],
{ from, gasPrice: "10000000000" }
);

deposit function of ChildToken is called by the ChildChainManager. Tokens should be minted when this call is made.

Sidenote: Deposits from Ethereum to Polygon happen using the State Sync mechanism and this takes about 5-7 minutes. After waiting for this time interval, it is recommended to check the balance using 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 the deposit events.

Burn

To burn the tokens, call the withdraw function of the ChildToken contract. To do this, Polygon PoS client exposes the burnERC1155 and the burnBatchERC1155 methods

This are what the burnERC1155 and burnBatchERC1155 methods looks like

await maticPOSClient.burnSingleERC1155(rootToken, tokenId, amount, {
from,
gasPrice: "10000000000",
});
await maticPOSClient.burnBatchERC1155(rootToken, [...tokenId], [...amount], {
from,
gasPrice: "10000000000",
});

Make sure to 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 burn transaction, please call the exit function of the RootChainManager contract and submit the proof of burn. Upon submitting valid proof tokens are transferred to the user. The Polygon PoS client exposes the exitBatchERC1155 and exitSingleERC1155 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

await maticPOSClient.exitSingleERC1155(burnTxHash, { from });
await maticPOSClient.exitBatchERC1155(burnTxHash, { from });