From 927b869db9a08684e5a9f1b4865fd73376b4f9f6 Mon Sep 17 00:00:00 2001 From: mossid Date: Tue, 13 Mar 2018 17:10:26 +0100 Subject: [PATCH] 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 a47ad6e40..a7f5e8f8e 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 000000000..15406dc1c --- /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 000000000..5049178f8 --- /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 000000000..ede6b1300 --- /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 +} +```