This tutorial will act as a guide for step-by-step process to understand and use Matic JS, which is the easiest way to interact with the Matic Network.
The process followed here is:
- Deposit assets from root chain to Matic (Ethereum → Matic)
- Transfer assets between accounts on Matic (Matic ↔ Matic)
- Withdraw assets from Matic on to root chain (Matic → Ethereum)
- ERC20: In this tutorial we use ERC-20 assets to be transferred from Görli to Matic.
- ERC721: The flow discussed below remains similar for ERC-721 assets with minor changes that will be mentioned wherever required.
- Ether: The flow discussed below is simliar for transfer and withdraw, The only difference is at deposit, it's only one step by using
matic.depositEthers. For transfer and withdraw you can find the Görli_ERC20Address & Matic_ERC20Address in network detail
Using Matic JS
We will be showcasing the flow for asset transfers on the Matic Network in this tutorial and how you can do the same using Matic.js:
- User deposits crypto assets in Matic contract on mainchain
- Once deposited tokens get confirmed on the mainchain, the corresponding tokens will get reflected on the Matic chain
- The user can now transfer tokens to anyone they want instantly with negligible fees. Matic chain has faster blocks (approximately 1 second). That way, the transfer will be done almost instantly.
- Once a user is ready, they can withdraw remaining tokens from the mainchain. Withdrawal of funds is initiated from the Plasma Sidechain. A checkpoint interval of 5 mins is set, where all the blocks on the Matic block layer are validated since the last checkpoint.
- Once the checkpoint is submitted to the mainchain Ethereum contract, an Exit NFT (ERC721) token is created of equivalent value.
- Users need to wait for a 7 day challenge period
- Once the challenge period is complete, the withdrawn funds can be claimed back to your Ethereum acccount from the mainchain contract using a process-exit procedure.
- User can also get a fast exit via 0x or Dharma (coming soon!)
In order to make any transactions, you will also need some Ether in the test accounts that you will use while following the tutorial. In case you don’t have some ETH on Görli, you can use the faucet links given here — https://goerli-faucet.slock.it/.
Throughout this tutorial, we will be using the ERC20 token
TEST on the Görli network as an example. This is a TEST token. In your DApp, you can replace it with any ERC20 token. To get some Test
TEST tokens on Matic Network, you can access the Matic Faucet by clicking on the link below.
Note: To use your own tokens for deposits and withdrawals, you'll have to get the token 'mapped'. Which essentially means making the contracts on main chain and side chain 'aware' of your custom token. Read more about the Mapping process here, or you can submit a mapping request here.
Basic setup for the tutorial
- Create a wallet: If you are new to wallets, then Setup a Metamask Account.
- Configure the Matic testnet: To easily visualise the flow of funds on the Matic Network, it is instructive if you configure the Matic testnet on Metamask.
Note that we are using Metamask here solely for visualization purposes. There is no requirement to use Metamask at all for using the Matic Network.
- Create Multiple Accounts: Before starting with the tutorial, go ahead and have 3 Ethereum test accounts ready.
- Configure token on Matic: In order to view the flow of funds easily on the Matic Network using Matic.js, you can configure tokens on Metamask.
TESTtoken, taken as an example for this tutorial, can be configured in Metamask so as to easily visualise account balances. > Again note this is optional. You can very easily query the token balances and other variables using web3
These Test tokens needs to be added (depending upon the type of asset you are using - erc20/erc721/ether) to all 3 test accounts in Metamask once each in both the Görli and Matic testnets:
The Matic.js repository is hosted on Github at https://github.com/maticnetwork/matic.js/
For reference purposes, I will be creating a test folder to showcase how to setup Matic.js step-by-step. Go ahead and create a folder for this tutorial — I am going with
$ mkdir matic-js-test
maticjs package via npm:
If you wish to directly refer a set of code examples, you can do so at https://github.com/maticnetwork/matic.js/tree/master/examples
matic-js-test folder, create a new file and name it
matic-example.js, and add the following code
Never store your private key in code on production — this is added in the
config.jsfile for illustration purposes. Typically a user’s private key will be stored in a browser wallet such as Metamask or a mobile wallet such as the Matic wallet, Status or a hardware wallet.
You will also need to create another file
config.json. This will contain all configuration related to Matic.js.
For now, don’t worry about these values — just keep them as is.
Note: You will need to add your private key here. Signing of transactions will require your private key. Again, it is NOT ADVISABLE to hard code your private key when on production. Later, you can build keeping in mind that the user will be handling their keys at their end with MetaMask, Matic Wallet or any other compatible user wallet.
Important: Make sure you prefix
0xto your private key.
Let's move to the next part of this tutorial - Deposit assets from root chain to Matic (Ethereum → Matic)