diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index a3f8ebdd..26e8419d 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -1,39 +1,104 @@ import { Callout } from 'nextra-theme-docs' import Expandable from '../../components/Expandable' +import { Steps } from 'nextra-theme-docs' # Relaying on Namada -This document describes how to operate a relayer for the Inter-Blockchain Communication (IBC) protocol with Namada. This documentation covers being able to create connections through IBC as well as setting up local chains of Namada for testing purposes. +This section of the documentation describes how to operate a relayer on Namada, how to open IBC connections with other IBC compatible chains and how to +test your relayer setup by making a connection between two mock local chains. -This document covers essential steps for using IBC with Namada: +## Introduction +Relayers are a crucial piece of infrastructure that allow IBC compatible chains to pass messages to one another. +A relayer is responsible for posting IBC packets to the destination chain, as well as performing other IBC functions +such as creating channels, updating the light client states and checking for misbehavior. -1. [Configure Hermes](#configure-hermes) -2. [Install Hermes](#install-hermes) +Operating a relayer is permissionless. There must be at least one relayer running on a given channel between two chains if the chains are +to pass messages to each other on that channel. IBC transfers that are attempted but not picked +up by a relayer will timeout and the tokens will be refunded to the sender. + +To operate a relayer, you will need: +- A dedicated server +- [Hermes](#installing-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. +- Full nodes on both chains; a relayer needs to access several weeks worth of chain history and to frequently post +transactions to both chains. For testing, a public RPC node may suffice, but for production it is highly recommended +for reliability that relayer operators also operate both full nodes themselves. +- Gas funds for each chain; since relayers will need to regularly post transactions to both chains, they will need a +wallet on each with enough funds to cover gas costs (monitoring and topping up as necessary). + + +This document covers the essentials for installing, configuring and running a relayer on Namada: + +1. [Installing Hermes](#installing-hermes) +2. [Configuring Hermes](#configuring-hermes) 3. [Setting up the relayer](#setting-up-the-relayer) -4. [Start the relayer](#start-the-relayer) -5. [Set up local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) +4. [Creating an IBC channel](#creating-an-ibc-channel) +5. [Running the relayer](#running-the-relayer) + +And for setting up a testing environment by running two local Namada chains, see the section +[Testing with local Namada chains](#testing-with-local-namada-chains) + + +### Installing Hermes +Heliax maintains a fork of the Hermes relayer software. You can download a prebuilt binary or build it from source. + +#### From binaries +One can download the latest binary release from our [releases page](https://github.com/heliaxdev/hermes/releases) by choosing the appropriate architecture. -The below is intended for those that wish to relay IBC message transfers between two Namada chains. There is of course the capability to do this between any two IBC compatible chains (such as a Cosmos chain). -In this case, it is necessary to have a node running on both the destination and the source chain in order to make any package transfers. -Below, we discuss first how to enable this connection between two pre-existing chains by Hermes, and second, setting up two Namada local chains for this purpose. +E.g. +```bash copy +export TAG="v1.8.2-namada-beta11" # or the appropriate release for your version of namada +export ARCH="x86_64-unknown-linux-gnu" # or "aarch64-apple-darwin" +curl -Lo /tmp/hermes.tar.gz https://github.com/heliaxdev/hermes/releases/download/${TAG}/hermes-${TAG}-${ARCH}.tar.gz +tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin +``` + + +For some systems, `/usr/local/bin` is a protected directory. In this case, you may need to run the above command with `sudo`. +I.e +```bash copy +sudo tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin +``` +This is also true for the command `cp ./target/release/hermes /usr/local/bin/` below (see the comment). + + +#### From source +```bash copy +export TAG="v1.8.2-namada-beta11" # or the appropriate release for your version of namada + +git clone https://github.com/heliaxdev/hermes.git +git checkout $TAG +cd hermes +cargo build --release --bin hermes +export HERMES=$(pwd) # if needed +``` +Check the binary: +```bash copy +./target/release/hermes --version +``` + +It is recommended to now add hermes to `$PATH` such that it is callable without any pre-fixes. +For ubuntu users, this can be achieved by +```bash copy +sudo cp ./target/release/hermes /usr/local/bin/ +``` + -## Configure Hermes -Hermes is an IBC relayer to relay IBC packets between chains. -Namada uses a [fork of Hermes supporting Namada chains](https://github.com/heliaxdev/hermes/tree/v1.7.4-namada-beta7). +### Configuring Hermes -### Make Hermes config file -One essential piece of the puzzle is to create a `config.toml` file that describes what connections will be set up that the relayer will be responsible for. +#### Make Hermes config file +The Hermes `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: ```bash copy -export HERMES_CONFIG="/config.toml" +export HERMES_CONFIG="$HOME/.hermes/config.toml" touch $HERMES_CONFIG ``` -If you don't specify the file path, `~/.hermes/config.toml` is read as default. +When running Hermes commands, if you don't specify the config file path, `~/.hermes/config.toml` is read as default. -You can find an example of the config file below. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-chains-using-the-hermes-script). +__You can find an example of the config file below__. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. +If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-chains-using-the-hermes-script).
Example: config.toml @@ -139,84 +204,42 @@ These are the pieces of this puzzle you want to keep your ๐Ÿ‘€ on: - `chains.rpc_address` specifies the port that the channel is communicating through, and will be the argument for the `ledger_address` of Namada when interacting with the ledger (will become clearer later) - Make sure to change the IP address to the IP address of your local machine that is running this node! - `chains.grpc_addr` currently is not used in Namada but needs to be configured for other Cosmos chains - - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer. + - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer and + will need to be kept topped up with gas funds. - `chains.event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. - `trusting_period` specifies the maximum period before which the client can not expire. This should be not more than unbonding time in the particular chain. -You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). +You can see more details of configuration in [the official Hermes documentation](https://hermes.informal.systems/documentation/configuration). -### Export environment variables -The relaying user will need to save certain environment variables. These are: +#### Export environment variables +You may find it convenient to save certain environment variables. These are: ```bash copy export CHAIN_A_ID="" export CHAIN_B_ID="" export HERMES_CONFIG="" ``` -## Install Hermes -Before conducting any IBC operations, one must download Heliax's fork Hermes binary or build it from source. - -### From binaries -One can download the latest binary release from our [releases page](https://github.com/heliaxdev/hermes/releases) by choosing the appropriate architecture. - -E.g. -```bash copy -export TAG="v1.7.4-namada-beta7" -export ARCH="x86_64-unknown-linux-gnu" # or "aarch64-apple-darwin" -curl -Lo /tmp/hermes.tar.gz https://github.com/heliaxdev/hermes/releases/download/${TAG}/hermes-${TAG}-${ARCH}.tar.gz -tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin -``` - - -For some systems, `/usr/local/bin` is a protected directory. In this case, you may need to run the above command with `sudo`. -I.e -```bash copy -sudo tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin -``` -This is also true for the command `cp ./target/release/hermes /usr/local/bin/` below (see the comment). - - -### From source -```bash copy -export TAG="v1.7.4-namada-beta7" - -git clone https://github.com/heliaxdev/hermes.git -git checkout $TAG -cd hermes -cargo build --release --bin hermes -export HERMES=$(pwd) # if needed -``` -Check the binary: -```bash copy -./target/release/hermes --version -``` - - -It is recommended to now add hermes to `$PATH` such that it is callable without any pre-fixes. -For ubuntu users, this can be achieved by -```bash copy -sudo cp ./target/release/hermes /usr/local/bin/ -``` - +### Setting up the relayer -## Setting up the relayer - -### Create the relayer account +#### Create the relayer account On each chain, there must be a `relayer` account. The alias should be the same as `chains.key_name` in the config. On a Namada chain, this can be done by running ```bash copy namadaw gen --alias relayer ``` -This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `shielded-expedition.88f17d1d14`, the `wallet.toml` will be found in `$HOME/.local/share/namada/shielded-expedition.88f17d1d14/wallet.toml` (on a ubuntu machine where `base-dir` has not been set up properly). +This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `shielded-expedition.88f17d1d14`, the `wallet.toml` will be found in `$HOME/.local/share/namada/shielded-expedition.88f17d1d14/wallet.toml` (on a Ubuntu machine where `base-dir` has not been changed from default). The relayer account should have some balance to pay the fee of transactions. Before creating an IBC channel or relaying an IBC packet, you need to transfer the fee token to the relayer account. -### Add the relayer key to Hermes -To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't need the wallet anymore. +#### Add the relayer key to Hermes +To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. +It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't +need the wallet anymore. (Rather than providing the `wallet.toml`, you can instead provide a text file which contains the 24 word mnemonic for your key.) ```bash copy hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --key-file $WALLET_PATH +# or hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --mnemonic-file $SEED_PATH ``` @@ -226,10 +249,8 @@ Hermes will store the key in `~/.hermes/keys/${CHAIN_ID}` as default. You can sp If you want to use an encrypted key with a password, you have to set an environment variable `NAMADA_WALLET_PASSWORD_FILE` for the password file or `NAMADA_WALLET_PASSWORD` to avoid entering the password for each transaction submission. -It is now possible to set up the client. - -# Verify configuration files -After editing `config.toml` and adding wallet keys, itโ€™s time to test the configurations and ensure the system is healthy. Run the following: +#### Verify configuration files +After editing `config.toml` and adding wallet keys, it's time to test the configurations and ensure the system is healthy. Run the following: ```bash copy hermes health-check @@ -241,8 +262,21 @@ SUCCESS performed health check for all chains in the config SUCCESS "configuration is valid" ``` -### Create IBC channel -The "create channel" command (below) creates not only the IBC channel but also the necessary IBC client connection. +### Creating an IBC channel +All IBC transfers between two chains take place along a given IBC channel associated with a given IBC connection. + +Channels must be maintained after creation by regularly submitting headers to keep the client state up to date with +the counterparty chain. A client that is allowed to fall out of date may expire, and further IBC transfers along the +channel will not be possible until the client is revived through governance. Operators should not create new channels +on public networks unneccessarily; instead, they should relay on existing channels if possible. + + +The same asset transferred through different channels will not be fungible on the destination chain. Therefore, to avoid +confusion and liquidity fragmentation, it is good etiquette to check with a chain's community before creating any +new channels and to use existing channels whenever possible. + + +If no existing channel can be used, the "create channel" command (below) creates not only the IBC channel but also the necessary IBC client connection. ```bash copy hermes --config $HERMES_CONFIG \ @@ -258,14 +292,8 @@ hermes --config $HERMES_CONFIG \ Note that the above `CHAIN_IDs` will depend on your own setup, so do check this for yourself! -When the creation has been completed, you can see the channel IDs. For example, the following text shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. You will need the channel IDs for a transfer over IBC. It means that you have to specify `channel-955` as a channel ID (The prefix `channel-` is always required) for a transfer from Chain A to Chain B. Also, you have to specify `channel-460` as a channel ID for a transfer from Chain B to Chain A. - -Remember the ClientId for each of the chains, we will need them on the next step: `07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` - -```bash copy -export CLIENT_A_ID="" -export CLIENT_B_ID="" -``` +When the creation has been completed, you can see the channel IDs. For example, the output text below shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, +and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. ``` @@ -324,9 +352,23 @@ SUCCESS Channel { ``` -### Change Hermes configuration +Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID +for a transfer from Chain A to Chain B. Also, you specify +`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) + +Also note the ClientId for each of the chains; we will need them on the next step: +`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` + +```bash copy +export CLIENT_A_ID="" +export CLIENT_B_ID="" +``` + +#### Update Hermes configuration -Now when the channels are created we need to update the [Hermes configuration](#Make-Hermes-config-file) +By default, Hermes will attempt to relay packets on all channels between the chains listed in its configuration file. +We can restrict Hermes to only relay packets on our newly created channels by updating the [Hermes configuration](#Make-Hermes-config-file) +with the following (for each chain): ```bash copy ... @@ -338,50 +380,53 @@ list = [ ... ``` -### Update IBC clients - -In order to have IBC channels running they need active IBC clients they rely on. When clients are not in use they tend to expire and to prevent this they are required to be updated manually. - -The "update channel" command (below) update the actual state of the client in the particular chain. +### Running the relayer +While Hermes is running, it monitors chains via the nodes and relays packets according to monitored events. You will +likely want to use `systemd`, `tmux`, `Docker` or some similar solution to ensure Hermes is running persistently in the background. +The command to run Hermes is simply: ```bash copy -hermes update client --host-chain $CHAIN_A_ID --client $CLIENT_A_ID -hermes update client --host-chain $CHAIN_B_ID --client $CLIENT_B_ID +hermes --config $HERMES_CONFIG start ``` -It is recommended to perform this manual update or use specific scripts to automate it. Otherwise, you risk your clients will be expired. The restoration is possible only from the Governance of the specific chain. +You can see more details of Hermes at [the official documentation](https://hermes.informal.systems/). -## Start the relayer -Once you run Hermes, it monitors chains via the nodes and relays packets according to monitored events. -```bash copy -hermes --config $HERMES_CONFIG start -``` -You can see more details of Hermes at [the official document](https://hermes.informal.systems/). +#### Updating IBC clients + +In order to keep IBC channels open for transfers, they must have active IBC clients. An IBC client on chain A references +the state of chain B, and vice versa. These clients must be regularly updated to maintain trust guarantees; if they are +allowed to lapse, the client will enter an 'expired' state, and no further IBC transfers will be allowed on that channel +until the client is revived through governance. + +Whenever Hermes relays an IBC transfer, it will automatically update the clients on both chains. However, since reviving +an expired client through governance is a time-consuming task, it is worthwhile to regularly submit manual updates to +avoid any issues should transfer frequency be lower than expected. + +The "update channel" command (below) manually updates the state of a client on a particular chain. -After the sync, you can create the channel and start Hermes as explained [above](#create-ibc-channel). ```bash copy -# create a channel -hermes --config $HERMES_CONFIG \ - create channel \ - --a-chain $CHAIN_A_ID \ - --b-chain $CHAIN_B_ID \ - --a-port transfer \ - --b-port transfer \ - --new-client-connection --yes +hermes update client --host-chain $CHAIN_A_ID --client $CLIENT_A_ID +hermes update client --host-chain $CHAIN_B_ID --client $CLIENT_B_ID ``` -### Transferring assets over IBC -It is now possible to [transfer assets between the two chains.](../users/ibc.mdx) +It is recommended to schedule the above commands to run periodically (using a scheduler such `cron` or `systemd`) so that any client expiration issues can be avoided entirely. + +### Done! +You're now ready to test [transferring assets between the two chains.](../users/ibc.mdx) + + -## Set up local Namada chains using the Hermes script -The script `setup-namada` will set up two chains with one validator node, copy necessary files for Hermes, and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` in the `hermes` directory. +## Testing with local Namada chains +The script `setup-namada` in the Heliax Hermes repo will set up two chains, each with one validator node, copy necessary files for Hermes, +and make an account for Hermes on each ledger. Also, it will make a Hermes config file `config_for_namada.toml` +in the `hermes` directory. First, you will need to export some environment variables: ```bash copy export NAMADA_DIR="" -export TAG="v1.7.4-namada-beta7" +export TAG="v1.8.2-namada-beta11" # or the appropriate hermes version for your namada version ``` ```bash copy @@ -391,7 +436,7 @@ cd hermes ./scripts/setup-namada $NAMADA_DIR ``` -In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#create-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. +In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#creating-an-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. ```bash copy # create a channel hermes --config $HERMES_CONFIG \ @@ -406,7 +451,7 @@ hermes --config $HERMES_CONFIG \ hermes --config $HERMES_CONFIG start ``` -Each node data and configuration files are in `hermes/data/namada-*/.namada`. +Each node's data and configuration files are in `hermes/data/namada-*/.namada`. In order to close any ledgers setup by the script, one can run ```bash copy diff --git a/packages/docs/pages/users/ibc/_meta.json b/packages/docs/pages/users/ibc/_meta.json index a72eb5dd..031a9e38 100644 --- a/packages/docs/pages/users/ibc/_meta.json +++ b/packages/docs/pages/users/ibc/_meta.json @@ -1,4 +1,4 @@ { - "shielded-ibc": "Shielded IBC", - "transparent-ibc": "Transparent IBC" + "transparent-ibc": "Transparent IBC", + "shielded-ibc": "Shielded IBC" } \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/shielded-ibc.mdx b/packages/docs/pages/users/ibc/shielded-ibc.mdx index 09a45aae..6d22b9a3 100644 --- a/packages/docs/pages/users/ibc/shielded-ibc.mdx +++ b/packages/docs/pages/users/ibc/shielded-ibc.mdx @@ -14,57 +14,48 @@ software such as [Hermes](https://github.com/heliaxdev/hermes). - You will need to know the corresponding channel id ## IBC transfer to a shielded address -{/* TODO: instructions are out of date? */} + +Previous versions of Namada required a two-step process to make IBC transfers to a shielded address: first a MASP proof was generated using the +`ibc-gen-shielded` command, and this proof was included in the `memo` field of the transfer. -Before sending your IBC transfer, you will need to generate a MASP +It is no longer necessary to manually generate the MASP proof, and the `ibc-gen-shielded` command has been removed. + + +IBC transfers to a shielded address work similarly to those for a [tranparent address](./transparent-ibc.mdx), +the only difference being that we provide for `$RECV_ADDRESS` a shielded (`znam`) address instead of a transparent (`tnam`) one: -Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer - to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including - required data. In this case, Chain B is the destination chain. -```bash copy -namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \ - --output-folder-path ${OUTPUT_PATH} \ - --target ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --port-id transfer \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_B} -``` -Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field. -The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file -path created by `namadac ibc-gen-shielded` on the destination chain. ```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --channel-id channel-0 \ - --memo-path ${memo_path} \ - --node ${LEDGER_ADDRESS_A} +namadac ibc-transfer \ + --source $SOURCE_ADDRESS \ + --receiver $RECEIVER_PAYMENT_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT \ + --channel-id $CHANNEL_ID ``` + +Or, when sending from a Cosmos Sdk chain: -When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option. ```bash copy -memo=$(cat ${memo_path}) gaiad tx ibc-transfer transfer \ - ${CHANNEL_ID} \ - ${RECEIVER_PAYMENT_ADDRESS} \ + $CHANNEL_ID \ + $RECEIVER_PAYMENT_ADDRESS \ ${AMOUNT}${IBC_TOKEN_ADDRESS} \ - --from ${COSMOS_ALIAS} \ - --memo ${memo} \ - --node ${COSMOS_RPC_ENDPOINT} \ + --from $COSMOS_ALIAS \ + --node $COSMOS_RPC_ENDPOINT \ --fees 5000uatom ``` -You can do unshielding transfers over IBC without generating a proof. +## IBC transfer from a shielded address +You can also send IBC transfers from a shielded address, by providing the associated spending key as the source: ```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${RECEIVER_RAW_ADDRESS} \ - --token nam \ - --amount 100 \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_A} +namadac ibc-transfer \ + --source $SOURCE_SPEND_KEY \ + --receiver $RECV_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT \ + --channel-id $CHANNEL_ID \ + --gas-payer $IMPLICIT_ADDRESS ``` + +When sending any transaction from a shielded address, you must also provide an implicit address which you control with enough funds to cover gas costs. + \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/transparent-ibc.mdx b/packages/docs/pages/users/ibc/transparent-ibc.mdx index 65ea9ceb..66424c6d 100644 --- a/packages/docs/pages/users/ibc/transparent-ibc.mdx +++ b/packages/docs/pages/users/ibc/transparent-ibc.mdx @@ -3,7 +3,7 @@ import { Callout } from 'nextra-theme-docs' # Transparent IBC You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the -`ibc-transfer` command in `namadac`. +`ibc-transfer`. This section covers sending assets to and from a transparent ( `tnam` ) address. @@ -18,15 +18,15 @@ software such as [Hermes](https://github.com/heliaxdev/hermes). To make an outgoing IBC transfer from a Namada transparent address: ```bash copy namadac ibc-transfer \ - --source $YOUR_TRANSPARENT_ADDRESS \ - --receiver $ADDRESS_ON_RECEIVING_CHAIN \ + --source $SOURCE_ADDRESS \ + --receiver $RECV_ADDRESS \ --token $TOKEN_ADDRESS \ - --amount $AMOUNT + --amount $AMOUNT \ --channel-id $CHANNEL_ID ``` Note: -- the `receiver` address is the address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, -while if you're sending to a Cosmos SDK chain it might start with `cosmos...` or some other prefix. +- the `receiver` address is the raw address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, +while if you're sending to a Cosmos SDK chain it might start with `cosmos...`, `osmo...`, or some other prefix. - the `channel-id` parameter is a string, for example `channel-27`. #### Example: Sending NAM to the Cosmos Hub @@ -66,4 +66,30 @@ gaiad tx ibc-transfer transfer \ The double use of 'transfer' in the above command is not a typo. The command takes an IBC port name as one of its parameters; and the name of the port happens to be 'transfer'. - \ No newline at end of file + + +## Querying IBC balances +You can query an account's balance of tokens received through IBC similarly to other tokens, using the 'IBC denom' token name which is a function of +the IBC port, channel, and token name (or address) on the originating chain: + +``` +IBC denom = {receiving_port}/{receiving_channel}/{token_name} +``` + + +Sending the same asset through two different IBC channels will result in two different token denoms on the receiving chain, which will not be fungible with +each other. This is expected behavior as defined in the IBC protocol. + + +#### Example: Balance query +If we have sent 100 NAM (token address `tnam1q87wtaqqtlwkw927gaff34hgda36huk0kgry692a`) from chain A to chain B over IBC, where the port is `transfer` and channel __on the receiving chain__ +is `channel-0`, we can check the balance on chain B using either of these (equivalent) commands: + +```bash copy +namadac balance --owner $ALIAS --token transfer/channel-0/nam +# or +namadac balance --owner $ALIAS --token transfer/channel-0/tnam1q87wtaqqtlwkw927gaff34hgda36huk0kgry692a + +# Output: +# transfer/channel-0/nam: 100 +```