Merge PR cosmos#115: Document some design patterns

README.md

@@ -21,6 +21,7 @@ If you are diving in or planning to review specifications, the following are rec
 - [IBC Design Principles](./ibc/2_IBC_DESIGN_PRINCIPLES.md)
 - [IBC Terminology](./ibc/3_IBC_TERMINOLOGY.md)
 - [IBC Usecases](./ibc/4_IBC_USECASES.md)
+- [IBC Design Patterns](./ibc/5_IBC_DESIGN_PATTERNS.md)
 - [IBC specification progress tracking](https://github.com/cosmos/ics/issues/26)
 
 ## Interchain Standards

ibc/1_IBC_ARCHITECTURE.md

@@ -8,6 +8,8 @@
 
 **For a set of example use cases, see [here](./4_IBC_USECASES.md).**
 
+**For a discussion of design patterns, see [here](./5_IBC_DESIGN_PATTERNS.md).**
+
 This document outlines the architecture of the authentication, transport, and ordering layers of the inter-blockchain communication (IBC) protocol stack. This document does not describe specific protocol details — those are contained in individual ICSs.
 
 > Note: *Ledger*, *chain*, and *blockchain* are used interchangeably throughout this document, in accordance with their colloquial usage.
@@ -150,16 +152,16 @@ Consider the path of an IBC packet between two chains — call them *A* and *B*:
 1. On chain *A*
     1. Module (application-specific)
     1. Handler (parts defined in different ICSs)
-    1. Packet (defined in [ICS 5](../../spec/ics-5-packet-semantics))
-    1. Channel (defined in [ICS 4](../../spec/ics-4-channel-semantics))
-    1. Connection (defined in [ICS 3](../../spec/ics-3-connection-semantics))
-    1. Consensus (defined in [ICS 2](../../spec/ics-2-consensus-requirements))
+    1. Packet (defined in [ICS 4](../spec/ics-4-channel-and-packet-semantics))
+    1. Channel (defined in [ICS 4](../spec/ics-4-channel-and-packet-semantics))
+    1. Connection (defined in [ICS 3](../spec/ics-3-connection-semantics))
+    1. Consensus (defined in [ICS 2](../spec/ics-2-consensus-verification))
 2. Off-chain
-    1. Relayer (defined in [ICS 18](../../spec/ics-18-offchain-relayer))
+    1. Relayer (defined in [ICS 18](../../spec/ics-18-relayer-algorithms))
 3. On chain *B*
-    1. Consensus (defined in [ICS 2](../../spec/ics-2-consensus-requirements))
-    1. Connection (defined in [ICS 3](../../spec/ics-3-connection-semantics))
-    1. Channel (defined in [ICS 4](../../spec/ics-4-channel-semantics))
-    1. Packet (defined in [ICS 5](../../spec/ics-5-packet-semantics))
+    1. Consensus (defined in [ICS 2](/../spec/ics-2-consensus-verification))
+    1. Connection (defined in [ICS 3](/../spec/ics-3-connection-semantics))
+    1. Channel (defined in [ICS 4](/../spec/ics-4-channel-and-packet-semantics))
+    1. Packet (defined in [ICS 4](/../spec/ics-4-channel-and-packet-semantics))
     1. Handler (parts defined in different ICSs)
     1. Module (application-specific)

ibc/2_IBC_DESIGN_PRINCIPLES.md

@@ -8,6 +8,8 @@
 
 **For a set of example use cases, see [here](./4_IBC_USECASES.md).**
 
+**For a discussion of design patterns, see [here](./5_IBC_DESIGN_PATTERNS.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.
 
 ## Versatility

ibc/3_IBC_TERMINOLOGY.md

@@ -8,6 +8,8 @@
 
 **For a set of example use cases, see [here](./4_IBC_USECASES.md).**
 
+**For a discussion of design patterns, see [here](./5_IBC_DESIGN_PATTERNS.md).**
+
 This document provides definitions in plain English of key terms used throughout the IBC specification set.
 
 ## Definitions

ibc/4_IBC_USECASES.md

@@ -8,6 +8,8 @@
 
 **For definitions of terms used in IBC specifications, see [here](./3_IBC_TERMINOLOGY.md).**
 
+**For a discussion of design patterns, see [here](./5_IBC_DESIGN_PATTERNS.md).**
+
 This is a far-from-comprehensive list of possible concrete application use-cases for the inter-blockchain communication protocol (IBC), listed here for inspiration & with the intent of providing inspiration and a set of viewpoints from which to evaluate the design of the protocol.
 
 For each use case, we define the requirements of the involved chains, the high-level packet handling logic, the application properties maintained across a combined-state view of the involved chains, and a list of potential involved zones with different comparative advantages or other application features.

ibc/5_IBC_DESIGN_PATTERNS.md

@@ -0,0 +1,63 @@
+# 5: IBC Design Patterns
+
+**This is a discussion of design patterns used throughout the interblockchain communication protocol specification.**
+
+**For an architectural overview, see [here](./1_IBC_ARCHITECTURE.md).**
+
+**For a broad set of protocol design principles, see [here](./2_IBC_DESIGN_PRINCIPLES.md).**
+
+**For definitions of terms used in IBC specifications, see [here](./3_IBC_TERMINOLOGY.md).**
+
+**For a set of example use cases, see [here](./4_IBC_USECASES.md).**
+
+## Verification instead of computation
+
+Computation on distributed ledgers is expensive: any computations performed
+in the IBC handler must be replicated across all full nodes. Therefore, when it
+is possible to merely *verify* a computational result instead of performing the
+computation, the IBC handler should elect to do so and require extra parameters as necessary.
+
+In some cases, there is no cost difference - adding two numbers and checking that two numbers sum to
+a particular value both require one addition, so the IBC handler should elect to do whatever is simpler.
+However, in other cases, performing the computation may be much more expensive. For example, connection
+and channel identifiers must be uniquely generated. This could be implemented by
+the IBC handler hashing the genesis state plus a nonce when a new channel is created, to create
+a pseudorandom identifier - but that requires computing a hash function on-chain, which is expensive.
+Instead, the IBC handler should require that the random identifier generation be performed
+off-chain and merely check that a new channel creation attempt doesn't use a previously
+reserved identifier.
+
+## Call receiver instead of call dispatch
+
+Essential to the functionality of the IBC handler is an interface to other modules
+running on the same ledger, so that it can accept requests to send packets and can
+route incoming packets to modules. This interface should be as minimal as possible
+in order to reduce implementation complexity and requirements imposed on host state machines.
+
+For this reason, the core IBC logic uses a receive-only call pattern that differs
+slightly from the intuitive dataflow. As one might expect, modules call into the IBC handler to create
+connections, channels, and send packets. However, instead of the IBC handler, upon receipt
+of a packet from another chain, selecting and calling into the appropriate module,
+the module itself must call `recvPacket` on the IBC handler (likewise for accepting
+channel creation handshakes). When `recvPacket` is called, the IBC handler will check
+that the calling module is authorized to receive and process the packet (based on included proofs and
+known state of connections / channels), perform appropriate state updates (incrementing
+sequence numbers to prevent replay), and return control to the module or throw on error.
+The IBC handler never calls into modules directly.
+
+Although a bit counterintuitive to reason about at first, this pattern has a few notable advantages:
+- It minimizes requirements of the host state machine, since the IBC handler need not understand how to call
+  into other modules or store any references to them.
+- It avoids the necessity of managing a module lookup table in the handler state.
+- It avoids the necessity of dealing with module return data or failures. If a module does not want to 
+  receive a packet (perhaps having implemented additional authorization on top), it simply never calls
+  `recvPacket`. If the routing logic were implemented in the IBC handler, the handler would need to deal
+  with the failure of the module, which is tricky to interpret.
+
+It also has one notable disadvantage:
+- Without an additional abstraction, the relayer logic becomes more complex, since off-chain
+  relayer processes will need to track the state of multiple modules to determine when packets
+  can be submitted.
+
+However, for common relay patterns, an "IBC relayer" module can optionally be implemented, outside of IBC
+core, which maintains a module dispatch table and simplifies the job of relayers. This relayer module will be defined in ICS 26.

ibc/README.md

@@ -8,3 +8,4 @@ For an overview of the IBC protocol, read the following documents in numerical o
 1. [IBC Design Principles](./2_IBC_DESIGN_PRINCIPLES.md)
 1. [IBC Terminology](./3_IBC_TERMINOLOGY.md)
 1. [IBC Usecases](./4_IBC_USECASES.md)
+1. [IBC Design Patterns](./5_IBC_DESIGN_PATTERNS.md)