diff --git a/README.md b/README.md index 830bd1554..bbdaaf18f 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,69 @@
-

interchaintest

+

interchaintest

Formerly known as `ibctest`. [![Go Reference](https://pkg.go.dev/badge/github.com/strangelove-ventures/interchaintest@main.svg)](https://pkg.go.dev/github.com/strangelove-ventures/interchaintest@main) [![License: Apache-2.0](https://img.shields.io/github/license/strangelove-ventures/interchaintest.svg?style=flat-square)](https://github.com/strangelove-ventures/interchaintest/blob/main/create-test-readme/LICENSE) [![Go Report Card](https://goreportcard.com/badge/github.com/strangelove-ventures/interchaintest)](https://goreportcard.com/report/github.com/strangelove-ventures/interchaintest) +[![Conforms to README.lint](https://img.shields.io/badge/README.lint-conforming-brightgreen)](https://github.com/strangelove-ventures/readme-dot-lint) +
-`interchaintest` orchestrates Go tests that utilize Docker containers for multiple -[IBC](https://docs.cosmos.network/master/ibc/overview.html)-compatible blockchains. +🌌 Why use `interchaintest`? +============================= -It allows users to quickly spin up custom testnets and dev environments to test IBC, chain infrastructures, smart contracts, etc. - +In order to ship production-grade software for the Interchain, we needed sophisticated developer tooling...but IBC and Web3 have a *lot* of moving parts, which can lead to a steep learning curve and all sorts of pain. Recognize any of these? + +- repeatedly building repo-specific, Docker- and shell-based testing solutions, +- duplication of effort, and +- difficulty in repurposing existing testing harnesses for new problem domains. + +We built `interchaintest` to extract patterns and create a generic test harness: a use-case-agnostic framework for generating repeatable, diagnostic tests for every aspect of IBC. + +Read more at the [Announcing `interchaintest` blog post](https://strange.love/blog/announcing-interchaintest). + +🌌🌌 Who benefits from `interchaintest`? +============================= + +`interchaintest` is for developers who expect top-shelf testing tools when working on blockchain protocols such as Cosmos or Ethereum. + + +🌌🌌🌌 What does `interchaintest` do? +============================= + +`interchaintest` is a framework for testing blockchain functionality and interoperability between chains, primarily with the Inter-Blockchain Communication (IBC) protocol. + +Want to quickly spin up custom testnets and dev environments to test IBC, [Relayer](https://github.com/cosmos/relayer) setup, chain infrastructure, smart contracts, etc.? `interchaintest` orchestrates Go tests that utilize Docker containers for multiple [IBC](https://www.ibcprotocol.dev/)-compatible blockchains. -## Table Of Contents -- [Branch Versioning](#maintained-branches) -- **Use Cases:** - - **Importing as a Module** - - [Chain Integration and GitHub CI](./docs/ciTests.md) - - [Running Conformance Tests](./docs/conformance-tests-lib.md) - - **Running as a Binary** - - [Building Binary](./docs/buildBinary.md) - - [Running Conformance Tests](./docs/conformance-tests-bin.md) - Suite of built-in tests that test high-level IBC compatibility -- [Write Custom Tests](./docs/writeCustomTests.md) + + +🌌🌌🌌🌌 How do I use it? +============================= + +## As a Module + +Most people choose to import `interchaintest` as a module. +- Often, teams will [integrate `interchaintest` with a github CI/CD pipeline](./docs/ciTests.md). +- Most teams will write their own suite. Here's a tutorial on [Writing Custom Tests](./docs/writeCustomTests.md). +- You can also [utilize our suite of built-in Conformance Tests that exercise high-level IBC compatibility](./docs/conformance-tests-lib.md). + +## As a Binary + +There's also an option to [build and run `interchaintest` as a binary](./docs/buildBinary.md) (which might be preferable, e.g., with custom chain sets). You can still [run Conformance Tests](./docs/conformance-tests-bin.md). + + +## References - [Environment Variable Options](./docs/envOptions.md) - [Retaining Data on Failed Tests](./docs/retainingDataOnFailedTests.md) +🌌🌌🌌🌌🌌 Extras +============================= + + + ### Maintained Branches | **Branch Name** | **IBC-Go** | **Cosmos-sdk** | @@ -36,29 +71,29 @@ It allows users to quickly spin up custom testnets and dev environments to test | [main](https://github.com/strangelove-ventures/interchaintest) | v8 | v0.50 | | [v7](https://github.com/strangelove-ventures/interchaintest/tree/v7) | v7 | v0.47 | -### Depreciated Branches +### Deprecated Branches These are branches that we no longer actively update or maintain but may be of use if a chain is running older versions of the `Cosmos SDK ` or `IBC Go`. Please see the [Backport Policy](#backport-policy) below. -| **Branch Name** | **IBC-Go** | **Cosmos-sdk** | **Depreciated Date** | +| **Branch Name** | **IBC-Go** | **Cosmos-sdk** | **Deprecated Date** | |:----------------------------------------------------------------------------:|:----------:|:--------------:|:--------------------:| -| [v6](https://github.com/strangelove-ventures/interchaintest/tree/v6) | v6 | v0.46 | Sept 5 2023 | -| [v5](https://github.com/strangelove-ventures/interchaintest/tree/v5) | v5 | v0.46 | Aug 11 2023 | -| [v4](https://github.com/strangelove-ventures/interchaintest/tree/v4) | v4 | v0.45 | Aug 11 2023 | -| [v4-ics](https://github.com/strangelove-ventures/interchaintest/tree/v4-ics) | v4 | v0.45.x-ics | Aug 11 2023 | -| [v3](https://github.com/strangelove-ventures/interchaintest/tree/v3) | v3 | v0.45 | June 25 2023 | -| [v3-ics](https://github.com/strangelove-ventures/interchaintest/tree/v3-ics) | v3 | v0.45.11-ics | April 24 2023 | +| [v6](https://github.com/strangelove-ventures/interchaintest/tree/v6) | v6 | v0.46 | Sept 5 2023 | +| [v5](https://github.com/strangelove-ventures/interchaintest/tree/v5) | v5 | v0.46 | Aug 11 2023 | +| [v4](https://github.com/strangelove-ventures/interchaintest/tree/v4) | v4 | v0.45 | Aug 11 2023 | +| [v4-ics](https://github.com/strangelove-ventures/interchaintest/tree/v4-ics) | v4 | v0.45.x-ics | Aug 11 2023 | +| [v3](https://github.com/strangelove-ventures/interchaintest/tree/v3) | v3 | v0.45 | June 25 2023 | +| [v3-ics](https://github.com/strangelove-ventures/interchaintest/tree/v3-ics) | v3 | v0.45.11-ics | April 24 2023 | #### Backport Policy: -Strangelove maintains `n` and `n - 1` branches of interchaintest, `n` being current `main`. +Strangelove maintains `n` and `n - 1` branches of `interchaintest`, `n` being current `main`. -We strive to keep interchaintest inline with the latest from the ibc-go and cosmos sdk teams. Once an alpha versions of the next major ibc-go version is released, we will discontinue `n - 1` and branch off a new `n`. +We strive to keep `interchaintest` inline with the latest from the ibc-go and cosmos sdk teams. Once an alpha versions of the next major ibc-go version is released, we will discontinue `n - 1` and branch off a new `n`. **Recommendation:** Even if your chain uses an older version of ibc-go, try importing from `main`. This should work unless you are decoding transactions that require a specific ibc-go version. -If there is a feature you would like backported to an older branch, make an issue! We are happy to work with you. +If there is a feature you would like backported to an older branch, make an issue! We are happy to work with you. ## Contributing diff --git a/ibc/relayer.go b/ibc/relayer.go index 0202f2a3a..f48a42f72 100644 --- a/ibc/relayer.go +++ b/ibc/relayer.go @@ -27,7 +27,7 @@ type Relayer interface { RestoreKey(ctx context.Context, rep RelayerExecReporter, cfg ChainConfig, keyName, mnemonic string) error // generate a new key - AddKey(ctx context.Context, rep RelayerExecReporter, chainID, keyName, coinType string) (Wallet, error) + AddKey(ctx context.Context, rep RelayerExecReporter, chainID, keyName, coinType, signingAlgorithm string) (Wallet, error) // GetWallet returns a Wallet for that relayer on the given chain and a boolean indicating if it was found. GetWallet(chainID string) (Wallet, bool) diff --git a/ibc/types.go b/ibc/types.go index ee814cfd3..cfacb718b 100644 --- a/ibc/types.go +++ b/ibc/types.go @@ -30,6 +30,8 @@ type ChainConfig struct { Denom string `yaml:"denom"` // Coin type CoinType string `default:"118" yaml:"coin-type"` + // Key signature algorithm + SigningAlgorithm string `default:"secp256k1" yaml:"signing-algorithm"` // Minimum gas prices for sending transactions, in native currency denom. GasPrices string `yaml:"gas-prices"` // Adjustment multiplier for gas fees. diff --git a/relayer/docker.go b/relayer/docker.go index 2fb06e9a9..c67be6efa 100644 --- a/relayer/docker.go +++ b/relayer/docker.go @@ -186,8 +186,8 @@ func (r *DockerRelayer) AddChainConfiguration(ctx context.Context, rep ibc.Relay return res.Err } -func (r *DockerRelayer) AddKey(ctx context.Context, rep ibc.RelayerExecReporter, chainID, keyName, coinType string) (ibc.Wallet, error) { - cmd := r.c.AddKey(chainID, keyName, coinType, r.HomeDir()) +func (r *DockerRelayer) AddKey(ctx context.Context, rep ibc.RelayerExecReporter, chainID, keyName, coinType, signingAlgorithm string) (ibc.Wallet, error) { + cmd := r.c.AddKey(chainID, keyName, coinType, signingAlgorithm, r.HomeDir()) // Adding a key should be near-instantaneous, so add a 1-minute timeout // to detect if Docker has hung. @@ -325,7 +325,7 @@ func (r *DockerRelayer) Exec(ctx context.Context, rep ibc.RelayerExecReporter, c func (r *DockerRelayer) RestoreKey(ctx context.Context, rep ibc.RelayerExecReporter, cfg ibc.ChainConfig, keyName, mnemonic string) error { chainID := cfg.ChainID coinType := cfg.CoinType - cmd := r.c.RestoreKey(chainID, keyName, coinType, mnemonic, r.HomeDir()) + cmd := r.c.RestoreKey(chainID, keyName, coinType, cfg.SigningAlgorithm, mnemonic, r.HomeDir()) // Restoring a key should be near-instantaneous, so add a 1-minute timeout // to detect if Docker has hung. @@ -551,7 +551,7 @@ type RelayerCommander interface { // The remaining methods produce the command to run inside the container. AddChainConfiguration(containerFilePath, homeDir string) []string - AddKey(chainID, keyName, coinType, homeDir string) []string + AddKey(chainID, keyName, coinType, signingAlgorithm, homeDir string) []string CreateChannel(pathName string, opts ibc.CreateChannelOptions, homeDir string) []string CreateClients(pathName string, opts ibc.CreateClientOptions, homeDir string) []string CreateConnections(pathName, homeDir string) []string @@ -562,7 +562,7 @@ type RelayerCommander interface { GetConnections(chainID, homeDir string) []string GetClients(chainID, homeDir string) []string LinkPath(pathName, homeDir string, channelOpts ibc.CreateChannelOptions, clientOpts ibc.CreateClientOptions) []string - RestoreKey(chainID, keyName, coinType, mnemonic, homeDir string) []string + RestoreKey(chainID, keyName, coinType, signingAlgorithm, mnemonic, homeDir string) []string StartRelayer(homeDir string, pathNames ...string) []string UpdateClients(pathName, homeDir string) []string CreateWallet(keyName, address, mnemonic string) ibc.Wallet diff --git a/relayer/hermes/hermes_commander.go b/relayer/hermes/hermes_commander.go index ad9cc5a7d..0d1bbdb7a 100644 --- a/relayer/hermes/hermes_commander.go +++ b/relayer/hermes/hermes_commander.go @@ -165,7 +165,7 @@ func (c commander) LinkPath(pathName, homeDir string, channelOpts ibc.CreateChan panic("link path implemented in hermes relayer not the commander") } -func (c commander) RestoreKey(chainID, keyName, coinType, mnemonic, homeDir string) []string { +func (c commander) RestoreKey(chainID, keyName, coinType, signingAlgorithm, mnemonic, homeDir string) []string { panic("restore key implemented in hermes relayer not the commander") } @@ -173,7 +173,7 @@ func (c commander) AddChainConfiguration(containerFilePath, homeDir string) []st panic("add chain configuration implemented in hermes relayer not the commander") } -func (c commander) AddKey(chainID, keyName, coinType, homeDir string) []string { +func (c commander) AddKey(chainID, keyName, coinType, signingAlgorithm, homeDir string) []string { panic("add key implemented in hermes relayer not the commander") } diff --git a/relayer/hyperspace/hyperspace_commander.go b/relayer/hyperspace/hyperspace_commander.go index e98544ddf..eff0c96cf 100644 --- a/relayer/hyperspace/hyperspace_commander.go +++ b/relayer/hyperspace/hyperspace_commander.go @@ -30,7 +30,7 @@ type pathConfiguration struct { // pathChainConfig holds all values that will be required when interacting with a path. type pathChainConfig struct { - chainID string + chainID string } func (hyperspaceCommander) Name() string { @@ -51,7 +51,7 @@ func (c *hyperspaceCommander) AddChainConfiguration(containerFilePath, homeDir s } // Hyperspace doesn't not have this functionality -func (hyperspaceCommander) AddKey(chainID, keyName, coinType, homeDir string) []string { +func (hyperspaceCommander) AddKey(chainID, keyName, coinType, signingAlgorithm, homeDir string) []string { panic("[AddKey] Do not call me") } @@ -193,7 +193,7 @@ func (hyperspaceCommander) LinkPath(pathName, homeDir string, channelOpts ibc.Cr // There is no hyperspace call to restore the key, so this can't return an executable. // HyperspaceRelayer's RestoreKey will restore the key in the chain's config file -func (hyperspaceCommander) RestoreKey(chainID, bech32Prefix, coinType, mnemonic, homeDir string) []string { +func (hyperspaceCommander) RestoreKey(chainID, bech32Prefix, coinType, signingAlgorithm, mnemonic, homeDir string) []string { panic("[RestoreKey] Do not use me") } diff --git a/relayer/rly/cosmos_relayer.go b/relayer/rly/cosmos_relayer.go index c59f2d1c0..d686b7005 100644 --- a/relayer/rly/cosmos_relayer.go +++ b/relayer/rly/cosmos_relayer.go @@ -120,10 +120,12 @@ func (commander) AddChainConfiguration(containerFilePath, homeDir string) []stri } } -func (commander) AddKey(chainID, keyName, coinType, homeDir string) []string { +func (commander) AddKey(chainID, keyName, coinType, signingAlgorithm, homeDir string) []string { return []string{ "rly", "keys", "add", chainID, keyName, - "--coin-type", fmt.Sprint(coinType), "--home", homeDir, + "--coin-type", fmt.Sprint(coinType), + "--signing-algorithm", signingAlgorithm, + "--home", homeDir, } } @@ -224,10 +226,12 @@ func (commander) LinkPath(pathName, homeDir string, channelOpts ibc.CreateChanne } } -func (commander) RestoreKey(chainID, keyName, coinType, mnemonic, homeDir string) []string { +func (commander) RestoreKey(chainID, keyName, coinType, signingAlgorithm, mnemonic, homeDir string) []string { return []string{ "rly", "keys", "restore", chainID, keyName, mnemonic, - "--coin-type", fmt.Sprint(coinType), "--home", homeDir, + "--coin-type", fmt.Sprint(coinType), + "--signing-algorithm", signingAlgorithm, + "--home", homeDir, } }