Added document of Bifrost/ISOT cross chain function (#134)

Signed-off-by: Qiannan Lyu <lvqiannan@gmail.com>
bifrost-io · Jun 8, 2021 · dd6851b · dd6851b
1 parent fb1d14d
commit dd6851b
Show file tree

Hide file tree

Showing 9 changed files with 139 additions and 75 deletions.
diff --git a/docs/iost/README.md b/docs/iost/README.md
@@ -1,6 +1,7 @@
 ## All related repotories
 - [bifrost](https://github.com/bifrost-finance/bifrost) (branch: develop)
-- [rust-eos](https://github.com/bifrost-finance/rust-iost) (branch: master)
+- [rust-iost](https://github.com/bifrost-finance/rust-iost) (branch: master)
+- [demux-js-iost](https://github.com/liebi-official/demux-js-iost) (branch: master)
 
 ## Bifrost
 
@@ -17,27 +18,30 @@ $ cargo build --release
 Start two Bifrost nodes.
 
 Alice node:
-```
+
+```shell script
 $ ./target/release/bifrost --base-path /tmp/alice \
 --rpc-port 4321 \
 --ws-port 9944 \
 --chain=dev \
 --alice \
 --port 30333 \
 --node-key 0000000000000000000000000000000000000000000000000000000000000001 \
---validator
+--validator 
+
 ```
 
 Bob node:
-```
-$ ./target/release/bifrost --base-path /tmp/bob \
---rpc-port 1234 \
---ws-port 9933 \
---bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp \
---chain=dev \
---bob \
---port 30334 \
---validator
+
+```shell script
+$ ./target/release/bifrost --base-path /tmp/bob \  
+--rpc-port 1234 \                                                                                                                      
+--ws-port 9933 \                                                                                                                       
+--bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp \            
+--chain=dev \                                                                                                                          
+--bob \                                                                                                                                
+--port 30334 \                                                                                    
+--validator  
 ```
 
 Ensure both node are producing blocks and synchronizing each other.
@@ -50,122 +54,182 @@ Follow the instructions to build [IOST](https://developers.iost.io/docs/en/4-run
 
 ### 2. Launch local IOST server
 
-```shell
+Using the default config provided by IOST.
+
+```shell script
 $ iserver -f ./config/iserver.yml
 ```
 
 - Follow the instructions to create accounts [Command Line Wallet Tool](https://developers.iost.io/docs/en/4-running-iost-node/iWallet.html).
 
+1. Create account `bifrost` as the cross account of Bifrost - IOST.
+2. Create account `lispczz5` as the test account.
 
 **Tips**:
 > While you're creating account for test, use the `--sign_algo secp256k1` to specify the sign algorithm as SECP256K1.
 
-```shell
+```shell script
+$ iwallet --server 127.0.0.1:30002 --account admin --amount_limit "ram:1000|iost:10" --sign_algo secp256k1  account create lispczz5 --initial_balance 600 --initial_gas_pledge 10 --initial_ram 0
+$ iwallet --server 127.0.0.1:30002 --account admin --amount_limit "ram:1000|iost:10" --sign_algo secp256k1  account create bifrost --initial_balance 200 --initial_gas_pledge 10 --initial_ram 0
+```
 
-$ iwallet --server 127.0.0.1:30002 --account admin --amount_limit "ram:1000|iost:10" --sign_algo secp256k1  account create lispczz4 --initial_balance 0 --initial_gas_pledge 10 --initial_ram 0
-$ iwallet --server 127.0.0.1:30002 --account admin --amount_limit "ram:1000|iost:10" --sign_algo secp256k1  account create lispczz5 --initial_balance 0 --initial_gas_pledge 10 --initial_ram 0
-$ iwallet --server 127.0.0.1:30002 --account admin --amount_limit "ram:1000|iost:10" --sign_algo secp256k1  account create bifrost --initial_balance 0 --initial_gas_pledge 10 --initial_ram 0
+> If don't have enough gas, using following command to issue more [Economic Contract](https://developers.iost.io/docs/en/6-reference/EconContract.html#pledgepledgor-to-amount).
 
+```shell script
+$ iwallet --account lispczz4 call 'gas.iost' 'pledge' '["lispczz5","lispczz5","10"]'
 ```
-> If don't have enought gas, using following command to issue more [Economic Contract](https://developers.iost.io/docs/en/6-reference/EconContract.html#pledgepledgor-to-amount).
 
-```
-$ iwallet --account lispczz4 call 'gas.iost' 'pledge' '["lispczz4","lispczz4","10"]'
+> Check the IOST chain status
+
+```shell script
+$ iwallet --server 127.0.0.1:30002 state      
 ```
 
-## Testing
+## DEMUX-JS-IOST
 
-### Configure Browser
+### Configuration
 
-Go to [polkadot.js.org](https://polkadot.js.org/apps/#/settings/developer), Copy content data from the file ```developer_setting.json``` to **Deveoper** tab like this, and save it.
-![developer_setting](developer_setting.png)
+Update the IOST endpoint in `index.js`, use the local IOST address `http://127.0.0.1:30001`.
 
-### IOST to Bifrost
+Update the Bifrost address in `IostActionHandler.js`, use the local Bifrost address `ws://127.0.0.1:9944`.
 
-Before you send a transaction to Bifrost, check **jim**'s and **bifrost**'s balance.
+Set the sign account to `Alice`.
 
 ```
-# should print 10000.0000 EOS
-$ cleos get currency balance eosio.token jim
-
-# bifrost is contract account, should print nothing
-$ cleos get currency balance eosio.token bifrostcross
+  const keyring = new Keyring({ type: "sr25519" });
+  const alice = keyring.addFromUri("//Alice", { name: "Alice default" });
 ```
 
-Now send a transaction.
-```
-$ cleos push action eosio.token transfer '["jim", "bifrostcross", "100.0000 EOS", "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY@bifrost:vEOS"]' -p jim@active
+### Run bridge node
+
+```shell script
+
+$ node index.js
 ```
 
-Go to [polkadot.js.org](https://polkadot.js.org/apps/#/extrinsics), to check whether transaction is sent successfully to Bifrost or not.
+## Configuration
 
-Wait about 90 seconds for the transaction is verified. If all go well, you can see a event like the following screencapture.
+### Configure Bifrost
 
-![prove_action_event](prove_action_event.png)
+Check the `bifrost` account information file in `~/.iwallet/bifrost.json`, and set the security key and algorithm in [subkey_setting_iost.sh](docs/iost/subkey_setting_iost.sh) as the raw_key and key_type of `bifrost`.
 
-If that event happens, Alice's assets will be created, the amount is 1000000(due to EOS precision), go to check Alice's assets that just created.
+Execute the shell script, it will store necessary data into alice and bob's node.
 
-![assets_creation](assets_creation.png)
+```shell script
+$ ./subkey_setting_iost.sh                     
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
+Set local storage successfully
 
-If you see that figure above, go check **jim**'s and **bifrostcross**'s balance again.
 ```
-# should print 9900.0000 EOS
-$ cleos get currency balance eosio.token jim
 
-# should print 100.0000 EOS
-$ cleos get currency balance eosio.token bifrostcross
-```
+### Configure Browser
 
-### Bifrost to IOST
+Go to [polkadot.js.org](https://polkadot.js.org/apps/#/settings/developer), Copy content data from the file [developer_setting.json](./developer_setting.json) to **Deveoper** tab like this, and save it.
+![developer_setting](./image/developer_setting.png)
 
-Before testing, you have to setup some necessary steps.
 
-- Multisignature Configuration
 
-Bifrost side:
+### Alice account balance in Bifrost
 
-There're two Bifrost nodes that you start in previous steps, here you need add EOS node address info and EOS secret key
-to both running Bifrost nodes by tool **subkey**.
+![Alice balance](./image/alice_init.png)
 
-Execute the script. This script will add necessary data to alice node and bob node.
-```
-$ ./subkey_setting.sh
-```
 
-EOS side:
 
-```
-$ cleos set account permission bifrostcross active '{"threshold":2,"keys":[],"accounts":[{"permission":{"actor":"testa","permission":"active"},"weight":1}, {"permission":{"actor":"testb","permission":"active"},"weight":1}, {"permission":{"actor":"testc","permission":"active"},"weight":1}, {"permission":{"actor":"testd","permission":"active"},"weight":1}]}' owner
-```
+## Testing
+
+### IOST to Bifrost
+
+Before you send a transaction to Bifrost, check the IOST balance of account `bifrost` and `lispczz5`.
+
+```shell script
+$ iwallet --server 127.0.0.1:30002 balance lispczz5 | head -n 4
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "lispczz5",
+    "balance": 600,
 
-After you set permission for account bifrost, try this command to verify the result.
+$ iwallet --server 127.0.0.1:30002 balance bifrost | head -n 4 
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "bifrost",
+    "balance": 200,
 ```
-$ cleos get account bifrostcross
+
+Now send a transaction. `(5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY is the Alice's address in Bifrost)`
+
+```shell script
+$ iwallet --account lispczz5 call 'token.iost' 'transfer' '["iost","lispczz5","bifrost","100","5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY@bifrost:IOST"]'
 ```
 
-It should print some info like this.
+Go to [polkadot.js.org](https://polkadot.js.org/apps/#/explorer), to check whether transaction is sent successfully to Bifrost or not.
+
+Wait about 90 seconds for the transaction is verified. If all go well, you can see a event like the below screenshot.
+
+![prove_action_event](image/prove_action_event.png)
+
+If that event happens, Alice's assets will be created, the amount is 100(IOST asset id is 8), go to check Alice's assets that just created.
+
+![assets_creation](image/assets_creation.png)
 
+If you see that figure above, go to check the IOST balance of `bifrost` and `lispczz5` again.
+
+```shell script
+$ iwallet --server 127.0.0.1:30002 balance lispczz5 | head -n 4                                                                                                
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "lispczz5",
+    "balance": 500,
 ```
-permissions:
-     owner     1:    1 EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV
-        active     2:    1 testa@active, 1 testb@active, 1 testc@active, 1 testd@active
+
+```shell script
+$ iwallet --server 127.0.0.1:30002 balance bifrost | head -n 4                                                                                                 
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "bifrost",
+    "balance": 300,
+
 ```
 
+### Bifrost to IOST
+
+
 - Send transaction
 
-Now, we can send a transaction to EOS node.
+Now, we can send a transaction to IOST node.
 
-Follow the picture to send a transaction to EOS node( "jim" to hex: "0x6a696d").
-![send_transaction](transaction_to_eos.png)
+Follow the picture to send a transaction to IOST node `("lispczz5" to hex: "0x6c697370637a7a35")`.
+![send_transaction](image/transaction_to_iost.png)
 
-Surely you can go to [polkadot.js.org](https://polkadot.js.org/apps/#/extrinsics) to check Alice's assets change or not
+Surely you can go to [polkadot.js.org](https://polkadot.js.org/apps/#/chainstate) to check Alice's assets change or not.
 
-Check jim's and bifrostcross's balance in EOS node if it runs without error.
+And you will see 10 Unit of Alice's asset are locked.
+![asset_locked](image/alice_asset_locked.png)
 
-```
-# should print 9910 EOS
-$ cleos get currency balance eosio.token jim
+Wait a moment, a prove action and a withdraw event are shown in the recent events list.
+![withdraw_event](image/event_withdraw.png)
+
+Go back to check Alice's asset again.
+![alice_asset](image/alice_asset_after_transfer.png)
+
+Check the IOST balance of `lispczz5` and `bifrost` again.
+
+```shell script
+$ iwallet --server 127.0.0.1:30002 balance bifrost | head -n 4                                                                                                
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "bifrost",
+    "balance": 290,
+
+$ iwallet --server 127.0.0.1:30002 balance lispczz5 | head -n 4                                                                                               
+Connecting to server 127.0.0.1:30002 ...
+{
+    "name": "lispczz5",
+    "balance": 510,
 
-# should print 90 EOS
-$ cleos get currency balance eosio.token bifrostcross
 ```
diff --git a/docs/iost/image/alice_asset_after_transfer.png b/docs/iost/image/alice_asset_after_transfer.png
diff --git a/docs/iost/image/alice_asset_locked.png b/docs/iost/image/alice_asset_locked.png
diff --git a/docs/iost/image/alice_init.png b/docs/iost/image/alice_init.png
diff --git a/docs/iost/image/assets_creation.png b/docs/iost/image/assets_creation.png
diff --git a/docs/iost/image/developer_setting.png b/docs/iost/image/developer_setting.png
diff --git a/docs/iost/image/event_withdraw.png b/docs/iost/image/event_withdraw.png
diff --git a/docs/iost/image/prove_action_event.png b/docs/iost/image/prove_action_event.png
diff --git a/docs/iost/image/transaction_to_iost.png b/docs/iost/image/transaction_to_iost.png