docs: initial README.md

README.md

@@ -2,81 +2,94 @@
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache)](LICENSE)
 
-Forcerelay aims to allow [CKB](https://github.com/nervosnetwork/ckb)
-and chains built on [Axon](https://github.com/axonweb3/axon) gain the ability to
-interact with Ethereum and Cosmos-SDK chains via [IBC protocol](https://github.com/cosmos/ibc).
-
-Forcerelay is based on [Hermes](https://github.com/informalsystems/hermes), which helps Cosmos-SDK chains to interact with each other. Many thanks to them!
-
-## **WARNING**
-
-This repo is still in early stage. Your issues or PRs are welcome.
-
-## Using Forcerelay/Eth
-
-Create or modify `~/.hermes/config.toml`. Here is an example:
-
-```toml
-[global]
-log_level = 'trace'
-
-[mode]
-
-[mode.clients]
-enabled = true
-refresh = true
-misbehaviour = true
-
-[mode.connections]
-enabled = false
-
-[mode.channels]
-enabled = false
-
-[mode.packets]
-enabled = true
-clear_interval = 100
-clear_on_start = true
-tx_confirmation = true
-
-[[chains]]
-id = 'ibc-eth-1'
-genesis_time = 1606824023
-genesis_root = "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95"
-initial_checkpoint = "0x6c668d888d2b892bf26c25ee937ed43b48048dedda971ff33ebaaae7b2bd3890"
-key_name = 'relayer_eth_wallet'
-rpc_addr_pool = [
-  "https://www.lightclientdata.org",
-]
-rpc_port = 8545
-[chains.forks]
-genesis = { epoch = 0, fork_version = "0x00000000" }
-altair = { epoch = 74240, fork_version = "0x01000000" }
-bellatrix = { epoch = 144896, fork_version = "0x02000000" }
-capella = { epoch = 194048, fork_version = "0x03000000" }
-
-[[chains]]
-id = 'ckb-multi-client-4-1'
-ckb_rpc = "https://testnet.ckbapp.dev"
-ckb_indexer_rpc = "https://testnet.ckbapp.dev"
-lightclient_contract_typeargs = "0x75ca34f9f1c28cf16d160fc485d5ed4a2a8f34424ec5854a7579ca82e72b7671"
-lightclient_lock_typeargs = "0x8d5300c03081b19a28a30d2e8202a467ab19fafa5285c86896db035e783186d5"
-minimal_updates_count = 1
-key_name = "relayer_ckb_wallet"
-data_dir = "./ckb_mmr_storage_multi_client_4_1"
-client_type_args = { cells_count = 4, type_id = "0x673e557da4c8381638fc808956aa27e384cf66d9a63899a6e4e932c2395f7a40" }
+
+Forcerelay is an IBC-Compatible bridge that aims to open up the Nervos ecosystem and the Cosmos ecosystem, and it also serves as a standard cross-chain solution within the Nervos ecosystem.
+
+Forcerelay is built on [Hermes](https://github.com/informalsystems/hermes), this means we will keep continue to track and update the latest version of Hermes, and won't stop it on any specific old version.
+
+Currently, Forcerelay only supports Axon, CKB and Cosmos-SDK chains, but not support other mainstream EVM chains, like Ethereum, Arbitrum and BSC, because it's not easy to run a light-client from any chains above on EVM. However, the implementation of mainstream EVM chains is on our future plan, we will keep you up-to-date with this.
+
+## Progress Tracking
+Forcerelay is in development, any issues and PRs are welcome. Here is where we are in gerneral:
+- [ ] Upgrade the underline Hermes from v1.4.0 to the latest v1.6.0
+- [x] Implement connection and channel layer of IBC protocol between Axon and CKB
+- [ ] Implement packet layer of IBC protocol between Axon and CKB
+- [ ] Implement entire IBC protocol between Axon and Cosmos-SDK chains
+- [ ] Implement entire IBC protocol between CKB and Cosmos-SDK chains
+
+## Architecture Design
+Cosmos IBC is a cross-chain protocol designed based on light-client technology. In case of homogeneous chains, it's supposed to implement only one light-client module to run the protocol. However, in case of Forcerelay, chains are non-homogeneous, so we have to implement at least three light-client modules to run IBC protocol between Axon, CKB and Cosmos.
+
+Contract development environment is sensitive to the blockchain's VM implementation, which means the different VM implementation requires us to provide different light-client solutions, even the solutions come from the same blockchain.
+
+High level diagram of Forcerelay:
+![Alt text](docs/Forcerelay.jpg)
+
+## Usage Guidance
+Take the IBC cross-chain betwwen Axon and CKB as an example.
+
+### Contract Deployment on Axon
+Before deploying [ibc-solidity-contract](https://github.com/synapseweb3/ibc-solidity-contract) on Axon, please make sure Node.js and Yarn are installed:
+
+```
+$ git clone https://github.com/synapseweb3/ibc-solidity-contract
+$ cd ibc-solidity-contract
+$ echo AXON_HTTP_RPC_URL="YOUR_AXON_URL" > .env
+$ yarn migrate > migrate.log | tail -f migrate.log
 ```
 
-Run command `forcerelay eth-ckb --ethereum-chain-id ibc-eth-1 --ckb-chain-id ibc-ckb-1` to start up relay of ETH headers to CKB network.
+After running `yarn migrate`, the `OwnableIBCHandler` address is listing in console, we record it and mark as **`YOUR_IBC_AXON_ADDRESS`** to use later.
+
+### Contract Deployment on CKB
+Detailed deployment steps can be found in [ibc-ckb-contracts](https://github.com/synapseweb3/ibc-ckb-contracts), or pre-deployed contracts `TYPE_ARGS` on testnet and mainnet can be found here:
+||Mainnet|Testnet|
+|-|-|-|
+|connection|WIP|WIP|
+|channel|WIP|WIP|
+|packet|WIP|WIP|
+|utility|WIP|WIP|
+|escrow|WIP|WIP|
 
-Warn: relayer is still under rapid development and the configuration example and command above may be outdated.
+### Register Business Module
+When deploying the solidity contract on Axon, an initial ICS20 transfer module has been registered in `OwnableIBCHandler` on port `port-0` while contract migration, and it's open to everyone to register their own business module, [here](https://github.com/synapseweb3/ibc-solidity-contract) is the detailed registry steps.
 
-## Using Forcerelay/Axon (WIP)
+Unlike Axon, modules cannot be registered directly in contract on CKB. To fix that, we introduce [forcerelay-ckb-sdk](https://github.com/synapseweb3/forcerelay-ckb-sdk), which is designed to complete the distribution and calling of custom modules.
 
-Run `cargo test -p ibc-test --lib --all-features -- tests::integration_test --exact --nocapture --ignored` to check Ckb endpoint, which tests connection and channel layers between two Ckb chains
+Which needs to be noticed is, IBC port on CKB currently is the `LOCK_HASH` of your wallet cell on CKB, we mark it as `WALLET_LOCK_HASH` and use later.
 
-Run `Forcerelay create connection --a-chain axon-0 --b-chain axon-1` and `Forcerelay create channel --a-chain axon-0 --a-connection connection-0 --a-port mock-port-0 --b-port mock-port-0` to create connection and channel between two Axon chains
+### Installation and Settings
+We recommand you to download the pre-compiled binary, or you can compile mannully from the source code, which requires `Rust ^v1.56.0` installed:
 
-## Rqeuirements
+```
+$ git clone https://github.com/synapseweb3/forcerelay
+$ cd forcerelay
+$ cargo install -p ibc-relayer-cli
+$ forcerelay --version
+```
+
+Forcerelay can run by specifying a configuration file in the command line, or the `~/.hermes/config.toml` file will be accessed. An [example](https://github.com/synapseweb3/forcerelay/blob/main/config.toml) configuration file written for Axon and CKB (Testnet) have been pre-generated, and only minimal modifications are required to support running Forcerelay:
+
+```
+websocket_addr = "ws://<YOUR_AXON_URL>:<WS_PORT>"
+rpc_addr = "http://<YOUR_AXON_URL>:<HTTP_PORT>/"
+contract_address = "<YOUR_IBC_AXON_ADDRESS>"
+```
 
-This project requires Rust `^1.65.0`.
+### Import Secret Key
+Before running Forcerelay, accounts at both sides of blockchains should be prepared and imported. In the scenario of Axon and CKB, Forcerelay needs its own Axon and CKB accounts with sufficient tokens. Here are steps to import Secp256k1 secret keys:
+
+```
+$ forcerelay keys add --chain axon-0 --secret-file <SECRET_KEY_PATH>
+$ forcerelay keys add --chain ckb4ibc-0 --secret-file <SECRET_KEY_PATH>
+```
+
+### Connecting and Start Forcerelay
+Establishing IBC channels on both sides of Axon and CKB is required to run Forcerelay:
+
+```
+$ forcerelay create channel \
+    --a-chain axon-0 --b-chain ckb4ibc-0 \
+    --a-port  port-0 --b-port <WALLET_LOCK_HASH> \
+    --new-client-connection
+$ forcerelay start --config <YOUR_CONFIG_PATH>
+```