IBC architecture document

.gitattributes

@@ -1 +1,2 @@
 _layouts/* linguist-vendored
+*.pdf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -17,9 +17,9 @@ See [PROCESS.md](PROCESS.md) for a description of the standardization process.
 The subject of most initial interchain standards is the inter-blockchain communication protocol, "IBC".
 
 If you are diving in or planning to review specifications, the following are recommended reading:
-- [IBC Design Philosophy](./docs/ibc/1_IBC_DESIGN_PHILOSOPHY.md)
-- [IBC Terminology](./docs/ibc/2_IBC_TERMINOLOGY.md)
-- [IBC Architecture](./docs/ibc/3_IBC_ARCHITECTURE.md)
+- [IBC Architecture](./docs/ibc/1_IBC_ARCHITECTURE.md)
+- [IBC Design Principles](./docs/ibc/2_IBC_DESIGN_PRINCIPLES.md)
+- [IBC Terminology](./docs/ibc/3_IBC_TERMINOLOGY.md)
 - [IBC specification progress tracking](https://github.com/cosmos/ics/issues/26)
 
 ## Interchain Standards

docs/README.md

@@ -0,0 +1 @@
+You might be looking for the [IBC documentation](./ibc).

docs/ibc/1_IBC_DESIGN_PHILOSOPHY.md → docs/ibc/2_IBC_DESIGN_PRINCIPLES.md

@@ -1,10 +1,10 @@
-# 1: IBC Design Philosophy
+# 2: IBC Design Principles
 
-> This is an explanation of the "design philosophy" of IBC.
+**This is an explanation of the "design principles" of IBC.**
 
-> For definitions of terms used in IBC specifications, see [here](./2_IBC_TERMINOLOGY.md).
+**For an architectural overview, see [here](./1_IBC_ARCHITECTURE.md).**
 
-> For an architectural overview, see [here](./3_IBC_ARCHITECTURE.md).
+**For definitions of terms used in IBC specifications, see [here](./3_IBC_TERMINOLOGY.md).**
 
 The design space of "interblockchain communication protocols" is wide, and the term itself has become a bit too all-encompassing. The "Interblockchain Communication Protocol" (IBC) is a very particular point in that design space, chosen to provide specific versatility, locality, modularity, and efficiency properties for the expected interchain ecosystem of interoperable blockchains. This document outlines the "why" of IBC and enumerates the primary high-level design goals.
 

docs/ibc/2_IBC_TERMINOLOGY.md → docs/ibc/3_IBC_TERMINOLOGY.md

@@ -1,10 +1,10 @@
-# 2: IBC Terminology
+# 3: IBC Terminology
 
-> This is an overview of terms used in IBC specifications.
+**This is an overview of terms used in IBC specifications.**
 
-> For the design rationale behind the protocol, see [here](./1_IBC_DESIGN_RATIONALE.md).
+**For an architectural overview, see [here](./1_IBC_ARCHITECTURE.md).**
 
-> For an architectural overview, see [here](./3_IBC_ARCHITECTURE.md).
+**For a broad set of protocol design principles, see [here](./2_IBC_DESIGN_PRINCIPLES.md).**
 
 This document provides definitions in plain English of key terms used throughout the IBC specification set.
 
@@ -14,9 +14,9 @@ This document provides definitions in plain English of key terms used throughout
 
 An *actor*, or a *user* (used interchangeably), is an entity interacting with the IBC protocol. An actor can be a human end-user, a module or smart contract running on a blockchain, or an off-chain relayer process capable of signing transactions.
 
-### Chain
+### Chain / Ledger
 
-A *chain*, or *ledger* (used interchangeably), is a distributed ledger (or "blockchain", although a strict chain of blocks may not be required) implementing part or all of the IBC specification as a component or module within its state machine.
+A *chain*, *blockchain*, or *ledger* (used interchangeably), is a distributed ledger (or "blockchain", although a strict chain of blocks may not be required) implementing part or all of the IBC specification as a component or module within its state machine.
 
 ### State Machine
 

docs/ibc/README.md

@@ -0,0 +1,9 @@
+# Inter-blockchain Communication Protocol (IBC)
+
+The *inter-blockchain communication protocol* is a reliable & secure inter-module communication protocol, where modules are deterministic processes that run on independent distributed ledgers (also referred to as blockchains). IBC can be used by any application which builds on top of reliable & secure interchain communication. Example applications include cross-chain asset transfer, atomic swaps, multi-chain smart contracts (with or without mutually comprehensible VMs), and data & code sharding of various kinds.
+
+For an overview of the IBC protocol, read the following documents in numerical order.
+
+1. [IBC Architecture](./1_IBC_ARCHITECTURE.md)
+1. [IBC Design Principles](./2_IBC_DESIGN_PRINCIPLES.md)
+1. [IBC Terminology](./3_IBC_TERMINOLOGY.md)