ibc

Documentation

Index

• type Chain
• type ChainConfig
• type DockerImage
  • func (i DockerImage) Ref() string
• type NopRelayerExecReporter
  • func (NopRelayerExecReporter) TrackRelayerExec(string, []string, string, string, int, time.Time, time.Time, error)
• type Order
• type Relayer
• type RelayerConfig
• type RelayerExecReporter
• type RelayerExecResult
• type RelayerMap
  • func (r RelayerMap) AddRelayer(testName string, relayer Relayer, chainID string)
  • func (r RelayerMap) ContainsRelayer(testName string, wallet Wallet) bool
• type Wallet
• type WalletAmount

Types

type Chain

type Chain interface {
	// Config fetches the chain configuration.
	Config() ChainConfig

	// Initialize initializes node structs so that things like initializing keys can be done before starting the chain
	Initialize(ctx context.Context, testName string, cli *client.Client, networkID string) error

	// Start sets up everything needed (validators, gentx, fullnodes, peering, additional accounts) for chain to start from genesis.
	Start(testName string, ctx context.Context, additionalGenesisWallets ...WalletAmount) error

	// Exec runs an arbitrary command using Chain's docker environment.
	// Whether the invoked command is run in a one-off container or execing into an already running container
	// is up to the chain implementation.
	//
	// "env" are environment variables in the format "MY_ENV_VAR=value"
	Exec(ctx context.Context, cmd []string, env []string) (stdout, stderr []byte, err error)

	// ExportState exports the chain state at specific height.
	ExportState(ctx context.Context, height int64) (string, error)

	// GetRPCAddress retrieves the rpc address that can be reached by other containers in the docker network.
	GetRPCAddress() string

	// GetGRPCAddress retrieves the grpc address that can be reached by other containers in the docker network.
	GetGRPCAddress() string

	// GetHostRPCAddress returns the rpc address that can be reached by processes on the host machine.
	// Note that this will not return a valid value until after Start returns.
	GetHostRPCAddress() string

	// GetHostGRPCAddress returns the grpc address that can be reached by processes on the host machine.
	// Note that this will not return a valid value until after Start returns.
	GetHostGRPCAddress() string

	// HomeDir is the home directory of a node running in a docker container. Therefore, this maps to
	// the container's filesystem (not the host).
	HomeDir() string

	// CreateKey creates a test key in the "user" node (either the first fullnode or the first validator if no fullnodes).
	CreateKey(ctx context.Context, keyName string) error

	// RecoverKey recovers an existing user from a given mnemonic.
	RecoverKey(ctx context.Context, name, mnemonic string) error

	// GetAddress fetches the bech32 address for a test key on the "user" node (either the first fullnode or the first validator if no fullnodes).
	GetAddress(ctx context.Context, keyName string) ([]byte, error)

	// SendFunds sends funds to a wallet from a user account.
	SendFunds(ctx context.Context, keyName string, amount WalletAmount) error

	// Height returns the current block height or an error if unable to get current height.
	Height(ctx context.Context) (uint64, error)

	// GetBalance fetches the current balance for a specific account address and denom.
	GetBalance(ctx context.Context, address string, denom string) (int64, error)

	// GetGasFeesInNativeDenom gets the fees in native denom for an amount of spent gas.
	GetGasFeesInNativeDenom(gasPaid int64) int64

	// BuildWallet will return a chain-specific wallet
	// If mnemonic != "", it will restore using that mnemonic
	// If mnemonic == "", it will create a new key, mnemonic will not be populated
	BuildWallet(ctx context.Context, keyName string, mnemonic string) (Wallet, error)

	// BuildRelayerWallet will return a chain-specific wallet populated with the mnemonic so that the wallet can
	// be restored in the relayer node using the mnemonic. After it is built, that address is included in
	// genesis with some funds.
	BuildRelayerWallet(ctx context.Context, keyName string) (Wallet, error)
}

type ChainConfig

type ChainConfig struct {
	// Chain type, e.g. cosmos.
	Type string `yaml:"type"`
	// Chain name, e.g. cosmoshub.
	Name string `yaml:"name"`
	// Chain ID, e.g. cosmoshub-4
	ChainID string `yaml:"chain-id"`
	// Docker images required for running chain nodes.
	Images []DockerImage `yaml:"images"`
	// Binary to execute for the chain node daemon.
	Bin string `yaml:"bin"`
	// Bech32 prefix for chain addresses, e.g. cosmos.
	Bech32Prefix string `yaml:"bech32-prefix"`
	// Denomination of native currency, e.g. uatom.
	Denom string `yaml:"denom"`
	// Coin type
	CoinType string `default:"118" yaml:"coin-type"`
	// Minimum gas prices for sending transactions, in native currency denom.
	GasPrices string `yaml:"gas-prices"`
	// Adjustment multiplier for gas fees.
	GasAdjustment float64 `yaml:"gas-adjustment"`
	// Trusting period of the chain.
	TrustingPeriod string `yaml:"trusting-period"`
	// Do not use docker host mount.
	NoHostMount bool `yaml:"no-host-mount"`
	// When true, will skip validator gentx flow
	SkipGenTx bool
	// When provided, will run before performing gentx and genesis file creation steps for validators.
	PreGenesis func(ChainConfig) error
	// When provided, genesis file contents will be altered before sharing for genesis.
	ModifyGenesis func(ChainConfig, []byte) ([]byte, error)
	// Override config parameters for files at filepath.
	ConfigFileOverrides map[string]any
}

