docs: ADR-008 to restructure the ibc crate

docs/architecture/adr-008-restructure-ibc-crate.md

@@ -0,0 +1,122 @@
+# ADR 008: RESTRUCTURE `ibc` CRATE
+
+## Context
+
+The current state of the **`ibc`** crate exhibits a mix of different implementation layers. From a module-based perspective, it encompasses essential elements like ibc core, clients, applications, along with testing facilities. However, an architectural view reveals a fusion of diverse layers of type definitions, interfaces (APIs), and handler functions, resulting in a mix of dependencies and features that may lead to potential conflicts or unnecessary imports for users.
+
+As of [this pull request](https://github.com/cosmos/ibc-rs/pull/954), we've separated our mock testing kit into the standalone **`ibc-testkit`** library. This decoupling from the main **`ibc`** crate sets the stage for the objectives of this ADR.
+
+The primary goals here are twofold: firstly, to reduce interdependence within the codebase among various components such as ibc core, clients, and applications, and secondly, to improve the overall usability of the `ibc-rs` implementation. The overarching aim is to empower users to selectively import specific IBC layers, mitigating potential conflicts related to dependencies or features that may arise in the context of a monolithic library and letting `ibc-rs` be used in the following scenarios:
+
+1. **Selective Module Import**
+    - Users cannot import only the necessary components/modules for their projects. For instance, importing only the **`ics07_tendermint`** implementation is impractical.
+2. **Selective Types Import**
+    - Relayers, like Hermes, or any off-chain consumers cannot import their desired layer of implementation like ibc types without pulling in unnecessary dependencies into their project.
+3. **Smoother IBC Core Integration with Hosts**
+    - Integrating ibc core with host chains without introducing light client or app dependencies is currently not straightforward, impeding smooth integration.
+4. **Easier Development of CosmWasm Contracts**
+    - For developing a CosmWasm tendermint light client, we ideally should only be dependent on implementation under the **`ics07_tendermint`** and also be importing relevant parts from the **`ibc-core-client`** layer without pulling in all the ibc codebase and dependencies.
+
+This ADR aims to enhance both the usability and practicality of `ibc-rs` by restructuring the codebase and organizing it under multiple sub-libraries, as stated in the [decision](#decision) section. This will make different parts of `ibc-rs` accessible to users, positioning it as a more comprehensive, one-stop solution catering to diverse users groups, whether for on-chain or off-chain use cases.
+
+## Decision
+
+For the library organization, the first stage of separation is to split off the codebase of each IBC applications, clients, and core implementation, decoupling them from each other. The top-level libraries and the naming schema would look like as follow:
+
+```markdown
+.
+├── ibc -> Primarily re-exports sub-libraries
+├── ibc-core 
+│   ├── ibc-core-client (contains the implementation + Re-exports types)
+│   ├── ibc-core-connection
+│   ├── ibc-core-channel
+│   ├── ibc-core-commitment
+│   └── ibc-core-host
+│       └── .
+├── ibc-clients
+│   ├── ibc-client-tendermint
+│   ├── ibc-client-tendermint-cw
+│   └── .
+├── ibc-apps
+│   ├── ibc-app-transfer
+│   ├── ibc-app-ica
+│   │   └── .
+│   └── .
+├── ibc-preludes
+├── ibc-testkit (previously mock module + `test-utils` feature)
+├── ibc-query
+└── ibc-derive
+```
+
+With this restructure, the main `ibc` crate primarily re-exports types, interfaces, and implementation of all the sub-libraries. Therefore, if someone only wants to depend on the `ibc` crate without caring about this granularity, they can do so.
+
+Afterward, we split off data structure of each IBC layer into a separate sub-library under a `types` folder, still maintained under the directory of that relevant component/module. As an example, the `ibc-core-client` crate’s tree and the naming schema looks like this:
+
+```markdown
+ibc-core
+└── ibc-core-client (dir: ibc-core/ics02-client)
+    └── ibc-core-client-types (dir: ibc-core/ics02-client/types)
+        ├── msgs
+        ├── events
+        └── .
+```
+
+This way, the main crate of each IBC module contains all the necessary APIs and implementation to integrate with host chains, along with re-exporting the sub-library types. This allows projects to selectively import types (e.g. `ibc-core-client-types`), often required by off-chain users such as relayers. Or to pick the library containing the entire implementation of that particular module (e.g. `ibc-core-client`), typically more convenient for host chains or smart contract developers to integrate with their end.
+
+By this restructuring, the **directory tree** of the repo would look like as follow:
+
+```markdown
+ibc
+ibc-core
+├── ics02-client
+|   ├── src
+|   ├── types
+|   |   ├── src
+|   |   ├── README.md
+|   |   └── cargo.toml
+|   ├── README.md
+|   └── cargo.toml
+├── ics03-connection
+|   └── .
+├── ics04-channel
+|   └── .
+├── ics23-commitment
+|   └── .
+└── ics24-host
+    └── .
+ibc-clients
+├── ics07-tendermint
+├── ics08-wasm
+└── .
+ibc-apps
+├── ics20-transfer
+├── ics27-ica
+└── .
+ibc-preludes
+ibc-testkit
+ibc-query
+ibc-derive
+```
+
+To implement this change efficiently and for more organization, we use the workspace inheritance feature and will add an initial README for each of these newly added libraries.
+
+Later, to streamline our release process, it is crucial to come up with a Github action to automate and simplify the release process.
+
+## **Status**
+
+Proposed
+
+## **Consequences**
+
+We should acknowledge this restructuring, while a significant step forward, will not completely address all existing design couplings. Subsequent improvements in implementation logic will be necessary to completely decouple ibc core, clients, and applications from each other and make the entire logic as chain-agnostic as possible. For an instance, currently, our `IbcEvent` type depends on the Tendermint events in their conversion, which needs to be addressed afterward. There may be other mix-ups as well, but the new repository structure significantly simplifies their handling and ensures `ibc-rs` evolves into a more adaptable, modular, and composable implementation that can serve various use cases.
+
+### **Positive**
+
+- Opens up a range of new use cases for `ibc-rs`
+- Facilitates moving toward more chain-agnostic and flexible design and interfaces
+- Simplifies development on top of each layer of `ibc-rs` implementation
+
+### **Negative**
+
+- Multiple libraries are more challenging to maintain
+- Enforces current users to update a large number of their import paths from `ibc` crates