From 5240ae17aba70cfbad3f03c46a51ecf3195e1c07 Mon Sep 17 00:00:00 2001 From: Kirill Fedoseev Date: Tue, 12 Nov 2019 17:35:12 +0300 Subject: [PATCH] Updated demo instructions --- DEMO.md | 317 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 196 insertions(+), 121 deletions(-) diff --git a/DEMO.md b/DEMO.md index a408598..9dde9b6 100644 --- a/DEMO.md +++ b/DEMO.md @@ -13,7 +13,13 @@ This demo supports two ways of dealing with the Ethereum side of a bridge: As part of this demo two EVM-based chains ([ganache](https://github.com/trufflesuite/ganache-cli)) will be started: - **Home chain** - it keeps an ERC20 contract (`0xd5fE0D28e058D375b0b038fFbB446Da37E85fFdc`) and the bridge contract (`0x44c158FE850821ae69DaF37AADF5c539e9d0025B`). - **Side chain** - the MPC orchestration contract (`0xd5fE0D28e058D375b0b038fFbB446Da37E85fFdc`) is located here -Both chains are run in separate docker containers. +Both chains are run in separate docker containers. +JSON-RPC ports are mapped to the host (7545 - side chain, 8545 - home chain) + +Local Binance network within separate docker container will be used. +In addition, some part of Binance accelerated node [HTTP API](https://docs.binance.org/api-reference/dex-api/paths.html) +will be emulated, since a regular full-node API does not provide all required features. +APIs and NODE RPC ports are mapped to the host (26657 - RPC, 8080 - api-server, 8000 - emulated accelerated node api) #### Staging mode @@ -22,6 +28,9 @@ As part of this demo two EVM-based public chains will be used: - **Side chain** - Sokol POA testnet keeps the MPC orchestration contract. Interaction with chains is done by using public available RPC urls. +Public Binance testnet will be used for demo purposes. +Interaction with chain is done by using a public available HTTP API endpoint. + ### Demo validators Three validators will be run and only two validators are required to confirm the transfer. Every validator node is a set of docker containers (`eth-watcher`, `bnc-watcher`, `signer`, `proxy`, `redis`, `rabbitmq`). @@ -30,161 +39,92 @@ Three validators will be run and only two validators are required to confirm the The public Binance Chain testnet will keep a BEP2 token. -### Running demo +### Running demo in development mode 1. Preparation - * (1.1) Download `tbnbcli` from https://github.com/binance-chain/node-binary/tree/master/cli. - * (1.2) Create a new account through the [web-interface](https://testnet.binance.org/en/create) in the Binance testnet wallet. Copy the private key and mnemonic phrase. The private key will be used to import it in an Ethereum Wallet. The mnemonic phrase is to recover the BNB with `tbnbcli`. - * (1.3) Recover the account in the console with the mnemonic. - ``` - ./tbnbcli keys add test_account1 --recover - ``` - * (1.4) Create few BNB accounts from the console. They will be donors to provide enough funds to issue a BEP2 tokens (500 BNB required). - ``` - ./tbnbcli keys add test_account2 - ./tbnbcli keys add test_account3 - ``` - * (1.5) Register on the Binance site and fund the accounts from the [testnet faucet](https://www.binance.com/en/dex/testnet/address). - * (1.6) Re-arrange funds on the accounts as so the first account will have 550 BNB and others 10-20 BNBs to make transactions. - ``` - ./tbnbcli send --from test_account2 --to
\ - --amount 18500000000:BNB --chain-id=Binance-Chain-Nile \ - --node=data-seed-pre-2-s1.binance.org:80 --memo "donate" - ./tbnbcli send --from test_account3 --to
\ - --amount 18500000000:BNB --chain-id=Binance-Chain-Nile - --node=data-seed-pre-2-s1.binance.org:80 --memo "donate" - ``` - * (1.7) Issue the BEP2 token from the first account. `3141500000000000` corresponds to `31415000.0` tokens. - ``` - ./tbnbcli token issue --token-name "ERC20toBEP2Bridge" --total-supply 3141500000000000 \ - --symbol ETB0819 --mintable --from test_account1 --chain-id=Binance-Chain-Nile \ - --node=data-seed-pre-2-s1.binance.org:80 --trust-node - ``` - In the real deployment most probably the token must not be mintable. - * (1.8) Get the BEP2 token ID in `denom` field (in this example it is `ETB0819-863`). - ``` - ./tbnbcli account
\ - --chain-id=Binance-Chain-Nile --node=data-seed-pre-2-s1.binance.org:80 --trust-node - ``` - * (1.9) Clone the repo and initialize git submodules: + * (1.1) Clone the repo and initialize git submodules: ``` git clone --recurse-submodules https://github.com/k1rill-fedoseev/eth-to-bnc-bridge.git ``` - * (1.10) Build TSS to be used in the bridge oracles: + * (1.2) Build TSS to be used in the bridge oracles: ``` docker build -t tss ./src/tss ``` + * (1.3) Generate several private keys for bridge testing. (e. g. `openssl rand -hex 32`) + * (1.4) Get Ethereum and Binance addresses for recently created accounts via running + ``` + ./src/test-services/getAddresses/run.sh + ``` 2. Run test environment - * 2.1 Running in development mode (using local ganache networks): - * (2.1.1) Modify `src/deploy/deploy-test/.env.development` and specify the amount of tokens to mint in the parameter `TOKEN_INITIAL_MINT`. - * (2.1.2) Run testnets and deploy contracts - ``` - TARGET_NETWORK=development ./demo/start-environment.sh - ``` - This command will also mint tokens, the owner of tokens is the address that corresponds to the - private key specified in `HOME_PRIVATE_KEY` of `src/deploy/deploy-test/.env.development` (`0xA374DC09057D6B3253d04fACb15736B43fBc7943`). - * 2.2 Running in staging mode (using public test networks): - * (2.2.1) Prepare three private keys for validators. Get the Ethereum account addresses for these keys. - * (2.2.2) Modify `src/deploy/deploy-home/.env.staging` and specify the token contract address in - the Kovan network via `HOME_TOKEN_ADDRESS` (use empty address `0x` if you want to create new - ERC20 contract while deployment). \ - Set `VALIDATOR_ADDRESS_*` to Ethereum addresses obtained in the previous step. - * (2.2.3) Modify `src/deploy/.keys.staging` and specify private keys for prefunded accounts in both networks. - These accounts are used for contract deployment. Use `src/deploy/.keys.staging.example` as an example. - * (2.2.4) Deploy contracts - ``` - TARGET_NETWORK=staging ./demo/start-environment.sh - ``` - This command will deploy ERC20 contract and also mint tokens if you left `HOME_TOKEN_ADDRESS` empty, - the owner of tokens is the address that corresponds to the private key specified in - `HOME_PRIVATE_KEY` of `src/deploy/.keys.staging`.\ - Deployed contract address will be automatically updates in all required validators - and test services configs. - * (2.2.5) Prefund validator accounts in home network (Kovan): - ``` - TARGET_NETWORK=staging ./src/test-services/ethereumSend/run.sh 0 0.5 - ``` - * (2.2.6) Prefund validator accounts in side network (Sokol): - ``` - TARGET_NETWORK=staging ./src/test-services/sidePrefund/run.sh 1 - ``` - * (2.3) Get the Ethereum account address for the first test account from its private key (step 1.2). [NiftyWallet](https://forum.poa.network/c/nifty-wallet) could be used for this. - * (2.4) Send few tokens and coins from the current token owner to the first account. Coins are needed to pay transaction fees. + * (2.1) Modify `src/deploy/deploy-test/.env.development` and specify the amount of tokens to mint in the parameter `TOKEN_INITIAL_MINT`. + * (2.2) Run Ethereum testnets and deploy contracts ``` - TARGET_NETWORK= ./src/test-services/ethereumSend/run.sh 5000000000000000000 0.5 + TARGET_NETWORK=development ./demo/start-ethereum-environment.sh ``` - * (2.5) Check that the tokens were transferred properly: + This command will also mint tokens, the owner of tokens is the address that corresponds to the + private key specified in `HOME_PRIVATE_KEY` of `src/deploy/deploy-test/.env.development` (`0xA374DC09057D6B3253d04fACb15736B43fBc7943`). + * (2.4) Run Binance testnet and api services ``` - TARGET_NETWORK= ./src/test-services/ethereumBalance/run.sh + ./demo/start-binance-environment.sh + ``` + This command will also issue a BEP2 token, the owner of tokens is the address that corresponds to the + private key specified in `FOREIGN_PRIVATE_KEY` of `src/test-services/binanceSend/.env.development` (`tbnb1z7u9f8mcuwxanns9xa6qgjtlka0d392epc0m9x`). + The balance of `tbnb1z7u9f8mcuwxanns9xa6qgjtlka0d392epc0m9x` will contain 10000 BNB and 10000 Test Tokens. + * (2.5) Send few tokens and coins from the current token owner to the first account. Coins are needed to pay transaction fees. + ``` + ./src/test-services/ethereumSend/run.sh 5 0.5 + ``` + * (2.6) Check that the tokens were transferred properly: + ``` + ./src/test-services/ethereumBalance/run.sh ``` 3. Run validators nodes: - * (3.1) Modify the parameter `FOREIGN_ASSET` in `demo/validator1/.env.`, `demo/validator2/.env.` - and `demo/validator3/.env.` to specify the identificator of the token (step 1.8) that the oracle will watch. \ - For staging environment additionally specify `VALIDATOR_PRIVATE_KEY` in the `demo/validator/.keys.staging` (step 2.2.1) - * (3.2) Run three validators in separate terminal sessions. + * (3.1) Run three validators in separate terminal sessions. ``` - N=1 TARGET_NETWORK= ./demo/validator-demo.sh - N=2 TARGET_NETWORK= ./demo/validator-demo.sh - N=3 TARGET_NETWORK= ./demo/validator-demo.sh + N=1 ./demo/validator-demo.sh + N=2 ./demo/validator-demo.sh + N=3 ./demo/validator-demo.sh ``` Wait for when the line like the following appears: ``` keygen_1 | Generated multisig account in binance chain: tbnb1mutgnx9n9devmrjh3d0wz332fl8ymgel6tydx6 ``` - The line contains the address of the bridge address in the Bincance Chain. + The line contains the address of the bridge address in the Binance Chain. 4. Initialize the state of the bridge account in the Binance Chain * (4.1) Fill the balance Fund with BNB coins as so the account will be able to make transactions: ``` - ./tbnbcli send --from test_account1 --to
\ - --amount 1000000000:BNB --chain-id=Binance-Chain-Nile \ - --node=data-seed-pre-2-s1.binance.org:80 --memo "initialization" - ``` - * (4.2) Fund the account with bridgeable tokens. **This transaction should have 'funding' in the memo**: + ./src/test-services/binanceSend/run.sh
100 1 ``` - ./tbnbcli send --from test_account1 --to
\ - --amount 3141500000000000:ETB0819-863 --chain-id=Binance-Chain-Nile \ - --node=data-seed-pre-2-s1.binance.org:80 --memo "funding" - ``` - The oracles should catch this transaction but will ignore it: - ``` - bnc-watcher_1 | Fetching new transactions - bnc-watcher_1 | Sending api transactions request - bnc-watcher_1 | Found 1 new transactions - ``` - To check the balance of the bridge account the [Binance Testnet Explorer](https://testnet-explorer.binance.org) could be used. It should report about two assets owned by the account. + To check the balance of the bridge account use `./src/test-services/binanceBalance/run.sh
` 5. Transfer tokens from Ethereum-based chain to the Binance Chain: - * (5.1) Modify the parameter `HOME_PRIVATE_KEY` - (in `src/test-services/ethereumSend/.env.development` or `src/test-services/.keys.staging`) - as so it contains the private key of the first test account (step 1.2) - * (5.2) Send some amount of tokens to the bridge contract: + * (5.1) Send some amount of tokens to the bridge contract, for `PRIVATE_KEY` use some of the keys from step (1.3): ``` - TARGET_NETWORK= ./src/test-services/ethereumSend/run.sh bridge 5000000000000000000 + PRIVATE_KEY= ./src/test-services/ethereumSend/run.sh bridge 5 ``` - * (5.3) The validators will catch the event and start the process to sign the transaction. - * (5.4) As soon as the signature is generated and sent, the balance of the bridge account in both chains will be changed: + * (5.2) The validators will catch the event and start the process to sign the transaction. + * (5.3) As soon as the signature is generated and sent, the balance of the bridge account in both chains will be changed: ``` - TARGET_NETWORK= ./src/test-services/ethereumBalance/run.sh 0x94b40CC641Ed7db241A1f04C8896ba6f6cC36b85 + ./src/test-services/ethereumBalance/run.sh ``` - should report non-zero balance + should report non-zero balance, ``` - ./tbnbcli account
\ - --chain-id=Binance-Chain-Nile --node=data-seed-pre-2-s1.binance.org:80 --trust-node + ./src/test-services/binanceBalance/run.sh ``` should report about the balance reduction. - The balance and transactions related to the bridge account in the Binance Chain could be checked in [Binance Testnet Explorer](https://testnet-explorer.binance.org). - * (5.5) Check that the tokens was transferred to the first test account either by `tbnbcli` or by [Binance Testnet Explorer](https://testnet-explorer.binance.org). + * (5.4) Check that the tokens were transferred properly to the test account: + ``` + ./src/test-services/binanceBalance/run.sh + ``` 6. Transfer tokens from the Binance Chain to Ethereum-based chain: - * Use either `tbnbcli` or the [Binance testnet wallet](https://testnet.binance.org/) to send tokens to the bridge account: + * (6.1) Send some amount of tokens to the bridge account: ``` - ./tbnbcli send --from test_account1 --to
\ - --amount 300000000:ETB0819-863 --chain-id=Binance-Chain-Nile \ - --node=data-seed-pre-2-s1.binance.org:80 --memo "any note" + PRIVATE_KEY= ./src/test-services/binanceSend/run.sh 3 ``` - * Check the balances of the test account on both sides of the bridge to see that the funds were transferred properly. + * (6.2) Check the balances of the test account on both sides of the bridge to see that the funds were transferred properly using commands from (5.3), (5.4). 7. Bridge supports changing the list of validators and required voting threshold via voting process, and then keys regeneration. * (7.0) Obtain information about current epoch, current list validators, upcoming epoch information, bridge state via: ``` - ./curl http://localhost:$PORT/info + curl http://localhost:$PORT/info ``` Where `$PORT` is specific port for some validator oracle. The response object contains lots of useful information about current bridge state. @@ -247,21 +187,156 @@ The public Binance Chain testnet will keep a BEP2 token. * (7.2.2) Change threshold for the next epoch, via sending `$THRESHOLD` requests to `/vote/changeThreshold/$THRESHOLD`. * (7.3) Start keygen process for next epoch, via sending `$THRESHOLD` requests to `/vote/startKeygen` url. Bridge state should be successfully changed to `keygen`, and in some time to `funds_transfer`, and then to `ready`. - * (7.4) If keygen process at some state was stopped(i. e. one validator turned of his oracle), - it can be cancelled via via sending `$THRESHOLD + 1` requests to `/vote/cancelKeygen` url. After + * (7.4) If keygen process at some state was stopped(i. e. one validator turned off his oracle), + it can be cancelled via via sending `$THRESHOLD` requests to `/vote/cancelKeygen` url. After keygen cancellation, bridge state will return to `voting`, and later it can be restarted manually once again. +### Running demo in staging mode + +Staging mode demo is similar to development mode demo, but requires additional manual actions for preparing demo. +Make sure, to first run demo in development mode, before trying to run it in the staging environment. + +1. Preparation + * (1.1) Download `tbnbcli` from https://github.com/binance-chain/node-binary/tree/master/cli. + * (1.2) Create a new account through the [web-interface](https://testnet.binance.org/en/create) in the Binance testnet wallet. Copy the private key and mnemonic phrase. The private key will be used to import it in an Ethereum Wallet. The mnemonic phrase is to recover the BNB with `tbnbcli`. + * (1.3) Recover the account in the console with the mnemonic. + ``` + ./tbnbcli keys add test_account1 --recover + ``` + * (1.4) Create few BNB accounts from the console. They will be donors to provide enough funds to issue a BEP2 tokens (500 BNB required). + ``` + ./tbnbcli keys add test_account2 + ./tbnbcli keys add test_account3 + ``` + * (1.5) Register on the Binance site and fund the accounts from the [testnet faucet](https://www.binance.com/en/dex/testnet/address). + * (1.6) Re-arrange funds on the accounts as so the first account will have 550 BNB and others 10-20 BNBs to make transactions. + ``` + ./tbnbcli send --from test_account2 --to
\ + --amount 18500000000:BNB --chain-id=Binance-Chain-Nile \ + --node=data-seed-pre-2-s1.binance.org:80 --memo "donate" + ./tbnbcli send --from test_account3 --to
\ + --amount 18500000000:BNB --chain-id=Binance-Chain-Nile + --node=data-seed-pre-2-s1.binance.org:80 --memo "donate" + ``` + * (1.7) Issue the BEP2 token from the first account. `3141500000000000` corresponds to `31415000.0` tokens. + ``` + ./tbnbcli token issue --token-name "ERC20toBEP2Bridge" --total-supply 3141500000000000 \ + --symbol ETB0819 --mintable --from test_account1 --chain-id=Binance-Chain-Nile \ + --node=data-seed-pre-2-s1.binance.org:80 --trust-node + ``` + In the real deployment most probably the token must not be mintable. + * (1.8) Get the BEP2 token ID in `denom` field (in this example it is `ETB0819-863`). + ``` + ./tbnbcli account
\ + --chain-id=Binance-Chain-Nile --node=data-seed-pre-2-s1.binance.org:80 --trust-node + ``` + * (1.9) Clone the repo and initialize git submodules: + ``` + git clone --recurse-submodules https://github.com/k1rill-fedoseev/eth-to-bnc-bridge.git + ``` + * (1.10) Build TSS to be used in the bridge oracles: + ``` + docker build -t tss ./src/tss + ``` +2. Run test environment + * (2.1) Prepare three private keys for validators. Get the Ethereum account addresses for these keys. + * (2.2) Modify `src/deploy/deploy-home/.env.staging` and specify the token contract address in + the Kovan network via `HOME_TOKEN_ADDRESS` (use empty address `0x` if you want to create new + ERC20 contract while deployment). \ + Set `VALIDATOR_ADDRESS_*` to Ethereum addresses obtained in the previous step. + * (2.3) Modify `src/deploy/.keys.staging` and specify private keys for prefunded accounts in both networks. + These accounts are used for contract deployment. Use `src/deploy/.keys.staging.example` as an example. + * (2.4) Deploy contracts + ``` + TARGET_NETWORK=staging ./demo/start-ethereum-environment.sh + ``` + This command will deploy ERC20 contract and also mint tokens if you left `HOME_TOKEN_ADDRESS` empty, + the owner of tokens is the address that corresponds to the private key specified in + `HOME_PRIVATE_KEY` of `src/deploy/.keys.staging`.\ + Deployed contract addresses will be automatically updated in all required validators + and test services configs. + * (2.5) Prefund validator accounts in home network (Kovan): + ``` + TARGET_NETWORK=staging ./src/test-services/ethereumSend/run.sh 0 0.5 + ``` + * (2.6) Prefund validator accounts in side network (Sokol): + ``` + TARGET_NETWORK=staging ./src/test-services/sidePrefund/run.sh 1 + ``` + * (2.7) Send few tokens and coins from the current token owner to the first account. Coins are needed to pay transaction fees. + ``` + TARGET_NETWORK=staging ./src/test-services/ethereumSend/run.sh 5 0.5 + ``` + * (2.8) Check that the tokens were transferred properly: + ``` + TARGET_NETWORK=staging ./src/test-services/ethereumBalance/run.sh + ``` +3. Run validators nodes: + * (3.1) Modify the parameter `FOREIGN_ASSET` in `demo/validator1/.env.staging`, `demo/validator2/.env.staging` + and `demo/validator3/.env.staging` to the identificator of the token (step 1.8) that the oracle will track. \ + For staging environment additionally specify `VALIDATOR_PRIVATE_KEY` in the `demo/validator/.keys.staging` (step 2.2.1) + * (3.2) Run three validators in separate terminal sessions. + ``` + N=1 TARGET_NETWORK=staging ./demo/validator-demo.sh + N=2 TARGET_NETWORK=staging ./demo/validator-demo.sh + N=3 TARGET_NETWORK=staging ./demo/validator-demo.sh + ``` + Wait for when the line like the following appears: + ``` + keygen_1 | Generated multisig account in binance chain: tbnb1mutgnx9n9devmrjh3d0wz332fl8ymgel6tydx6 + ``` + The line contains the address of the bridge address in the Binance Chain. +4. Initialize the state of the bridge account in the Binance Chain + * (4.1) Fill the balance Fund with BNB coins as so the account will be able to make transactions: + ``` + ./src/test-services/binanceSend/run.sh
100 1 + ``` + To check the balance of the bridge account use `./src/test-services/binanceBalance/run.sh` + or [Binance Testnet Explorer](https://testnet-explorer.binance.org). It should report about two assets owned by the account. +5. Transfer tokens from Ethereum-based chain to the Binance Chain: + * (5.1) Send some amount of tokens to the bridge contract, for `PRIVATE_KEY` use some of the keys from step (1.3): + ``` + TARGET_NETWORK=staging PRIVATE_KEY= ./src/test-services/ethereumSend/run.sh bridge 5 + ``` + * (5.2) The validators will catch the event and start the process to sign the transaction. + * (5.3) As soon as the signature is generated and sent, the balance of the bridge account in both chains will be changed: + ``` + ./src/test-services/ethereumBalance/run.sh + ``` + should report non-zero balance, + ``` + ./src/test-services/binanceBalance/run.sh + ``` + should report about the balance reduction. + * (5.4) Check that the tokens were transferred properly to the test account: + ``` + ./src/test-services/binanceBalance/run.sh + ``` + The balance and transactions related to the bridge account in the Binance Chain could be checked in + [Binance Testnet Explorer](https://testnet-explorer.binance.org). +6. Transfer tokens from the Binance Chain to Ethereum-based chain: + * (6.1) Send some amount of tokens to the bridge account: + ``` + TARGET_NETWORK=staging PRIVATE_KEY= ./src/test-services/binanceSend/run.sh 3 + ``` + * (6.2) Check the balances of the test account on both sides of the bridge to see that the funds were transferred properly using commands from (5.3), (5.4). +7. Steps for updating validators list are exactly the same for both demo modes. Check the steps from development mode. + ### Finish demo 1. Stop all validator instances by pressing `^C` in the terminal. -2. Stop the local testnets: +2. Stop the local testnets (if any): ``` + docker kill binance-testnet_http-api_1 + docker kill binance-testnet_node_1 + docker kill binance-testnet_api-server_1 docker kill ganache_home docker kill ganache_side ``` 3. Remove virtual networks: ``` + docker network rm binance_net docker network rm blockchain_home docker network rm blockchain_side docker network rm validator1_test_network