cosmos · fedekunze · Nov 9, 2020 · Nov 9, 2020
diff --git a/x/ibc/core/spec/README.md b/x/ibc/core/spec/README.md
@@ -1,11 +1,11 @@
 <!--
 order: 0
-title: IBC Overview
+title: IBC Core
 parent:
-  title: "ibc"
+  title: "ibc core"
 -->
 
-# `ibc`
+# `ibc core`
 
 ## Abstract
 
@@ -23,89 +23,3 @@ For the general specification please refer to the [Interchain Standards](https:/
 4. **[Messages](04_messages.md)**
 5. **[Callbacks](05_callbacks.md)**
 6. **[Events](06_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 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/core/02-client`](https://github.com/cosmos/tree/master/ibc/core/02-client)
-* [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/core/03-connection`](https://github.com/cosmos/tree/master/ibc/core/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/core/04-channel`](https://github.com/cosmos/tree/master/ibc/core/04-channel)
-* [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/core/05-port`](https://github.com/cosmos/tree/master/ibc/core/05-port)
-* [ICS 006 - Solo Machine Client](https://github.com/cosmos/ics/blob/master/spec/ics-006-solo-machine-client): Implemented in [`x/ibc/light-clients/06-solomachine`](https://github.com/cosmos/tree/master/ibc/solomachine)
-* [ICS 007 - Tendermint Client](https://github.com/cosmos/ics/blob/master/spec/ics-007-tendermint-client): Implemented in [`x/ibc/light-clients/07-tendermint`](https://github.com/cosmos/tree/master/ibc/light-clients/07-tendermint)
-* [ICS 009 - Loopback Client](https://github.com/cosmos/ics/blob/master/spec/ics-009-loopback-client):  Implemented in [`x/ibc/light-clients/09-localhost`](https://github.com/cosmos/tree/master/ibc/light-clients/09-localhost)
-* [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/applications/transfer`](https://github.com/cosmos/tree/master/ibc/applications/transfer)
-* [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/core/23-commitment`](https://github.com/cosmos/tree/master/ibc/core/23-commitment)
-* [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/core/24-host`](https://github.com/cosmos/tree/master/ibc/core/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 001 - Coin Source Tracing](../../../docs/architecture/adr-001-coin-source-tracing.md): standard to hash the ICS20's fungible token
-denomination trace path in order to support special characters and limit the maximum denomination length.
-* [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.
-* [ADR 020 - Protocol Buffer Transaction Encoding](./../../docs/architecture/adr-020-protobuf-transaction-encoding.md): Client side migration to Protobuf.
-* [ADR 021 - Protocol Buffer Query Encoding](../../../docs/architecture/adr-020-protobuf-query-encoding.md): Queries migration to Protobuf.
-* [ADR 026 - IBC Client Recovery Mechanisms](../../../docs/architecture/adr-026-ibc-client-recovery-mechanisms.md): Allows IBC Clients to be recovered after freezing or expiry.
-
-### SDK Modules
-
-* [`x/capability`](https://github.com/cosmos/tree/master/x/capability): The capability module provides object-capability keys support through scoped keepers in order to authenticate usage of ports or channels. Check [ADR 3 - Dynamic Capability Store](../../../docs/architecture/adr-003-dynamic-capability-store.md) for more details.
-* [`x/evidence`](https://github.com/cosmos/tree/master/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 development team separated the IBC TAO (Transport, Authentication, Ordering) ICS specifications from the IBC application level
-specification. The following tree describes the architecture of the directories that
-the `ibc` (TAO) and `ibc-transfer` ([ICS20](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer)) modules:
-
-```shell
-x/ibc
-├── applications/
-│   └──ibc-transfer/
-├── 02-client/
-├── 02-client/
-├── 03-connection/
-├── 04-channel/
-├── 05-port/
-├── light-clients/
-│   ├── 06-solomachine/
-│   ├── 07-tendermint/
-│   └── 09-localhost/
-├── 23-commitment/
-├── 24-host/
-├── client
-│   ├── cli
-│   │   └── cli.go
-│   └── rest
-│       └── rest.go
-├── keeper
-│   ├── keeper.go
-│   └── querier.go
-├── types
-│   ├── errors.go
-│   └── keys.go
-├── handler.go
-└── module.go
-```
diff --git a/x/ibc/spec/README.md b/x/ibc/spec/README.md
@@ -0,0 +1,114 @@
+<!--
+order: 0
+title: IBC Overview
+parent:
+  title: "ibc"
+-->
+
+# `ibc`
+
+## Abstract
+
+This specification 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. **Applications**
+
+    1.1. [Transfer](./../applications/transfer/spec/README.md)
+2. **[Core](./../core/spec/README.md)**
+3. **Light Clients**
+
+    3.1 [Solo Machine Client](./../light-clients/06-solomachine/spec/README.md)
+
+    3.2 [Tendermint Client](./../light-clients/07-tendermint/spec/README.md)
+
+    3.3 [Localhost Client](./../light-clients/09-localhost/spec/README.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 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/core/02-client`](https://github.com/cosmos/tree/master/ibc/core/02-client)
+* [ICS 003 - Connection Semantics](https://github.com/cosmos/ics/blob/master/spec/ics-003-connection-semantics): Implemented in [`x/ibc/core/03-connection`](https://github.com/cosmos/tree/master/ibc/core/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/core/04-channel`](https://github.com/cosmos/tree/master/ibc/core/04-channel)
+* [ICS 005 - Port Allocation](https://github.com/cosmos/ics/blob/master/spec/ics-005-port-allocation): Implemented in [`x/ibc/core/05-port`](https://github.com/cosmos/tree/master/ibc/core/05-port)
+* [ICS 006 - Solo Machine Client](https://github.com/cosmos/ics/blob/master/spec/ics-006-solo-machine-client): Implemented in [`x/ibc/light-clients/06-solomachine`](https://github.com/cosmos/tree/master/ibc/solomachine)
+* [ICS 007 - Tendermint Client](https://github.com/cosmos/ics/blob/master/spec/ics-007-tendermint-client): Implemented in [`x/ibc/light-clients/07-tendermint`](https://github.com/cosmos/tree/master/ibc/light-clients/07-tendermint)
+* [ICS 009 - Loopback Client](https://github.com/cosmos/ics/blob/master/spec/ics-009-loopback-client):  Implemented in [`x/ibc/light-clients/09-localhost`](https://github.com/cosmos/tree/master/ibc/light-clients/09-localhost)
+* [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/applications/transfer`](https://github.com/cosmos/tree/master/ibc/applications/transfer)
+* [ICS 023 - Vector Commitments](https://github.com/cosmos/ics/tree/master/spec/ics-023-vector-commitments): Implemented in [`x/ibc/core/23-commitment`](https://github.com/cosmos/tree/master/ibc/core/23-commitment)
+* [ICS 024 - Host Requirements](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements): Implemented in [`x/ibc/core/24-host`](https://github.com/cosmos/tree/master/ibc/core/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 001 - Coin Source Tracing](../../../docs/architecture/adr-001-coin-source-tracing.md): standard to hash the ICS20's fungible token
+denomination trace path in order to support special characters and limit the maximum denomination length.
+* [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.
+* [ADR 020 - Protocol Buffer Transaction Encoding](./../../docs/architecture/adr-020-protobuf-transaction-encoding.md): Client side migration to Protobuf.
+* [ADR 021 - Protocol Buffer Query Encoding](../../../docs/architecture/adr-020-protobuf-query-encoding.md): Queries migration to Protobuf.
+* [ADR 026 - IBC Client Recovery Mechanisms](../../../docs/architecture/adr-026-ibc-client-recovery-mechanisms.md): Allows IBC Clients to be recovered after freezing or expiry.
+
+### SDK Modules
+
+* [`x/capability`](https://github.com/cosmos/tree/master/x/capability): The capability module provides object-capability keys support through scoped keepers in order to authenticate usage of ports or channels. Check [ADR 3 - Dynamic Capability Store](../../../docs/architecture/adr-003-dynamic-capability-store.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 development team separated the IBC TAO (Transport, Authentication, Ordering) ICS specifications from the IBC application level
+specification. The following tree describes the architecture of the directories that
+the `ibc` (TAO) and `ibc-transfer` ([ICS20](https://github.com/cosmos/ics/tree/master/spec/ics-020-fungible-token-transfer)) modules:
+
+```shell
+x/ibc
+├── applications/
+│   └──transfer/
+├── core/
+│   ├── 02-client/
+│   ├── 03-connection/
+│   ├── 04-channel/
+│   ├── 05-port/
+│   ├── 23-commitment/
+│   ├── 24-host/
+│   ├── client
+│   │   └── cli
+│   │       └── cli.go
+│   ├── keeper
+│   │   ├── keeper.go
+│   │   └── querier.go
+│   ├── types
+│   │   ├── errors.go
+│   │   └── keys.go
+│   ├── handler.go
+│   └── module.go
+├── light-clients/
+│   ├── 06-solomachine/
+│   ├── 07-tendermint/
+│   └── 09-localhost/
+└── testing/
+```