From 2f5141af1f4c00e2dfe3fc8ddb915657ab5ebb8c Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Wed, 18 Dec 2019 13:42:50 -0300 Subject: [PATCH 1/6] IBC SDK specification --- docs/spec/ibc/README.md | 3 -- x/ibc/spec/01_concepts.md | 9 +++++ x/ibc/spec/02_state.md | 21 ++++++++++ x/ibc/spec/04_messages.md | 80 ++++++++++++++++++++++++++++++++++++++ x/ibc/spec/05_callbacks.md | 5 +++ x/ibc/spec/06_events.md | 76 ++++++++++++++++++++++++++++++++++++ x/ibc/spec/README.md | 25 ++++++++++++ 7 files changed, 216 insertions(+), 3 deletions(-) delete mode 100644 docs/spec/ibc/README.md create mode 100644 x/ibc/spec/01_concepts.md create mode 100644 x/ibc/spec/02_state.md create mode 100644 x/ibc/spec/04_messages.md create mode 100644 x/ibc/spec/05_callbacks.md create mode 100644 x/ibc/spec/06_events.md create mode 100644 x/ibc/spec/README.md 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/spec/01_concepts.md b/x/ibc/spec/01_concepts.md new file mode 100644 index 000000000000..84ceb303376d --- /dev/null +++ b/x/ibc/spec/01_concepts.md @@ -0,0 +1,9 @@ + + +# 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..c04bc5979b54 --- /dev/null +++ b/x/ibc/spec/06_events.md @@ -0,0 +1,76 @@ + + +# Events + +The IBC module emits the following events: + +## EndBlocker + +| Type | Attribute Key | Attribute Value | +|-----------------------|-----------------------|-----------------------| +| complete_unbonding | validator | {validatorAddress} | +| complete_unbonding | delegator | {delegatorAddress} | +| complete_redelegation | source_validator | {srcValidatorAddress} | +| complete_redelegation | destination_validator | {dstValidatorAddress} | +| complete_redelegation | delegator | {delegatorAddress} | + +## Handlers + +### MsgCreateValidator + +| Type | Attribute Key | Attribute Value | +|------------------|---------------|--------------------| +| create_validator | validator | {validatorAddress} | +| create_validator | amount | {delegationAmount} | +| message | module | staking | +| message | action | create_validator | +| message | sender | {senderAddress} | + +### MsgEditValidator + +| Type | Attribute Key | Attribute Value | +|----------------|---------------------|---------------------| +| edit_validator | commission_rate | {commissionRate} | +| edit_validator | min_self_delegation | {minSelfDelegation} | +| message | module | staking | +| message | action | edit_validator | +| message | sender | {senderAddress} | + +### MsgDelegate + +| Type | Attribute Key | Attribute Value | +|----------|---------------|--------------------| +| delegate | validator | {validatorAddress} | +| delegate | amount | {delegationAmount} | +| message | module | staking | +| message | action | delegate | +| message | sender | {senderAddress} | + +### MsgUndelegate + +| Type | Attribute Key | Attribute Value | +|---------|---------------------|--------------------| +| unbond | validator | {validatorAddress} | +| unbond | amount | {unbondAmount} | +| unbond | completion_time [0] | {completionTime} | +| message | module | staking | +| message | action | begin_unbonding | +| message | sender | {senderAddress} | + +* [0] Time is formatted in the RFC3339 standard + +### MsgBeginRedelegate + +| Type | Attribute Key | Attribute Value | +|------------|-----------------------|-----------------------| +| redelegate | source_validator | {srcValidatorAddress} | +| redelegate | destination_validator | {dstValidatorAddress} | +| redelegate | amount | {unbondAmount} | +| redelegate | completion_time [0] | {completionTime} | +| message | module | staking | +| message | action | begin_redelegate | +| message | sender | {senderAddress} | + +* [0] Time is formatted in the RFC3339 standard diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md new file mode 100644 index 000000000000..2d8f448c7d94 --- /dev/null +++ b/x/ibc/spec/README.md @@ -0,0 +1,25 @@ + + +# `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)** From 07739be324ec9482b3e1f28d18ac603919521c6e Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Thu, 19 Dec 2019 10:18:03 -0300 Subject: [PATCH 2/6] update events --- x/ibc/03-connection/handler.go | 2 + x/ibc/03-connection/types/events.go | 1 + x/ibc/04-channel/alias.go | 5 +- x/ibc/04-channel/handler.go | 19 ++- x/ibc/04-channel/types/events.go | 9 +- x/ibc/spec/01_concepts.md | 1 - x/ibc/spec/06_events.md | 207 +++++++++++++++++++--------- 7 files changed, 161 insertions(+), 83 deletions(-) diff --git a/x/ibc/03-connection/handler.go b/x/ibc/03-connection/handler.go index 854436eadd6a..8a94e5d1755c 100644 --- a/x/ibc/03-connection/handler.go +++ b/x/ibc/03-connection/handler.go @@ -17,6 +17,7 @@ func HandleMsgConnectionOpenInit(ctx sdk.Context, k keeper.Keeper, msg types.Msg sdk.NewEvent( types.EventTypeConnectionOpenInit, sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), + sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ), sdk.NewEvent( @@ -42,6 +43,7 @@ func HandleMsgConnectionOpenTry(ctx sdk.Context, k keeper.Keeper, msg types.MsgC sdk.NewEvent( types.EventTypeConnectionOpenTry, sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), + sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ), sdk.NewEvent( 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/alias.go b/x/ibc/04-channel/alias.go index d5494175505a..2c38d6901592 100644 --- a/x/ibc/04-channel/alias.go +++ b/x/ibc/04-channel/alias.go @@ -36,10 +36,9 @@ const ( CodePacketTimeout = types.CodePacketTimeout CodeInvalidChannel = types.CodeInvalidChannel CodeInvalidChannelState = types.CodeInvalidChannelState - AttributeKeySenderPort = types.AttributeKeySenderPort - AttributeKeyReceiverPort = types.AttributeKeyReceiverPort + AttributeKeyPortID = types.AttributeKeyPortID + AttributeCounterpartyPortID = types.AttributeCounterpartyPortID AttributeKeyChannelID = types.AttributeKeyChannelID - AttributeKeySequence = types.AttributeKeySequence SubModuleName = types.SubModuleName StoreKey = types.StoreKey RouterKey = types.RouterKey diff --git a/x/ibc/04-channel/handler.go b/x/ibc/04-channel/handler.go index 31c97b668e1a..b7dfb780dd63 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, @@ -44,9 +47,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, @@ -70,7 +75,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( @@ -93,7 +98,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( @@ -116,7 +121,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( @@ -139,7 +144,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 index 84ceb303376d..907893de27e4 100644 --- a/x/ibc/spec/01_concepts.md +++ b/x/ibc/spec/01_concepts.md @@ -6,4 +6,3 @@ order: 1 > 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/06_events.md b/x/ibc/spec/06_events.md index c04bc5979b54..e333e8af07d4 100644 --- a/x/ibc/spec/06_events.md +++ b/x/ibc/spec/06_events.md @@ -6,71 +6,142 @@ order: 6 The IBC module emits the following events: -## EndBlocker - -| Type | Attribute Key | Attribute Value | -|-----------------------|-----------------------|-----------------------| -| complete_unbonding | validator | {validatorAddress} | -| complete_unbonding | delegator | {delegatorAddress} | -| complete_redelegation | source_validator | {srcValidatorAddress} | -| complete_redelegation | destination_validator | {dstValidatorAddress} | -| complete_redelegation | delegator | {delegatorAddress} | - -## Handlers - -### MsgCreateValidator - -| Type | Attribute Key | Attribute Value | -|------------------|---------------|--------------------| -| create_validator | validator | {validatorAddress} | -| create_validator | amount | {delegationAmount} | -| message | module | staking | -| message | action | create_validator | -| message | sender | {senderAddress} | - -### MsgEditValidator - -| Type | Attribute Key | Attribute Value | -|----------------|---------------------|---------------------| -| edit_validator | commission_rate | {commissionRate} | -| edit_validator | min_self_delegation | {minSelfDelegation} | -| message | module | staking | -| message | action | edit_validator | -| message | sender | {senderAddress} | - -### MsgDelegate - -| Type | Attribute Key | Attribute Value | -|----------|---------------|--------------------| -| delegate | validator | {validatorAddress} | -| delegate | amount | {delegationAmount} | -| message | module | staking | -| message | action | delegate | -| message | sender | {senderAddress} | - -### MsgUndelegate - -| Type | Attribute Key | Attribute Value | -|---------|---------------------|--------------------| -| unbond | validator | {validatorAddress} | -| unbond | amount | {unbondAmount} | -| unbond | completion_time [0] | {completionTime} | -| message | module | staking | -| message | action | begin_unbonding | -| message | sender | {senderAddress} | - -* [0] Time is formatted in the RFC3339 standard - -### MsgBeginRedelegate - -| Type | Attribute Key | Attribute Value | -|------------|-----------------------|-----------------------| -| redelegate | source_validator | {srcValidatorAddress} | -| redelegate | destination_validator | {dstValidatorAddress} | -| redelegate | amount | {unbondAmount} | -| redelegate | completion_time [0] | {completionTime} | -| message | module | staking | -| message | action | begin_redelegate | -| message | sender | {senderAddress} | - -* [0] Time is formatted in the RFC3339 standard +## 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} | From 98c3918eeeafda5bc34599a149dea8f4eb952253 Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Thu, 19 Dec 2019 11:15:01 -0300 Subject: [PATCH 3/6] add implementation mapping --- x/ibc/spec/README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md index 2d8f448c7d94..15390dde9094 100644 --- a/x/ibc/spec/README.md +++ b/x/ibc/spec/README.md @@ -23,3 +23,56 @@ For the general specification please refer to the [Interchain Standards](https:/ 4. **[Messages](03_messages.md)** 5. **[Callbacks](06_callbacks.md)** 6. **[Events](07_events.md)** + +## Implementation mapping from ICS + +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`. + +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`](../02-client) +- [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/03-connection`](../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`](../04-channel) +- [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/05-port`](../05-port) +- [ICS 020 - Fungible Token Transfer](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer): Implemented in [`x/ibc/20-transfer`](../20-transfer) +- [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/23-commitment`](../23-commitment) +- [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/24-host`](../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). + +## 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. + +```shell +x/ibc +├── 02-client/ +├── 03-connection/ +├── 04-channel/ +├── 05-port/ +├── 20-transfer/ +├── 23-commitment/ +├── 24-host/ +├── client +│   ├── cli +│   │   └── cli.go +│   └── rest +│   └── rest.go +├── keeper +│   ├── keeper.go +│   └── querier.go +├── types +│   ├── errors.go +│   └── keys.go +├── alias.go +├── handler.go +└── module.go +``` + From dffd7134d351eddc8d8d04b7875a4c0b9f67ef50 Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Mon, 6 Jan 2020 08:20:50 -0300 Subject: [PATCH 4/6] minor additions to readme --- x/ibc/spec/README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md index 15390dde9094..18c1716bed70 100644 --- a/x/ibc/spec/README.md +++ b/x/ibc/spec/README.md @@ -24,7 +24,7 @@ For the general specification please refer to the [Interchain Standards](https:/ 5. **[Callbacks](06_callbacks.md)** 6. **[Events](07_events.md)** -## Implementation mapping from ICS +## 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 @@ -38,6 +38,8 @@ in the SDK's `x/ibc` module: - [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/03-connection`](../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`](../04-channel) - [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/05-port`](../05-port) +- [ICS 006 - Solo Machine Client](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/06-solo`](../06-solo) +- [ICS 007 - Tendermint Client](https://github.com/cosmos/ics/blob/master/spec/ics-007-tendermint-client): Implemented in [`x/ibc/07-tendermint`](../07-tendermint) - [ICS 020 - Fungible Token Transfer](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer): Implemented in [`x/ibc/20-transfer`](../20-transfer) - [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/23-commitment`](../23-commitment) - [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/24-host`](../24-host) @@ -45,12 +47,21 @@ in the SDK's `x/ibc` module: 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). +Other relevant pieces of work include: + +- [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. + ## 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/ @@ -75,4 +86,3 @@ x/ibc ├── handler.go └── module.go ``` - From a2969645b27e913cb39d6ce69c689e90b587700c Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Tue, 18 Feb 2020 15:05:18 +0100 Subject: [PATCH 5/6] fix conflicts --- x/ibc/03-connection/handler.go | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/x/ibc/03-connection/handler.go b/x/ibc/03-connection/handler.go index ddea75de8985..1cc1603ccc6c 100644 --- a/x/ibc/03-connection/handler.go +++ b/x/ibc/03-connection/handler.go @@ -14,16 +14,10 @@ func HandleMsgConnectionOpenInit(ctx sdk.Context, k Keeper, msg MsgConnectionOpe ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( -<<<<<<< HEAD types.EventTypeConnectionOpenInit, sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), -======= - EventTypeConnectionOpenInit, - sdk.NewAttribute(AttributeKeyConnectionID, msg.ConnectionID), - sdk.NewAttribute(AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ->>>>>>> efb28d7e4e69923fb79a494d00b151e4cb344df2 ), sdk.NewEvent( sdk.EventTypeMessage, @@ -49,16 +43,10 @@ func HandleMsgConnectionOpenTry(ctx sdk.Context, k Keeper, msg MsgConnectionOpen ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( -<<<<<<< HEAD types.EventTypeConnectionOpenTry, sdk.NewAttribute(types.AttributeKeyConnectionID, msg.ConnectionID), sdk.NewAttribute(types.AttributeKeyClientID, msg.ClientID), sdk.NewAttribute(types.AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), -======= - EventTypeConnectionOpenTry, - sdk.NewAttribute(AttributeKeyConnectionID, msg.ConnectionID), - sdk.NewAttribute(AttributeKeyCounterpartyClientID, msg.Counterparty.ClientID), ->>>>>>> efb28d7e4e69923fb79a494d00b151e4cb344df2 ), sdk.NewEvent( sdk.EventTypeMessage, From c4f3df748b274809c2fb029f0759abc58675cf94 Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Tue, 18 Feb 2020 15:29:57 +0100 Subject: [PATCH 6/6] add missing ADRs, modules and ICS --- x/ibc/spec/README.md | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md index 18c1716bed70..9023949b8294 100644 --- a/x/ibc/spec/README.md +++ b/x/ibc/spec/README.md @@ -31,26 +31,39 @@ 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`](../02-client) -- [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/03-connection`](../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`](../04-channel) -- [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/05-port`](../05-port) -- [ICS 006 - Solo Machine Client](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/06-solo`](../06-solo) -- [ICS 007 - Tendermint Client](https://github.com/cosmos/ics/blob/master/spec/ics-007-tendermint-client): Implemented in [`x/ibc/07-tendermint`](../07-tendermint) -- [ICS 020 - Fungible Token Transfer](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer): Implemented in [`x/ibc/20-transfer`](../20-transfer) -- [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/23-commitment`](../23-commitment) -- [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/24-host`](../24-host) +- [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). -Other relevant pieces of work include: +### 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 @@ -68,9 +81,14 @@ x/ibc ├── 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