This repository contains the maticjs
client library. maticjs
makes it easy for developers, who may not be deeply familiar with smart contract development, to interact with the various components of Matic Network.
This library will help developers to move assets from Ethereum chain to Matic chain, and withdraw from Matic to Ethereum using fraud proofs.
We will be improving this library to make all features available like Plasma Faster Exit, challenge exit, finalize exit and more.
$ npm install --save web3 maticjs # or yarn add web3 maticjs
Note: This library is dependent on web3.js library. Tested with [email protected]
Simply download dist/matic.js
and include with a script tag. Matic
will be registered as a global variable.
<script src="https://cdn.jsdelivr.net/npm/maticjs/dist/matic.js"></script>
Matic is also available on unpkg
// 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.safeDepositERC721Tokens(
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
)
The flow for asset transfers on the Matic Network is as follows:
- User deposits crypto assets in Matic contract on mainchain
- Once deposited tokens get confirmed on the main chain, 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 by establishing proof of remaining tokens on Root contract (contract deployed on Ethereum chain)
Matic Testnet
- RPC endpoint host: https://testnet2.matic.network
- TEST childchain ERC20 token: 0xcc5de81d1af53dcb5d707b6b33a50f4ee46d983e
Ropsten testnet addresses
- TEST mainchain ERC20 token: 0x6b0b0e265321e788af11b6f1235012ae7b5a6808
- Root Contract: 0x60e2b19b9a87a3f37827f2c8c8306be718a5f9b4
- DepositManager Contract: 0x4072fab2a132bf98207cbfcd2c341adb904a67e9
- WithdrawManager Contract: 0x4ef2b60cdd4611fa0bc815792acc14de4c158d22
Please write to [email protected] to request TEST tokens for development purposes. We will soon have a faucet in place for automatic distribution of tokens for testing.
new Matic()
matic.getMappedTokenAddress()
matic.balanceOfERC721()
matic.tokenOfOwnerByIndexERC721()
matic.depositEther()
matic.approveERC20TokensForDeposit()
matic.depositERC20Tokens()
matic.safeDepositERC721Tokens()
matic.approveERC721TokenForDeposit()
matic.depositERC721Tokens()
matic.depositEthers()
matic.transferTokens()
matic.transferERC721Tokens()
matic.transferEthers()
matic.startWithdraw()
matic.startERC721Withdraw()
matic.getHeaderObject()
matic.withdraw()
matic.processExits()
matic.getTx()
matic.getReceipt()
Creates Matic SDK instance with give options. It returns a MaticSDK object.
import Matic from "maticjs"
const matic = new Matic(options)
options
is simple Javascriptobject
which can have following fields:maticProvider
can bestring
orWeb3.providers
instance. This provider must connect to Matic chain. Value can be anyone of following:'https://testnet2.matic.network'
new Web3.providers.HttpProvider('http://localhost:8545')
- WalletConnect Provider instance
parentProvider
can bestring
orWeb3.providers
instance. This provider must connect to Ethereum chain (testnet or mainchain). Value can be anyone of following:'https://ropsten.infura.io'
new Web3.providers.HttpProvider('http://localhost:8545')
- WalletConnect Provider instance
rootChainAddress
must be valid Ethereum contract address.syncerUrl
must be valid API host. MaticSDK uses this value to fetch receipt/tx proofs instead of getting whole block to client side.watcherUrl
must be valid API host. MaticSDK uses this value to fetch headerBlock info from mainchain and to find appropriate headerBlock for given blockNumber.withdrawManagerAddress
must be valid Ethereum contract address.depositManagerAddress
must be valid Ethereum contract address.
get matic token address
mapped with mainchain tokenAddress
.
tokenAddress
must be valid token address
This returns matic address
.
Example:
matic
.getMappedTokenAddress("0x670568761764f53E6C10cd63b71024c31551c9EC")
.then(address => {
console.log("matic address", address)
})
get balance of ERC721 token
for address
.
token
must be valid token addressaddress
must be valid user address
This returns matic balance
.
Example:
matic
.balanceOfERC721("0xfeb14bc6aaf5d39fa43ff51ed94e6c260539e296")
.then(address => {
console.log("matic address", address)
})
get ERC721 tokenId at index
for token
and for address
.
token
must be valid token addressaddress
must be valid user addressindex
index of tokenId
This returns matic tokenId
.
Example:
matic
.tokenOfOwnerByIndexERC721("0xfeb14b...", "21", 0, {
from: "0xABc578455..."
})
.then(tokenID => {
console.log("Token ID", tokenID)
})
Approves given amount
of token
to rootChainContract
.
token
must be valid ERC20 token addressamount
must be token amount in wei (string, not in Number)options
(optional) must be valid javascript object containingfrom
,gasPrice
,gasLimit
,nonce
,value
,onTransactionHash
,onReceipt
oronError
from
must be valid account address(required)gasPrice
same as EthereumsendTransaction
gasLimit
same as EthereumsendTransaction
nonce
same as EthereumsendTransaction
nonce
same as EthereumsendTransaction
value
contains ETH value. Same as EthereumsendTransaction
.onTransactionHash
must befunction
. This function will be called when transaction will be broadcasted.onReceipt
must befunction
. This function will be called when transaction will be included in block (when transaction gets confirmed)onError
must befunction
. This function will be called when sending transaction fails.
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic
.approveERC20TokensForDeposit("0x718Ca123...", "1000000000000000000", {
from: "0xABc578455..."
})
.on("onTransactionHash", txHash => {
console.log("New transaction", txHash)
})
Deposit given amount
of token
with user user
.
token
must be valid ERC20 token addressuser
must be value account addressamount
must be token amount in wei (string, not in Number)options
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
const user = <your-address> or <any-account-address>
matic.depositToken('0x718Ca123...', user, '1000000000000000000', {
from: '0xABc578455...'
})
Deposit given tokenId
of token
.
token
must be valid ERC721 token addresstokenId
must be tokenIdoptions
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic.safeDepositERC721Tokens('0x718Ca123...', '21', {
from: '0xABc578455...'
})
Approves given amount
of token
to rootChainContract
.
token
must be valid ERC721 token addresstokenId
must be tokenId (string, not in Number)options
(optional) must be valid javascript object containingfrom
,gasPrice
,gasLimit
,nonce
,value
,onTransactionHash
,onReceipt
oronError
from
must be valid account address(required)gasPrice
same as EthereumsendTransaction
gasLimit
same as EthereumsendTransaction
nonce
same as EthereumsendTransaction
nonce
same as EthereumsendTransaction
value
contains ETH value. Same as EthereumsendTransaction
.onTransactionHash
must befunction
. This function will be called when transaction will be broadcasted.onReceipt
must befunction
. This function will be called when transaction will be included in block (when transaction gets confirmed)onError
must befunction
. This function will be called when sending transaction fails.
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic
.approveERC721TokenForDeposit("0x718Ca123...", "21", {
from: "0xABc578455..."
})
.on("onTransactionHash", txHash => {
console.log("New transaction", txHash)
})
Deposit given tokenId
of token
with user user
.
token
must be valid ERC721 token addressuser
must be value account addresstokenId
must be valid tokenIdoptions
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
const user = <your-address> or <any-account-address>
matic.depositERC721Tokens('0x718Ca123...', user, tokenId, {
from: '0xABc578455...'
})
Deposit options.value
options
see more infomation here.value
amount of ethers.from
must be valid account address(required)
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic.depositEthers({
from: '0xABc578455...',
value: '1000000000000000000'
})
Transfer given amount
of token
to user
.
token
must be valid ERC20 token addressuser
must be value account addressamount
must be token amount in wei (string, not in Number)options
see more infomation hereparent
must be boolean value. For token transfer on Main chain, useparent: true
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
const user = <your-address> or <any-account-address>
matic.transferERC20Tokens('0x718Ca123...', user, '1000000000000000000', {
from: '0xABc578455...',
// For token transfer on Main network
// parent: true
})
Transfer ownership tokenId
of token
to user
.
token
must be valid ERC721 token addressuser
must be value account addresstokenId
tokenIdoptions
see more infomation hereparent
must be boolean value. For token transfer on Main chain, useparent: true
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
const user = <your-address> or <any-account-address>
matic.transferERC721Tokens('0x718Ca123...', user, tokenId, {
from: '0xABc578455...',
// For token transfer on Main network
// parent: true
})
Transfer given amount
of ethers to user
.
user
must be value account addressamount
must be ethers amount in wei (string, not in Number)options
see more infomation hereparent
must be boolean value. For ether transfer on Main chain, useparent: true
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
const user = <your-address> or <any-account-address>
matic.transferEthers(user, '1000000000000000000', {
from: '0xABc578455...',
// For token transfer on Main network
// parent: true
})
Start withdraw process with given amount
for token
.
token
must be valid ERC20 token addressamount
must be token amount in wei (string, not in Number)options
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic
.startWithdraw("0x718Ca123...", "1000000000000000000", {
from: "0xABc578455..."
})
.on("onTransactionHash", txHash => {
console.log("Started withdraw process with txId", txHash)
})
Start withdraw process with given tokenId
for token
.
token
must be valid ERC721 token addresstokenId
must be token tokenId in wei (string, not in Number)options
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic
.startERC721Withdraw("0x718Ca123...", "21", {
from: "0xABc578455..."
})
.on("onTransactionHash", txHash => {
console.log("Started withdraw process with txId", txHash)
})
Fetch header/checkpoint corresponding to blockNumber
blockNumber
must be valid Matic's sidechain block number
This returns Promise
object, which will be fulfilled when header/checkpoint is found corresponding to blockNumber
.
Example:
matic.getHeaderObject(673874).then(header => {
// header.start
// header.end
// header.proposer
// header.number
})
Withdraw tokens on mainchain using txId
from startWithdraw
method after header has been submitted to mainchain.
txId
must be valid tx hashoptions
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic.withdraw("0xabcd...789", {
from: "0xABc578455..."
})
Call processExits after completion of challenge period, after that withdrawn funds get transfered to your account on mainchain
rootTokenAddress
RootToken addressoptions
see more infomation here
This returns Promise
object, which will be fulfilled when transaction gets confirmed (when receipt is generated).
Example:
matic.processExits("0xabcd...789", {
from: "0xABc578455..."
})
Get transaction object using txId
from Matic chain.
txId
must be valid tx id
This returns Promise
object.
Example:
matic
.getTx("0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b")
.then(txObject => {
console.log(txObject)
})
Get receipt object using txId
from Matic chain.
txId
must be valid tx id
This returns Promise
object.
Example:
matic
.getReceipt(
"0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"
)
.then(obj => {
console.log(obj)
})
Please write to [email protected] for integration support. If you have any queries, feedback or feature requests, feel free to reach out to us on telegram: t.me/maticnetwork
MIT