Move specification.md to README.md, cleanup overview, separate MVP directory

docs/spec/ibc/README.md

@@ -1,7 +1,44 @@
-# Inter Blockchain Communication protocol
+# Cosmos Inter-Blockchain Communication (IBC) Protocol
 
-IBC was defined in the [cosmos whitepaper](https://github.com/cosmos/cosmos/blob/master/WHITEPAPER.md#inter-blockchain-communication-ibc),
-and then in detail in a [specification paper](https://github.com/cosmos/ibc/raw/master/CosmosIBCSpecification.pdf).
+## Abstract
 
-This package builds on that and includes detailed specifications, pseudocode and protocol specification. Please read the [table of contents](specification.md) of the IBC specification.
+This paper specifies the Cosmos Inter-Blockchain Communication (IBC) protocol. The IBC protocol defines a set of semantics for authenticated, strictly-ordered message passing between two blockchains with independent consensus algorithms.  
 
+The protocol requires two blockchains with cheaply verifiable instant finality. The protocol makes no assumptions of block confirmation times or maximum network latency of packet transmissions, and the two consensus algorithms remain completely independent. Each chain maintains a local partial order and inter-chain message sequencing ensures cross-chain linearity. Once the two chains have registered a trust relationship, cryptographically provable packets can be sent between the chains.
+
+Each chain maintains a local partial order and inter-chain message sequencing ensures cross-chain linearity. The core IBC protocol is payload-agnostic. On top of IBC, developers can implement the semantics of a particular application, enabling users to transfer valuable assets between different blockchains while preserving, under particular security assumptions of the underlying blockchains, the contractual guarantees of the asset in question - such as scarcity and fungibility for a currency or global uniqueness for a digital kitty-cat. 
+
+IBC was first outlined in the [Cosmos Whitepaper](https://github.com/cosmos/cosmos/blob/master/WHITEPAPER.md#inter-blockchain-communication-ibc),
+and then later described in more detail by the [IBC specification paper](https://github.com/cosmos/ibc/raw/master/CosmosIBCSpecification.pdf).
+This documentation replaces and supersedes both. It explains the requirements and structure of the protocol and provides sufficient detail for both analysis and implementation, including example pseudocode.
+
+## Contents
+
+1.  **[Overview](overview.md)**
+    1.  Definitions
+    1.  Threat Models
+1.  **[Proofs](proofs.md)**
+    1.  Establishing a Root of Trust
+    1.  Following Block Headers
+1.  **[Messaging Queue](queues.md)**
+    1.  Merkle Proofs for Queues
+    1.  Naming Queues
+    1.  Message Contents
+    1.  Sending a Packet
+    1.  Receipts
+    1.  Relay Process
+1.  **[Optimizations](optimizations.md)**
+    1.  Cleanup
+    1.  Timeout
+    1.  Handling Byzantine Failures
+1.  **[Conclusion](conclusion.md)**
+
+**[Appendix A: Encoding Libraries](appendix.md#appendix-a-encoding-libraries)**
+
+**[Appendix B: IBC Queue Format](appendix.md#appendix-b-ibc-queue-format)**
+
+**[Appendix C: Merkle Proof Format](appendix.md#appendix-c-merkle-proof-formats)**
+
+**[Appendix D: Universal IBC Packets](appendix.md#appendix-d-universal-ibc-packets)**
+
+**[Appendix E: Tendermint Header Proofs](appendix.md#appendix-e-tendermint-header-proofs)**

docs/spec/ibc/appendix.md

@@ -1,6 +1,6 @@
 # Appendices
 
-([Back to table of contents](specification.md#contents))
+([Back to table of contents](README.md#contents))
 
 ## Appendix A: Encoding Libraries
 

docs/spec/ibc/optimizations.md

@@ -1,6 +1,6 @@
 ## 4 Optimizations
 
-([Back to table of contents](specification.md#contents))
+([Back to table of contents](README.md#contents))
 
 The above sections describe a secure messaging protocol that can handle all normal situations between two blockchains. It guarantees that all messages are processed exactly once and in order, and provides a mechanism for non-blocking atomic transactions spanning two blockchains. However, to increase efficiency over millions of messages with many possible failure modes on both sides of the connection, we can extend the protocol. These extensions allow us to clean up the receipt queue to avoid state bloat, as well as more gracefully recover from cases where large numbers of messages are not being relayed, or other failure modes in the remote chain.
 

docs/spec/ibc/overview.md

@@ -1,6 +1,6 @@
 ## 1 Overview
 
-([Back to table of contents](specification.md#contents))
+([Back to table of contents](README.md#contents))
 
 The IBC protocol creates a mechanism by which multiple sovereign replicated fault tolerant state machines my pass messages to each other. These messages provide a base layer for the creation of communicating blockchain architecture that overcomes challenges in the scalability and extensibility of computing blockchain environments.
 

docs/spec/ibc/proofs.md

@@ -1,6 +1,6 @@
 ## 2 Proofs
 
-([Back to table of contents](specification.md#contents))
+([Back to table of contents](README.md#contents))
 
 The basis of IBC is the ability to perform efficient proofs of a message packet on-chain and deterministically. All transactions must be attributable and provable without depending on any information outside of the blockchain. We define the following variables: _H<sub>h</sub>_ is the signed header at height _h_, _C<sub>h</sub>_ are the consensus rules at height _h_, and _P_ is the unbonding period of this blockchain. _V<sub>k,h</sub>_ is the value stored under key _k_ at height _h_. Note that of all these, only _H<sub>h</sub>_ defines a signature and is thus attributable.
 

docs/spec/ibc/queues.md

@@ -1,6 +1,6 @@
 ## 3 Messaging Queue
 
-([Back to table of contents](specification.md#contents))
+([Back to table of contents](README.md#contents))
 
 Messaging in distributed systems is a deeply researched field and a primitive upon which many other systems are built. We can model asynchronous message passing, and make no timing assumptions on the communication channels. By doing this, we allow each zone to move at its own speed, unblocked by any other zone, but able to communicate as fast as the network allows at that moment.
 

docs/spec/ibc/specification.md

@@ -1,48 +0,0 @@
-# IBC Protocol Specification
-
-_v0.4.0 / Feb. 13, 2018_
-
-**Ethan Frey**
-
-## Abstract
-
-This paper specifies the IBC (inter blockchain communication) protocol, which was first described in the Cosmos white paper [[1](./footnotes.md#1)] in June 2016. The IBC protocol uses authenticated message passing to simultaneously solve two problems: transferring value (and state) between two distinct chains, as well as sharding one chain securely. IBC follows the message-passing paradigm and assumes the participating chains are independent.
-
-Each chain maintains a local partial order, while inter-chain messages track any cross-chain causality relations. Once two chains have registered a trust relationship, cryptographically provable packets can be securely sent between the chains, using Tendermint's instant finality for quick and efficient transmission.
-
-We currently use this protocol for secure value transfer in the Cosmos Hub, but the protocol can support arbitrary application logic. Details of how Cosmos Hub uses IBC to securely route and transfer value ar
-e provided in a separate paper, along with a framework for expressing global invariants. Designing secure communication logic for other types of applications is still an area of research.
-
-The protocol makes no assumptions of block times or network delays in the transmission of the packets between chains and requires cryptographic proofs for every message, and thus is highly robust in a heterogeneous environment with Byzantine actors. This paper explains the requirements and structure of the Cosmos IBC protocol. It aims to provide enough detail to fully understand and analyze the security of the protocol.
-
-## Contents
-
-1.  **[Overview](overview.md)**
-    1.  Definitions
-    1.  Threat Models
-1.  **[Proofs](proofs.md)**
-    1.  Establishing a Root of Trust
-    1.  Following Block Headers
-1.  **[Messaging Queue](queues.md)**
-    1.  Merkle Proofs for Queues
-    1.  Naming Queues
-    1.  Message Contents
-    1.  Sending a Packet
-    1.  Receipts
-    1.  Relay Process
-1.  **[Optimizations](optimizations.md)**
-    1.  Cleanup
-    1.  Timeout
-    1.  Handling Byzantine Failures
-1.  **[Conclusion](conclusion.md)**
-
-**[Appendix A: Encoding Libraries](appendix.md#appendix-a-encoding-libraries)**
-
-**[Appendix B: IBC Queue Format](appendix.md#appendix-b-ibc-queue-format)**
-
-**[Appendix C: Merkle Proof Format](appendix.md#appendix-c-merkle-proof-formats)**
-
-**[Appendix D: Universal IBC Packets](appendix.md#appendix-d-universal-ibc-packets)**
-
-**[Appendix E: Tendermint Header Proofs](appendix.md#appendix-e-tendermint-header-proofs)**
-