IBC & OKC Document

charlie

IBC

What is the IBC
- The Inter-Blockchain Communication protocol (IBC) is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, and authenticated communication between heterogeneous blockchains arranged in an unknown and dynamic topology.IBC is a protocol that allows blockchains to talk to each other.
How It worked
- Step 1: Tracking Continuously, chain B receives the headers of chain A, and vice versa. This allows each chain to track the validator set of the other. In essence, each chain runs a light-client of the other.
- Step 2: Bonding When the IBC transfer is initiated, the TokenA are locked up (bonded) on chain A.
- Step 3: Proof Relay Then, a proof that the 10 TokenA are bonded is relayed from chain A to chain B.
- Step 4: Validation The proof is verified on chain B against chain A’s header and, if it is valid, then 10 TokenA-vouchers are created on chain B.
- Chain A locks token a and passes this lock proof (credential) to chain B. Once this action is completed and verified, chain B will cast an alternative token a' (which can be understood as a kind of equivalent ticket) on its own chain. After the alternative token a' can be destroyed by chain B, the completion of chain B After destruction, chain A will unlock the originally locked token a. Therefore, we can transfer the value of the token across the chain to achieve cross-chain asset transfer, but we cannot transfer the token itself.
- Basically ,The entire process of IBC can be described as belows
  - Handshake Once(Kind of TCP Handshake)
  - Transfer Tokens(For Now We only support token transfer ,nft transfer will be coming very soon)
  - Relay Packets By Relayer
  - See More

Interact IBC With OKC

OKC was built by cosmos-sdk's early version which was v0.39 .After we decide to support IBC ,we choose the version v2.0.2 as our final IBC version .Besides what makes the OKC different is OKC not only support cosmos ecosystem but also support evm ecosystem,that is when the tokens that crossed from IBC will be auto-transferred to the ERC20 token contract if the switch of auto_transfer is opened and then you can do anything you want with ERC20 token .
OKC is almost the same with the other blockchains built by cosmos-sdk except OKC does not support grpc-server which means hermes is not supported.

This is a detailed documentation for testing IBC on okc testnet exchain-65.

Pre-requisites

Before we start, please note that there are two things have to be prepared:

go-relayer (https://github.com/cosmos/relayer)
- OKC does not support grpc-server which means hermos is not supported
- Any version should be fine.
exchain bin binary(https://github.com/okex/exchain)
- It is not necessory actually unless you do want to test IBC with OKC local network and make sure you make with veneus1Height=1
```
 make install Venus1Height=1
```

Step 1. Initialize the relayer config

Let's initialize relayer firstly

rly config init

Initialize relayer's configuration files (including chains and paths)

OKC testnet config

  {
    "type": "cosmos",
    "value": {
      "key": "testkey",
      "chain-id": "exchain-65",
      "rpc-addr": "https://exchaintesttmrpc.okex.org:443",
      "grpc-addr": "",
      "account-prefix": "ex",
      "keyring-backend": "test",
      "gas-adjustment": 1.5,
      "gas-prices": "10000000000000wei",
      "debug": true,
      "timeout": "10s",
      "output-format": "json",
      "sign-mode": "direct"
    }
  }

Note:

If You want to test on your local okc network ,replace the rpc-addr with your local rpc

Of Course Do not forget to add your own blockchain config as well ,we will take ibc-0 for example

Now you can add the chain to the relayer

rly chains add --file exchain-65.json exchain-65
rly chains add --file yourOwnChain.json chain-name

Then you will have two chains

rly chains list

Now we can handle the paths.The path is an alias between your chain with okc ,When providing the path value, make sure you drop the square brackets since they are not needed. The example below shows how to initialize a path named oec65_ibc0 :

oec65_ibc0.json
{
  "dst": {
    "chain-id": "ibc-0",
    "port-id": "transfer",
    "order": "unordered",
    "version": "ics20-1"
  },
  "src": {
    "chain-id": "exchain-65",
    "port-id": "transfer",
    "order": "unordered",
    "version": "ics20-1"
  },
  "strategy": {
    "type": "naive"
  }
}

Finally ,you can add the path to the relayer

rly paths add exchain-65 ibc-0 oec65_ibc0 --file ./oec65_ibc0.json

And you should see one path info

rly paths list

After you setup the chains and the paths ,you have to do one more thing to bind your personal key with the relayer so that the relayer will relay the packet as expected

rly keys restore ibc-0 testkey "your mnemonic"
rly keys restore exchain-65 testkey "your mnemonic"

Step 2. HandShake

You can simply do handshake by:

rly tx link oec65_ibc0  --src-port transfer --dst-port transfer --order unordered --version ics20-1 -d

It may take some time ,finally you will see some output like Channel created {"src_chain_id": "exchain-65", "src_channel_id": "channel-0", "src_port_id": "transfer", "dst_chain_id": "ibc-0", "dst_channel_id": "channel-0", "dst_port_id": "transfer"}

Now,You can start the daemon relayer to relay packets automatically

rly start path oec65_ibd0

Step 3. Token Transfer

Now You can transfer your own token to OKC by IBC

Note: Before starting transfer ,you call execute rly q bal ibc-0 testkey to know your balances info

rly tx transfer exchain-65 ibc-0 400000000000000wei $(rly keys show ibc-0 testkey) channel-0 --path oec65_ibc0

It may take some time during the relayer relay the packet ,then you can do rly q bal ibc-0 testkey to find out your have a new token from OKC .

Step 4. Send Token Back

Your native token will be auto-transferred to the ERC20 token contract if the switch of auto_transfer is opened so that you are not able to send your token back by rly tx transfer , and as we another teammates are still working on to help send your token back conveniently . For now you have to do it a little complex.

Download the OKC erc20 contract
- https://github.com/okex/IBC-ERC20
Query to get your token addrees,and import the address to your metamask
- exchaincli query erc20 token-mapping --node https://exchaintesttmrpc.okex.org:443
- import the contract address to your metamask
Deploy MockNativeERC20 to the OKC testnet or your local OKC network
- Fill the arguments about send_native20_to_ibc and transact it to get your token back