Skip to content

Getting Started

This page will help you understand the basics of how Matic Network works.

To deploy contracts on the Matic, you can read our tutorial on How to deploy contracts on Matic Testnet

It is recommended that developers new to Matic, start with the Matic.js library. maticjs makes it easy for developers, who may not be deeply familiar with smart contract development and otherwise, to quickly interact with the various components of Matic Network.

This page will help developers to move assets from Ethereum chain to Matic chain, transfer assets on Matic and withdraw from Matic to Ethereum using fraud proofs.

We will be improving this library on an ongoing basis to make all features available like Plasma Faster Exit, Challenge exit, Finalize exit and more.

Sidechain basics

The basic workflow of how we can scale transactions on a sidechain is that we can take

  • assets from one chain and transfer them to another (called the “sidechain")
  • by locking the assets up on the primary chain (or “root chain”) and
  • “creating” them again on the sidechain and
  • transfer assets cheaply on the sidechain.
  • When you want to go back, you simply need to “destroy” the asset on the sidechain and
  • unlock them on the root chain.

How Matic works?

The flow for asset transfers on the Matic Network is as follows:

  1. User deposits crypto assets in Matic contract on mainchain
  2. 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.
  3. 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.
  4. Once the checkpoint is submitted to the mainchain Ethereum contract, an Exit NFT (ERC721) token is created of equivalent value.
  5. Users need to wait for a 7 day challenge period
  6. 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!)

Prerequisites

  • Add ETH on your Ropsten account
  • Add TEST token to your Ropsten account on Metamask
    • Refer the tutorial given here to add a custom token
    • TEST token contract address on Ropsten: 0x70459e550254b9d3520a56ee95b78ee4f2dbd846
  • Get TEST tokens from the faucet https://wallet.matic.today/faucet
  • Add Matic RPC endpoint on Metamask
    • Refer the tutorial here to add a custom RPC endpoint
    • Matic RPC endpoint: https://testnet2.matic.network/

Important contracts and addresses

Ropsten testnet addresses

  • Ropsten MATIC ERC20 token (TEST token): 0x70459e550254b9d3520a56ee95b78ee4f2dbd846
  • Root Contract: 0x60e2b19b9a87a3f37827f2c8c8306be718a5f9b4
  • DepositManager Contract: 0x4072fab2a132bf98207cbfcd2c341adb904a67e9
  • WithdrawManager Contract: 0x4ef2b60cdd4611fa0bc815792acc14de4c158d22

Matic Testnet

  • RPC endpoint host: https://testnet2.matic.network
  • Matic testnet MATIC ERC20 token (TEST token): 0xc82c13004c06E4c627cF2518612A55CE7a3Db699

Installation

NPM

$ npm install --save web3 maticjs # or yarn add web3 maticjs

Note: This library is dependent on web3.js library. Tested with web3@1.0.0-beta.34

Direct <script> include

Simply download dist/matic.js and include with a script tag. Matic will be registered as a global variable.

CDN

<script src="https://cdn.jsdelivr.net/npm/maticjs/dist/matic.js"></script>

Unpkg

Matic is also available on unpkg

Getting started

// Import Matic sdk
import Matic from 'maticjs'

// Create sdk instance
const matic = new Matic({

  // Set Matic provider - string or provider instance
  // Example: 'https://testnet.matic.network' OR new Web3.providers.HttpProvider('http://localhost:8545')
  maticProvider: <web3-provider>,

  // Set Mainchain provider - string or provider instance
  // Example: 'https://kovan.infura.io' OR new Web3.providers.HttpProvider('http://localhost:8545')
  parentProvider: <web3-provider>,

  // Set rootchain contract. See below for more information
  rootChainAddress: <root-contract-address>,

  // Set withdraw-manager Address. See below for more information
  withdrawManagerAddress: <withdraw-manager-address>,

  // Set deposit-manager Address. See below for more information
  depositManagerAddress: <deposit-manager-address>,

  // Set matic network's WETH address. See below for more information
  maticWethAddress: <matic-weth-address>,

  // Syncer API URL
  // Fetches tx/receipt proof data instead of fetching whole block on client side
  syncerUrl: 'https://matic-syncer2.api.matic.network/api/v1', // (optional)

  // Watcher API URL
  // Fetches headerBlock info from mainchain & finds appropriate headerBlock for given blockNumber
  watcherUrl: 'https://ropsten-watcher2.api.matic.network/api/v1', // (optional)
})

