certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
cosmos-sdk/x/ibc/core/spec/04_messages.md

14 KiB
Raw Blame History

Messages

In this section we describe the processing of the IBC messages and the corresponding updates to the state.

ICS 02 - Client

MsgCreateClient

A light client is created using the MsgCreateClient.

type MsgCreateClient struct {
  ClientId        string
  ClientState     *types.Any // proto-packed client state
  ConsensusState  *types.Any // proto-packed consensus state
  Signer          sdk.AccAddress
}

This message is expected to fail if:

  • ClientId is invalid (see naming requirements)
  • ClientState is empty or invalid
  • ConsensusState is empty or invalid
  • Signer is empty
  • A light client with the provided id and type already exist

The message creates and stores a light client with the given ID and consensus type, stores the validator set as the Commiter of the given consensus state and stores both the consensus state and its commitment root (i.e app hash).

MsgUpdateClient

A light client is updated with a new header using the MsgUpdateClient.

type MsgUpdateClient struct {
  ClientId string
  Header   *types.Any // proto-packed header
  Signer   sdk.AccAddress
}

This message is expected to fail if:

  • ClientId is invalid (not alphanumeric or not within 10-20 characters)
  • Header is empty or invalid
  • Signer is empty
  • A ClientState hasn't been created for the given ID
  • the header's client type is different from the registered one
  • the client is frozen due to misbehaviour and cannot be updated

The message validates the header and updates the consensus state with the new height, commitment root and validator sets, which are then stored.

MsgSubmitMisbehaviour

Submit a evidence of light client misbehaviour to freeze the client state and prevent additional packets from being relayed.

type MsgSubmitMisbehaviour struct {
  ClientId     string
  Misbehaviour *types.Any // proto-packed misbehaviour
  Signer       sdk.AccAddress
}

This message is expected to fail if:

  • ClientId is invalid (not alphanumeric or not within 10-20 characters)
  • Misbehaviour is empty or invalid
  • Signer is empty
  • A ClientState hasn't been created for the given ID
  • Misbehaviour check failed

The message validates the header and updates the consensus state with the new height, commitment root and validator sets, which are then stored.

ICS 03 - Connection

MsgConnectionOpenInit

A connection is initialized on a light client using the MsgConnectionOpenInit.

type MsgConnectionOpenInit struct {
	ClientId     string                                       
	ConnectionId string                                        
	Counterparty Counterparty                                  
	Version      string
	Signer       sdk.AccAddress
}

This message is expected to fail if:

  • ClientId is invalid (see naming requirements)
  • ConnectionId is invalid (see naming requirements)
  • Counterparty is empty
  • 'Version' is not empty and invalid
  • Signer is empty
  • A Client hasn't been created for the given ID
  • A Connection for the given ID already exists

The message creates a connection for the given ID with an INIT state.

MsgConnectionOpenTry

When a counterparty connection is initialized then a connection is initialized on a light client using the MsgConnectionOpenTry.

type MsgConnectionOpenTry struct {
	ClientId                       string
	DesiredConnectionId            string
	CounterpartyChosenConnectionId string
	ClientState                    *types.Any // proto-packed counterparty client
	Counterparty                   Counterparty
	CounterpartyVersions           []string
	ProofHeight                    Height
	ProofInit                      []byte
	ProofClient                    []byte
	ProofConsensus                 []byte
	ConsensusHeight                Height
	Signer                         sdk.AccAddress
}

This message is expected to fail if:

  • ClientId is invalid (see naming requirements)
  • DesiredConnectionId is invalid (see naming requirements)
  • CounterpartyChosenConnectionId is not empty and doesn't match DesiredConnectionId
  • ClientState is not a valid client of the executing chain
  • Counterparty is empty
  • CounterpartyVersions is empty
  • ProofHeight is zero
  • ProofInit is empty
  • ProofClient is empty
  • ProofConsensus is empty
  • ConsensusHeight is zero
  • Signer is empty
  • A Client hasn't been created for the given ID
  • A Connection for the given ID already exists
  • ProofInit does not prove that the counterparty connection is in state INIT
  • ProofClient does not prove that the counterparty has stored the ClientState provided in message
  • ProofConsensus does not prove that the counterparty has the correct consensus state for this chain

