​
Background

IBC Eureka is the official native implementation of IBC v2 that 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
cd solidity-ibc-eureka
  1. Fetch and checkout the devnet deployment branch that contains the CLI tool:
git fetch
git checkout gjermund/devenet-deployment
  1. Move into the cmd folder to build the CLI
cd e2e/interchaintestv8/cmd
  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 receiver of an Ethereum Sepolia to Cosmos Devnet transfer and initiates transfers in the opposite 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.

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

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"

​
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 0xAe3E5CCaF3216de61090E68Cf5a191f3b75CaAd3 \
  --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

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" \
  --verbose

​
Check Balance of Ethereum Sepolia Account

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. Script/CLI command to send IBC Eureka transfers from Cosmos to Ethereum.
  2. Deployment of CosmWasm forwarding contracts to test Ethereum → Cosmos Chain A → Cosmos Chain B.
Swap Venue RequirementsTerms of Service