From 83ce0ed1f9be757fe69ec2ce9ef370b22fed9ee3 Mon Sep 17 00:00:00 2001 From: Matt Bell Date: Mon, 12 Mar 2018 17:13:37 +0100 Subject: [PATCH 01/12] Added IBC MVP spec --- docs/spec/ibc/ibc.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/spec/ibc/ibc.md diff --git a/docs/spec/ibc/ibc.md b/docs/spec/ibc/ibc.md new file mode 100644 index 0000000000..2d8f0caacb --- /dev/null +++ b/docs/spec/ibc/ibc.md @@ -0,0 +1,36 @@ +# IBC Spec + +*This is a living document and should be edited as the IBC spec and implementation change* + +## MVP1 + +The initial implementation of IBC will include just enough for simple coin transfers between chains, with safety features such as ACK messages being added later. + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer +} + +type IBCInMsg struct { + IBCTransfer +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} +``` + +## Relayer + +**Packets** +- Connect to 2 Tendermint RPC endpoints +- Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time interval, or check after each new block, etc) +- For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain + +## CLI + +- Load relay process +- Execute `IBCOutMsg` From 9be287ced19d7107a80dbe33963799acb52e3158 Mon Sep 17 00:00:00 2001 From: mossid Date: Mon, 12 Mar 2018 17:17:42 +0100 Subject: [PATCH 02/12] add ibc2.md --- docs/spec/ibc/ibc2.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/spec/ibc/ibc2.md diff --git a/docs/spec/ibc/ibc2.md b/docs/spec/ibc/ibc2.md new file mode 100644 index 0000000000..215600e7b1 --- /dev/null +++ b/docs/spec/ibc/ibc2.md @@ -0,0 +1,31 @@ +# IBC Spec + +## MVP2 + +`IBCUpdate` is added, making it able to prove the header. + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer +} + +type IBCInMsg struct { + IBCTransfer + Proof merkle.IAVLProof + FromChainID string + FromChainHeight uint64 +} + +// update sync state of other blockchain +type IBCUpdateMsg struct { + Header tm.Header + Commit tm.Commit +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} +``` From e42aca05ebc4f5e4b35cdea6eee90bdd7f354913 Mon Sep 17 00:00:00 2001 From: Adrian Brink Date: Mon, 12 Mar 2018 17:47:07 +0100 Subject: [PATCH 03/12] Extend IBC specification --- docs/spec/ibc/ibc.md | 66 +++++++++++++++++++++++++++++++++++-------- docs/spec/ibc/ibc2.md | 31 -------------------- 2 files changed, 55 insertions(+), 42 deletions(-) delete mode 100644 docs/spec/ibc/ibc2.md diff --git a/docs/spec/ibc/ibc.md b/docs/spec/ibc/ibc.md index 2d8f0caacb..a47ad6e406 100644 --- a/docs/spec/ibc/ibc.md +++ b/docs/spec/ibc/ibc.md @@ -1,13 +1,25 @@ -# IBC Spec +# IBC Specification -*This is a living document and should be edited as the IBC spec and implementation change* +*This is a living document and should be edited as the IBC spec and +implementation change* -## MVP1 +## Engineering Philosophy -The initial implementation of IBC will include just enough for simple coin transfers between chains, with safety features such as ACK messages being added later. +The goal is to get the simplest implementation working end-to-end first. Once +the simplest and most insecure and most feature-less use-case is implemented +we can start adding features. Let's get to the end-to-end process first though. + + +## MVP One + +The initial implementation of IBC will include just enough for simple coin +transfers between chains, with safety features such as ACK messages being added +later. ### IBC Module +* handles message processing + ```golang type IBCOutMsg struct { IBCTransfer @@ -23,14 +35,46 @@ type IBCTransfer struct { } ``` -## Relayer +### Relayer **Packets** -- Connect to 2 Tendermint RPC endpoints -- Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time interval, or check after each new block, etc) -- For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain +* Connect to 2 Tendermint RPC endpoints +* Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time + interval, or check after each new block, etc) +* For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain -## CLI +### CLI -- Load relay process -- Execute `IBCOutMsg` +* Load relay process +* Execute `IBCOutMsg` + + +## MVP2 + +* `IBCUpdate` is added, making it able to prove the header. + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer +} + +type IBCInMsg struct { + IBCTransfer + Proof merkle.IAVLProof + FromChainID string + FromChainHeight uint64 +} + +// update sync state of other blockchain +type IBCUpdateMsg struct { + Header tm.Header + Commit tm.Commit +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} +``` diff --git a/docs/spec/ibc/ibc2.md b/docs/spec/ibc/ibc2.md deleted file mode 100644 index 215600e7b1..0000000000 --- a/docs/spec/ibc/ibc2.md +++ /dev/null @@ -1,31 +0,0 @@ -# IBC Spec - -## MVP2 - -`IBCUpdate` is added, making it able to prove the header. - -### IBC Module - -```golang -type IBCOutMsg struct { - IBCTransfer -} - -type IBCInMsg struct { - IBCTransfer - Proof merkle.IAVLProof - FromChainID string - FromChainHeight uint64 -} - -// update sync state of other blockchain -type IBCUpdateMsg struct { - Header tm.Header - Commit tm.Commit -} - -type IBCTransfer struct { - Destination sdk.Address - Coins sdk.Coins -} -``` From 927b869db9a08684e5a9f1b4865fd73376b4f9f6 Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 17:10:26 +0100 Subject: [PATCH 04/12] refactor spec structure --- docs/spec/ibc/ibc.md | 79 ++++++------------------------------------- docs/spec/ibc/mvp1.md | 55 ++++++++++++++++++++++++++++++ docs/spec/ibc/mvp2.md | 55 ++++++++++++++++++++++++++++++ docs/spec/ibc/mvp3.md | 32 ++++++++++++++++++ 4 files changed, 152 insertions(+), 69 deletions(-) create mode 100644 docs/spec/ibc/mvp1.md create mode 100644 docs/spec/ibc/mvp2.md create mode 100644 docs/spec/ibc/mvp3.md diff --git a/docs/spec/ibc/ibc.md b/docs/spec/ibc/ibc.md index a47ad6e406..a7f5e8f8e8 100644 --- a/docs/spec/ibc/ibc.md +++ b/docs/spec/ibc/ibc.md @@ -1,80 +1,21 @@ # IBC Specification -*This is a living document and should be edited as the IBC spec and -implementation change* +IBC(Inter-Blockchain Communication) protocol is used by multiple zones on Cosmos. Using IBC, the zones can send coins or arbitrary data to other zones. -## Engineering Philosophy +## MVP Specifications -The goal is to get the simplest implementation working end-to-end first. Once -the simplest and most insecure and most feature-less use-case is implemented -we can start adding features. Let's get to the end-to-end process first though. +### [MVP1](./mvp1.md) +MVP1 will contain the basic functionalities, including packet generation and packet receivement. There will be no security check for incoming packets. -## MVP One +### [MVP2](./mvp2.md) -The initial implementation of IBC will include just enough for simple coin -transfers between chains, with safety features such as ACK messages being added -later. +IBC module will be more modular in MVP2. Indivisual modules can register custom handlers to IBC module. -### IBC Module +### [MVP3](./mvp3.md) -* handles message processing +Light client verification is added to verify the message from the other chain. Registering chains with their ROT(Root Of Trust) is needed. -```golang -type IBCOutMsg struct { - IBCTransfer -} +### [MVP4](./mvp4.md) -type IBCInMsg struct { - IBCTransfer -} - -type IBCTransfer struct { - Destination sdk.Address - Coins sdk.Coins -} -``` - -### Relayer - -**Packets** -* Connect to 2 Tendermint RPC endpoints -* Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time - interval, or check after each new block, etc) -* For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain - -### CLI - -* Load relay process -* Execute `IBCOutMsg` - - -## MVP2 - -* `IBCUpdate` is added, making it able to prove the header. - -### IBC Module - -```golang -type IBCOutMsg struct { - IBCTransfer -} - -type IBCInMsg struct { - IBCTransfer - Proof merkle.IAVLProof - FromChainID string - FromChainHeight uint64 -} - -// update sync state of other blockchain -type IBCUpdateMsg struct { - Header tm.Header - Commit tm.Commit -} - -type IBCTransfer struct { - Destination sdk.Address - Coins sdk.Coins -} -``` +ACK verification and messaging queue is implemented to make it failsafe. Modules will register callback to handle failure when they register handlers. diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md new file mode 100644 index 0000000000..15406dc1c9 --- /dev/null +++ b/docs/spec/ibc/mvp1.md @@ -0,0 +1,55 @@ +# IBC Spec + +*This is a living document and should be edited as the IBC spec and implementation change* + +## MVP1 + +The initial implementation of IBC will include just enough for simple coin transfers between chains, with safety features such as ACK messages being added later. + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer +} + +type IBCInMsg struct { + IBCTransfer +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} + +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 +} + +type EgressKey struct { + DestChain string + Index int64 +} + +``` + +`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`. + +`ingressKey` stores the last income `IBCTransfer`'s sequence. Its getter takes an `IngressKey`. + +## Relayer + +**Packets** +- Connect to 2 Tendermint RPC endpoints +- Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time interval, or check after each new block, etc) +- For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain + +## CLI + +- Load relay process +- Execute `IBCOutMsg` diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md new file mode 100644 index 0000000000..5049178f86 --- /dev/null +++ b/docs/spec/ibc/mvp2.md @@ -0,0 +1,55 @@ +# IBC Spec + +*This is a living document and should be edited as the IBC spec and implementation change* + +## MVP2 + +IBC module will store its own router for handling custom incoming msgs. `IBCPush` and `IBCReceive` are made for inter-module communication + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer +} + +type IBCInMsg struct { + IBCTransfer +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} + +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 +} + +type EgressKey struct { + DestChain string + Index int64 +} + +``` + +`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`. + +`ingressKey` stores the last income `IBCTransfer`'s sequence. Its getter takes an `IngressKey`. + +## Relayer + +**Packets** +- Connect to 2 Tendermint RPC endpoints +- Query for IBC outgoing `IBCOutMsg` queue (can poll on a certain time interval, or check after each new block, etc) +- For any new `IBCOutMsg`, build `IBCInMsg` and post to destination chain + +## CLI + +- Load relay process +- Execute `IBCOutMsg` diff --git a/docs/spec/ibc/mvp3.md b/docs/spec/ibc/mvp3.md new file mode 100644 index 0000000000..ede6b13004 --- /dev/null +++ b/docs/spec/ibc/mvp3.md @@ -0,0 +1,32 @@ +# IBC Spec + +## MVP3 + +`IBCOpen` is added to open the connection between two chains. Also, `IBCUpdate` is added, making it able to prove the header. + +### IBC Module + +```golang +type IBCOutMsg struct { + IBCTransfer + DestChainID string +} + +type IBCInMsg struct { + IBCTransfer + Proof merkle.IAVLProof + SourceChainID string + SourceChainHeight uint64 +} + +// update sync state of other blockchain +type IBCUpdateMsg struct { + Header tm.Header + Commit tm.Commit +} + +type IBCTransfer struct { + Destination sdk.Address + Coins sdk.Coins +} +``` From 8b55006fca2f48888696afff84aab9267dced00a Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 19:05:27 +0100 Subject: [PATCH 05/12] fill mvp1/2/3 --- docs/spec/ibc/mvp1.md | 22 +++++++++----- docs/spec/ibc/mvp2.md | 31 ++++++++++++++----- docs/spec/ibc/mvp3.md | 71 ++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 108 insertions(+), 16 deletions(-) diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md index 15406dc1c9..6f94b7e80b 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 5049178f86..3a3fc14ec8 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 ede6b13004..774bef43cf 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 From a9064c97c3a7e5d472b0e0159e9f24ffd2b77ddb Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 19:08:16 +0100 Subject: [PATCH 06/12] remove leftover in mvp3 --- docs/spec/ibc/mvp3.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/spec/ibc/mvp3.md b/docs/spec/ibc/mvp3.md index 774bef43cf..5b18ab2940 100644 --- a/docs/spec/ibc/mvp3.md +++ b/docs/spec/ibc/mvp3.md @@ -75,27 +75,4 @@ func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, packet IBCTransfe ``` -```golang -type IBCOutMsg struct { - IBCTransfer - DestChainID string -} -type IBCInMsg struct { - IBCTransfer - Proof merkle.IAVLProof - SourceChainID string - SourceChainHeight uint64 -} - -// update sync state of other blockchain -type IBCUpdateMsg struct { - Header tm.Header - Commit tm.Commit -} - -type IBCTransfer struct { - Destination sdk.Address - Coins sdk.Coins -} -``` From 2217aaf54fd9219fb134aac1a1b78d2ae74c3f72 Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 19:39:06 +0100 Subject: [PATCH 07/12] router -> dispatcher, get rid of sdk.Msg --- docs/spec/ibc/mvp1.md | 2 ++ docs/spec/ibc/mvp2.md | 18 +++++++++--------- docs/spec/ibc/mvp3.md | 16 ++++++++-------- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md index 6f94b7e80b..718c9e4a85 100644 --- a/docs/spec/ibc/mvp1.md +++ b/docs/spec/ibc/mvp1.md @@ -16,11 +16,13 @@ type IBCTransferPacket struct { Coins sdk.Coins } +// Implements sdk.Msg type IBCTransferMsg struct { IBCTransferPacket DestChain string } +// Implements sdk.Msg type IBCReceiveMsg struct { IBCTransferPacket SrcChain string diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md index 3a3fc14ec8..860bbdc2f9 100644 --- a/docs/spec/ibc/mvp2.md +++ b/docs/spec/ibc/mvp2.md @@ -4,7 +4,7 @@ ## MVP2 -IBC module will store its own router for handling custom incoming msgs. `IBCPush` and `IBCReceive` are made for inter-module communication +IBC module will store its own router for handling custom incoming msgs. `IBCPush` are made for inter-module communication. `IBCRegisterMsg` adds a handler in the router of the module. ### IBC Module @@ -17,25 +17,25 @@ type IBCTransferData struct { Coins sdk.Coins } -// Implements sdk.Msg -type IBCTransferMsg struct { +// Implements ibc.PacketData +type IBCTransferPacket struct { IBCTransferData } -// Implements sdk.Msg -type IBCReceiveMsg struct { +// Implements ibc.PacketData +type IBCReceivePacket struct { IBCTransferData } -type IBCPacket struct { - Msg IBCMsg +type Packet struct { + Data PacketData SrcChain string DestChain string } // Internal API -func NewHandler(router sdk.Router, ibcm IBCMapper) sdk.Handler +func NewHandler(dispatcher Dispatcher, ibcm IBCMapper) sdk.Handler type IBCMapper struct { ingressKey sdk.StoreKey // Source Chain ID => last income msg's sequence @@ -52,7 +52,7 @@ type EgressKey struct { } // Used by other modules -func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, packet IBCTransferPacket) +func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, data PacketData) ``` `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 5b18ab2940..d53e2c00e3 100644 --- a/docs/spec/ibc/mvp3.md +++ b/docs/spec/ibc/mvp3.md @@ -15,18 +15,18 @@ type IBCTransferData struct { Coins sdk.Coins } -// Implements sdk.Msg -type IBCTransferMsg struct { +// Implements ibc.PacketData +type IBCTransferPacket struct { IBCTransferData } -// Implements sdk.Msg -type IBCReceiveMsg struct { +// Implements ibc.PacketData +type IBCReceivePacket struct { IBCTransferData } -type IBCPacket struct { - Msg IBCMsg +type Packet struct { + Data PacketData SrcChain string DestChain string } @@ -49,7 +49,7 @@ type IBCUpdateMsg struct { // Internal API -func NewHandler(router sdk.Router, ibcm IBCMapper) sdk.Handler +func NewHandler(dispatcher Dispatcher, ibcm IBCMapper) sdk.Handler type IBCMapper struct { ingressKey sdk.StoreKey // ChannelID => last income msg's sequence @@ -71,7 +71,7 @@ type HeaderKey struct { } // Used by other modules -func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, packet IBCTransferPacket) +func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, data PacketData) ``` From 259400cbda6724e32cca486d60cf51e19fb57137 Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 19:47:02 +0100 Subject: [PATCH 08/12] in progress --- docs/spec/ibc/mvp1.md | 4 ++-- docs/spec/ibc/mvp2.md | 29 ++++++++++++----------------- 2 files changed, 14 insertions(+), 19 deletions(-) diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md index 718c9e4a85..cadc745dd5 100644 --- a/docs/spec/ibc/mvp1.md +++ b/docs/spec/ibc/mvp1.md @@ -14,18 +14,18 @@ The initial implementation of IBC will include just enough for simple coin trans type IBCTransferPacket struct { DestAddr sdk.Address Coins sdk.Coins + SrcChain string + DestChain string } // Implements sdk.Msg type IBCTransferMsg struct { IBCTransferPacket - DestChain string } // Implements sdk.Msg type IBCReceiveMsg struct { IBCTransferPacket - SrcChain string } // Internal API diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md index 860bbdc2f9..deee209527 100644 --- a/docs/spec/ibc/mvp2.md +++ b/docs/spec/ibc/mvp2.md @@ -11,28 +11,23 @@ IBC module will store its own router for handling custom incoming msgs. `IBCPush ```golang // User facing API -type IBCTransferData struct { - SrcAddr sdk.Address +type IBCTransferPacket struct { DestAddr sdk.Address Coins sdk.Coins -} - -// Implements ibc.PacketData -type IBCTransferPacket struct { - IBCTransferData -} - -// Implements ibc.PacketData -type IBCReceivePacket struct { - IBCTransferData -} - -type Packet struct { - Data PacketData - SrcChain string + SrcChain string DestChain string } +// Implements sdk.Msg +type IBCTransferMsg struct { + IBCTransferPacket +} + +// Implements sdk.Msg +type IBCReceiveMsg struct { + IBCTransferPacket +} + // Internal API func NewHandler(dispatcher Dispatcher, ibcm IBCMapper) sdk.Handler From ac004be491ca557309e43b679724e23a8cce498e Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 19:55:38 +0100 Subject: [PATCH 09/12] merge storeKeys --- docs/spec/ibc/mvp1.md | 11 ++++++----- docs/spec/ibc/mvp2.md | 13 +++++++------ docs/spec/ibc/mvp3.md | 13 +++++++------ 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/spec/ibc/mvp1.md b/docs/spec/ibc/mvp1.md index cadc745dd5..3cfaf88ce8 100644 --- a/docs/spec/ibc/mvp1.md +++ b/docs/spec/ibc/mvp1.md @@ -11,7 +11,7 @@ The initial implementation of IBC will include just enough for simple coin trans ```golang // User facing API -type IBCTransferPacket struct { +type IBCPacket struct { DestAddr sdk.Address Coins sdk.Coins SrcChain string @@ -20,19 +20,20 @@ type IBCTransferPacket struct { // Implements sdk.Msg type IBCTransferMsg struct { - IBCTransferPacket + IBCPacket } // Implements sdk.Msg type IBCReceiveMsg struct { - IBCTransferPacket + IBCPacket } // 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 + ibcKey sdk.StoreKey // IngressKey / EgressKey => Value + // Ingress: Source Chain ID => last income msg's sequence + // Egress: (Dest chain ID, Msg index) => length / indexed msg } type IngressKey struct { diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md index deee209527..acfd45e22f 100644 --- a/docs/spec/ibc/mvp2.md +++ b/docs/spec/ibc/mvp2.md @@ -11,7 +11,7 @@ IBC module will store its own router for handling custom incoming msgs. `IBCPush ```golang // User facing API -type IBCTransferPacket struct { +type IBCPacket struct { DestAddr sdk.Address Coins sdk.Coins SrcChain string @@ -20,12 +20,12 @@ type IBCTransferPacket struct { // Implements sdk.Msg type IBCTransferMsg struct { - IBCTransferPacket + IBCPacket } // Implements sdk.Msg type IBCReceiveMsg struct { - IBCTransferPacket + IBCPacket } // Internal API @@ -33,12 +33,13 @@ type IBCReceiveMsg struct { func NewHandler(dispatcher Dispatcher, 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 + ibcKey sdk.StoreKey // IngressKey / EgressKey => Value + // Ingress: Source Chain ID => last income msg's sequence + // Egress: (Dest chain ID, Msg index) => length / indexed msg } type IngressKey struct { - SourceChain string + SrcChain string } type EgressKey struct { diff --git a/docs/spec/ibc/mvp3.md b/docs/spec/ibc/mvp3.md index d53e2c00e3..1f12b3bfee 100644 --- a/docs/spec/ibc/mvp3.md +++ b/docs/spec/ibc/mvp3.md @@ -16,13 +16,13 @@ type IBCTransferData struct { } // Implements ibc.PacketData -type IBCTransferPacket struct { - IBCTransferData +type IBCPacket struct { + IBCData } // Implements ibc.PacketData type IBCReceivePacket struct { - IBCTransferData + IBCData } type Packet struct { @@ -52,9 +52,10 @@ type IBCUpdateMsg struct { func NewHandler(dispatcher Dispatcher, 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 + ibcKey sdk.StoreKey // IngressKey / EgressKey / HeaderKey => Value + // ChannelID => last income msg's sequence + // (ChannelID, Msg index) => length / indexed msg + // ChannelID => last known header } type IngressKey struct { From ded9de18cfcd8cc4fe397cfa013dd6f9eab6094f Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 20:22:03 +0100 Subject: [PATCH 10/12] add term description, packetdata abstraction in 2/3 --- docs/spec/ibc/ibc.md | 12 ++++++++- docs/spec/ibc/mvp2.md | 28 +++++++++++++++++---- docs/spec/ibc/mvp3.md | 58 +++++++++++++++++++++++++++++++++---------- 3 files changed, 79 insertions(+), 19 deletions(-) diff --git a/docs/spec/ibc/ibc.md b/docs/spec/ibc/ibc.md index a7f5e8f8e8..42fd7639ae 100644 --- a/docs/spec/ibc/ibc.md +++ b/docs/spec/ibc/ibc.md @@ -2,6 +2,16 @@ IBC(Inter-Blockchain Communication) protocol is used by multiple zones on Cosmos. Using IBC, the zones can send coins or arbitrary data to other zones. +## Terms + +How IBC module treats incoming IBC packets is simillar with how BaseApp treats incoming transactions. Therefore, the components of IBC module have their corresponding pair in BaseApp. + +| BaseApp Terms | IBC Terms | +| ------------- | ---------- | +| Router | Dispatcher | +| Tx | Packet | +| Msg | PacketData | + ## MVP Specifications ### [MVP1](./mvp1.md) @@ -18,4 +28,4 @@ Light client verification is added to verify the message from the other chain. R ### [MVP4](./mvp4.md) -ACK verification and messaging queue is implemented to make it failsafe. Modules will register callback to handle failure when they register handlers. +ACK verification / timeout handler helper functions and messaging queue are implemented to make it failsafe. Callbacks will be registered to the dispatcher to handle failure when they register handlers. diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md index acfd45e22f..a785c30027 100644 --- a/docs/spec/ibc/mvp2.md +++ b/docs/spec/ibc/mvp2.md @@ -11,25 +11,43 @@ IBC module will store its own router for handling custom incoming msgs. `IBCPush ```golang // User facing API -type IBCPacket struct { +type Packet struct { + Data PacketData + SrcChain string + DestChain string +} + +type PacketData interface { + Type() string + ValidateBasic() sdk.Error +} + +type TransferPacketData struct { DestAddr sdk.Address Coins sdk.Coins - SrcChain string - DestChain string } // Implements sdk.Msg type IBCTransferMsg struct { - IBCPacket + Packet } // Implements sdk.Msg type IBCReceiveMsg struct { - IBCPacket + Packet } // Internal API +type rule struct { + r string + f func(sdk.Context, IBCPacket) sdk.Result +} + +type Dispatcher struct { + rules []rule +} + func NewHandler(dispatcher Dispatcher, ibcm IBCMapper) sdk.Handler type IBCMapper struct { diff --git a/docs/spec/ibc/mvp3.md b/docs/spec/ibc/mvp3.md index 1f12b3bfee..87f789bb27 100644 --- a/docs/spec/ibc/mvp3.md +++ b/docs/spec/ibc/mvp3.md @@ -6,29 +6,52 @@ ### IBC Module + +// Implements sdk.Msg +type IBCTransferMsg struct { + Packet +} + +// Implements sdk.Msg +type IBCReceiveMsg struct { + Packet +} + +// Internal API + + + ```golang // User facing API -type IBCTransferData struct { +type Packet struct { + Data PacketData + SrcChain string + DestChain string +} + +type PacketData interface { + Type() string + ValidateBasic() sdk.Error +} + +type TransferPacketData struct { SrcAddr sdk.Address DestAddr sdk.Address Coins sdk.Coins } -// Implements ibc.PacketData -type IBCPacket struct { - IBCData +// Implements sdk.Msg +type IBCTransferMsg struct { + Packet } -// Implements ibc.PacketData -type IBCReceivePacket struct { - IBCData -} - -type Packet struct { - Data PacketData - SrcChain string - DestChain string +// Implements sdk.Msg +type IBCReceiveMsg struct { + Packet + Proof iavl.Proof + FromChainID string + FromChainHeight uint64 } type RootOfTrust struct { @@ -49,6 +72,15 @@ type IBCUpdateMsg struct { // Internal API +type rule struct { + r string + f func(sdk.Context, IBCPacket) sdk.Result +} + +type Dispatcher struct { + rules []rule +} + func NewHandler(dispatcher Dispatcher, ibcm IBCMapper) sdk.Handler type IBCMapper struct { From 5ebdff2e5e002d0b5daf3063fd839621545dd17c Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 20:28:38 +0100 Subject: [PATCH 11/12] packetdata->payload --- docs/spec/ibc/ibc.md | 2 +- docs/spec/ibc/mvp2.md | 8 ++++---- docs/spec/ibc/mvp3.md | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/spec/ibc/ibc.md b/docs/spec/ibc/ibc.md index 42fd7639ae..dedbdc3016 100644 --- a/docs/spec/ibc/ibc.md +++ b/docs/spec/ibc/ibc.md @@ -10,7 +10,7 @@ How IBC module treats incoming IBC packets is simillar with how BaseApp treats i | ------------- | ---------- | | Router | Dispatcher | | Tx | Packet | -| Msg | PacketData | +| Msg | Payload | ## MVP Specifications diff --git a/docs/spec/ibc/mvp2.md b/docs/spec/ibc/mvp2.md index a785c30027..6cada51cc0 100644 --- a/docs/spec/ibc/mvp2.md +++ b/docs/spec/ibc/mvp2.md @@ -12,17 +12,17 @@ IBC module will store its own router for handling custom incoming msgs. `IBCPush // User facing API type Packet struct { - Data PacketData + Data Payload SrcChain string DestChain string } -type PacketData interface { +type Payload interface { Type() string ValidateBasic() sdk.Error } -type TransferPacketData struct { +type TransferPayload struct { DestAddr sdk.Address Coins sdk.Coins } @@ -66,7 +66,7 @@ type EgressKey struct { } // Used by other modules -func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, data PacketData) +func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, payload Payload) ``` `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 87f789bb27..bcbf39a921 100644 --- a/docs/spec/ibc/mvp3.md +++ b/docs/spec/ibc/mvp3.md @@ -25,17 +25,17 @@ type IBCReceiveMsg struct { // User facing API type Packet struct { - Data PacketData + Data Payload SrcChain string DestChain string } -type PacketData interface { +type Payload interface { Type() string ValidateBasic() sdk.Error } -type TransferPacketData struct { +type TransferPayload struct { SrcAddr sdk.Address DestAddr sdk.Address Coins sdk.Coins @@ -104,7 +104,7 @@ type HeaderKey struct { } // Used by other modules -func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, data PacketData) +func (ibcm IBCMapper) PushPacket(ctx sdk.Context, dest string, payload Payload) ``` From 77b2a63156d6dbf6b61177b8a66d12c595ee697c Mon Sep 17 00:00:00 2001 From: Adrian Brink Date: Wed, 14 Mar 2018 13:08:19 +0100 Subject: [PATCH 12/12] IBC Spec --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index b7ce3693bc..c6100edb50 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,8 @@ examples/basecoin/app/data baseapp/data/* docs/_build .DS_Store +coverage.txt +profile.out ### Vagrant ###