Devnet Testing Guide

This document describes how to test IBC Eureka on Devnet

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. This guide currently shows the steps for transactions between Ethereum Sepolia Testnet and a Cosmos Hub Devnet we spun up for the purpose.

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

Clone the repository

git clone https://github.com/cosmos/solidity-ibc-eureka && cd solidity-ibc-eureka

2

Checkout the devnet branch

git fetch
git checkout gjermund/devnet-3

3

Change to the cmd folder

cd e2e/interchaintestv8/cmd

4

Build the CLI tool

go build -o eureka-cli

Keys

Do not use mainnet keys for the testing CLI

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.

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 Etheruem to Cosmos

Usage

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

This will give you a txHash in the output.

Relay the transction from Ethereum to Cosmos

Usage

go run ./ relay-tx [txHash] [flags]

Transfer tokens back from Cosmos to Ethereum

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).

Usage

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

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

Relay the transaction from Cosmos to Ethereum

Usage

go run ./ relay_tx [txHash] [flags]

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 the balance of a Cosmos account

Usage

# To check the balance on Cosmos, enter a Cosmos `cosmos1` address into the `[address]` flag.
go run ./ balance [address] [optional-denom-or-erc20-address] [flags]

Check the balance of an Ethereum Sepolia account

Usage

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

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!

Telegram handles: @OllieGilbey, @NotJeremyLiu