{"id":13746503,"url":"https://github.com/maticnetwork/pos-portal","last_synced_at":"2025-05-14T20:08:19.573Z","repository":{"id":37961861,"uuid":"255267642","full_name":"maticnetwork/pos-portal","owner":"maticnetwork","description":"Smart contracts that powers the PoS (proof-of-stake) based bridge mechanism for Matic Network","archived":false,"fork":false,"pushed_at":"2024-12-06T13:56:26.000Z","size":61777,"stargazers_count":386,"open_issues_count":37,"forks_count":270,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-09T01:37:07.182Z","etag":null,"topics":["blockchain","ethereum","matic","web3"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maticnetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audits/ChainSecurity_Polygon_PoS_Portal_audit.pdf","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-13T08:09:31.000Z","updated_at":"2025-04-04T22:56:41.000Z","dependencies_parsed_at":"2023-02-18T05:00:45.086Z","dependency_job_id":"517b8510-cd9e-4149-9b79-265e20868887","html_url":"https://github.com/maticnetwork/pos-portal","commit_stats":{"total_commits":561,"total_committers":17,"mean_commits":33.0,"dds":"0.47593582887700536","last_synced_commit":"5fbd35ba9cdc8a07bf32d81d6d1f4ce745feabd6"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maticnetwork%2Fpos-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maticnetwork%2Fpos-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maticnetwork%2Fpos-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maticnetwork%2Fpos-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maticnetwork","download_url":"https://codeload.github.com/maticnetwork/pos-portal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248759566,"owners_count":21157192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","ethereum","matic","web3"],"created_at":"2024-08-03T06:00:54.700Z","updated_at":"2025-05-14T20:08:19.567Z","avatar_url":"https://github.com/maticnetwork.png","language":"Solidity","funding_links":[],"categories":["Smart Contract Platforms"],"sub_categories":[],"readme":"# Matic PoS (Proof-of-Stake) portal contracts\n\n![Build Status](https://github.com/maticnetwork/pos-portal/workflows/CI/badge.svg)\n\nSmart contracts that powers the PoS (proof-of-stake) based bridge mechanism for [Matic Network](https://matic.network). \n\n## Audits\n\n- [Hexens](audits/Matic_PoS_upd.pdf)\n- [Halborn](audits/Pos-portal-halborn-audit-07-07-2021.pdf)\n- [CertiK](audits/Matic.Audit.CertiK.Report.pdf)\n- [PeckShield](audits/Pos-portal-peckshield-audit-30-07-2021.pdf)\n\n## Usage\n\nInstall package from **NPM** using\n\n```bash\nnpm i @maticnetwork/pos-portal\n```\n\n## Develop\n\nMake sure you've NodeJS \u0026 NPM installed\n\n```bash\nnode --version\nv10.24.1\n\nnpm --version\n6.14.12\n```\n\n## Test\n\nMake sure you have installed NVM and switched to the correct node version\n\n```bash\nnvm -v\n0.39.7\n\nnvm use\nnpm run test\n```\n\nClone repository \u0026 install all dependencies\n\n```bash\ngit clone https://github.com/maticnetwork/pos-portal\ncd pos-portal\n\nnpm i\n```\n\nCompile all contracts\n\n```bash\nnpm run template:process\nnpm run build\n```\n\nIf you prefer not using docker for compiling contracts, consider setting `docker: false` in truffle-config.js.\n\n```js\n// file: truffle-config.js\n...\n\n127|    solc: {\n128|        version: '0.6.6',\n129|        docker: false,\n        }\n...\n```\n\nFor deploying all contracts in `pos-portal`, we need to have at least two chains running --- simulating RootChain ( Ethereum ) \u0026 ChildChain ( Polygon ). There are various ways of building this multichain setup, though two of them are majorly used\n\n1. With `matic-cli`\n2. Without `matic-cli`\n\n`matic-cli` is a project, which makes setting up all components of Ethereum \u003c-\u003e Polygon multichain ecosystem easier. Three components matic-cli sets up for you\n\n- Ganache ( simulating RootChain )\n- Heimdall ( validator node of Polygon )\n- Bor ( block production layer of Polygon i.e. ChildChain )\n\nYou may want to check [matic-cli](https://github.com/maticnetwork/matic-cli).\n\n---\n\n### 1. With `matic-cli`\n\nAssuming you've installed `matic-cli` \u0026 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.\n\nThis should give you RPC listen addresses for both RootChain ( read Ganache ) \u0026 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.\n\n`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* ) \u0026 StateReceiver contract ( deployed on Bor ). These two contract addresses need to be updated [here](migrations/config.js).\n\n\u003e You may not need to change `stateReceiver` field, because that's where Bor deploys respective contract, by default.\n\n\u003e 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.\n\n```js\n// file: migrations/config.js\n\nmodule.exports = {\n  plasmaRootChain: '0x\u003cfill-it-up\u003e', // aka checkpointer\n  stateReceiver: '0x0000000000000000000000000000000000001001'\n}\n```\n\nNow you can update preferred mnemonic to be used for migration in [truffle config](truffle-config.js)\n\n```js\n// file: truffle-config.js\n\n29| const MNEMONIC = process.env.MNEMONIC || '\u003cpreferred-mnemonic\u003e'\n```\n\nAlso consider updating network configurations for `root` \u0026 `child` in truffle-config.js\n\n```js\n// make sure host:port of RPC matches properly\n// that's where all following transactions to be sent\n\n52| root: {\n        host: 'localhost',\n        port: 9545,\n        network_id: '*', // match any network\n        skipDryRun: true,\n        gas: 7000000,\n        gasPrice: '0'\n    },\n    child: {\n        host: 'localhost',\n        port: 8545,\n        network_id: '*', // match any network\n        skipDryRun: true,\n        gas: 7000000,\n        gasPrice: '0'\n67| },\n```\n\nNow start migration, which is 4-step operation\n\nMigration Step | Effect\n:-- | --:\n`migrate:2` | Deploys all rootchain contracts, on Ganache\n`migrate:3` | Deploys all childchain contracts, on Bor\n`migrate:4` | Initialises rootchain contracts, on Ganache\n`migrate:5` | Initialises childchain contracts, on Bor\n\n\n```bash\n# assuming you're in root of pos-portal\n\nnpm run migrate # runs all steps\n```\n\nYou'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.\n\n\u003e 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.\n\n\u003e Migration files are kept here `./migrations/{1,2,3,4,5}*.js`\n\n---\n\n### 2. Without `matic-cli`\n\nYou can always independently start a Ganache instance to act as RootChain \u0026 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.\n\nStart RootChain by\n\n```bash\nnpm run testrpc # RPC on localhost:9545 --- default\n```\n\nNow start ChildChain ( requires docker )\n\n```bash\nnpm run bor # RPC on localhost:8545 --- default\n```\n\n\u003e If you ran a bor instance before, a dead docker container might still be lying around, clean it using following command:\n\n```bash\nnpm run bor:clean # optional\n```\n\nRun testcases\n\n```bash\nnpm run test\n```\n\nDeploy contracts on local Ganache \u0026 Bor instance\n\n```bash\nnpm run migrate\n```\n\nThis should generate `./contractAddresses.json`, which contains all deployed contract addresses --- use it for interacting with those.\n\n---\n\n### Production\n\n\u003e Use this guide for deploying contracts in Ethereum Mainnet.\n\n1. Moonwalker needs rabbitmq and local geth running\n```bash\ndocker run -d -p 5672:5672 -p 15672:15672 rabbitmq:3-management\nnpm run testrpc\n```\n\n2. Export env vars\n```bash\nexport MNEMONIC=\nexport FROM=\nexport PROVIDER_URL=\nexport ROOT_CHAIN_ID=\nexport CHILD_CHAIN_ID=\nexport PLASMA_ROOT_CHAIN=\nexport GAS_PRICE=\n```\n\n3. Compile contracts\n```bash\nnpm run template:process -- --root-chain-id $ROOT_CHAIN_ID --child-chain-id $CHILD_CHAIN_ID\nnpm run build\n```\n\n4. Add root chain contract deployments to queue\n```bash\nnpm run truffle exec moonwalker-migrations/queue-root-deployment.js\n```\n\n5. Process queue (rerun if interrupted)\n```bash\nnode moonwalker-migrations/process-queue.js\n```\n\n6. Extract contract addresses from moonwalker output\n```bash\nnode moonwalker-migrations/extract-addresses.js\n```\n\n7. Deploy child chain contracts\n```bash\nnpm run truffle -- migrate --network mainnetChild --f 3 --to 3\n```\n\n8. Add root chain initializations to queue\n```bash\nnode moonwalker-migrations/queue-root-initializations.js\n```\n\n9. Process queue (rerun if interrupted)\n```bash\nnode moonwalker-migrations/process-queue.js\n```\n\n10. Initialize child chain contracts\n```bash\nnpm run truffle -- migrate --network mainnetChild --f 5 --to 5\n```\n\n11. Register State Sync\n- Register RootChainManager and ChildChainManager on StateSender\n- Set stateSenderAddress on RootChainManager\n- Grant STATE_SYNCER_ROLE on ChildChainManager\n\n---\n\n### Command scripts (Management scripts)\n\n```bash\nnpm run truffle exec scripts/update-implementation.js -- --network \u003cnetwork-name\u003e \u003cnew-address\u003e\n```\n\n---\n\n### Transfer proxy ownership and admin role\nSet list of contract addresses and new owner address in `6_change_owners.js` migration script  \nSet `MNEMONIC` and `API_KEY` as env variables\n```bash\nnpm run change-owners -- --network \u003cnetwork-name\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaticnetwork%2Fpos-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaticnetwork%2Fpos-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaticnetwork%2Fpos-portal/lists"}