Merge PR cosmos#290: Doc fixes

ibc/1_IBC_TERMINOLOGY.md

@@ -1,4 +1,4 @@
-# 3: IBC Terminology
+# 1: IBC Terminology
 
 **This is an overview of terms used in IBC specifications.**
 

ibc/2_IBC_ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# 1: Inter-blockchain Communication Protocol Architecture
+# 2: Inter-blockchain Communication Protocol Architecture
 
 **This is an overview of the high-level architecture & data-flow of the IBC protocol.**
 

ibc/3_IBC_DESIGN_PRINCIPLES.md

@@ -1,4 +1,4 @@
-# 2: IBC Design Principles
+# 3: IBC Design Principles
 
 **This is an explanation of the "design principles" of IBC.**
 

spec/ics-002-client-semantics/README.md

@@ -187,14 +187,14 @@ The headers generated from a `Blockchain` are expected to satisfy the following:
 * Satisfied if: correct block generation & state machine
 * Possible violation scenario: invariant break, super-majority validator cartel
 
-If the blockchain does not satisfy any of the above then the IBC protocol
+Unless the blockchain satisfies all of the above the IBC protocol
 may not work as intended: the chain can receive multiple conflicting
 packets, the chain cannot recover from the timeout event, the chain can
 steal the user's asset, etc.
 
 The validity of the validity predicate is dependent on the security model of the
 `Consensus`. For example, the `Consensus` can be a proof of authority with
-a trusted operator, or the a proof of stake but with
+a trusted operator, or a proof of stake but with
 insufficient value of stake. In such cases, it is possible that the
 security assumptions break, the correspondence between `Consensus` and
 the validity predicate no longer exists, and the behaviour of the validity predicate becomes
@@ -520,7 +520,7 @@ Not applicable.
 
 ## Forwards Compatibility
 
-New client types can be added by IBC implementations at-will as long as they confirm to this interface.
+New client types can be added by IBC implementations at-will as long as they conform to this interface.
 
 ## Example Implementation
 

spec/ics-003-connection-semantics/README.md

@@ -275,7 +275,7 @@ function connOpenTry(
     abortTransactionUnless(provableStore.get(connectionPath(desiredIdentifier)) === null)
     identifier = desiredIdentifier
     state = TRYOPEN
-       provableStore.set(connectionPath(identifier), connection)
+    provableStore.set(connectionPath(identifier), connection)
     addConnectionToClient(clientIdentifier, identifier)
 }
 ```

spec/ics-004-channel-and-packet-semantics/README.md

@@ -645,7 +645,7 @@ can no longer be executed and to allow the calling module to safely perform appr
 
 Calling modules MAY atomically execute appropriate application timeout-handling logic in conjunction with calling `timeoutPacket`.
 
-In the case of an ordered channel, `timeoutPacket` checks the recvSequence of the receiving channel end and closes the channel if a packet has timed out.
+In the case of an ordered channel, `timeoutPacket` checks the `recvSequence` of the receiving channel end and closes the channel if a packet has timed out.
 
 In the case of an unordered channel, `timeoutPacket` checks the absence of an acknowledgement (which will have been written if the packet was received). Unordered channels are expected to continue in the face of timed-out packets.
 

spec/ics-005-port-allocation/README.md

@@ -67,7 +67,7 @@ As a helpful comparison, the following analogies to TCP are roughly accurate:
 The host state machine MUST support either object-capability reference or source authentication for modules.
 
 In the former object-capability case, the IBC handler must have the ability to generate *object-capabilities*, unique, opaque references
-which can be passed to a module and will not be duplicable by other modules. Two examples are store keys as used in the Cosmos SDK ([reference](https://github.com/cosmos/cosmos-sdk/blob/master/store/types/store.go#L224))
+which can be passed to a module and will not be duplicable by other modules. Two examples are store keys as used in the Cosmos SDK ([reference](https://github.com/cosmos/cosmos-sdk/blob/97eac176a5d533838333f7212cbbd79beb0754bc/store/types/store.go#L275))
 and object references as used in Agoric's Javascript runtime ([reference](https://github.com/Agoric/SwingSet)).
 
 ```typescript
