mukan-ibc/docs/requirements/localhost-requirements.md

Business requirements

The localhost client provides a unified interface to interact with different applications on a single chain.

Problem

Currently applications, or smart contracts, on a single chain cannot communicate through a single interface. This means a user must interact with each application or smart contract directly which can be cumbersome, especially when a user wants to interact with many applications on one chain.

Objectives

To provide a single interface in line with IBC application layer semantics, that enables a user to interact with multiple different applications or smart contracts remotely on a given blockchain.

Scope

Features	Release
To interface with applications or smart contracts on a blockchain through the IBC application layer	v7.1.0
To use the localhost client without requiring third party relayer infrastructure	N/A

User requirements

Use cases

Interacting with Smart Contracts

Many IBC connected blockchains utilise smart contracts, these could be written in rust, solidity or javascript depending on the smart contract platform being used. Through the localhost client, a user can interact with and call into smart contracts by sending ibc messages from the localhost client to the smart contract.

On Agoric, a planned use case is for managing delegations and staking with smart contracts on a given chain. MsgDelegate, MsgUndelegate, MsgBeginRedelegate messages would be sent using the localhost client to the staking module. The same interface could be used to manage staking cross chain, sending the same messages through IBC to an interchain account.

Interoperability Infrastructure

Polymer plans to leverage the localhost client with multiple connections as part of their architecture to connect chains not using Tendermint or the Cosmos SDK to IBC enabled chains. Polymer will act as a hub connecting multiple blockchains together.

Functional requirements

Assumptions and dependencies

1. Chains utilising the localhost client must be using an ibc-go release in the v7 line.
2. The channel behaviour of a localhost client will be as ICS 04 specifies.

Features

1 - Configuration

ID	Description	Verification	Status	Release
1.01	The localhost client shall have a client ID of the string 09-localhost.	Localhost client is created with client ID 09-localhost.	Verified	v7.1.0
1.02	The localhost client shall have a sentinel connection ID of the string connection-localhost.	Creation of sentinel connection with ID connection-localhost.	Verified	v7.1.0
1.03	Only 1 localhost connection is required	Localhost connection handshakes are forbidden in Init and Try.	Verified	v7.1.0
1.04	When the localhost client is initialised the consensus state must be nil.	Error is returned if consensus state is not nil.	Verified	v7.1.0
1.05	The localhost client can be added to a chain through an upgrade.	Automatic migration handler configured in core IBC module to set the localhost ClientState and sentinel ConnectionEnd in state..	Verified	v7.1.0
1.06	A chain can enable the localhost client by initialising the client in the genesis state.	InitGenesis handler in 02-client and InitGenesis handler in 03-connection.	Verified	v7.1.0

2 - Operation

ID	Description	Verification	Status	Release
2.01	A user of the localhost client can send IBC messages to an application on the same chain.	e2e test with transfer.	Verified	v7.1.0
2.02	A user can use the localhost client through the existing IBC application module interfaces.	e2e test with transfer.	Verified	v7.1.0

External interface requirements

3 - CLI

ID	Description	Verification	Status	Release
3.01	Existing CLI interfaces used with IBC application modules shall be usable with the localhost client.	Manual test	Verified	v7.1.0