// Set wallet
// Warning: Not-safe
// matic.wallet = <private-key> // Use metamask provider or use WalletConnect provider instead.

// get token address mapped with mainchain token address
const tokenAddressOnMatic = await matic.getMappedTokenAddress(
  tokenAddress // token address on mainchain
)

// get ERC721 token balance
await matic.balanceOfERC721(
  user, // User address
  tokenAddress,  // Token address
  options // transaction fields
)

// get ERC721 token ID
await matic.tokenOfOwnerByIndexERC721(
  from, // User address
  tokenAddress,  // Token address
  index, // index of tokenId
  options // transaction fields
)

// get ERC721 token ID
await matic.tokenOfOwnerByIndexERC721(
  from, // User address 
  tokenAddress,  // Token address
  index, // index of tokenId
  options // transaction fields
)

// Deposit Ether into Matic chain
await matic.depositEthers(
  options // transaction fields
)

// Approve ERC20 token for deposit
await matic.approveERC20TokensForDeposit(
  token,  // Token address,
  amount,  // Token amount for approval (in wei)
  options // transaction fields
)

// Deposit token into Matic chain. Remember to call `approveERC20TokensForDeposit` before
await matic.depositERC20Tokens(
  token,  // Token address
  user,   // User address (in most cases, this will be sender's address),
  amount,  // Token amount for deposit (in wei)
  options // transaction fields
)

// Deposit ERC721 token into Matic chain.(older ERC721 or some newer contracts will not support this.
// in that case, first call `approveERC721TokenForDeposit` and `depositERC721Tokens`)
await matic.safeTransferFrom(
  token,  // Token addres
  tokenId,  // Token Id for deposit
  options // transaction fields
)

// Approve ERC721 token for deposit
await matic.approveERC721TokenForDeposit(
  token,  // Token address,
  tokenId,  // Token Id
  options // transaction fields
)


// Deposit token into Matic chain. Remember to call `approveERC721TokenForDeposit` before
await matic.depositERC721Tokens(
  token,  // Token address
  user,   // User address (in most cases, this will be sender's address),
  tokenId,  // Token Id
  options // transaction fields
)

// Transfer token on Matic
await matic.transferTokens(
  token,  // Token address
  user,   // Recipient address
  amount,  // Token amount
  options // transaction fields
)

// Transfer ERC721 token on Matic
await matic.transferERC721Tokens(
  token,  // Token address
  user,   // Recipient address
  tokenId,  // Token Id
  options // transaction fields
)

// Transfer Ether
await matic.transferEthers(
  user,   // Recipient address
  amount,  // Token amount
  options // transaction fields
)

// Initiate withdrawal of ERC20 from Matic and retrieve the Transaction id
await matic.startWithdraw(
  token, // Token address
  amount, // Token amount for withdraw (in wei)
  options // transaction fields
)

// Initiate withdrawal of ERC721 from Matic and retrieve the Transaction id
await matic.startERC721Withdraw(
  token, // Token address
  tokenId, // tokenId
  options // transaction fields
)

// Withdraw funds from the Matic chain using the Transaction id generated from the 'startWithdraw' method
// after header has been submitted to mainchain
await matic.withdraw(
  txId, // Transaction id generated from the 'startWithdraw' method
  options // transaction fields
)

// Process exits after completion of challenge period
await matic.processExits(
  rootTokenAddress, // RootToken address
  options // transaction fields
)

Code Samples

Please refer https://github.com/maticnetwork/matic.js/tree/master/examples for code samples.