ChainConfig defines the chain parameters requires to run an interchaintest testnet for a chain.

type DockerImage

type DockerImage struct {
	Repository string `yaml:"repository"`
	Version    string `yaml:"version"`
	UidGid     string `yaml:"uid-gid"`
}

func (DockerImage) Ref

func (i DockerImage) Ref() string

Ref returns the reference to use when e.g. creating a container.

type NopRelayerExecReporter

type NopRelayerExecReporter struct{}

NopRelayerExecReporter is a no-op RelayerExecReporter.

func (NopRelayerExecReporter) TrackRelayerExec

func (NopRelayerExecReporter) TrackRelayerExec(string, []string, string, string, int, time.Time, time.Time, error)

type Order

type Order int

const (
	Invalid Order = iota
	Ordered
	Unordered
)

type Relayer

type Relayer interface {
	// restore a mnemonic to be used as a relayer wallet for a chain
	RestoreKey(ctx context.Context, rep RelayerExecReporter, cfg ChainConfig, keyName, mnemonic string) 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)

	// After configuration is initialized, begin relaying.
	// This method is intended to create a background worker that runs the relayer.
	// You must call StopRelayer to cleanly stop the relaying.
	StartRelayer(ctx context.Context, rep RelayerExecReporter) error

	// StopRelayer stops a relayer that started work through StartRelayer.
	StopRelayer(ctx context.Context, rep RelayerExecReporter) error

	// Exec runs an arbitrary relayer command.
	// If the Relayer implementation runs in Docker,
	// whether the invoked command is run in a one-off container or execing into an already running container
	// is an implementation detail.
	//
	// "env" are environment variables in the format "MY_ENV_VAR=value"
	Exec(ctx context.Context, rep RelayerExecReporter, cmd []string, env []string) RelayerExecResult

	ExecBin(ctx context.Context, rep RelayerExecReporter, command string, params ...interface{}) RelayerExecResult

	HomeDir() string
	RestartRelayerContainer(context.Context) error
	StopRelayerContainer(context.Context, RelayerExecReporter) error
	WriteBlockHeight(context.Context, string, uint64) error
	GetKeystore(chain string, wallet Wallet) ([]byte, error)

	RestoreKeystore(ctx context.Context, keyJSON []byte, chainID string, name string) error

	CreateConfig(ctx context.Context, configYAML []byte) error
}

type RelayerConfig

type RelayerConfig struct {
	Global struct {
		ApiListenAddr  int    `yaml:"api-listen-addr"`
		Timeout        string `yaml:"timeout"`
		Memo           string `yaml:"memo"`
		LightCacheSize int    `yaml:"light-cache-size"`
	} `yaml:"global"`
	Chains map[string]interface{} `yaml:"chains"`
}

type RelayerExecReporter

type RelayerExecReporter interface {
	TrackRelayerExec(

		containerName string,

		command []string,

		stdout, stderr string,

		exitCode int,

		startedAt, finishedAt time.Time,

		err error,
	)
}

ExecReporter is the interface of a narrow type returned by testreporter.RelayerExecReporter. This avoids a direct dependency on the testreporter package, and it avoids the relayer needing to be aware of a *testing.T.

type RelayerExecResult

type RelayerExecResult struct {

	// Err is only set when there is a failure to execute.
	// A successful execution that exits non-zero will have a nil Err
	// and an appropriate ExitCode.
	Err error

	ExitCode       int
	Stdout, Stderr []byte
}

RelyaerExecResult holds the details of a call to Relayer.Exec.

type RelayerMap

type RelayerMap map[string]map[Wallet]bool

RelayerMap is a mapping from test names to a relayer set for that test.

func (RelayerMap) AddRelayer

func (r RelayerMap) AddRelayer(testName string, relayer Relayer, chainID string)

AddRelayer adds the given relayer to the relayer set for the given test name.

func (RelayerMap) ContainsRelayer

func (r RelayerMap) ContainsRelayer(testName string, wallet Wallet) bool

containsRelayer returns true if the given relayer is in the relayer set for the given test name.

type Wallet

type Wallet interface {
	KeyName() string
	FormattedAddress() string
	Mnemonic() string
	Address() []byte
}

type WalletAmount

type WalletAmount struct {
	Address string
	Denom   string
	Amount  int64
}