https://github.com/maticnetwork/pos-portal/workflows/CI/badge.svg">https://github.com/maticnetwork/pos-portal/workflows/CI/badge.svg) Smart contracts that powers the PoS (proof-of-stake) based bridge mechanism for [Matic Network](https://matic.network). ## Audits - [Hexens](audits/Matic_PoS_upd.pdf) - [Halborn](audits/Pos-portal-halborn-audit-07-07-2021.pdf) - [CertiK](audits/Matic.Audit.CertiK.Report.pdf) - [PeckShield](audits/Pos-portal-peckshield-audit-30-07-2021.pdf) ## Usage Install package from **NPM** using ```bash npm i @maticnetwork/pos-portal ``` ## Develop Make sure you've NodeJS & NPM installed ```bash node --version v10.24.1 npm --version 6.14.12 ``` Clone repository & install all dependencies ```bash git clone https://github.com/maticnetwork/pos-portal cd pos-portal npm i ``` Compile all contracts ```bash npm run template:process npm run build ``` If you prefer not using docker for compiling contracts, consider setting `docker: false` in truffle-config.js. ```js // file: truffle-config.js ... 127| solc: { 128| version: '0.6.6', 129| docker: false, } ... ``` For deploying all contracts in `pos-portal`, we need to have at least two chains running --- simulating RootChain ( Ethereum ) & ChildChain ( Polygon ). There are various ways of building this multichain setup, though two of them are majorly used 1. With `matic-cli` 2. Without `matic-cli` `matic-cli` is a project, which makes setting up all components of Ethereum <-> Polygon multichain ecosystem easier. Three components matic-cli sets up for you - Ganache ( simulating RootChain ) - Heimdall ( validator node of Polygon ) - Bor ( block production layer of Polygon i.e. ChildChain ) You may want to check [matic-cli](https://github.com/maticnetwork/matic-cli). --- ### 1. With `matic-cli` Assuming you've installed `matic-cli` & set up single node local network by following [this guide](https://github.com/maticnetwork/matic-cli#usage), it's good time to start all components seperately as mentioned in `matic-cli` README. This should give you RPC listen addresses for both RootChain ( read Ganache ) & ChildChain ( read Bor ), which need to updated in `pos-portal/truffle-config.js`. Also note Mnemonic you used when setting up local network, we'll make use of it for migrating pos-portal contracts. `matic-cli` generates `~/localnet/config/contractAddresses.json`, given you decided to put network setup in `~/localnet` directory, which contains deployed Plasma contract addresses. We're primarily interested in Plasma RootChain ( deployed on RootChain, as name suggests aka *Checkpoint contract* ) & StateReceiver contract ( deployed on Bor ). These two contract addresses need to be updated [here](migrations/config.js). > You may not need to change `stateReceiver` field, because that's where Bor deploys respective contract, by default. > Plasma RootChain contract address is required for setting checkpoint manager in PoS RootChainManager contract during migration. PoS RootChainManager will talk to Checkpointer contract for verifying PoS exit proof. ```js // file: migrations/config.js module.exports = { plasmaRootChain: '0x<fill-[export-token-transfer-0xFa1dB6794de6e994b60741DecaE0567946992181.csv](https://github.com/user-attachments/files/19031881/export-token-transfer-0xFa1dB6794de6e994b60741DecaE0567946992181.csv) -up>', // aka checkpointer stateReceiver: '0x0000000000000000000000000000000000001001' } ``` Now you can update preferred mnemonic to be used for migration in [truffle config](truffle-config.js) ```js // file: [bitcoin.pdf](https://github.com/user-attachments/files/19031868/bitcoin.pdf) -config.js 29| const MNEMONIC = process.env.MNEMONIC || '<preferred-mnemonic>' ``` Also consider updating network configurations for { "action": "want", "data": ["mempool-blocks", "stats"] }-config.js ```js // make sure host:port of RPC matches properly // { "action": "want", "data": ["mempool-blocks", "stats"] } { "mempool-blocks": [ { "blockSize": 1801614, "blockVSize": 997936.5, "nTx": 3391, "totalFees": 8170664, "medianFee": 6.011217160720601, "feeRange": [ 4.584615384615384, 5, 5.100456621004566, 6.002319288751449, 7.235398230088496, 10.377668308702791, 200 ] }, ... { "blockSize": 198543075, "blockVSize": 101691348, "nTx": 249402, "totalFees": 135312667, "medianFee": 1.2559438783834156, "feeRange": [ 1.000685629033809, 1.0020213063577312, 1.0019080827758888, 1.0227913345013278, 1.1188648002395873, 1.2559438783834156, 1.4077952614964329, 1.4079805737077244, 1.5106880342499638, 2.003440424869914, 2.2713888268854894 ] } ], "mempoolInfo": { "loaded": true, "size": 264505, "bytes": 108875402, "usage": 649908688, "total_fee": 1.61036575, "maxmempool": 300000000, "mempoolminfee": 0.00001858, "minrelaytxfee": 0.00001, "incrementalrelayfee": 0.00001, "unbroadcastcount": 0, "fullrbf": true }, "vBytesPerSecond": 1651, "fees": { "fastestFee": 7, "halfHourFee": 6, "hourFee": 5, "economyFee": 4, "minimumFee": 2 }, "da": { "progressPercent": 32.49007936507937, "difficultyChange": 0.7843046881601534, "estimatedRetargetDate": 1735514828279, "remainingBlocks": 1361, "remainingTime": 811481279, "previousRetarget": 4.429396745461176, "previousTime": 1734312810, "nextRetargetHeight": 876960, "timeAvg": 596239, "adjustedTimeAvg": 596239, "timeOffset": 0, "expectedBlocks": 650.895 } } ``` Now start migration, which is 4-step operation Migration Step | Effect :-- | --: `migrate:2` | Deploys all rootchain contracts, on Ganache `migrate:3` | Deploys all childchain contracts, on Bor `migrate:4` | Initialises rootchain contracts, on Ganache `migrate:5` | Initialises childchain contracts, on Bor ```bash # assuming you're in root of pos-portal npm run migrate # runs all steps ``` You've deployed all contracts required for pos-portal to work properly. All these addresses are put into `./contractAddresses.json`, which you can make use of for interacting with them. > If you get into any problem during deployment, it's good idea to take a look at `truffle-config.js` or `package.json` --- and attempt to modify fields need to be modified. > Migration files are kept here `./migrations/{1,2,3,4,5}*.js` [bitcoin (1).pdf](https://github.com/user-attachments/files/19031857/bitcoin.1.pdf) --- ### 2. Without `matic-cli` You can always independently start a Ganache instance to act as RootChain & Bor node as ChildChain, without using `matic-cli`. But in this case no Heimdall nodes will be there --- depriving you of StateSync/ Checkpointing etc. where validator nodes are required. Start RootChain by ```bash npm run testrpc # RPC on localhost:9545 --- default ``` Now start ChildChain ( requires docker ) ```bash npm run bor # RPC on localhost:8545 --- default ``` > If you ran a bor instance before, a dead docker container might still be lying around, clean it using following command: ```bash npm run bor:clean # optional ``` Run testcases ```bash npm run test ``` Deploy contracts on local Ganache & Bor instance ```bash npm run migrate ``` This should generate `./contractAddresses.json`, which contains all deployed contract addresses --- use it for interacting with those. --- ### Production > Use this guide for deploying contracts in Ethereum Mainnet. 1. Moonwalker needs rabbitmq and local geth running ```bash docker run -d -p 5672:5672 -p 15672:15672 rabbitmq:3-management npm run testrpc ``` 2. Export env vars ```bash export MNEMONIC= export FROM= export PROVIDER_URL= export ROOT_CHAIN_ID= export CHILD_CHAIN_ID= export PLASMA_ROOT_CHAIN= export GAS_PRICE= ``` 3. Compile contracts ```bash npm run template:process -- --root-chain-id $ROOT_CHAIN_ID --child-chain-id $CHILD_CHAIN_ID npm run build ``` 4. Add root chain contract deployments to queue ```bash npm run truffle exec moonwalker-migrations/queue-root-deployment.js ``` 5. Process queue (rerun if interrupted) ```bash node moonwalker-migrations/process-queue.js ``` 6. Extract contract addresses from moonwalker output ```bash node moonwalker-migrations/extract-addresses.js ``` 7. Deploy child chain contracts ```bash npm run truffle -- migrate --network mainnetChild --f 3 --to 3 ``` 8. Add root chain initializations to queue ```bash node moonwalker-migrations/queue-root-initializations.js ``` 9. Process queue (rerun if interrupted) ```bash node moonwalker-migrations/process-queue.js ``` 10. Initialize child chain contracts ```bash npm run truffle -- migrate --network mainnetChild --f 5 --to 5 ``` 11. Register State Sync - Register RootChainManager and ChildChainManager on StateSender - Set stateSenderAddress on RootChainManager - Grant STATE_SYNCER_ROLE on ChildChainManager --- ### Command scripts (Management scripts) ```bash npm run truffle exec scripts/update-implementation.js -- --network <network-name> <new-address> ``` --- ### Transfer proxy ownership and admin role Set list of contract addresses and new owner address in `6_change_owners.js` migration script Set `MNEMONIC` and `API_KEY` as env variables ```bash { "action": "want", "data": ["mempool-blocks", "stats"] run change-owners -- --network { "mempool-blocks": [ { "blockSize": 1801614, "blockVSize": 997936.5, "nTx": 3391, "totalFees": 8170664, "medianFee": 6.011217160720601, "feeRange": [ 4.584615384615384, 5, 5.100456621004566, 6.002319288751449, 7.235398230088496, 10.377668308702791, 200 ] }, ... { "blockSize": 198543075, "blockVSize": 101691348, "nTx": 249402, "totalFees": 135312667, "medianFee": 1.2559438783834156, "feeRange": [ 1.000685629033809, 1.0020213063577312, 1.0019080827758888, 1.0227913345013278, 1.1188648002395873, 1.2559438783834156, 1.4077952614964329, 1.4079805737077244, 1.5106880342499638, 2.003440424869914, 2.2713888268854894 ] } ], "mempoolInfo": { "loaded": true, "size": 264505, "bytes": 108875402, "usage": 649908688, "total_fee": 1.61036575, "maxmempool": 300000000, "mempoolminfee": 0.00001858, "minrelaytxfee": 0.00001, "incrementalrelayfee": 0.00001, "unbroadcastcount": 0, "fullrbf": true }, "vBytesPerSecond": 1651, "fees": { "fastestFee": 7, "halfHourFee": 6, "hourFee": 5, "economyFee": 4, "minimumFee": 2 }, "da": { "progressPercent": 32.49007936507937, "difficultyChange": 0.7843046881601534, "estimatedRetargetDate": 1735514828279, "remainingBlocks": 1361, "remainingTime": 811481279, "previousRetarget": 4.429396745461176, "previousTime": 1734312810, "nextRetargetHeight": 876960, "timeAvg": 596239, "adjustedTimeAvg": 596239, "timeOffset": 0, "expectedBlocks": 650.895 } }<network-name> npm run change-owners -- --network <network-name>

Commits

Commits on Feb 28, 2025

Update README.md