{"id":13791363,"url":"https://github.com/omni/tokenbridge-contracts","last_synced_at":"2025-05-12T10:31:40.130Z","repository":{"id":29317703,"uuid":"121341498","full_name":"omni/tokenbridge-contracts","owner":"omni","description":"Smart contracts for TokenBridge","archived":false,"fork":false,"pushed_at":"2024-04-03T06:46:32.000Z","size":8623,"stargazers_count":222,"open_issues_count":86,"forks_count":224,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-05-19T00:46:46.665Z","etag":null,"topics":["bridge","bridge-validators","solidity"],"latest_commit_sha":null,"homepage":"http://docs.tokenbridge.net","language":"JavaScript","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/omni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-13T05:10:29.000Z","updated_at":"2024-08-03T22:05:08.083Z","dependencies_parsed_at":"2024-08-03T22:04:55.606Z","dependency_job_id":"02f25d10-f247-421a-b2d0-734c330c858b","html_url":"https://github.com/omni/tokenbridge-contracts","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni%2Ftokenbridge-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni%2Ftokenbridge-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni%2Ftokenbridge-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni%2Ftokenbridge-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omni","download_url":"https://codeload.github.com/omni/tokenbridge-contracts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253719964,"owners_count":21952934,"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":["bridge","bridge-validators","solidity"],"created_at":"2024-08-03T22:00:59.324Z","updated_at":"2025-05-12T10:31:39.581Z","avatar_url":"https://github.com/omni.png","language":"JavaScript","funding_links":[],"categories":["Roadmap","JavaScript"],"sub_categories":[],"readme":"[![Join the chat at https://gitter.im/poanetwork/poa-bridge](https://badges.gitter.im/poanetwork/poa-bridge.svg)](https://gitter.im/poanetwork/poa-bridge?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Build Status](https://github.com/poanetwork/tokenbridge-contracts/workflows/tokenbridge-contracts/badge.svg?branch=master)](https://github.com/poanetwork/tokenbridge-contracts/workflows/tokenbridge-contracts/badge.svg?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/poanetwork/tokenbridge-contracts/badge.svg?branch=master)](https://coveralls.io/github/poanetwork/tokenbridge-contracts?branch=master)\n\n# POA Bridge Smart Contracts\nThese contracts provide the core functionality for the POA bridge. They implement the logic to relay assests between two EVM-based blockchain networks. The contracts collect bridge validator's signatures to approve and facilitate relay operations.\n\nThe POA bridge smart contracts are intended to work with [the bridge process implemented on NodeJS](https://github.com/poanetwork/token-bridge).\nPlease refer to the bridge process documentation to configure and deploy the bridge.\n\n## Bridge Overview\n\nThe POA Bridge allows users to transfer assets between two chains in the Ethereum ecosystem. It is composed of several elements which are located in different POA Network repositories:\n\n**Bridge Elements**\n1. Solidity smart contracts, contained in this repository.\n2. [Token Bridge](https://github.com/poanetwork/token-bridge). A NodeJS oracle responsible for listening to events and sending transactions to authorize asset transfers.\n3. [Bridge UI Application](https://github.com/poanetwork/bridge-ui). A DApp interface to transfer tokens and coins between chains.\n4. [Bridge Monitor](https://github.com/poanetwork/bridge-monitor). A tool for checking balances and unprocessed events in bridged networks.\n5. [Bridge Deployment Playbooks](https://github.com/poanetwork/deployment-bridge). Manages configuration instructions for remote deployments.\n\n## Bridge Smart Contracts Summary\n\n### Operations\n\nCurrently, the contracts support four types of relay operations:\n* Tokenize the native coin in one blockchain network (Home) into an ERC20 token in another network (Foreign).\n* Swap a token presented by an existing ERC20 contract in a Foreign network into an ERC20 token in the Home network, where one pair of bridge contracts corresponds to one pair of ERC20 tokens.\n* to mint new native coins in Home blockchain network from a token presented by an existing ERC20 contract in a Foreign network.\n* Transfer arbitrary data between two blockchain networks as so the data could be interpreted as an arbitrary contract method invocation.\n\n### Components\n\nThe POA bridge contracts consist of several components:\n* The **Home Bridge** smart contract. This is currently deployed in POA.Network.\n* The **Foreign Bridge** smart contract. This is deployed in the Ethereum Mainnet.\n* Depending on the type of relay operations the following components are also used:\n  * in `AMB-ERC-TO-ERC` mode: the ERC20 token (in fact, the ERC677 extension is used) is deployed on the Home network;\n  * in `ERC-TO-NATIVE` mode: The home network nodes must support consensus engine that allows using a smart contract for block reward calculation;\n* The **Validators** smart contract is deployed in both the POA.Network and the Ethereum Mainnet.\n\n### Bridge Roles and Responsibilities\n\nResponsibilities and roles of the bridge:\n- **Administrator** role (representation of a multisig contract):\n  - add/remove validators\n  - set daily limits on both bridges\n  - set maximum per transaction limit on both bridges\n  - set minimum per transaction limit on both bridges\n  - upgrade contracts in case of vulnerability\n  - set minimum required signatures from validators in order to relay a user's transaction\n- **Validator** role:\n  - provide 100% uptime to relay transactions\n  - listen for `UserRequestForSignature` events on Home Bridge and sign an approval to relay assets on Foreign network\n  - listen for `CollectedSignatures` events on Home Bridge. As soon as enough signatures are collected, transfer all collected signatures to the Foreign Bridge contract.\n  - listen for `UserRequestForAffirmation` or `Transfer` (depending on the bridge mode) events on the Foreign Bridge and send approval to Home Bridge to relay assets from Foreign Network to Home\n- **User** role:\n  - sends assets to Bridge contracts:\n    - in `ERC-TO-NATIVE` mode: send ERC20 tokens to the Foreign Bridge to receive native coins from the Home Bridge, send native coins to the Home Bridge to unlock ERC20 tokens from the Foreign Bridge;\n    - in `ARBITRARY-MESSAGE` mode: Invoke Home/Foreign Bridge to send a message that will be executed on the other Network as an arbitrary contract method invocation;\n    - in `AMB-ERC-TO-ERC` mode: transfer ERC20 tokens to the Foreign Mediator which will interact with Foreign AMB Bridge to mint ERC20 tokens on the Home Network, transfer ERC20 tokens to the Home Mediator which will interact with Home AMB Bridge to unlock ERC20 tokens on Foreign network.\n\n## Usage\n\nThere are two ways to deploy contracts:\n* install and use NodeJS\n* use Docker to deploy\n\n### Deployment with NodeJS\n\n#### Install Dependencies\n```bash\nnpm install\n```\n#### Deploy\nPlease read the [README.md](deploy/README.md) in the `deploy` folder for instructions and .env file configuration\n\n#### Test\n```bash\nnpm test\n```\n\n#### Run coverage tests\n```bash\nnpm run coverage\n```\n\nThe results can be found in the `coverage` directory.\n\n#### Flatten\nFattened contracts can be used to verify the contract code in a block explorer like BlockScout or Etherscan.\nThe following command will prepare flattened version of the contracts:\n\n```bash\nnpm run flatten\n```\nThe flattened contracts can be found in the `flats` directory.\n\n### Deployment in the Docker environment\n[Docker](https://www.docker.com/community-edition) and [Docker Compose](https://docs.docker.com/compose/install/) can be used to deploy contracts without NodeJS installed on the system.\nIf you are on Linux, we recommend you [create a docker group and add your user to it](https://docs.docker.com/install/linux/linux-postinstall/), so that you can use the CLI without `sudo`.\n\n#### Prepare the docker container\n```bash\ndocker-compose up --build\n```\n_Note: The container must be rebuilt every time the code in a contract or deployment script is changed._\n\n#### Deploy the contracts\n1. Create the `.env` file in the `deploy` directory as described in the deployment [README.md](deploy/README.md).\n2. Run deployment process:\n   ```bash\n   docker-compose run bridge-contracts deploy.sh\n   ```\n   or with Linux:\n   ```bash\n   ./deploy.sh\n   ```\n\n#### Copy flatten sources (if needed)\n1. Discover the container name:\n   ```bash\n   docker-compose images bridge-contracts\n   ```\n2. In the following command, use the container name to copy the flattened contracts code to the current working directory. The contracts will be located in the `flats` directory.\n   ```bash\n   docker cp name-of-your-container:/contracts/flats ./\n   ```\n\n#### Test contract and run coverage (if needed)\n```bash\n$ docker-compose run bridge-contracts bash\n$ npm test\n$ npm run coverage\n```\n\n#### Shutdown the container\nIf the container is no longer needed, it can be shutdown:\n```bash\ndocker-compose down\n```\n\n### Gas Consumption\nThe [GAS_CONSUMPTION](GAS_CONSUMPTION.md) file includes Min, Max, and Avg gas consumption figures for contracts associated with each bridge mode.\n\n### Reward Management\nThe [REWARD_MANAGEMENT](REWARD_MANAGEMENT.md) file includes information on how rewards are distributed among the validators on each bridge mode.\n\n### Testing environment\nTo test the bridge scripts in ERC20-to-ERC20 mode on a testnet like Sokol or Kovan, you must deploy an ERC20 token to the foreign network.\nThis can be done by running the following command:\n```bash\ncd deploy\nnode testenv-deploy.js token\n```\nor with Docker:\n```bash\n./deploy.sh token\n```\n\n## Contributing\n\nSee the [CONTRIBUTING](CONTRIBUTING.md) document for contribution, testing and pull request protocol.\n\n## License\n\n[![License: GPL v3.0](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nThis project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomni%2Ftokenbridge-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomni%2Ftokenbridge-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomni%2Ftokenbridge-contracts/lists"}