Local-Interchain: Launch Private Testnets for Rapid Development

Local-Interchain is a local testnet platform written for Inter-Blockchain Communication (IBC) contracts and protocols. This product leverages Strangelove’s interchaintest to easily configure and interact with chains in a language-agnostic way. This helps developers stand up multi-chain environments with smart contracts and connect them seamlessly via IBC.

Historically, local environments are specific to their chain’s application. With our approach, we can leverage any appropriate docker image to spin up a network with a few lines of JSON. Further interaction in any language can be accomplished through a REST API, with Rust and Python drivers built out already.

Get started today with our pre-built binary found in the Github releases. Our Video Walkthrough gives examples using Juno.

Background

One of the hardest parts of end-to-end testing is the lack of tooling for cross-chain interactions. It is our goal to minimize the hurdles for setup and operations of local testing environments so developers can focus on their applications, not the hassle of setup. Developers come from many backgrounds in terms of skill, languages, and understanding of blockchain platforms. As we drive further adoption of IBC, the hurdles required to begin developing must be reduced to allow for a wider audience of builders. Local Interchain is that solution.

Previous teams would have to write their own setups independently for each use case. This is simple for single chain interactions (e.g. launch a single chain and run simd binary commands against the network to test interactions). The issue arises when it comes to scaling to multiple networks, adding a relayer, interacting with contracts, or performing more complex IBC scenarios.

While developers could use interchaintest for this, the biggest downside is the requirement to know the Go programming language. This solution is perfect for protocol engineers in Cosmos who already write their networks in Go. It is less viable for programmers who are not conversant in Golang. The elimination of this knowledge requirement enables faster development in the ecosystem by saving test setup time and catching issues before they are pushed to the public.

Another missing piece to improved IBC testing workflows is the support for other major platforms. Until now only Mac and Linux have been supported. This changes with local-interchain as we have Mac, Linux, Windows (7+), and Windows Server (2016 or newer) support from day one. This sets the foundation for the test suite to become the HardHat for the Cosmos.

Interaction & Setup

Local-Interchain only assumes three requirements for developers to understand:

1. JSON formatting
2. REST API functions
3. Absolute basics of a Cosmos chain (name, wallet prefix, and token)

With these low barriers to entry, we abstract all the initial complexities into the setup phase with JSON. They do not need to know what IBC channels are or the details of the send tokens command. They just interact with the Rust or Python client drivers to perform these on their behalf. Once a developer is comfortable with this, they can look deeper into the drivers to see how the binary interactions and queries take place, but this is not a requirement to get started.

Here is an example JSON file provided in the local-interchain directory

{
    "chains": [
        {
            "name": "juno",
            "chain_id": "localjuno-1",
            "binary": "junod",
            "bech32_prefix": "juno",
            "denom": "ujuno",
            "docker_image": {
                "version": "v17.0.0"
            },
            "encoding-options": ["wasm"]
        }
    ]
}

With the above configuration we set up the chain on the requested version with the desired variables set. As a developer you do not have to know what these mean initially, the defaults work right away.

Advanced developers can add extra fields to modify the chain, tailoring it to their use cases. This includes using external docker repository images, coin types, trusting periods, block times, IBC connections, genesis modifications, extra pre-funded accounts, and startup commands.

{    
    "chains": [
        {
            "name": "juno",            
            "chain_id": "localjuno-1",
            "denom": "ujuno",
            "binary": "junod",
            "bech32_prefix": "juno",
            "docker_image": {
                "repository": "ghcr.io/strangelove-ventures/heighliner/juno",
                "version": "v17.0.0"
            },            
            "gas_prices": "0%DENOM%",
            "chain_type": "cosmos",
            "coin_type": 118,
            "trusting_period": "112h",
            "gas_adjustment": 2.0,
            "number_vals": 2,
            "number_node": 0,           
            "debugging": true,
            "block_time": "500ms",
            "encoding-options": ["wasm"],
      "ibc_paths": ["juno-ibc"],
            "genesis": {
                "modify": [
                    {
                        "key": "app_state.gov.params.voting_period",
                        "value": "15s"
                    },
                    {
                        "key": "app_state.gov.params.max_deposit_period",
                        "value": "15s"
                    },
                    {
                        "key": "app_state.gov.params.min_deposit.0.denom",
                        "value": "%DENOM%"
                    },
                    {
                        "key": "app_state.gov.params.min_deposit.0.amount",
                        "value": "1"
                    }
                ],     
                "accounts": [
                    {
                        "name": "acc0",
                        "address": "juno1hj5fveer5cjtn4wd6wstzugjfdxzl0xps73ftl", 
                        "amount": "10000000000%DENOM%",
                        "mnemonic": "decorate bright ozone fork gallery riot bus exhaust worth way bone indoor calm squirrel merry zero scheme cotton until shop any excess stage laundry"
                    }
                ],
                "startup_commands": [
                    "%BIN% keys add example-key-after --keyring-backend test --home %HOME%"                    
                ] 
            }
        },
    ...
    ]
}

Once your chain is configured and running, the REST API (documentation) offers an interface to interact with your local blockchain environment(s). This API serves as a tool for developers to automate testing processes, upload files, perform relayer actions, and execute transactions.

Use cases

CosmWasm Contracts with IBC

As a developer you may want to ensure your code works in production, this is where end-to-end testing is most valuable. Using Github CI and local-interchain, you can now do this all natively in Rust! This removes the hassle of setting up multiple chains and a relayer, simplifying your workflow drastically.

• Rust E2E Contracts example (Action CI)

• Simple External Repo Example (Video Walkthrough)

Quick Testnets

Another great feature is the ability to spin up a local testnet for development purposes. Larger chains typically have both a testnet and mainnet network. For newer smaller teams this may not be economically viable. Now you can get this same level of validation with significantly less resources. Easily setting up relayers, pre-funding accounts, and getting your users to interact with your product.

Proposals

With the ability to modify genesis state, you can match the configuration of a mainnet to simulate governance proposals. Developers can tailor the JSON configuration to simulate various on-chain governance scenarios. The proposer can then execute it on the local environment, wait a few seconds for the proposal to pass, and query the chain to validate all parameters updated as intended. From here you can push to the mainnet with confidence.

Future Plans

Interactions with live environments

An exciting future update to local-interchain will bring support to interact with testnets and mainnets, not just locally. This will remove the hassle of multiple binary versions being installed  and instead automatically update docker images in accordance to their mainnet versions. E.g. if mainnet is on v13.0.2, we can automatically pull this down on a request to mainnet so you are up to date. This is especially useful for cross chain bots and future webapps to improve cross-chain UX outside of the browser.

This also enables continuous delivery pipelines via Github Actions. When a release is tagged, the contract(s) can be automatically pushed to testnet or mainnet and save those code-ids for others to use.

More IBC Abilities

Currently ics-20 transfer and wasm<->wasm IBC are the core features to local-interchain. As the IBC stack continues to grow we will add further support for interchain-accounts, the 08-wasm light client, and also other interchain protocols not built on the native Cosmos-SDK stack.

Typescript / Javascript Drivers

While Rust, Python, Go, and Bash cover a large portion of the market, expansion into the Javascript ecosystem is necessary to onboard web developers to build on the IBC stack. This is a high priority to bridge the gap between backend and frontend engineer testing environments.