The message creates a connection for the given ID with an TRYOPEN State. The CounterpartyChosenConnectionID represents the connection ID the counterparty set under connection.Counterparty.ConnectionId to represent the connection ID this chain should use. An empty string indicates the connection identifier is flexible and gives this chain an opportunity to choose its own identifier.

MsgConnectionOpenAck

When a counterparty connection is initialized then a connection is opened on a light client using the MsgConnectionOpenAck.

type MsgConnectionOpenAck struct {
	ConnectionId             string
	CounterpartyConnectionId string 
	Version                  string
	ClientState              *types.Any // proto-packed counterparty client
	ProofHeight              Height
	ProofTry                 []byte
	ProofClient              []byte
	ProofConsensus           []byte
	ConsensusHeight          Height
	Signer                   sdk.AccAddress
}

This message is expected to fail if:

  • ConnectionId is invalid (see naming requirements)
  • CounterpartyConnectionId is invalid (see naming requirements)
  • Version is empty
  • ClientState is not a valid client of the executing chain
  • ProofHeight is zero
  • ProofTry is empty
  • ProofClient is empty
  • ProofConsensus is empty
  • ConsensusHeight is zero
  • Signer is empty
  • ProofTry does not prove that the counterparty connection is in state TRYOPEN
  • ProofClient does not prove that the counterparty has stored the ClientState provided by message
  • ProofConsensus does not prove that the counterparty has the correct consensus state for this chain

The message sets the connection state for the given ID to OPEN. CounterpartyConnectionId should be the ConnectionId used by the counterparty connection.

MsgConnectionOpenConfirm

When a counterparty connection is opened then a connection is opened on a light client using the MsgConnectionOpenConfirm.

type MsgConnectionOpenConfirm struct {
  ConnectionId string
	ProofAck     []byte
	ProofHeight  Height
	Signer       sdk.AccAddress
}

This message is expected to fail if:

  • ConnectionId is invalid (see naming requirements)
  • ProofAck is empty
  • ProofHeight is zero
  • Signer is empty
  • A Connection with the given ID does not exist
  • ProofAck does not prove that the counterparty connection is in state OPEN

The message sets the connection state for the given ID to OPEN.

ICS 04 - Channels

MsgChannelOpenInit

A channel handshake is initiated by a chain A using the MsgChannelOpenInit message.

