feat: adding 09-localhost loopback client module

.github/workflows/e2e-upgrade.yaml

@@ -41,3 +41,15 @@ jobs:
       upgrade-plan-name: "v7"
       test-entry-point:  "TestUpgradeTestSuite"
       test: "TestV6ToV7ChainUpgrade"
+
+  upgrade-v7_1:
+    uses: cosmos/ibc-go/.github/workflows/e2e-test-workflow-call.yml@main
+    with:
+      chain-image: ghcr.io/cosmos/ibc-go-simd
+      chain-binary: simd
+      chain-a-tag: pr-3136 # TODO: needs v7.0.0 (with simapp fixes) when cut
+      chain-b-tag: pr-3136 # TODO: needs v7.0.0 (with simapp fixes) when cut
+      chain-upgrade-tag: pr-3164 # TODO: needs v7.1.0 when cut
+      upgrade-plan-name: "v7.1"
+      test-entry-point:  "TestUpgradeTestSuite"
+      test: "TestV7ChainUpgradeAddLocalhost"

docs/.vuepress/config.js

@@ -215,6 +215,11 @@ module.exports = {
               directory: false,
               path: "/roadmap/roadmap.html",
             },
+            {
+              title: "Troubleshooting",
+              directory: false,
+              path: "/ibc/troubleshooting.html",
+            },
           ],
         },
         {
@@ -393,6 +398,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,

docs/ibc/light-clients/localhost/client-state.md

@@ -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([]byte(host.KeyClientState), 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.

docs/ibc/light-clients/localhost/connection.md

@@ -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.

docs/ibc/light-clients/localhost/integration.md

@@ -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}
+)
+```

docs/ibc/light-clients/localhost/overview.md

@@ -0,0 +1,40 @@
+<!--
+order: 1
+-->
+
+# `09-localhost`
+
+## Overview
+
+Learn about the 09-localhost light client module. {synopsis}
+
+The 09-localhost light client module implements a localhost loopback client with the ability to send and receive IBC packets to and from the same state machine.
+
+### Context
+
+In a multichain environment, application developers will be used to developing cross-chain applications through IBC. From their point of view, whether or not they are interacting with multiple modules on the same chain or on different chains should not matter. The localhost client module enables a unified interface to interact with different applications on a single chain, using the familiar IBC application layer semantics.
+
+### Implementation
+
+There exists a [single sentinel `ClientState`](./client-state.md) instance with the client identifier `09-localhost`.
+
+To supplement this, a [sentinel `ConnectionEnd` is stored in core IBC](./connection.md) state with the connection identifier `connection-localhost`. This enables IBC applications to create channels directly on top of the sentinel connection which leverage the 09-localhost loopback functionality.
+
+[State verification](./state-verification.md) for channel state in handshakes or processing packets is reduced in complexity, the `09-localhost` client can simply compare bytes stored under the standardized key paths.
+
+### Localhost vs *regular* client
+
+The localhost client aims to provide a unified approach to interacting with applications on a single chain, as the IBC application layer provides for cross-chain interactions. To achieve this unified interface though, there are a number of differences under the hood compared to a 'regular' IBC client (excluding `06-solomachine` and `09-localhost` itself).
+
+The table below lists some important differences:
+
+|                                              | Regular client | Localhost |
+| -------------------------------------------- | --------------------------------------------------------------------------- | --------- |
+| Number of clients                            | Many instances of a client *type* corresponding to different counterparties | A single sentinel client with the client identifier `09-localhost`|
+| Client creation                              | Relayer (permissionless) | `ClientState` is instantiated in the `InitGenesis` handler of the 02-client submodule in core IBC |
+| Client updates                               | Relayer submits headers using `MsgUpdateClient` | 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 |
+| Number of connections                        | Many connections, 1 (or more) per client | A single sentinel connection with the connection identifier `connection-localhost` |
+| Connection creation                          | Connection handshake, provided underlying client | Sentinel `ConnectionEnd` is created and set in store in the `InitGenesis` handler of the 03-connection submodule in core IBC |
+| Counterparty                                 | Underlying client, representing another chain | Client with identifier `09-localhost` in same chain |
+| `VerifyMembership` and `VerifyNonMembership` | Performs proof verification using consensus state roots | Performs state verification using key-value lookups in the core IBC store |
+| Integration | Expected to register codec types using the `AppModuleBasic` interface | Registers codec types within the core IBC module |

docs/ibc/light-clients/localhost/state-verification.md

@@ -0,0 +1,18 @@
+<!--
+order: 5
+-->
+
+# State verification
+
+The localhost client handles state verification through the `ClientState` interface methods `VerifyMembership` and `VerifyNonMembership` by performing read-only operations directly on the core IBC store.
+
+When verifying channel state in handshakes or processing packets the `09-localhost` client can simply compare bytes stored under the standardized key paths defined by [ICS-24](https://github.com/cosmos/ibc/tree/main/spec/core/ics-024-host-requirements).
+
+For existence proofs via `VerifyMembership` the 09-localhost client will retrieve the value stored under the provided key path and compare it against the value provided by the caller. In contrast, non-existence proofs via `VerifyNonMembership` assert the absence of a value at the provided key path.
+
+Relayers are expected to provide a sentinel proof when sending IBC messages. Submission of nil or empty proofs is disallowed in core IBC messaging. 
+The 09-localhost light client module defines a `SentinelProof` as a single byte. Localhost client state verification will fail if the sentintel proof value is not provided.
+
+```go
+var SentinelProof = []byte{0x01}
+```

docs/ibc/troubleshooting.md

@@ -0,0 +1,8 @@
+# Troubleshooting
+
+### Unauthorized client states
+
+If it is being reported that a client state is unauthorized, this is due to the client type not being present
+in the [`AllowedClients`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/02-client/types/client.pb.go#L345) array.
+
+Unless the client type is present in this array, all usage of clients of this type will be prevented.

docs/migrations/v7-to-v7_1.md

@@ -0,0 +1,30 @@
+# Migrating from v7 to v7.1
+
+This guide provides instructions for migrating to a new version of ibc-go.
+
+There are four sections based on the four potential user groups of this document:
+
+- [Chains](#chains)
+- [IBC Apps](#ibc-apps)
+- [Relayers](#relayers)
+- [IBC Light Clients](#ibc-light-clients)
+
+**Note:** ibc-go supports golang semantic versioning and therefore all imports must be updated on major version releases.
+
+## Chains
+
+- No relevant changes were made in this release.
+
+## IBC Apps
+
+- No relevant changes were made in this release.
+
+## Relayers
+
+The event attribute `packet_connection` (`connectiontypes.AttributeKeyConnection`) has been deprecated. 
+Please use the `connection_id` attribute (`connectiontypes.AttributeKeyConnectionID`) which is emitted by all channel events.
+Only send packet, receive packet, write acknowledgement, and acknowledge packet events used `packet_connection` previously.
+
+## IBC Light Clients
+
+- No relevant changes were made in this release.

e2e/relayer/relayer.go

@@ -15,8 +15,8 @@ const (
 	Rly    = "rly"
 	Hermes = "hermes"
 
-	cosmosRelayerRepository = "ghcr.io/cosmos/relayer"
-	cosmosRelayerUser       = "100:1000" // docker run -it --rm --entrypoint echo ghcr.io/cosmos/relayer "$(id -u):$(id -g)"
+	cosmosRelayerRepository = "damiannolan/rly" //"ghcr.io/cosmos/relayer"
+	cosmosRelayerUser       = "100:1000"        // docker run -it --rm --entrypoint echo ghcr.io/cosmos/relayer "$(id -u):$(id -g)"
 )
 
 // Config holds configuration values for the relayer used in the tests.

e2e/testconfig/testconfig.go

@@ -46,7 +46,7 @@ const (
 	defaultBinary = "simd"
 	// defaultRlyTag is the tag that will be used if no relayer tag is specified.
 	// all images are here https://github.com/cosmos/relayer/pkgs/container/relayer/versions
-	defaultRlyTag = "andrew-tendermint_v0.37" // "v2.2.0"
+	defaultRlyTag = "latest" // "andrew-tendermint_v0.37" // "v2.2.0"
 	// defaultChainTag is the tag that will be used for the chains if none is specified.
 	defaultChainTag = "main"
 	// defaultRelayerType is the default relayer that will be used if none is specified.