Skip to content

Commit

Permalink
feat: adding 09-localhost loopback client module (backport #3229) (#3262
Browse files Browse the repository at this point in the history
)

* Adding 09-localhost loopback client module (#3229)

feat: adding 09-localhost loopback client module [\#3034](#3034). Please see the 09-localhost documentation [here](https://ibc.cosmos.network/main/ibc/light-clients/localhost/overview.html).
feat: AllowedClients on-chain param allows chains to pause usage of specific client types by removing the client type from the param.
imp: Update all channel events to use `connection_id` attribute. The `packet_connection` attribute has been deprecated.
(cherry picked from commit d840c69)

# Conflicts:
#	.github/workflows/e2e-upgrade.yaml
#	docs/ibc/events.md
#	e2e/relayer/relayer.go
#	e2e/testconfig/testconfig.go
#	e2e/tests/upgrades/upgrade_test.go
#	e2e/testsuite/codec.go
#	e2e/testsuite/grpc_query.go
#	e2e/testsuite/testsuite.go
#	modules/core/02-client/keeper/client.go
#	modules/core/02-client/keeper/proposal.go
#	modules/core/02-client/types/errors.go
#	modules/core/03-connection/keeper/verify.go
#	modules/core/03-connection/types/msgs_test.go
#	modules/core/04-channel/keeper/packet.go
#	modules/core/04-channel/types/msgs.go

* rm -rf e2e

* rm .github/workflows/e2e-upgrade.yaml

* fix errorsmod -> sdkerrors

* ibcerror -> sdkerror in localhost client_state.go

---------

Co-authored-by: Damian Nolan <[email protected]>
  • Loading branch information
mergify[bot] and damiannolan authored Mar 9, 2023
1 parent 9403c30 commit 893b7af
Show file tree
Hide file tree
Showing 63 changed files with 1,921 additions and 243 deletions.
42 changes: 42 additions & 0 deletions docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,11 @@ module.exports = {
directory: false,
path: "/roadmap/roadmap.html",
},
{
title: "Troubleshooting",
directory: false,
path: "/ibc/troubleshooting.html",
},
],
},
{
Expand Down Expand Up @@ -389,6 +394,38 @@ module.exports = {
},
]
},
{
title: "Localhost",
directory: true,
path: "/ibc/light-clients/localhost",
children: [
{
title: "Overview",
directory: false,
path: "/ibc/light-clients/localhost/overview.html",
},
{
title: "Integration",
directory: false,
path: "/ibc/light-clients/localhost/integration.html",
},
{
title: "ClientState",
directory: false,
path: "/ibc/light-clients/localhost/client-state.html",
},
{
title: "Connection",
directory: false,
path: "/ibc/light-clients/localhost/connection.html",
},
{
title: "State Verification",
directory: false,
path: "/ibc/light-clients/localhost/state-verification.html",
},
],
},
{
title: "Solomachine",
directory: true,
Expand Down Expand Up @@ -504,6 +541,11 @@ module.exports = {
directory: false,
path: "/migrations/v6-to-v7.html",
},
{
title: "IBC-Go v7 to v7.1",
directory: false,
path: "/migrations/v7-to-v7_1.html",
},
],
},
{
Expand Down
120 changes: 81 additions & 39 deletions docs/ibc/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,54 +185,81 @@ callbacks to IBC applications.

### SendPacket (application module call)

| Type | Attribute Key | Attribute Value |
|-------------|--------------------------|----------------------------------|
| send_packet | packet_data | {data} |
| send_packet | packet_timeout_height | {timeoutHeight} |
| send_packet | packet_timeout_timestamp | {timeoutTimestamp} |
| send_packet | packet_sequence | {sequence} |
| send_packet | packet_src_port | {sourcePort} |
| send_packet | packet_src_channel | {sourceChannel} |
| send_packet | packet_dst_port | {destinationPort} |
| send_packet | packet_dst_channel | {destinationChannel} |
| send_packet | packet_channel_ordering | {channel.Ordering} |
| message | action | application-module-defined-field |
| message | module | ibc-channel |
| Type | Attribute Key | Attribute Value | Status |
|-------------|--------------------------|----------------------------------|------------|
| send_packet | packet_data | {data} | Deprecated |
| send_packet | packet_data_hex | {hex.Encode(data)} | |
| send_packet | packet_timeout_height | {timeoutHeight} | |
| send_packet | packet_timeout_timestamp | {timeoutTimestamp} | |
| send_packet | packet_sequence | {sequence} | |
| send_packet | packet_src_port | {sourcePort} | |
| send_packet | packet_src_channel | {sourceChannel} | |
| send_packet | packet_dst_port | {destinationPort} | |
| send_packet | packet_dst_channel | {destinationChannel} | |
| send_packet | packet_channel_ordering | {channel.Ordering} | |
| send_packet | packet_connection | {channel.ConnectionHops[0]} | Deprecated |
| send_packet | connection_id | {channel.ConnectionHops[0]} | |
| message | action | application-module-defined-field | |
| message | module | ibc-channel | |

### MsgRecvPacket

| Type | Attribute Key | Attribute Value |
|-------------|--------------------------|----------------------|
| recv_packet | packet_data | {data} |
| recv_packet | packet_ack | {acknowledgement} |
| recv_packet | packet_timeout_height | {timeoutHeight} |
| recv_packet | packet_timeout_timestamp | {timeoutTimestamp} |
| recv_packet | packet_sequence | {sequence} |
| recv_packet | packet_src_port | {sourcePort} |
| recv_packet | packet_src_channel | {sourceChannel} |
| recv_packet | packet_dst_port | {destinationPort} |
| recv_packet | packet_dst_channel | {destinationChannel} |
| recv_packet | packet_channel_ordering | {channel.Ordering} |
| message | action | recv_packet |
| message | module | ibc-channel |
| Type | Attribute Key | Attribute Value | Status |
|-------------|--------------------------|-------------------------------|------------|
| recv_packet | packet_data | {data} | Deprecated |
| recv_packet | packet_data_hex | {hex.Encode(data)} | |
| recv_packet | packet_timeout_height | {timeoutHeight} | |
| recv_packet | packet_timeout_timestamp | {timeoutTimestamp} | |
| recv_packet | packet_sequence | {sequence} | |
| recv_packet | packet_src_port | {sourcePort} | |
| recv_packet | packet_src_channel | {sourceChannel} | |
| recv_packet | packet_dst_port | {destinationPort} | |
| recv_packet | packet_dst_channel | {destinationChannel} | |
| recv_packet | packet_channel_ordering | {channel.Ordering} | |
| recv_packet | packet_connection | {channel.ConnectionHops[0]} | Deprecated |
| recv_packet | connection_id | {channel.ConnectionHops[0]} | |
| message | action | recv_packet | |
| message | module | ibc-channel | |

| Type | Attribute Key | Attribute Value | Status |
|-----------------------|--------------------------|-------------------------------|------------|
| write_acknowledgement | packet_data | {data} | Deprecated |
| write_acknowledgement | packet_data_hex | {hex.Encode(data)} | |
| write_acknowledgement | packet_timeout_height | {timeoutHeight} | |
| write_acknowledgement | packet_timeout_timestamp | {timeoutTimestamp} | |
| write_acknowledgement | packet_sequence | {sequence} | |
| write_acknowledgement | packet_src_port | {sourcePort} | |
| write_acknowledgement | packet_src_channel | {sourceChannel} | |
| write_acknowledgement | packet_dst_port | {destinationPort} | |
| write_acknowledgement | packet_dst_channel | {destinationChannel} | |
| write_acknowledgement | packet_ack | {ack} | Deprecated |
| write_acknowledgement | packet_ack_hex | {hex.Encode(ack)} | |
| write_acknowledgement | packet_channel_ordering | {channel.Ordering} | |
| write_acknowledgement | packet_connection | {channel.ConnectionHops[0]} | Deprecated |
| write_acknowledgement | connection_id | {channel.ConnectionHops[0]} | |
| message | action | write_acknowledgement | |
| message | module | ibc-channel | |

### MsgAcknowledgePacket

| Type | Attribute Key | Attribute Value |
|--------------------|--------------------------|----------------------|
| acknowledge_packet | packet_timeout_height | {timeoutHeight} |
| acknowledge_packet | packet_timeout_timestamp | {timeoutTimestamp} |
| acknowledge_packet | packet_sequence | {sequence} |
| acknowledge_packet | packet_src_port | {sourcePort} |
| acknowledge_packet | packet_src_channel | {sourceChannel} |
| acknowledge_packet | packet_dst_port | {destinationPort} |
| acknowledge_packet | packet_dst_channel | {destinationChannel} |
| acknowledge_packet | packet_channel_ordering | {channel.Ordering} |
| message | action | acknowledge_packet |
| message | module | ibc-channel |
| Type | Attribute Key | Attribute Value | Status |
|--------------------|--------------------------|-------------------------------|------------|
| acknowledge_packet | packet_timeout_height | {timeoutHeight} | |
| acknowledge_packet | packet_timeout_timestamp | {timeoutTimestamp} | |
| acknowledge_packet | packet_sequence | {sequence} | |
| acknowledge_packet | packet_src_port | {sourcePort} | |
| acknowledge_packet | packet_src_channel | {sourceChannel} | |
| acknowledge_packet | packet_dst_port | {destinationPort} | |
| acknowledge_packet | packet_dst_channel | {destinationChannel} | |
| acknowledge_packet | packet_channel_ordering | {channel.Ordering} | |
| acknowledge_packet | packet_connection | {channel.ConnectionHops[0]} | Deprecated |
| acknowledge_packet | connection_id | {channel.ConnectionHops[0]} | |
| message | action | acknowledge_packet | |
| message | module | ibc-channel | |

### MsgTimeoutPacket & MsgTimeoutOnClose

<<<<<<< HEAD
| Type | Attribute Key | Attribute Value |
|----------------|--------------------------|----------------------|
| timeout_packet | packet_timeout_height | {timeoutHeight} |
Expand All @@ -246,3 +273,18 @@ callbacks to IBC applications.
| message | action | timeout_packet |
| message | module | ibc-channel |

=======
| Type | Attribute Key | Attribute Value |
|----------------|--------------------------|-------------------------------|
| timeout_packet | packet_timeout_height | {timeoutHeight} |
| timeout_packet | packet_timeout_timestamp | {timeoutTimestamp} |
| timeout_packet | packet_sequence | {sequence} |
| timeout_packet | packet_src_port | {sourcePort} |
| timeout_packet | packet_src_channel | {sourceChannel} |
| timeout_packet | packet_dst_port | {destinationPort} |
| timeout_packet | packet_dst_channel | {destinationChannel} |
| timeout_packet | packet_channel_ordering | {channel.Ordering} |
| timeout_packet | connection_id | {channel.ConnectionHops[0]} |
| message | action | timeout_packet |
| message | module | ibc-channel |
>>>>>>> d840c699 (Adding 09-localhost loopback client module (#3229))
60 changes: 60 additions & 0 deletions docs/ibc/light-clients/localhost/client-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
<!--
order: 3
-->

# `ClientState`

The 09-localhost `ClientState` maintains a single field used to track the latest sequence of the state machine i.e. the height of the blockchain.

```go
type ClientState struct {
// the latest height of the blockchain
LatestHeight clienttypes.Height
}
```

The 09-localhost `ClientState` is instantiated in the `InitGenesis` handler of the 02-client submodule in core IBC.
It calls `CreateLocalhostClient`, declaring a new `ClientState` and initializing it with its own client prefixed store.

```go
func (k Keeper) CreateLocalhostClient(ctx sdk.Context) error {
var clientState localhost.ClientState
return clientState.Initialize(ctx, k.cdc, k.ClientStore(ctx, exported.LocalhostClientID), nil)
}
```

It is possible to disable the localhost client by removing the `09-localhost` entry from the `allowed_clients` list through governance.

## Client updates

The latest height is updated periodically through the ABCI [`BeginBlock`](https://docs.cosmos.network/v0.47/building-modules/beginblock-endblock) interface of the 02-client submodule in core IBC.

[See `BeginBlocker` in abci.go.](https://github.com/cosmos/ibc-go/blob/09-localhost/modules/core/02-client/abci.go#L12)

```go
func BeginBlocker(ctx sdk.Context, k keeper.Keeper) {
// ...

if clientState, found := k.GetClientState(ctx, exported.Localhost); found {
if k.GetClientStatus(ctx, clientState, exported.Localhost) == exported.Active {
k.UpdateLocalhostClient(ctx, clientState)
}
}
}
```

The above calls into the the 09-localhost `UpdateState` method of the `ClientState` .
It retrieves the current block height from the application context and sets the `LatestHeight` of the 09-localhost client.

```go
func (cs ClientState) UpdateState(ctx sdk.Context, cdc codec.BinaryCodec, clientStore sdk.KVStore, clientMsg exported.ClientMessage) []exported.Height {
height := clienttypes.GetSelfHeight(ctx)
cs.LatestHeight = height

clientStore.Set(host.ClientStateKey(), clienttypes.MustMarshalClientState(cdc, &cs))

return []exported.Height{height}
}
```

Note that the 09-localhost `ClientState` is not updated through the 02-client interface leveraged by conventional IBC light clients.
25 changes: 25 additions & 0 deletions docs/ibc/light-clients/localhost/connection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!--
order: 4
-->

# Localhost connections

The 09-localhost light client module integrates with core IBC through a single sentinel localhost connection.
The sentinel `ConnectionEnd` is stored by default in the core IBC store.

This enables channel handshakes to be initiated out of the box by supplying the localhost connection identifier (`connection-localhost`) in the `connectionHops` parameter of `MsgChannelOpenInit`.

The `ConnectionEnd` is created and set in store via the `InitGenesis` handler of the 03-connection submodule in core IBC.
The `ConnectionEnd` and its `Counterparty` both reference the `09-localhost` client identifier, and share the localhost connection identifier `connection-localhost`.

```go
// CreateSentinelLocalhostConnection creates and sets the sentinel localhost connection end in the IBC store.
func (k Keeper) CreateSentinelLocalhostConnection(ctx sdk.Context) {
counterparty := types.NewCounterparty(exported.LocalhostClientID, exported.LocalhostConnectionID, commitmenttypes.NewMerklePrefix(k.GetCommitmentPrefix().Bytes()))
connectionEnd := types.NewConnectionEnd(types.OPEN, exported.LocalhostClientID, counterparty, types.ExportedVersionsToProto(types.GetCompatibleVersions()), 0)

k.SetConnection(ctx, exported.LocalhostConnectionID, connectionEnd)
}
```

Note that connection handshakes are disallowed when using the `09-localhost` client type.
16 changes: 16 additions & 0 deletions docs/ibc/light-clients/localhost/integration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!--
order: 2
-->

# Integration

The 09-localhost light client module registers codec types within the core IBC module. This differs from other light client module implementations which are expected to register codec types using the `AppModuleBasic` interface.

The localhost client is added to the 02-client submodule param [`allowed_clients`](https://github.com/cosmos/ibc-go/blob/v7.0.0-rc0/proto/ibc/core/client/v1/client.proto#L102) by default in ibc-go.

```go
var (
// DefaultAllowedClients are the default clients for the AllowedClients parameter.
DefaultAllowedClients = []string{exported.Solomachine, exported.Tendermint, exported.Localhost}
)
```
Loading

0 comments on commit 893b7af

Please sign in to comment.