IBC & OKTC Document

charlie

Attention

IBC is now ready on the OKC mainnet ,And If you want to test it , Here are the channels you should know about.For now ,OKC only support three other blockchains

chains	out (okc -> blockchains)	in(other chains -> okc)
cosmos	channel-0	channel-361
osmosis	channel-1	channel-277
kujira	channel-2	channel-27
comdex	channel-10	channel-33
persistence	channel-12	channel-47
sifchain	channel-24	channel-74
axelar	channel-25	channel-34
secret	channel-27	channel-36
stargaze	channel-29	channel-114
assetmantle	channel-30	channel-14
chihuahua	channel-35	channel-31
nym	channel-41	channel-5
umee	channel-42	channel-39
kava	channel-45	channel-82

And The IBC bridge is ready as well , Take a try: https://www.okx.com/okc/ibc
KeplrAddress: https://static.coinall.ltd/cdn/assets/ibc_keplr/index.html

Note

There are several things you should know before
- Your token is not missing !!
- When you send your token through IBC , Your token will be auto-transferred to the ERC20 token contract,That means you can not send your token back by rly tx transfer neither will you find your account balance changed,If you want to know where are your tokens exactly, Follow these steps
  - execute exchaincli query erc20 token-mapping --node https://exchaintesttmrpc.okex.org(It is not convinent for now,But it is temporary) to get your contract address ,Or you can get your contract address by your transaction hash through okc-explorer like(https://www.oklink.com/en/okc-test/tx/0x98bb64ea6168d8ec8e5af0e08358926b5ec2e48543fab14d9131d56a2db2d0dd). Finally you will get your contract address like 0x7dE0E2253E303D60471B9A44BDF449f8a3b04F36(uatom) . Or try get by api : https://exchainrpc.okex.org/okexchain/v1/erc20/token_mapping
  - Import the contract address to your metamask
  - Finally you will find out that your token were transferred into ERC20 token(Of course ,Do not forget to switch the network to okc-mainnet or okc-testnet)
What should I do to get my token back?
- Because your token has been transferred into to ERC20 token .You are now in EVM ecosystem ,Thus you have to deploy the ERC20 contract and call the concrete methods to send your token back
- See Step4: End of the document

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/okx/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": "100000000wei",
      "debug": true,
      "timeout": "10s",
      "output-format": "json",
      "sign-mode": "direct"
    }
  }

OKC mainnet config

rly chains add okexchain
change the gas-price from 0.01wei to 100000000wei,
change the gas-adjustment from 1.2 to 1.5

  {
    "type": "cosmos",
    "value": {
      "key": "testkey",
      "chain-id": "exchain-66",
      "rpc-addr": "https://exchaintmrpc.okex.org:443",
      "grpc-addr": "",
      "account-prefix": "ex",
      "keyring-backend": "test",
      "gas-adjustment": 1.5,
      "gas-prices": "100000000wei",
      "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 // okc testnet
rly chains add --file exchain-66.json exchain-66 // okc mainnet
rly chains add --file yourOwnChain.json chain-name

Then you will have several 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 okc_ibc0 :

okc_ibc0.json
{
  "dst": {
    "chain-id": "ibc-0",
    "port-id": "transfer",
    "order": "unordered",
    "version": "ics20-1"
  },
  "src": {
    "chain-id": "exchain-65", // if you want to test mainnet,change the 'chain-id' with exchain-66
    "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 okc_ibc0 --file ./okc_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" --coin-type 60
rly keys restore exchain-66 testkey "your mnemonic" --coin-type 60

Step 2. HandShake

You can simply do handshake by:

rly tx link okc_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 okc_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 that you have a new token from OKC .

Step 4. Send Token Back

Your 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 neither you will find your account balance changed, 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/okx/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 , then you will find your token which were transfered before
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

Or ,You can try okc-explorer:
Let's take uatom for example

https://www.oklink.com/en/okc/address/0x7dE0E2253E303D60471B9A44BDF449f8a3b04F36

You will see the contract information :

Click the write proxy
Find the method called "send_to_ibc"
Full fill the arguments
Done