Documentation ¶
Overview ¶
Package ibc provides chain and relayer agnostic types and interfaces for the IBC spec. It attempts to expose the domain model of IBC.
The official spec documentation can be found at https://github.com/cosmos/ibc/tree/master/spec.
Currently, the interfaces may be biased towards chains built with the cosmos sdk and the cosmos/relayer.
Index ¶
- Constants
- type Chain
- type ChainConfig
- func (c ChainConfig) Clone() ChainConfig
- func (c ChainConfig) IsFullyConfigured() bool
- func (c ChainConfig) MergeChainSpecConfig(other ChainConfig) ChainConfig
- func (c ChainConfig) UsesCometMock() bool
- func (c ChainConfig) VerifyCoinType() (string, error)
- func (c *ChainConfig) WithCodeCoverage(override ...string)
- type ChannelCounterparty
- type ChannelFilter
- type ChannelOutput
- type ClientOutput
- type ClientOutputs
- type ClientState
- type CometMockConfig
- type ConnectionOutput
- type ConnectionOutputs
- type CreateChannelOptions
- type CreateClientOptions
- type DockerImage
- type GenesisConfig
- type IBCTimeout
- type ICSConfig
- type Nanoseconds
- type NopRelayerExecReporter
- type Order
- type Packet
- type PacketAcknowledgement
- type PacketTimeout
- type PathUpdateOptions
- type Relayer
- type RelayerExecReporter
- type RelayerExecResult
- type RelayerImplementation
- type SidecarConfig
- type TransferOptions
- type Tx
- type Wallet
- type WalletAmount
Constants ¶
const ( Polkadot = "polkadot" Parachain = "parachain" RelayChain = "relaychain" Cosmos = "cosmos" Penumbra = "penumbra" Ethereum = "ethereum" Thorchain = "thorchain" UTXO = "utxo" )
Chain type constant values, used to determine if a ChainConfig is of a certain type.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 // GetHostPeerAddress returns the p2p address that can be reached by processes on the host machine. // Note that this will not return a valid value until after Start returns. GetHostPeerAddress() 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 // SendFundsWithNote sends funds to a wallet from a user account with a note/memo SendFundsWithNote(ctx context.Context, keyName string, amount WalletAmount, note string) (string, error) // SendIBCTransfer sends an IBC transfer returning a transaction or an error if the transfer failed. SendIBCTransfer(ctx context.Context, channelID, keyName string, amount WalletAmount, options TransferOptions) (Tx, error) // Height returns the current block height or an error if unable to get current height. Height(ctx context.Context) (int64, error) // GetBalance fetches the current balance for a specific account address and denom. GetBalance(ctx context.Context, address string, denom string) (math.Int, error) // GetGasFeesInNativeDenom gets the fees in native denom for an amount of spent gas. GetGasFeesInNativeDenom(gasPaid int64) int64 // Acknowledgements returns all acknowledgements in a block at height. Acknowledgements(ctx context.Context, height int64) ([]PacketAcknowledgement, error) // Timeouts returns all timeouts in a block at height. Timeouts(ctx context.Context, height int64) ([]PacketTimeout, error) // 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"` // https://github.com/informalsystems/CometMock usage. CometMock CometMockConfig `yaml:"comet-mock-image"` // 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"` // 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. GasAdjustment float64 `yaml:"gas-adjustment"` // Default gas limit for transactions. May be empty, "auto", or a number. Gas string `yaml:"gas" default:"auto"` // 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(Chain) error // When provided, genesis file contents will be altered before sharing for genesis. ModifyGenesis func(ChainConfig, []byte) ([]byte, error) // Modify genesis-amounts for the validator at the given index ModifyGenesisAmounts func(int) (sdk.Coin, sdk.Coin) // Override config parameters for files at filepath. ConfigFileOverrides map[string]any // Non-nil will override the encoding config, used for cosmos chains only. EncodingConfig *testutil.TestEncodingConfig // Required when the chain requires the chain-id field to be populated for certain commands UsingChainIDFlagCLI bool `yaml:"using-chain-id-flag-cli"` // Configuration describing additional sidecar processes. SidecarConfigs []SidecarConfig // Configuration describing additional interchain security options. InterchainSecurityConfig ICSConfig // CoinDecimals for the chains base micro/nano/atto token configuration. CoinDecimals *int64 // HostPortOverride exposes ports to the host. // To avoid port binding conflicts, ports are only exposed on the 0th validator. HostPortOverride map[int]int `yaml:"host-port-override"` // ExposeAdditionalPorts exposes each port id to the host on a random port. ex: "8080/tcp" // Access the address with ChainNode.GetHostAddress ExposeAdditionalPorts []string // Additional start command arguments AdditionalStartArgs []string // Environment variables for chain nodes Env []string // Genesis file contents for the chain // Used if starting from an already populated genesis.json, e.g for hard fork upgrades. // When nil, the chain will generate the number of validators specified in the ChainSpec. Genesis *GenesisConfig }
ChainConfig defines the chain parameters requires to run an interchaintest testnet for a chain.
func (ChainConfig) Clone ¶
func (c ChainConfig) Clone() ChainConfig
func (ChainConfig) IsFullyConfigured ¶
func (c ChainConfig) IsFullyConfigured() bool
IsFullyConfigured reports whether all required fields have been set on c. It is possible for some fields, such as GasAdjustment and NoHostMount, to be their respective zero values and for IsFullyConfigured to still report true.
func (ChainConfig) MergeChainSpecConfig ¶
func (c ChainConfig) MergeChainSpecConfig(other ChainConfig) ChainConfig
func (ChainConfig) UsesCometMock ¶ added in v8.3.0
func (c ChainConfig) UsesCometMock() bool
func (ChainConfig) VerifyCoinType ¶
func (c ChainConfig) VerifyCoinType() (string, error)
func (*ChainConfig) WithCodeCoverage ¶ added in v8.5.0
func (c *ChainConfig) WithCodeCoverage(override ...string)
WithCodeCoverage enables Go Code Coverage from the chain node directory.
type ChannelCounterparty ¶
type ChannelFilter ¶
ChannelFilter provides the means for either creating an allowlist or a denylist of channels on the src chain which will be used to narrow down the list of channels a user wants to relay on.
type ChannelOutput ¶
type ChannelOutput struct { State string `json:"state"` Ordering string `json:"ordering"` Counterparty ChannelCounterparty `json:"counterparty"` ConnectionHops []string `json:"connection_hops"` Version string `json:"version"` PortID string `json:"port_id"` ChannelID string `json:"channel_id"` }
func GetTransferChannel ¶
func GetTransferChannel(ctx context.Context, r Relayer, rep RelayerExecReporter, srcChainID, dstChainID string) (*ChannelOutput, error)
GetTransferChannel will return the transfer channel assuming only one client, one connection, and one channel with "transfer" port exists between two chains.
type ClientOutput ¶
type ClientOutput struct { ClientID string `json:"client_id"` ClientState ClientState `json:"client_state"` }
type ClientOutputs ¶
type ClientOutputs []*ClientOutput
type ClientState ¶
type ClientState struct {
ChainID string `json:"chain_id"`
}
type CometMockConfig ¶ added in v8.3.0
type CometMockConfig struct { Image DockerImage `yaml:"image"` BlockTimeMs int `yaml:"block-time"` }
type ConnectionOutput ¶
type ConnectionOutput struct { ID string `json:"id,omitempty" yaml:"id"` ClientID string `json:"client_id,omitempty" yaml:"client_id"` Versions []*ibcexported.Version `json:"versions,omitempty" yaml:"versions"` State string `json:"state,omitempty" yaml:"state"` Counterparty *ibcexported.Counterparty `json:"counterparty" yaml:"counterparty"` DelayPeriod string `json:"delay_period,omitempty" yaml:"delay_period"` }
ConnectionOutput represents the IBC connection information queried from a chain's state for a particular connection.
type ConnectionOutputs ¶
type ConnectionOutputs []*ConnectionOutput
type CreateChannelOptions ¶
type CreateChannelOptions struct { SourcePortName string DestPortName string Order Order Version string Override bool // only implemented on Go Relayer }
CreateChannelOptions contains the configuration for creating a channel.
func DefaultChannelOpts ¶
func DefaultChannelOpts() CreateChannelOptions
DefaultChannelOpts returns the default settings for creating an ics20 fungible token transfer channel.
func (CreateChannelOptions) Validate ¶
func (opts CreateChannelOptions) Validate() error
Validate will check that the specified CreateChannelOptions are valid.
type CreateClientOptions ¶
type CreateClientOptions struct { TrustingPeriod string TrustingPeriodPercentage int64 // only available for Go Relayer MaxClockDrift string Override bool // only available for Go Relayer }
a zero value is the same as not specifying the flag and will use the relayer defaults.
func DefaultClientOpts ¶
func DefaultClientOpts() CreateClientOptions
empty values will use the relayer defaults.
func (CreateClientOptions) Validate ¶
func (opts CreateClientOptions) Validate() error
type DockerImage ¶
type DockerImage struct { Repository string `json:"repository" yaml:"repository"` Version string `json:"version" yaml:"version"` UIDGID string `json:"uid-gid" yaml:"uid-gid"` }
func NewDockerImage ¶
func NewDockerImage(repository, version, uidGID string) DockerImage
func (DockerImage) IsFullyConfigured ¶
func (i DockerImage) IsFullyConfigured() bool
IsFullyConfigured reports whether all of i's required fields are present. Version is not required, as it can be superseded by a ChainSpec version.
func (DockerImage) Ref ¶
func (i DockerImage) Ref() string
Ref returns the reference to use when e.g. creating a container.
func (DockerImage) Validate ¶
func (i DockerImage) Validate() error
Validate returns an error describing which of i's required fields are missing and returns nil if all required fields are present. Version is not required, as it can be superseded by a ChainSpec version.
type GenesisConfig ¶ added in v8.7.0
type GenesisConfig struct { // Genesis file contents for the chain (e.g. genesis.json for CometBFT chains). Contents []byte // If true, all validators will be emulated in the genesis file. // By default, only the first 2/3 (sorted by Voting Power desc) of validators will be emulated. AllValidators bool // MaxVals is a safeguard so that we don't accidentally emulate too many validators. Defaults to 10. // If more than MaxVals validators are required to meet 2/3 VP, the test will fail. MaxVals int }
GenesisConfig is used to start a chain from a pre-defined genesis state.
type IBCTimeout ¶
type Nanoseconds ¶
type Nanoseconds uint64
type NopRelayerExecReporter ¶
type NopRelayerExecReporter struct{}
NopRelayerExecReporter is a no-op RelayerExecReporter.
type Order ¶
type Order int
Order represents an IBC channel's ordering.
type Packet ¶
type Packet struct { Sequence uint64 // the order of sends and receives, where a packet with an earlier sequence number must be sent and received before a packet with a later sequence number SourcePort string // the port on the sending chain SourceChannel string // the channel end on the sending chain DestPort string // the port on the receiving chain DestChannel string // the channel end on the receiving chain Data []byte // an opaque value which can be defined by the application logic of the associated modules TimeoutHeight string // a consensus height on the destination chain after which the packet will no longer be processed, and will instead count as having timed-out // Indicates a timestamp (in nanoseconds) on the destination chain after which the packet will no longer be processed, and will instead count as having timed-out. // The IBC spec does not indicate the unit of time. However, ibc-go's protos define it as nanoseconds. TimeoutTimestamp Nanoseconds }
Packet is a packet sent over an IBC channel as defined in ICS-4. See: https://github.com/cosmos/ibc/blob/52a9094a5bc8c5275e25c19d0b2d9e6fd80ba31c/spec/core/ics-004-channel-and-packet-semantics/README.md Proto defined at: github.com/cosmos/ibc-go/v3@v3.0.0/proto/ibc/core/channel/v1/tx.proto.
type PacketAcknowledgement ¶
type PacketAcknowledgement struct { Packet Packet Acknowledgement []byte // an opaque value defined by the application logic }
PacketAcknowledgement signals the packet was processed and accepted by the counterparty chain. See: https://github.com/cosmos/ibc/blob/52a9094a5bc8c5275e25c19d0b2d9e6fd80ba31c/spec/core/ics-004-channel-and-packet-semantics/README.md#writing-acknowledgements
func (PacketAcknowledgement) Validate ¶
func (ack PacketAcknowledgement) Validate() error
Validate returns an error if the acknowledgement is not well-formed.
type PacketTimeout ¶
type PacketTimeout struct {
Packet Packet
}
PacketTimeout signals a packet was not processed by the counterparty chain. Indicates the sending chain should undo or rollback state. Timeout conditions are block height and timestamp. See: https://github.com/cosmos/ibc/blob/52a9094a5bc8c5275e25c19d0b2d9e6fd80ba31c/spec/core/ics-004-channel-and-packet-semantics/README.md#timeouts
func (PacketTimeout) Validate ¶
func (timeout PacketTimeout) Validate() error
Validate returns an error if the timeout is not well-formed.
type PathUpdateOptions ¶ added in v8.3.0
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 // generate a new key 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) // add relayer configuration for a chain AddChainConfiguration(ctx context.Context, rep RelayerExecReporter, chainConfig ChainConfig, keyName, rpcAddr, grpcAddr string) error // generate new path between two chains GeneratePath(ctx context.Context, rep RelayerExecReporter, srcChainID, dstChainID, pathName string) error // setup channels, connections, and clients LinkPath(ctx context.Context, rep RelayerExecReporter, pathName string, channelOpts CreateChannelOptions, clientOptions CreateClientOptions) error // update path channel filter or src/dst clients, conns, or chain IDs UpdatePath(ctx context.Context, rep RelayerExecReporter, pathName string, opts PathUpdateOptions) error // update clients, such as after new genesis UpdateClients(ctx context.Context, rep RelayerExecReporter, pathName string) error // get channel IDs for chain GetChannels(ctx context.Context, rep RelayerExecReporter, chainID string) ([]ChannelOutput, error) // GetConnections returns a slice of IBC connection details composed of the details for each connection on a specified chain. GetConnections(ctx context.Context, rep RelayerExecReporter, chainID string) (ConnectionOutputs, error) // GetClients returns a slice of IBC client details composed of the details for each client on a specified chain. GetClients(ctx context.Context, rep RelayerExecReporter, chainID string) (ClientOutputs, error) // 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, pathNames ...string) error // StopRelayer stops a relayer that started work through StartRelayer. StopRelayer(ctx context.Context, rep RelayerExecReporter) error // PauseRelayer halts a relayer that started work through StartRelayer. PauseRelayer(ctx context.Context) error // ResumeRelayer resumes a relayer that was paused through PauseRelayer. ResumeRelayer(ctx context.Context) error // Flush flushes any outstanding packets and then returns. Flush(ctx context.Context, rep RelayerExecReporter, pathName string, channelID string) error // CreateClients performs the client handshake steps necessary for creating a light client // on src that tracks the state of dst, and a light client on dst that tracks the state of src. CreateClients(ctx context.Context, rep RelayerExecReporter, pathName string, opts CreateClientOptions) error // CreateClient performs the client handshake steps necessary for creating a light client // on src that tracks the state of dst. // Unlike CreateClients, this only creates the client on the destination chain CreateClient(ctx context.Context, rep RelayerExecReporter, srcChainID string, dstChainID string, pathName string, opts CreateClientOptions) error // CreateConnections performs the connection handshake steps necessary for creating a connection // between the src and dst chains. CreateConnections(ctx context.Context, rep RelayerExecReporter, pathName string) error // CreateChannel creates a channel on the given path with the provided options. CreateChannel(ctx context.Context, rep RelayerExecReporter, pathName string, opts CreateChannelOptions) error // UseDockerNetwork reports whether the relayer is run in the same docker network as the other chains. // // If false, the relayer will connect to the localhost-exposed ports instead of the docker hosts. // // Relayer implementations provided by the interchaintest module will report true, // but custom implementations may report false. UseDockerNetwork() bool // 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 // Set the wasm client contract hash in the chain's config if the counterparty chain in a path used 08-wasm // to instantiate the client. SetClientContractHash(ctx context.Context, rep RelayerExecReporter, cfg ChainConfig, hash string) error }
Relayer represents an instance of a relayer that can be support IBC. Built-in implementations are run through Docker, but they could exec out to external processes or even be implemented in-process in Go.
All of the methods on Relayer accept a RelayerExecReporter. It is intended that Relayer implementations will call the reporters' TrackRelayerExec method so that details of the relayer execution are included in the test report.
If a relayer does not properly call into the reporter, the tests will still execute properly, but the report will be missing details.
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 RelayerImplementation ¶
type RelayerImplementation int64
const ( CosmosRly RelayerImplementation = iota Hermes Hyperspace )
type SidecarConfig ¶
type SidecarConfig struct { ProcessName string Image DockerImage HomeDir string Ports []string StartCmd []string Env []string PreStart bool ValidatorProcess bool }
SidecarConfig describes the configuration options for instantiating a new sidecar process.
type TransferOptions ¶
type TransferOptions struct { Timeout *IBCTimeout Memo string AbsoluteTimeouts bool Port string // default: transfer }
TransferOptions defines the options for an IBC packet transfer.
type Tx ¶
type Tx struct { // The block height. Height int64 // The transaction hash. TxHash string // Amount of gas charged to the account. GasSpent int64 Packet Packet }
Tx is a generalized IBC transaction.