​
Background

IBC Eureka is the official native implementation of IBC v2 It leverages the Cosmos Hub and Interchain Labs contracts, relayers, and infrastructure to enable seamless cross-chain user and liquidity mobility.

The following guide explains how to test IBC Eureka’s Devnet deployment via a CLI tool developed to interact with IBC Eureka, enabling trust-minimized token transfers between Ethereum and Cosmos chains.

​
Prerequisites

  • Go 1.19 or later
  • Access to Ethereum and Cosmos endpoints
  • Private keys for both chains
  • Sepolia ETH for gas fees on the Ethereum Sepolia Testnet
  • An ERC20 token on Ethereum Sepolia Testnet

​
Installation

  1. First clone the repository
git clone https://github.com/cosmos/solidity-ibc-eureka
  1. Navigate to where the repo now lives on your machine, and move into the cmd folder to build the CLI
cd solidity-ibc-eureka/e2e/interchaintestv8/cmd
  1. Fetch and checkout the devenet-deployment [sic] branch that contains the CLI tool:
git fetch
git checkout gjermund/devenet-deployment
  1. Build the CLI tool to test transferring and relaying Eureka packets on devnet
go build -o eureka-cli

​
Keys

Once the CLI is built, the next steps are to set up the Ethereum Sepolia and Cosmos devnet keys and addresses to use. Currently, you’ll need to store your private keys for both Cosmos and Ethereum as environment variables.

Warning: Do not use mainnet keys for this testing CLI.

There are three accounts required:

  1. ETH_PRIVATE_KEY: You can retrieve an Ethereum private key from within Metamask by creating a new account > navigating to “Account details” > and pressing “Show private key”
    • To test a transfer from Ethereum Sepolia to the Cosmos Devnet, you’ll need to have testnet ETH on this account. You can use any Ethereum Sepolia faucet for this, an example is: Google Cloud Ethereum Sepolia Faucet
    • You’ll also be transferring an ERC20 token. You can use Token Tool to create a new ERC20 token on Ethereum Sepolia Testnet and use that in your command to do a Eureka transfer from Sepolia Testnet to Cosmos Devnet.
  2. COSMOS_PRIVATE_KEY: This will be used as the initiator of a transfer in the other direction. You can retrieve a Cosmos unarmored-hex private key by following the following steps:
    1. Installing a node daemon CLI: simd or gaiad.
    2. Adding keys to the daemon CLI: gaiad keys add <account-name> --recover
    3. Entering the BIP-39 mnemonic for the account you want to add. (Remove --recover to generate new)
    4. Exporting the unarmored hex: gaiad keys export <account-name> --unarmored-hex --unsafe
  3. RELAYER_WALLET: For devnet, we are providing relayer keys manually. Reach out to the Interchain Labs team, and we will provide the private key for your use.

Once all the necessary private keys are obtained, run the following command to set them as environment variables:

export ETH_PRIVATE_KEY="your-ethereum-private-key"
export COSMOS_PRIVATE_KEY="your-cosmos-unarmored-hex-private-key"
export RELAYER_WALLET="ask-icl-team-for-the-testing-key"

Note: All three of the above are hexadecimal private keys, each 64 characters long.

​
Commands

​
Transfer ERC20 Tokens from Ethereum to Cosmos

Format:

go run ./ transfer-from-eth-to-cosmos [amount] [erc20-contract-address] [to-address] [flags]

Example:

go run ./ transfer-from-eth-to-cosmos 1 0xA4ff49eb6E2Ea77d7D8091f1501385078642603f cosmos1u5d4hk8294fs9pq556jxmlju2ceh4jmurcpfv7 \
  --eth-rpc="https://ethereum-sepolia-rpc.publicnode.com" \
  --ics20-address="0xbb87C1ACc6306ad2233a4c7BBE75a1230409b358" \
  --source-client-id="client-0"

This will give you a tx hash in the output.

​
Relay the Transaction from Ethereum to Cosmos

Format:

go run ./ relay_tx [txHash] [flags]

Example:

go run ./ relay_tx 0xed13b2567a00eae7d0a6c8e24d1cf6342116d1d89d72ff9b52b690cdd3a5dd98 \
  --eth-rpc="https://ethereum-sepolia-rpc.publicnode.com" \
  --cosmos-rpc="https://eureka-devnet-node-01-rpc.dev.skip.build:443"

​
Transfer Tokens from Cosmos to Ethereum (Back Again!)

Depending on if the token is native to the chain (uatom for the Cosmos Devnet) or is an IBC’d token from Ethereum Sepolia, the denom to use in the command is as follows:

  1. If IBC transferring a token native to the chain, you can use the denom you expect (uatom) in the command.
  2. If IBC transferring a token that was already IBC transferred from Ethereum, you’ll use the IBC denom of the token, beginning with transfer/08-wasm-0/0x (from the balance command below).

Format:

go run ./ transfer-from-cosmos-to-eth [amount] [denom] [to-ethereum-address] [flags]

Example (Native token):

go run ./ transfer-from-cosmos-to-eth 1 uatom 0x94B00F484232D55Cc892BbE0b0C1c4a9ad112098

Example (IBC token):

go run ./ transfer-from-cosmos-to-eth 1 transfer/08-wasm-0/0xa4ff49eb6e2ea77d7d8091f1501385078642603f 0x94B00F484232D55Cc892BbE0b0C1c4a9ad112098

This will give you a tx hash in the output, needed for relaying.

​
Relay the Transaction from Cosmos to Ethereum

Format:

go run ./ relay_tx [txHash] [flags]

Example:

go run ./ relay_tx 28D0B356557DC625D62649E7B1E05B8730898389B8D888E9C920BED33429D9EB \
  --eth-rpc="https://ethereum-sepolia-rpc.publicnode.com" \
  --cosmos-rpc="https://eureka-devnet-node-01-rpc.dev.skip.build:443"

This is the same as the previous relay, but from the format of the txHash, the relayer knows in which direction the relay needs to happen.

​
Check Balance of Cosmos Account

To check the balance on Cosmos, enter a Cosmos cosmos1 address into the [address] flag.

#Usage:
go run ./ balance [address] [optional-denom-or-erc20-address] [flags]

Example:

go run ./ balance cosmos1u5d4hk8294fs9pq556jxmlju2ceh4jmurcpfv7

Output:

IBC Denom: ibc/2351096B1729B2C64AED9F6AFD4A4BC28EB56F624881556947A8C48EDB9ED444
transfer/08-wasm-0/0xa4ff49eb6e2ea77d7d8091f1501385078642603f: 1

​
Check Balance of Ethereum Sepolia Account

To check the balance on Ethereum, enter an Ethereum 0x address into the [address] flag.

Format:

go run ./ balance [address] [optional-denom-or-erc20-address] [flags]

Example:

go run ./ balance 0x94B00F484232D55Cc892BbE0b0C1c4a9ad112098

Example Output:

0xA4ff49eb6E2Ea77d7D8091f1501385078642603f: 999999997
ETH: 0.092298623946995983

​
Coming Soon

  1. Deployment of CosmWasm forwarding contracts to test Ethereum → Cosmos Chain A → Cosmos Chain B.

​
Contact Us

Please reach out to the Interchain Labs team if you have any issues using the Telegram handles below, reaching out to us on any established communication channels, or by opening up a support ticket in our Discord via the Support button in the left side menu!

Tg: @OllieGilbey, @NotJeremyLiu

Swap Venue RequirementsTerms of Service