diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md
index 15406dc1c..6f94b7e80 100644
--- a/docs/spec/ibc/mvp1.md
+++ b/docs/spec/ibc/mvp1.md
@@ -9,26 +9,32 @@ The initial implementation of IBC will include just enough for simple coin trans
 ### IBC Module
 
 ```golang
-type IBCOutMsg struct {
-    IBCTransfer
+// User facing API
+
+type IBCTransferPacket struct {
+    DestAddr sdk.Address
+    Coins    sdk.Coins
 }
 
-type IBCInMsg struct {
-    IBCTransfer
+type IBCTransferMsg struct {
+    IBCTransferPacket
+    DestChain string
 }
 
-type IBCTransfer struct {
-    Destination sdk.Address
-    Coins       sdk.Coins
+type IBCReceiveMsg struct {
+    IBCTransferPacket
+    SrcChain string
 }
 
+// Internal API
+
 type IBCMapper struct {
     ingressKey sdk.StoreKey // Source Chain ID            => last income msg's sequence
     egressKey  sdk.StoreKey // (Dest chain ID, Msg index) => length / indexed msg
 }
 
 type IngressKey struct {
-    SourceChain string
+    SrcChain string
 }
 
 type EgressKey struct {
diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md
index 5049178f8..3a3fc14ec 100644
--- a/docs/spec/ibc/mvp2.md
+++ b/docs/spec/ibc/mvp2.md
@@ -9,19 +9,34 @@ IBC module will store its own router for handling custom incoming msgs. `IBCPush
 ### IBC Module
 
 ```golang
-type IBCOutMsg struct {
-    IBCTransfer
+// User facing API
+
+type IBCTransferData struct {
+    SrcAddr  sdk.Address
+    DestAddr sdk.Address
+    Coins    sdk.Coins
 }
 
-type IBCInMsg struct {
-    IBCTransfer
+// Implements sdk.Msg
+type IBCTransferMsg struct {
+    IBCTransferData
 }
 
-type IBCTransfer struct {
-    Destination sdk.Address
-    Coins       sdk.Coins
+// Implements sdk.Msg
+type IBCReceiveMsg struct {
+    IBCTransferData    
 }
 
+type IBCPacket struct {
+    Msg       IBCMsg
+    SrcChain  string    
+    DestChain string
+}
+
+// Internal API
+
+func NewHandler(router sdk.Router, ibcm IBCMapper) sdk.Handler
+
 type IBCMapper struct {
     ingressKey sdk.StoreKey // Source Chain ID            => last income msg's sequence
     egressKey  sdk.StoreKey // (Dest chain ID, Msg index) => length / indexed msg
@@ -36,6 +51,8 @@ type EgressKey struct {
     Index       int64
 }
 
+// Used by other modules
+func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, packet IBCTransferPacket)
 ```
 
 `egressKey` stores the outgoing `IBCTransfer`s as a list. Its getter takes an `EgressKey` and returns the length if `egressKey.Index == -1`, an element if `egressKey.Index > 0`.
diff --git a/docs/spec/ibc/mvp3.md b/docs/spec/ibc/mvp3.md
index ede6b1300..774bef43c 100644
--- a/docs/spec/ibc/mvp3.md
+++ b/docs/spec/ibc/mvp3.md
@@ -2,10 +2,79 @@
 
 ## MVP3
 
-`IBCOpen` is added to open the connection between two chains. Also, `IBCUpdate` is added, making it able to prove the header.
+`IBCOpenMsg` is added to open the connection between two chains. Also, `IBCUpdateMsg` is added, making it able to prove the header.
 
 ### IBC Module
 
+```golang
+// User facing API
+
+type IBCTransferData struct {
+    SrcAddr  sdk.Address
+    DestAddr sdk.Address
+    Coins    sdk.Coins
+}
+
+// Implements sdk.Msg
+type IBCTransferMsg struct {
+    IBCTransferData
+}
+
+// Implements sdk.Msg
+type IBCReceiveMsg struct {
+    IBCTransferData    
+}
+
+type IBCPacket struct {
+    Msg       IBCMsg
+    SrcChain  string    
+    DestChain string
+}
+
+type RootOfTrust struct {
+    // 
+}
+
+// Implements sdk.Msg
+type IBCOpenMsg struct {
+    ROT   RootOfTrust
+    Chain string   
+}
+
+// Implements sdk.Msg
+type IBCUpdateMsg struct {
+    Header tm.Header
+    Commit tm.Commit
+}
+
+// Internal API
+
+func NewHandler(router sdk.Router, ibcm IBCMapper) sdk.Handler
+
+type IBCMapper struct {
+    ingressKey sdk.StoreKey // ChannelID              => last income msg's sequence
+    egressKey  sdk.StoreKey // (ChannelID, Msg index) => length / indexed msg
+    headerKey  sdk.StoreKey // ChannelID              => last known header
+}
+
+type IngressKey struct {
+    ChannelID uint64
+}
+
+type EgressKey struct {
+    ChannelID uint64
+    Index     int64
+}
+
+type HeaderKey struct {
+    ChannelID uint64
+}
+
+// Used by other modules
+func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, packet IBCTransferPacket)
+
+```
+
 ```golang
 type IBCOutMsg struct {
   IBCTransfer