Mapping Assets Explained

ERC20 and ERC721 tokens on Ethereum can be deposited and withdrawn from matic chain using plasma protocol. To enable this, a token contract on Ethereum (rootToken) needs to be mapped to a token contract on Matic chain(childToken).

You can submit your mapping request here. Please make note that this mapping submission form is for Plasma Bridge and for PoS bridge you have to directly contact the matic team on discord.

Mapping a token

Mapping a token involves deploying a childToken contract on matic chain and registering the token on both main and matic chain.

A restricted childToken is deployed and registered on Matic chain automatically by making a contract call to the ChildChain contract. But if the rootToken has extra functionality apart from basic ERC20/ERC721, a custom childToken contract needs to be deployed manually. (Read adding additional functionality)

Deploying a 'Restricted' Child Token

Step 1: On Matic

The addToken function call on ChildChain contract deploys a child Token on matic, with restricted functionality (see: ChildERC20 and ChildERC721), these is done to ensure Plasma security for the asset, otherwise the model gets broken. So if you need Plasma security with a custom token and added functionality on top of what the generic token provides, you need to write your contracts safely with restrictions as mandated.

Certain Data structures are maintained to keep track of the asset on Matic: such as the events, Deposit, Withdraw, LogTransfer. These are absolutely essential to the Plasma contracts that read this data to ensure data verification of the sidechain via fraud proofs and Plasma predicates.

Based on feedback from developers, we have added mechanisms that allow devs to now program any restrictions that they wish to keep for transfers for example - see this doc for example. This allows arbitrary logic to be coded before the Plasma-safe transfer takes place, keeping the transfer and custom logic separated - so as to ensure Plasma safety.

Note on Restrictions

Plasma security is relatively straightforward to implement for user-controlled accounts or EOAs, since ownership of an asset is easy to derive. However, contracts are difficult to program for Plasma, since ownership of assets cannot be known in advance, and can vary depending on the complexity of the contract.

Therefore, we support some types of contracts as Plasma predicates. We are beginning with a few pre-built predicates such as asset transfers, asset swaps, etc. - and will be increasing the number of pre-built predicates to reflect a wide variety of use cases.

Step 2: On Ethereum

A mapping on Registry contract is updated for each asset to be mapped. This is done via the mapToken function call on Ethereum (or Ropsten). This function takes the mapped address returned from the addToken call to ChildChain and updates the mapping on Ethereum.

Moving an Asset

Deposits

  1. The Deposit Manager Contract is approved to spend X on behalf of msg.sender
  2. The Deposit Manager transfers the amount from msg.sender to itself

This ensures the asset is locked on Main chain and isn't transferrable while the token is being used on Matic

Withdrawals

  1. Burn tokens on Matic sidechain
  2. Submit proof of burn (the receipt of burn tx) on Root Chain
    1. This step is executed only after the block consisting of the burn tx has been included in a checkpoint on the Root Chain.
    2. After checkpoint submission, a successful execution of this step
      1. marks the initiation of the Challenge Exit Period (which is a 7-day period on main network, and set to 5 minute on test networks)
      2. Mints an ExitNFT token to the exitor's account - which is representative of the exit initiated on the child chain by the exitor
    3. After the challenge period has ended, processExits burns the Exit NFT and transfers the tokens back from Deposit manager to the exitor.

Adding functionality to Child token

In some cases you might require added functionality on top of what the restricted child token provides. To add your custom token as child on Matic, you can inherit the standard plasma contract and add custom functions according to your use. Eg.,

pragma solidity ^0.5.2;
import { ChildERC20 } from "./ChildERC20.sol";
contract YourCustomChildToken is ChildERC20 {
// your custom functions
}

To submit such a custom token for mapping, submit the form here. Please make note that this mapping submission form is for Plasma Bridge and for PoS bridge you have to directly contact the matic team on discord.