type MsgChannelOpenInit struct {
  PortId    string
  ChannelId string
  Channel   Channel
  Signer    sdk.AccAddress
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • ChannelId is invalid (see naming requirements)
  • Channel is empty
  • Signer is empty
  • A Channel End exists for the given Channel ID and Port ID

The message creates a channel on chain A with an INIT state for the given Channel ID and Port ID.

MsgChannelOpenTry

A channel handshake initialization attempt is acknowledged by a chain B using the MsgChannelOpenTry message.

type MsgChannelOpenTry struct {
	PortId                      string    
	DesiredChannelId            string   
	CounterpartyChosenChannelId string 
	Channel                     Channel 
	CounterpartyVersion         string 
	ProofInit                   []byte
	ProofHeight                 Height
	Signer                      sdk.AccAddress 
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • DesiredChannelId is invalid (see naming requirements)
  • CounterpartyChosenChannelId is not empty and not equal to ChannelId
  • Channel is empty
  • CounterpartyVersion is empty
  • ProofInit is empty
  • ProofHeight is zero
  • Signer is empty
  • A Channel End exists for the given Channel and Port ID
  • ProofInit does not prove that the counterparty's Channel state is in INIT

The message creates a channel on chain B with an TRYOPEN state for the given Channel ID and Port ID. The CounterpartyChosenChannelId represents the channel ID the counterparty set under connection.Counterparty.ChannelId to represent the channel ID this chain should use. An empty string indicates the channel identifier is flexible and gives this chain an opportunity to choose its own identifier.

MsgChannelOpenAck

A channel handshake is opened by a chain A using the MsgChannelOpenAck message.

type MsgChannelOpenAck struct {
	PortId                string
	ChannelId             string
	CounterpartyChannelId string 
	CounterpartyVersion   string
	ProofTry              []byte
	ProofHeight           Height
	Signer                sdk.AccAddress
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • ChannelId is invalid (see naming requirements)
  • CounterpartyChannelId is invalid (see naming requirements)
  • CounterpartyVersion is empty
  • ProofTry is empty
  • ProofHeight is zero
  • Signer is empty
  • ProofTry does not prove that the counterparty's Channel state is in TRYOPEN

The message sets a channel on chain A to state OPEN for the given Channel ID and Port ID. CounterpartyChannelId should be the ChannelId used by the counterparty channel.

MsgChannelOpenConfirm

A channel handshake is confirmed and opened by a chain B using the MsgChannelOpenConfirm message.

type MsgChannelOpenConfirm struct {
	PortId              string
	ChannelId           string
	ProofAck            []byte
	ProofHeight         Height
	Signer              sdk.AccAddress
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • ChannelId is invalid (see naming requirements)
  • ProofAck is empty
  • ProofHeight is zero
  • Signer is empty
  • ProofAck does not prove that the counterparty's Channel state is in OPEN

The message sets a channel on chain B to state OPEN for the given Channel ID and Port ID.

MsgChannelCloseInit

A channel is closed on chain A using the MsgChannelCloseInit.

type MsgChannelCloseInit struct {
		PortId    string
		ChannelId string  
		Signer    sdk.AccAddress
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • ChannelId is invalid (see naming requirements)
  • Signer is empty
  • A Channel for the given Port ID and Channel ID does not exist or is already closed

The message closes a channel on chain A for the given Port ID and Channel ID.

MsgChannelCloseConfirm

A channel is closed on chain B using the MsgChannelCloseConfirm.

type MsgChannelCloseConfirm struct {
	PortId      string
	ChannelId   string
	ProofInit   []byte  
	ProofHeight Height
	Signer      sdk.AccAddress
}

This message is expected to fail if:

  • PortId is invalid (see naming requirements)
  • ChannelId is invalid (see naming requirements)
  • ProofInit is empty
  • ProofHeight is zero
  • Signer is empty
  • A Channel for the given Port ID and Channel ID does not exist or is already closed
  • ProofInit does not prove that the counterparty set its channel to state CLOSED

The message closes a channel on chain B for the given Port ID and Channel ID.

MsgRecvPacket

A packet is received on chain B using the MsgRecvPacket.

type MsgRecvPacket struct {
    Packet      Packet
    Proof       []byte
    ProofHeight Height
    Signer      sdk.AccAddress
}

This message is expected to fail if:

  • Proof is empty
  • ProofHeight is zero
  • Signer is empty
  • Packet fails basic validation
  • Proof does not prove that the counterparty sent the Packet.

The message receives a packet on chain B.

MsgTimeout

A packet is timed out on chain A using the MsgTimeout.

type MsgTimeout struct {
    Packet           Packet
    Proof            []byte
    ProofHeight      Height
    NextSequenceRecv uint64
    Signer           sdk.AccAddress
}

This message is expected to fail if:

  • Proof is empty
  • ProofHeight is zero
  • NextSequenceRecv is zero
  • Signer is empty
  • Packet fails basic validation
  • Proof does not prove that the packet has not been received on the counterparty chain.

The message times out a packet on chain B.

MsgTimeoutOnClose

A packet is timed out on chain A due to the closure of the channel end on chain B using the MsgTimeoutOnClose.

type MsgTimeoutOnClose struct {
    Packet           Packet
    Proof            []byte
    ProofClose       []byte
    ProofHeight      Height
    NextSequenceRecv uint64
    Signer           sdk.AccAddress
}

This message is expected to fail if:

  • Proof is empty
  • ProofClose is empty
  • ProofHeight is zero
  • NextSequenceRecv is zero
  • Signer is empty
  • Packet fails basic validation
  • Proof does not prove that the packet has not been received on the counterparty chain.
  • ProofClose does not prove that the counterparty channel end has been closed.

The message times out a packet on chain B.

MsgAcknowledgement

A packet is acknowledged on chain A using the MsgAcknowledgement.

type MsgAcknowledgement struct {
    Packet          Packet
    Acknowledgement []byte
    Proof           []byte
    ProofHeight     Height
    Signer          sdk.AccAddress
}

This message is expected to fail if:

  • Proof is empty
  • ProofHeight is zero
  • Signer is empty
  • Packet fails basic validation
  • Acknowledgement is empty
  • Proof does not prove that the counterparty received the Packet.

The message receives a packet on chain A.