{"id":19382415,"url":"https://github.com/bnb-chain/bsc-relayer","last_synced_at":"2025-08-14T02:33:08.930Z","repository":{"id":39519032,"uuid":"265484077","full_name":"bnb-chain/bsc-relayer","owner":"bnb-chain","description":"An implementation of relay service to relay cross chain packages from BNB Beacon Chain to BNB Smart Chain","archived":false,"fork":false,"pushed_at":"2024-06-18T03:26:02.000Z","size":197,"stargazers_count":102,"open_issues_count":1,"forks_count":52,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-12-08T01:40:20.961Z","etag":null,"topics":["blockchain","bsc-relayer","cross-chain","interchain","relayer"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bnb-chain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2020-05-20T07:23:11.000Z","updated_at":"2024-11-15T07:04:25.000Z","dependencies_parsed_at":"2024-06-20T15:35:16.169Z","dependency_job_id":null,"html_url":"https://github.com/bnb-chain/bsc-relayer","commit_stats":null,"previous_names":["binance-chain/bsc-relayer"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb-chain%2Fbsc-relayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb-chain%2Fbsc-relayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb-chain%2Fbsc-relayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnb-chain%2Fbsc-relayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnb-chain","download_url":"https://codeload.github.com/bnb-chain/bsc-relayer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229795874,"owners_count":18125286,"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","bsc-relayer","cross-chain","interchain","relayer"],"created_at":"2024-11-10T09:21:13.672Z","updated_at":"2024-12-15T08:07:12.697Z","avatar_url":"https://github.com/bnb-chain.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Relayer service from BBC to BSC\n\nThis is an canonical implementation of [bsc-relayer](https://github.com/bnb-chain/whitepaper/blob/master/WHITEPAPER.md#bsc-relayers) service to relay cross chain packages from BNB Beacon Chain to BNB Smart Chain. It can also monitor double sign behavior on BSC and submit evidence to BNB Chain Chain. Community members are encouraged to implement more implementations according to their own requirements.\n\n## Quick Start\n\n**Note**: Requires [Go 1.19+](https://golang.org/dl/)\n\n### Setup config\n\n1. Edit `config/config.json` and input your private key to `bsc_config.private_key`\n2. Transfer enough BNB to this account - more than 10:BNB for transaction fee.\n3. Setup relayer mode:\n    ```json\n    {\n      \n      \"competition_mode\": true\n      \n    }\n    ```\n   If `competition_mode` is true, `bsc-relayer` will monitor cross chain packages in every block and try to deliver the packages immediately. Otherwise, `bsc-relayer` will check if there are undelivered packages in every `clean_up_block_interval` blocks and batch deliver these packages. Competition mode can accelerate package delivery but will cost more transaction fee. In contrary, in non-competition mode, package delivery will be slower but less transaction fee will be cost. \n   \n4. If you want to monitor double sign behavior on BSC, you need to fill more than 1 endpoints in `bsc_config.monitor_data_seed_list`.\n\n    3.1 Testnet `monitor_data_seed_list`:\n    ```json\n    {\n      \"monitor_data_seed_list\": [\n          \"wss://data-seed-prebsc-1-s1.binance.org:8545\",\n          \"wss://data-seed-prebsc-2-s1.binance.org:8545\",\n          \"wss://data-seed-prebsc-1-s2.binance.org:8545\",\n          \"wss://data-seed-prebsc-2-s2.binance.org:8545\",\n          \"wss://data-seed-prebsc-1-s3.binance.org:8545\",\n          \"wss://data-seed-prebsc-2-s3.binance.org:8545\"\n        ]\n    }\n    ```\n   \n   3.2 Mainnet: `monitor_data_seed_list`:\n   ```json\n   {\n     \"monitor_data_seed_list\": [\n           \"wss://bsc-dataseed1.binance.org:443\",\n           \"wss://bsc-dataseed2.binance.org:443\",\n           \"wss://bsc-dataseed3.binance.org:443\",\n           \"wss://bsc-dataseed4.binance.org:443\",\n           \"wss://bsc-dataseed1.defibit.io:443\",\n           \"wss://bsc-dataseed2.defibit.io:443\",\n           \"wss://bsc-dataseed3.defibit.io:443\",\n           \"wss://bsc-dataseed4.defibit.io:443\",\n           \"wss://bsc-dataseed1.ninicoin.io:443\",\n           \"wss://bsc-dataseed2.ninicoin.io:443\",\n           \"wss://bsc-dataseed3.ninicoin.io:443\",\n           \"wss://bsc-dataseed4.ninicoin.io:443\"\n       ]\n   }\n   ```\n   Besides, you also need to provide proper BNB Beacon Chain `mnemonic`.\n   \n5. The supported db platforms include `mysql` and `sqlite3`. This is an example db config:\n    ```json\n    {\n       \"dialect\": \"mysql\",\n       \"db_path\": \"relayer:12345678@(localhost:3306)/bsc_relayer?charset=utf8\u0026parseTime=True\u0026loc=Local\"\n    }\n    ```\n   If you don't want to specify a db for your bsc-relayer, just leave `db_path` to empty.\n   \n6. Send alert telegram message when the balance of relayer account is too low. This is an example alert config:\n    ```json\n    {\n        \"enable_alert\": true,\n        \"enable_heart_beat\": false,\n        \"interval\": 300,\n        \"telegram_bot_id\": \"your_bot_id\",\n        \"telegram_chat_id\": \"your_chat_id\",\n        \"balance_threshold\": \"1000000000000000000\",\n        \"sequence_gap_threshold\": 10\n    }\n    ```\n   Please refer to [telegram_bot](https://www.home-assistant.io/integrations/telegram_bot) to setup your telegram bot. If you don't want this feature, just set `enable_alert` to false.\n\n### Build\n\n#### Build Binary:\n```shell script\nmake build\n```\n\n#### Build Docker Image\n\n- Please complete configuration setup in `config/config.json` first, mainly including rpc endpoints, BSC private key and BC mnemonic(if you want to submit double sign evidence)\n- Docker build command:\n```shell script\ndocker build -t bsc-relayer:latest .\n```\n\n### Run\n\nRun locally for testnet:\n```shell script\n./build/bsc-relayer --bbc-network-type 0 --config-type local --config-path config/config.json\n```\n\nRun locally for mainnet:\n```shell script\n./build/bsc-relayer --bbc-network-type 1 --config-type local --config-path config/config.json\n```\n\nRun docker for testnet:\n```shell script\ndocker run -e BBC_NETWORK=0 -e CONFIG_TYPE=\"local\" -d -it bsc-relayer\n```\n\nRun docker for mainnet:\n```shell script\ndocker run -e BBC_NETWORK=1 -e CONFIG_TYPE=\"local\" -d -it bsc-relayer\n```\n\n### TroubleShooting\n\n1. Please fill proper bsc private key to `bsc_config.private_key`, example private key: `your_private_key`\n\n    ```\n    panic: privateKey of BNB Smart Chain should not be empty\n    \n    goroutine 1 [running]:\n    ```\n\n2. Please fill your mnemonic to `bbc_config.mnemonic`, example mnemonic: `your_mnemonic`\n\n    ```\n    ERROR main missing local mnemonic\n    ```\n\n### Monitor Relayer Status\n\nTo enable this function, you must specify proper db config for your relayer. Suppose `8080` is the admin port: \n```shell script\ncurl localhost:8080/status\n```\n\nExample response:\n```json\n{\n    \"total_tx\": 82,\n    \"success_tx\": 36,\n    \"failed_tx\": 46,\n    \"sync_header_tx\": 41,\n    \"deliver_package_tx\": 41,\n    \"accumulated_total_tx_fee\": \"0.14336928:BNB\",\n    \"accumulated_success_tx_fee\": \"0.1030536:BNB\",\n    \"accumulated_failed_tx_fee\": \"0.04031568:BNB\",\n    \"update_time\": \"2020-07-14 06:59:39 PM\"\n}\n```\n\n## License\n\nThe library is licensed under the [GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html),\nalso included in our repository in the [LICENSE](LICENSE) file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnb-chain%2Fbsc-relayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnb-chain%2Fbsc-relayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnb-chain%2Fbsc-relayer/lists"}