@@ -98,27 +98,27 @@ function callingModuleIdentifier(): SourceIdentifier {
 
 In the former case, `generate` returns a new object-capability key, which must be returned by the outer-layer function, and `authenticate` requires that the outer-layer function take an extra argument `capability`, which is an object-capability key with uniqueness enforced by the host state machine. Outer-layer functions are any functions exposed by the IBC handler ([ICS 25](../ics-025-handler-interface)) or routing module ([ICS 26](../ics-026-routing-module)) to modules.
 
-```
+```typescript
 function generate(): CapabilityKey {
     return newCapabilityPath()
 }
 ```
 
-```
+```typescript
 function authenticate(key: CapabilityKey): boolean {
     return capability === key
 }
 ```
 
 In the latter case, `generate` returns the calling module's identifier and `authenticate` merely checks it.
 
-```
+```typescript
 function generate(): SourceIdentifier {
     return callingModuleIdentifier()
 }
 ```
 
-```
+```typescript
 function authenticate(id: SourceIdentifier): boolean {
     return callingModuleIdentifier() === id
 }

spec/ics-020-fungible-token-transfer/README.md

@@ -27,7 +27,7 @@ The IBC handler interface & IBC routing module interface are as defined in [ICS
 - Preservation of total supply (constant or inflationary on a single source chain & module).
 - Permissionless token transfers, no need to whitelist connections, modules, or denominations.
 - Symmetric (all chains implement the same logic, no in-protocol differentiation of hubs & zones).
-- Fault containment: prevents Byzantine-inflation of tokens originating on chain `A`, on chain `A`, as a result of chain `B`'s Byzantine behaviour (though any users who sent tokens to chain `B` may be at risk).
+- Fault containment: prevents Byzantine-inflation of tokens originating on chain `A`, as a result of chain `B`'s Byzantine behaviour (though any users who sent tokens to chain `B` may be at risk).
 
 ## Technical Specification
 
@@ -84,7 +84,7 @@ An administrator (with the permissions to create connections & channels on the h
 to other instances of this module (or another module supporting this interface) on other chains. This specification defines packet handling semantics only, and defines them in such a fashion
 that the module itself doesn't need to worry about what connections or channels might or might not exist at any point in time.
 
-#### routing module callbacks
+#### Routing module callbacks
 
 ##### Channel lifecycle management
 

spec/ics-023-vector-commitments/README.md

@@ -43,15 +43,15 @@ A commitment construction MUST specify the following datatypes, which are otherw
 
 #### Commitment State
 
-An `CommitmentState` is the full state of the commitment, which will be stored by the manager.
+A `CommitmentState` is the full state of the commitment, which will be stored by the manager.
 
 ```typescript
 type CommitmentState = object
 ```
 
 #### Commitment Root
 
-An `CommitmentRoot` commits to a particular commitment state and should be constant-size.
+A `CommitmentRoot` commits to a particular commitment state and should be constant-size.
 
 In certain commitment constructions with constant-size states, `CommitmentState` and `CommitmentRoot` may be the same type.
 
@@ -89,7 +89,7 @@ type applyPrefix = (prefix: CommitmentPrefix, path: Path) => CommitmentPath
 
 #### Proof
 
-An `CommitmentProof` demonstrates membership or non-membership for an element or set of elements, verifiable in conjunction with a known commitment root. Proofs should be succinct.
+A `CommitmentProof` demonstrates membership or non-membership for an element or set of elements, verifiable in conjunction with a known commitment root. Proofs should be succinct.
 
 ```typescript
 type CommitmentProof = object

spec/ics-024-host-requirements/README.md

@@ -188,7 +188,7 @@ For a host state machine, the return value of `getCommitmentPrefix` MUST be cons
 
 Host state machines MUST implement a port system, where the IBC handler can allow different modules in the host state machine to bind to uniquely named ports. Ports are identified by an `Identifier`.
 
-Host state machines MUST permission interaction with the IBC handler such that:
+Host state machines MUST implement permission interaction with the IBC handler such that:
 
 - Once a module has bound to a port, no other modules can use that port until the module releases it
 - A single module can bind to multiple ports
@@ -200,7 +200,7 @@ Modules that wish to make use of particular IBC features MAY implement certain h
 
 ### Datagram submission
 
-Host state machines which implement the routing module MAY define a `submitDatagram` function to submit [datagrams](../../docs/ibc/2_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the routing module (defined in [ICS 26](../ics-026-routing-module):
+Host state machines which implement the routing module MAY define a `submitDatagram` function to submit [datagrams](../../ibc/1_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the routing module (defined in [ICS 26](../ics-026-routing-module)):
 
 ```typescript
 type submitDatagram = (datagram: Datagram) => void

spec/ics-026-routing-module/README.md

@@ -477,7 +477,7 @@ interface ChanOpenConfirm {
 
 ```typescript
 function handleChanOpenConfirm(datagram: ChanOpenConfirm) {
-    module = lookupModule(portIdentifier)
+    module = lookupModule(datagram.portIdentifier)
     module.onChanOpenConfirm(
       datagram.portIdentifier,
       datagram.channelIdentifier
@@ -500,7 +500,7 @@ interface ChanCloseInit {
 
 ```typescript
 function handleChanCloseInit(datagram: ChanCloseInit) {
-    module = lookupModule(portIdentifier)
+    module = lookupModule(datagram.portIdentifier)
     module.onChanCloseInit(
       datagram.portIdentifier,
       datagram.channelIdentifier