update: minor changes and adding architecture diagram for registratio…

…n flow

spec/app/ics-027-interchain-accounts/README.md

@@ -61,7 +61,9 @@ An unordered channel lets packets be relayed in any order. A user can send 100 p
 Interchain accounts is a perfect use case for partially ordered channels, whereby the order is based on account sequences. However, this has yet to be implemented in IBC. As of the time of writing this specification the current progress can be tracked [here](https://github.com/cosmos/ibc/issues/550). 
 
 ### Architecture Diagram
-**TODO: Diagram with flow for registration + RunTX**
+![](https://i.imgur.com/HX1h2u2.png)
+
+
 
 ### Authentication & Authorization
 The sending chain (the chain registering and controlling an account) will implement it's own authentication and authorization, which will determine who can create an interchain account and what type of transactions the registered accounts can invoke. One example of this may be a cosmos SDK chain that only allows the creation of an interchain account on behalf of the chains distribution module (community pool), whereby actions this interchain account takes are determined by governance proposals voted on by the token holders of the sending chain. Another example may be a smart contract that registers an interchain account and has a specific set of actions it is authorized to take.  
@@ -87,21 +89,21 @@ interface InterchainAccountModule {
 
 
 #### Sending Interface
-The `tryRegisterInterchainAccount` method in the `InterchainAccountModule` interface defines the way to request the creation of an interchain account on a remote chain. The remote chain creates an interchain account using its own account creation logic. Due to the limitation of ordered channels, the recommended way to achieve this when calling `tryRegisterInterchainAccount` is to dynamically bind a new port with the port id set as the address of the owner of the account (if the port is not already bound), invoke `OpenChanInit` via an IBC module which will initiate the handshake process and emit an event signaling to a relayer to generate a new channel between both chains. The remote chain can then create the interchain account in the `chanOpenConfirm` callback as part of the channel creation handshake process defined in [ics-4](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics). Once the `chanOpenAck` callback fires the handshake-originating (sending) chain can assume the account registration is succesful.  
+The `tryRegisterInterchainAccount` method in the `InterchainAccountModule` interface defines the way to request the creation of an interchain account on a remote chain. The remote chain creates an interchain account using its own account creation logic. Due to the limitation of ordered channels, the recommended way to achieve this when calling `tryRegisterInterchainAccount` is to dynamically bind a new port with the port id set as the address of the owner of the account (if the port is not already bound), invoke `OpenChanInit` via an IBC module which will initiate the handshake process and emit an event signaling to a relayer to generate a new channel between both chains. The remote chain can then create the interchain account in the `ChanOpenTry` callback as part of the channel creation handshake process defined in [ics-4](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics). Once the `chanOpenAck` callback fires the handshake-originating (sending) chain can assume the account registration is succesful.  
 
 
 The `tryRunTx` method in the`InterchainAccountModule` interface defines the way to create an outgoing packet for a specific chain type. The chain type determines how the IBC account transaction should be constructed and serialised for the recieving chain. The sending side should know in advance how the recieving side expects the incoming IBC packet to be structured. 
 
 #### Recieving Interfacce
 
-`createAccount` defines the way to determine the account's address by using the port & channel id. A newly created interchain account must not conflict with an existing account. Therefore, the host chain (the chain that the account will live on) must keep track of which blockchains have created an interchain account in order to verify the transaction signing authority in `authenticateTx`. `createAccount` should be called in the `chanOpenConfirm` callback as part of the channel creation handshake process defined in [ics-4](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics).
+`createAccount` defines the way to determine the account's address by using the port & channel id. A newly created interchain account must not conflict with an existing account. Therefore, the host chain (the chain that the account will live on) must keep track of which blockchains have created an interchain account in order to verify the transaction signing authority in `authenticateTx`. `createAccount` should be called in the `chanOpenTry` callback as part of the channel creation handshake process defined in [ics-4](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics).
 
 `authenticateTx` validates the transaction and checks that the signers in the transaction have the right permissions (are the owners of the account in question).`
 
 `runTx` executes a transaction after the transaction has been successfully authenticated.
 
 ### Packet Data
-`InterchainAccountPacketData` contains an array of messages that an interchain account can run and a string for passing useful information (**TODO: be more specific here**) to the recieving chain. The example below is defined as a proto encoded message but each chain can encode this differently. This should be clearly defined in the documentation for each chain specific implementation.
+`InterchainAccountPacketData` contains an array of messages that an interchain account can run and a memo string that is sent to the recieving chain. The example below is defined as a proto encoded message but each chain can encode this differently. This should be clearly defined in the documentation for each chain specific implementation.
 
 ```typescript
 message InterchainAccountPacketData  {
@@ -110,7 +112,7 @@ message InterchainAccountPacketData  {
 }
 ```
 
-The acknowledgement packet structure is defined as in [ics4](https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/ibc/core/channel/v1/channel.proto#L134-L147). The result should contain the chain-id and a success message. **TODO: define standardized error messages.**
+The acknowledgement packet structure is defined as in [ics4](https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/ibc/core/channel/v1/channel.proto#L134-L147). The acknowledgement result should contain the chain-id and the address of the targetted interchain account. If an error occurs on the recieving chain the acknowledgement should contain the error message.
 
 ```typescript
 message Acknowledgement {
@@ -159,8 +161,8 @@ Once the `setup` function has been called, channels can be created via the IBC r
 
 An interchain account module will accept new channels from any module on another machine, if and only if:
 
-- The channel being created is ordered.
-- The version string is "ics27-1".
+- The channel being created is ordered
+- The version string is "ics27-1"
 
 ```typescript
 function onChanOpenInit(
@@ -194,7 +196,7 @@ function onChanOpenTry(
   abortTransactionUnless(version === "ics27-1")
   abortTransactionUnless(counterpartyVersion === "ics27-1")
   // create an interchain account 
-  createAccount()
+  createAccount(counterpartyPortIdentifier, counterpartyChannelIdentifier)
 }
 ```
 
@@ -215,7 +217,6 @@ function onChanOpenAck(
 function onChanOpenConfirm(
   portIdentifier: Identifier,
   channelIdentifier: Identifier) {
-  // accept channel confirmations, port has already been validated
 }
 ```
 
@@ -236,8 +237,6 @@ function onChanCloseConfirm(
 ```
 
 ### Packet relay
-**TODO: add description here**
-
 `onRecvPacket` is called by the routing module when a packet addressed to this module has been received.
 
 ```typescript
@@ -255,7 +254,7 @@ function onRecvPacket(packet: Packet) {
       // Return ack with error.
       return Acknowledgement{
         error: e.message,
-      }
+    }
 }
 ```