diff --git a/DEMO.md b/DEMO.md index 037291c..8ed743b 100644 --- a/DEMO.md +++ b/DEMO.md @@ -2,13 +2,32 @@ These instructions describes how to run the bridge between an Ethereum-based chain and the Binance Chain testnet. +### Ethereum side of the bridge + +This demo supports two ways of dealing with the Ethereum side of a bridge: + - Using development EVM-base chains ([ganache](https://github.com/trufflesuite/ganache-cli)) + - Using public networks (predefined configs use Kovan testnet and Sokol POA testnet) + +#### Development mode + 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 (`0x44c158FE850821ae69DaF37AADF5c539e9d0025B`) and the bridge contract (`0x94b40CC641Ed7db241A1f04C8896ba6f6cC36b85`). - - **Side chain** - the MPC orchestration contract (`0x44c158FE850821ae69DaF37AADF5c539e9d0025B`) is located here + - **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. +#### Staging mode + +As part of this demo two EVM-based public chains will be used: + - **Home chain** - Kovan testnet keeps an ERC20 contract and the bridge contract. + - **Side chain** - Sokol POA testnet keeps the MPC orchestration contract. +Interaction with chains is done by using public available RPC urls. + +### 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`). +### Binance side of the bridge + The public Binance Chain testnet will keep a BEP2 token. ### Running demo @@ -56,28 +75,57 @@ The public Binance Chain testnet will keep a BEP2 token. docker build -t tss -f ./src/tss/Dockerfile-local ./src/tss ``` 2. Run test environment - * (2.1) Modify `src/deploy/deploy-test/.env` and specify the amount of tokens to mint in the parameter `TOKEN_INITIAL_MINT`. - * (2.2) Run testnets and deploy contracts - ``` - ./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 `PRIVATE_KEY_DEV` of `src/deploy/deploy-test/.env`. + * 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. ``` - ./src/test-services/ethereumSend/run.sh 5000000000000000000 0.5 + TARGET_NETWORK= ./src/test-services/ethereumSend/run.sh 5000000000000000000 0.5 ``` * (2.5) Check that the tokens were transferred properly: ``` - ./src/test-services/ethereumBalance/run.sh + TARGET_NETWORK= ./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. + * (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. ``` - N=1 ./demo/validator-demo.sh - N=2 ./demo/validator-demo.sh - N=3 ./demo/validator-demo.sh + N=1 TARGET_NETWORK= ./demo/validator-demo.sh + N=2 TARGET_NETWORK= ./demo/validator-demo.sh + N=3 TARGET_NETWORK= ./demo/validator-demo.sh ``` Wait for when the line like the following appears: ``` @@ -105,15 +153,17 @@ The public Binance Chain testnet will keep a BEP2 token. ``` 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. 5. Transfer tokens from Ethereum-based chain to the Binance Chain: - * (5.1) Modify the parameter `HOME_PRIVATE_KEY` as so it contains the private key of the first test account (step 1.2) + * (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: ``` - ./src/test-services/ethereumSend/run.sh bridge 5000000000000000000 + TARGET_NETWORK= ./src/test-services/ethereumSend/run.sh bridge 5000000000000000000 ``` * (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: ``` - ./src/test-services/ethereumBalance/run.sh 0x94b40CC641Ed7db241A1f04C8896ba6f6cC36b85 + TARGET_NETWORK= ./src/test-services/ethereumBalance/run.sh 0x94b40CC641Ed7db241A1f04C8896ba6f6cC36b85 ``` should report non-zero balance ``` @@ -150,7 +200,7 @@ The public Binance Chain testnet will keep a BEP2 token. ``` 4. Remove testnets and validators data: ``` - ./demo/clean.sh + TARGET_NETWORK= ./demo/clean.sh ``` #### Testing tools for both sides of the bridge @@ -163,10 +213,14 @@ In these tools, `run.sh` file simply builds and runs a docker container for inte - `NATIVE` - amount of BNB tokens to send, if present, the transaction is considered as a funding one. * `./src/test-services/ethereumSend/run.sh TO TOKENS NATIVE` - - Transfers specified amount of tokens and coins to the an Ethereum account. + - Transfers specified amount of tokens and coins to the an Ethereum account on the home network. - `TO` - receiver address in the Ethereum-based chain, specify `bridge` to send tokens to the bridge address. - `VALUE` - amount of tokens to transfer and exchange. - `NATIVE` - amount of coins to send (in `ether`). Could be omitted. +* `./src/test-services/sidePrefund/run.sh TO NATIVE` + - Transfers specified amount of tokens and coins to the an Ethereum account on the side network. + - `TO` - receiver address in the Ethereum-based chain. + - `NATIVE` - amount of coins to send (in `ether`). Could be omitted. * `./src/test-services/binanceBalance/run.sh ADDRESS` (it is recommended to use `tbnbcli` instead) - Gets current BEP2 token and BNB balances of the specified account. - `ADDRESS` - account address in the Binance Chain. @@ -194,4 +248,4 @@ container for listening GET requests - http://localhost:5001/vote/addValidator/ADDRESS - `ADDRESS` - Ethereum address of a validator. - After enough votes are collected, validator is removed from - the next validators list for the next epoch. \ No newline at end of file + the next validators list for the next epoch.