diff --git a/docs/spec/ibc/README.md b/docs/spec/ibc/README.md deleted file mode 100644 index e763c2760caa..000000000000 --- a/docs/spec/ibc/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Cosmos Inter-Blockchain Communication (IBC) Protocol - -__Disclaimer__ This module has been removed from the repository for the time being. If you would like to follow the process of IBC, go to [ICS repo](https://github.com/cosmos/ics), there you will find the standard and updates. \ No newline at end of file diff --git a/x/ibc/03-connection/handler.go b/x/ibc/03-connection/handler.go index 0350fa699f2d..1cc1603ccc6c 100644 --- a/x/ibc/03-connection/handler.go +++ b/x/ibc/03-connection/handler.go @@ -14,9 +14,10 @@ func HandleMsgConnectionOpenInit(ctx sdk.Context, k Keeper, msg MsgConnectionOpe ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( - EventTypeConnectionOpenInit, - sdk.NewAttribute(AttributeKeyConnectionID, msg.ConnectionID), - sdk.NewAttribute(AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), + types.EventTypeConnectionOpenInit, + sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), + sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), + sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ), sdk.NewEvent( sdk.EventTypeMessage, @@ -42,9 +43,10 @@ func HandleMsgConnectionOpenTry(ctx sdk.Context, k Keeper, msg MsgConnectionOpen ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( - EventTypeConnectionOpenTry, - sdk.NewAttribute(AttributeKeyConnectionID, msg.ConnectionID), - sdk.NewAttribute(AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), + types.EventTypeConnectionOpenTry, + sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), + sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), + sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ), sdk.NewEvent( sdk.EventTypeMessage, diff --git a/x/ibc/03-connection/types/events.go b/x/ibc/03-connection/types/events.go index 2ede46db907c..92a73afbebd3 100644 --- a/x/ibc/03-connection/types/events.go +++ b/x/ibc/03-connection/types/events.go @@ -9,6 +9,7 @@ import ( // IBC connection events const ( AttributeKeyConnectionID = "connection_id" + AttributeKeyClientID = "client_id" AttributeKeyCounterpartyClientID = "counterparty_client_id" ) diff --git a/x/ibc/04-channel/handler.go b/x/ibc/04-channel/handler.go index fb35ef8e5fbe..6b602e08ec87 100644 --- a/x/ibc/04-channel/handler.go +++ b/x/ibc/04-channel/handler.go @@ -19,8 +19,11 @@ func HandleMsgChannelOpenInit(ctx sdk.Context, k keeper.Keeper, msg types.MsgCha ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelOpenInit, - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), + sdk.NewAttribute(types.AttributeCounterpartyPortID, msg.Channel.Counterparty.PortID), + sdk.NewAttribute(types.AttributeCounterpartyChannelID, msg.Channel.Counterparty.ChannelID), + sdk.NewAttribute(types.AttributeKeyConnectionID, msg.Channel.ConnectionHops[0]), // TODO: iterate ), sdk.NewEvent( sdk.EventTypeMessage, @@ -46,9 +49,11 @@ func HandleMsgChannelOpenTry(ctx sdk.Context, k keeper.Keeper, msg types.MsgChan ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelOpenTry, + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), // TODO: double check sender and receiver - sdk.NewAttribute(types.AttributeKeyReceiverPort, msg.Channel.Counterparty.PortID), + sdk.NewAttribute(types.AttributeCounterpartyPortID, msg.Channel.Counterparty.PortID), + sdk.NewAttribute(types.AttributeCounterpartyChannelID, msg.Channel.Counterparty.ChannelID), + sdk.NewAttribute(types.AttributeKeyConnectionID, msg.Channel.ConnectionHops[0]), // TODO: iterate ), sdk.NewEvent( sdk.EventTypeMessage, @@ -74,7 +79,7 @@ func HandleMsgChannelOpenAck(ctx sdk.Context, k keeper.Keeper, msg types.MsgChan ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelOpenAck, - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), ), sdk.NewEvent( @@ -99,7 +104,7 @@ func HandleMsgChannelOpenConfirm(ctx sdk.Context, k keeper.Keeper, msg types.Msg ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelOpenConfirm, - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), ), sdk.NewEvent( @@ -124,7 +129,7 @@ func HandleMsgChannelCloseInit(ctx sdk.Context, k keeper.Keeper, msg types.MsgCh ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelCloseInit, - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), ), sdk.NewEvent( @@ -149,7 +154,7 @@ func HandleMsgChannelCloseConfirm(ctx sdk.Context, k keeper.Keeper, msg types.Ms ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeChannelCloseConfirm, - sdk.NewAttribute(types.AttributeKeySenderPort, msg.PortID), + sdk.NewAttribute(types.AttributeKeyPortID, msg.PortID), sdk.NewAttribute(types.AttributeKeyChannelID, msg.ChannelID), ), sdk.NewEvent( diff --git a/x/ibc/04-channel/types/events.go b/x/ibc/04-channel/types/events.go index b82b3e8700cf..212f8e254d9f 100644 --- a/x/ibc/04-channel/types/events.go +++ b/x/ibc/04-channel/types/events.go @@ -8,10 +8,11 @@ import ( // IBC channel events const ( - AttributeKeySenderPort = "sender_port" - AttributeKeyReceiverPort = "receiver_port" - AttributeKeyChannelID = "channel_id" - AttributeKeySequence = "sequence" + AttributeKeyConnectionID = "connection_id" + AttributeKeyPortID = "port_id" + AttributeKeyChannelID = "channel_id" + AttributeCounterpartyPortID = "counterparty_port_id" + AttributeCounterpartyChannelID = "counterparty_channel_id" ) // IBC channel events vars diff --git a/x/ibc/spec/01_concepts.md b/x/ibc/spec/01_concepts.md new file mode 100644 index 000000000000..907893de27e4 --- /dev/null +++ b/x/ibc/spec/01_concepts.md @@ -0,0 +1,8 @@ + + +# Concepts + +> NOTE: if you are not familiar with the IBC terminology and concepts, please read +this [document](https://github.com/cosmos/ics/blob/master/ibc/1_IBC_TERMINOLOGY.md) as prerequisite reading. diff --git a/x/ibc/spec/02_state.md b/x/ibc/spec/02_state.md new file mode 100644 index 000000000000..b53ece883720 --- /dev/null +++ b/x/ibc/spec/02_state.md @@ -0,0 +1,21 @@ + + +# State + +The paths for the values stored in state can be found [here](https://github.com/cosmos/ics/blob/master/spec/ics-024-host-requirements/README.md#path-space). Additionally, the SDK adds +a prefix to the path to be able to aggregate the values for querying purposes. + +| Prefix | Path | Value type | +|--------|------------------------------------------------------------------------|----------------| +| "0/" | "clients/{identifier}" | ClientState | +| "0/" | "clients/{identifier}/consensusState" | ConsensusState | +| "0/" | "clients/{identifier}/type" | ClientType | +| "0/" | "connections/{identifier}" | ConnectionEnd | +| "0/" | "ports/{identifier}" | CapabilityKey | +| "0/" | "ports/{identifier}/channels/{identifier}" | ChannelEnd | +| "0/" | "ports/{identifier}/channels/{identifier}/key" | CapabilityKey | +| "0/" | "ports/{identifier}/channels/{identifier}/nextSequenceRecv" | uint64 | +| "0/" | "ports/{identifier}/channels/{identifier}/packets/{sequence}" | bytes | +| "0/" | "ports/{identifier}/channels/{identifier}/acknowledgements/{sequence}" | bytes | \ No newline at end of file diff --git a/x/ibc/spec/04_messages.md b/x/ibc/spec/04_messages.md new file mode 100644 index 000000000000..39be055e29fe --- /dev/null +++ b/x/ibc/spec/04_messages.md @@ -0,0 +1,80 @@ + + +# 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`. + +```go +type MsgCreateClient struct { + ClientID string + ClientType string + ConsensusState ConsensusState + Signer AccAddress +} +``` + +This message is expected to fail if: + +- `ClientID` is invalid (not alphanumeric or not within 10-20 characters) +- `ClientType` is not registered +- `ConsensusState` is empty +- `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`. + +```go +type MsgUpdateClient struct { + ClientID string + Header Header + Signer AccAddress +} +``` + +This message is expected to fail if: + +- `ClientID` is invalid (not alphanumeric or not within 10-20 characters) +- `Header` is empty +- `Signer` is empty +- A Client 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. + +## ICS 03 - Connection + +## ICS 04 - Channels + +### MsgChannelOpenInit + +A channel handshake is initiated by a chain A using the `MsgChannelOpenInit` +message. + +```go +type MsgChannelOpenInit struct { + PortID string + ChannelID string + Channel Channel + Signer sdk.AccAddress +} +``` + +This message is expected to fail if: + +## ICS 20 - Fungible Token Transfer diff --git a/x/ibc/spec/05_callbacks.md b/x/ibc/spec/05_callbacks.md new file mode 100644 index 000000000000..cf77d8ec3688 --- /dev/null +++ b/x/ibc/spec/05_callbacks.md @@ -0,0 +1,5 @@ + + +# Callbacks diff --git a/x/ibc/spec/06_events.md b/x/ibc/spec/06_events.md new file mode 100644 index 000000000000..e333e8af07d4 --- /dev/null +++ b/x/ibc/spec/06_events.md @@ -0,0 +1,147 @@ + + +# Events + +The IBC module emits the following events: + +## ICS 02 - Client + +### MsgCreateClient + +| Type | Attribute Key | Attribute Value | +|---------------|---------------|-----------------| +| create_client | client_id | {clientID} | +| message | module | ibc_client | +| message | action | create_client | +| message | sender | {signer} | + +### MsgUpdateClient + +| Type | Attribute Key | Attribute Value | +|---------------|---------------|-----------------| +| update_client | client_id | {clientID} | +| message | module | ibc_client | +| message | action | update_client | +| message | sender | {signer} | + +### MsgSubmitMisbehaviour + +| Type | Attribute Key | Attribute Value | +|---------------------|---------------|---------------------| +| client_misbehaviour | client_id | {clientID} | +| message | module | evidence | +| message | action | client_misbehaviour | +| message | sender | {signer} | + +## ICS 03 - Connection + +### MsgConnectionOpenInit + +| Type | Attribute Key | Attribute Value | +|----------------------|------------------------|-------------------------| +| connection_open_init | connection_id | {connectionID} | +| connection_open_init | client_id | {clientID} | +| connection_open_init | counterparty_client_id | {counterparty.clientID} | +| message | module | ibc_connection | +| message | action | connection_open_init | +| message | sender | {signer} | + +### MsgConnectionOpenTry + +| Type | Attribute Key | Attribute Value | +|---------------------|---------------|---------------------| +| connection_open_try | connection_id | {connectionID} | +| connection_open_try | client_id | {clientID} | +| message | module | ibc_connection | +| message | action | connection_open_try | +| message | sender | {signer} | + +### MsgConnectionOpenAck + +| Type | Attribute Key | Attribute Value | +|----------------------|------------------------|-------------------------| +| connection_open_ack | connection_id | {connectionID} | +| connection_open_ack | client_id | {clientID} | +| connection_open_init | counterparty_client_id | {counterparty.clientID} | +| message | module | ibc_connection | +| message | action | connection_open_ack | +| message | sender | {signer} | + +### MsgConnectionOpenConfirm + +| Type | Attribute Key | Attribute Value | +|-------------------------|---------------|-------------------------| +| connection_open_confirm | connection_id | {connectionID} | +| message | module | ibc_connection | +| message | action | connection_open_confirm | +| message | sender | {signer} | + +## ICS 04 - Channel + +### MsgChannelOpenInit + +| Type | Attribute Key | Attribute Value | +|-------------------|-------------------------|----------------------------------| +| channel_open_init | port_id | {portID} | +| channel_open_init | channel_id | {channelID} | +| channel_open_init | counterparty_port_id | {channel.counterparty.portID} | +| channel_open_init | counterparty_channel_id | {channel.counterparty.channelID} | +| channel_open_init | connection_id | {channel.connectionHops} | +| message | module | ibc_channel | +| message | action | channel_open_init | +| message | sender | {signer} | + +### MsgChannelOpenTry + +| Type | Attribute Key | Attribute Value | +|------------------|-------------------------|----------------------------------| +| channel_open_try | port_id | {portID} | +| channel_open_try | channel_id | {channelID} | +| channel_open_try | counterparty_port_id | {channel.counterparty.portID} | +| channel_open_try | counterparty_channel_id | {channel.counterparty.channelID} | +| channel_open_try | connection_id | {channel.connectionHops} | +| message | module | ibc_channel | +| message | action | channel_open_try | +| message | sender | {signer} | + +### MsgChannelOpenAck + +| Type | Attribute Key | Attribute Value | +|------------------|---------------|------------------| +| channel_open_ack | port_id | {portID} | +| channel_open_ack | channel_id | {channelID} | +| message | module | ibc_channel | +| message | action | channel_open_ack | +| message | sender | {signer} | + +### MsgChannelOpenConfirm + +| Type | Attribute Key | Attribute Value | +|----------------------|---------------|----------------------| +| channel_open_confirm | port_id | {portID} | +| channel_open_confirm | channel_id | {channelID} | +| message | module | ibc_channel | +| message | action | channel_open_confirm | +| message | sender | {signer} | + +### MsgChannelCloseInit + +| Type | Attribute Key | Attribute Value | +|--------------------|---------------|--------------------| +| channel_close_init | port_id | {portID} | +| channel_close_init | channel_id | {channelID} | +| message | module | ibc_channel | +| message | action | channel_close_init | +| message | sender | {signer} | + +### MsgChannelCloseConfirm + +| Type | Attribute Key | Attribute Value | +|-----------------------|---------------|-----------------------| +| channel_close_confirm | port_id | {portID} | +| channel_close_confirm | channel_id | {channelID} | +| message | module | ibc_channel | +| message | action | channel_close_confirm | +| message | sender | {signer} | diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md new file mode 100644 index 000000000000..9023949b8294 --- /dev/null +++ b/x/ibc/spec/README.md @@ -0,0 +1,106 @@ + + +# `ibc` + +## Abstract + +This paper defines the implementation of the IBC protocol on the Cosmos SDK, the +changes made to the specification and where to find each specific ICS spec within +the module. + +For the general specification please refer to the [Interchain Standards](https://github.com/cosmos/ics). + +## Contents + +1. **[Concepts](01_concepts.md)** +2. **[State](02_state.md)** +3. **[State Transitions](02_state_transitions.md)** +4. **[Messages](03_messages.md)** +5. **[Callbacks](06_callbacks.md)** +6. **[Events](07_events.md)** + +## Implementation Details + +As stated above, the IBC implementation on the Cosmos SDK introduces some changes +to the general specification, in order to avoid code duplication and to take +advantage of the SDK architectural components such as the `AnteHandler` and +transaction routing through `Handlers`. + +### Interchain Standards reference + +The following list is a mapping from each Interchain Standard to their implementation +in the SDK's `x/ibc` module: + +- [ICS 002 - Client Semantics](https://github.com/cosmos/ics/tree/master/spec/ics-002-client-semantics): Implemented in [`x/ibc/02-client`](https://github.com/cosmos/x/ibc/02-client) +- [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/03-connection`](https://github.com/cosmos/x/ibc/03-connection) +- [ICS 004 - Channel and Packet Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-004-channel-and-packet-semantics): Implemented in [`x/ibc/04-channel`](https://github.com/cosmos/x/ibc/04-channel) +- [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/05-port`](https://github.com/cosmos/x/ibc/05-port) +- [ICS 006 - Solo Machine Client](https://github.com/cosmos/ics/blob/master/spec/ics-006-solo-machine-client): To be implemented in [`x/ibc/06-solo`](https://github.com/cosmos/x/ibc/06-solo) +- [ICS 007 - Tendermint Client](https://github.com/cosmos/ics/blob/master/spec/ics-007-tendermint-client): Implemented in [`x/ibc/07-tendermint`](https://github.com/cosmos/x/ibc/07-tendermint) +- [ICS 009 - Loopback Client](https://github.com/cosmos/ics/blob/master/spec/ics-009-loopback-client): To be implemented in [`x/ibc/09-loopback`](https://github.com/cosmos/x/ibc/09-loopback) +- [ICS 018- Relayer Algorithms](https://github.com/cosmos/ics/tree/master/spec/ics-018-relayer-algorithms): Implemented in it's own [relayer repository](https://github.com/cosmos/relayer) +- [ICS 020 - Fungible Token Transfer](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer): Implemented in [`x/ibc/20-transfer`](https://github.com/cosmos/x/ibc/20-transfer) +- [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/23-commitment`](https://github.com/cosmos/x/ibc/23-commitment) +- [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/24-host`](https://github.com/cosmos/x/ibc/24-host) +- [ICS 025 - Handler Interface](https://github.com/cosmos/ics/tree/master/spec/ics-025-handler-interface): Handler interfaces are implemented at the top level in `x/ibc/handler.go`, +which call each ICS submodule's handlers (i.e `x/ibc/{XX-ICS}/handler.go`). +- [ICS 026 - Routing Module](https://github.com/cosmos/ics/blob/master/spec/ics-026-routing-module): Replaced by [ADR 15 - IBC Packet Receiver](../../../docs/architecture/adr-015-ibc-packet-receiver.md). + +### Architecture Decision Records (ADR) + +The following ADR provide the design and architecture decision of IBC-related components. + +- [ADR 10 - Modular AnteHandler](../../../docs/architecture/adr-010-modular-antehandler.md): Introduces a decorator pattern for the [`AnteHandler`](../../../docs/basics/gas-fees.md#antehandler), making it modular. +- [ADR 15 - IBC Packet Receiver](../../../docs/architecture/adr-015-ibc-packet-receiver.md): replaces the ICS26 routing module with [`AnteHandler`](../../../docs/basics/gas-fees.md#antehandler) logic within IBC. This is implemented using the `AnteDecorators` defined in [ADR10]((../../../docs/architecture/adr-010-modular-antehandler.md)) +- [ADR 17 - Historical Header Module](../../../docs/architecture/adr-017-historical-header-module.md): Introduces the ability to introspect past +consensus states in order to verify their membership in the counterparty clients. +- [ADR 19 - Protobuf State Encoding](../../../docs/architecture/adr-019-protobuf-state-encoding.md): Migration from Amino to Protobuf for state encoding. + +### SDK Modules + +- [`x/evidence`](https://github.com/cosmos/x/evidence): The evidence module provides the interfaces and client logic to handle light client misbehaviour. Check [ADR 09 - Evidence Module](../../../docs/architecture/adr-009-evidence-module.md) for more details. + +## IBC module architecture + +> **NOTE for auditors**: If you're not familiar with the overall module structure from +the SDK modules, please check this [document](../../../docs/building-modules/structure.md) as +prerequisite reading. + +For ease of auditing, every Interchain Standard has been developed in its own +package. The following tree describes the architecture of the directories within +the IBC module: + +```shell +x/ibc +├── 02-client/ +├── 03-connection/ +├── 04-channel/ +├── 05-port/ +├── 06-solo/ +├── 07-tendermint/ +├── 09-loopback/ +├── 20-transfer/ +├── 23-commitment/ +├── 24-host/ +├── ante +│   └── ante.go +├── client +│   ├── cli +│   │   └── cli.go +│   └── rest +│   └── rest.go +├── keeper +│   ├── keeper.go +│   └── querier.go +├── types +│   ├── errors.go +│   └── keys.go +├── alias.go +├── handler.go +└── module.go +```