diff --git a/README.md b/README.md index a9f1dc8a068a..7f0a9f0c258d 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ All standards in the "draft" stage are listed here in order of their ICS numbers | [18](spec/ics-018-relayer-algorithms) | Relayer Algorithms | Draft | | [23](spec/ics-023-vector-commitments) | Vector Commitments | Draft | | [24](spec/ics-024-host-requirements) | Host Requirements | Draft | +| [26](spec/ics-026-relayer-module) | Relayer Module | Draft | ## Standard Dependency Visualization diff --git a/deps.png b/deps.png index 758724e748e4..ad29abe4c231 100644 --- a/deps.png +++ b/deps.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:6ea263078c31fb780f202e005e84bc57943e7d0742a0f910c8a18b26c5b7a5a8 -size 42633 +oid sha256:0ae6d783a726ce480749ff90e43e201fbb39e169a3e532a6ec836451e00926d5 +size 28176 diff --git a/ibc/5_IBC_DESIGN_PATTERNS.md b/ibc/5_IBC_DESIGN_PATTERNS.md index 1f812c1c6a45..339d03cbaabc 100644 --- a/ibc/5_IBC_DESIGN_PATTERNS.md +++ b/ibc/5_IBC_DESIGN_PATTERNS.md @@ -60,4 +60,4 @@ It also has one notable disadvantage: can be submitted. However, for common relay patterns, an "IBC relayer" module can optionally be implemented, outside of IBC -core, which maintains a module dispatch table and simplifies the job of relayers. This relayer module will be defined in ICS 26. +core, which maintains a module dispatch table and simplifies the job of relayers. This relayer module will be defined in [ICS 26](../spec/ics-026-relayer-module). diff --git a/spec/ics-003-connection-semantics/README.md b/spec/ics-003-connection-semantics/README.md index 80aa2bdcd796..1fa23715bd30 100644 --- a/spec/ics-003-connection-semantics/README.md +++ b/spec/ics-003-connection-semantics/README.md @@ -88,7 +88,7 @@ interface Connection { ### Subprotocols -This ICS defines two subprotocols: opening handshake and closing handshake. Header tracking and closing-by-equivocation are defined in [ICS 2](../ics-002-consensus-verification). Datagrams defined herein are handled as external messages by the IBC relayer module defined in ICS 26. +This ICS defines two subprotocols: opening handshake and closing handshake. Header tracking and closing-by-equivocation are defined in [ICS 2](../ics-002-consensus-verification). Datagrams defined herein are handled as external messages by the IBC relayer module defined in [ICS 26](../ics-026-relayer-module). ![State Machine Diagram](state.png) @@ -115,16 +115,6 @@ This subprotocol need not be permissioned, modulo anti-spam measures. *ConnOpenInit* initializes a connection attempt on chain A. -```typescript -interface ConnOpenInit { - identifier: Identifier - desiredCounterpartyIdentifier: Identifier - clientIdentifier: Identifier - counterpartyClientIdentifier: Identifier - nextTimeoutHeight: uint64 -} -``` - ```typescript function connOpenInit( identifier: Identifier, desiredCounterpartyIdentifier: Identifier, @@ -139,18 +129,6 @@ function connOpenInit( *ConnOpenTry* relays notice of a connection attempt on chain A to chain B. -```typescript -interface ConnOpenTry { - desiredIdentifier: Identifier - counterpartyIdentifier: Identifier - counterpartyClientIdentifier: Identifier - clientIdentifier: Identifier - proofInit: CommitmentProof - timeoutHeight: uint64 - nextTimeoutHeight: uint64 -} -``` - ```typescript function connOpenTry( desiredIdentifier: Identifier, counterpartyIdentifier: Identifier, @@ -174,15 +152,6 @@ function connOpenTry( *ConnOpenAck* relays acceptance of a connection open attempt from chain B back to chain A. -```typescript -interface ConnOpenAck { - identifier: Identifier - proofTry: CommitmentProof - timeoutHeight: uint64 - nextTimeoutHeight: uint64 -} -``` - ```typescript function connOpenAck( identifier: Identifier, proofTry: CommitmentProof, @@ -205,14 +174,6 @@ function connOpenAck( *ConnOpenConfirm* confirms opening of a connection on chain A to chain B, after which the connection is open on both chains. -```typescript -interface ConnOpenConfirm { - identifier: Identifier - proofAck: CommitmentProof - timeoutHeight: uint64 -} -``` - ```typescript function connOpenConfirm(identifier: Identifier, proofAck: CommitmentProof, timeoutHeight: uint64) assert(getConsensusState().getHeight() <= timeoutHeight) @@ -229,14 +190,6 @@ function connOpenConfirm(identifier: Identifier, proofAck: CommitmentProof, time *ConnOpenTimeout* aborts a connection opening attempt due to a timeout on the other side. -```typescript -interface ConnOpenTimeout { - identifier: Identifier - proofTimeout: CommitmentProof - timeoutHeight: uint64 -} -``` - ```typescript function connOpenTimeout(identifier: Identifier, proofTimeout: CommitmentProof, timeoutHeight: uint64) { connection = get("connections/{identifier}") @@ -295,13 +248,6 @@ A correct protocol execution flows as follows (note that all calls are made thro *ConnCloseInit* initializes a close attempt on chain A. -```typescript -interface ConnCloseInit { - identifier: Identifier - nextTimeoutHeight: uint64 -} -``` - ```typescript function connCloseInit(identifier: Identifier, nextTimeoutHeight: uint64) { connection = get("connections/{identifier}") @@ -314,15 +260,6 @@ function connCloseInit(identifier: Identifier, nextTimeoutHeight: uint64) { *ConnCloseTry* relays the intent to close a connection from chain A to chain B. -```typescript -interface ConnCloseTry { - identifier: Identifier - proofInit: CommitmentProof - timeoutHeight: uint64 - nextTimeoutHeight: uint64 -} -``` - ```typescript function connCloseTry( identifier: Identifier, proofInit: CommitmentProof, @@ -342,14 +279,6 @@ function connCloseTry( *ConnCloseAck* acknowledges a connection closure on chain B. -```typescript -interface ConnCloseAck { - identifier: Identifier - proofTry: CommitmentProof - timeoutHeight: uint64 -} -``` - ```typescript function connCloseAck(identifier: Identifier, proofTry: CommitmentProof, timeoutHeight: uint64) { assert(getConsensusState().getHeight() <= timeoutHeight) @@ -367,14 +296,6 @@ function connCloseAck(identifier: Identifier, proofTry: CommitmentProof, timeout *ConnCloseTimeout* aborts a connection closing attempt due to a timeout on the other side and reopens the connection. -```typescript -interface ConnCloseTimeout { - identifier: Identifier - proofTimeout: CommitmentProof - timeoutHeight: uint64 -} -``` - ```typescript function connCloseTimeout(identifier: Identifier, proofTimeout: CommitmentProof, timeoutHeight: uint64) { connection = get("connections/{identifier}") diff --git a/spec/ics-004-channel-and-packet-semantics/README.md b/spec/ics-004-channel-and-packet-semantics/README.md index a730b92f94dd..06f1ab688714 100644 --- a/spec/ics-004-channel-and-packet-semantics/README.md +++ b/spec/ics-004-channel-and-packet-semantics/README.md @@ -198,16 +198,6 @@ When the opening handshake is complete, the module which initiates the handshake it specifies will own the other end of the created channel on the counterparty chain. Once a channel is created, ownership cannot be changed (although higher-level abstractions could be implemented to provide this). -```typescript -interface ChanOpenInit { - connectionIdentifier: Identifier - channelIdentifier: Identifier - counterpartyChannelIdentifier: Identifier - counterpartyModuleIdentifier: Identifier - nextTimeoutHeight: uint64 -} -``` - ```typescript function chanOpenInit( connectionIdentifier: Identifier, channelIdentifier: Identifier, @@ -226,19 +216,6 @@ function chanOpenInit( The `chanOpenTry` function is called by a module to accept the first step of a chanel opening handshake initiated by a module on another chain. -```typescript -interface ChanOpenTry { - connectionIdentifier: Identifier - channelIdentifier: Identifier - counterpartyChannelIdentifier: Identifier - moduleIdentifier: Identifier - counterpartyModuleIdentifier: Identifier - timeoutHeight: uint64 - nextTimeoutHeight: uint64 - proofInit: CommitmentProof -} -``` - ```typescript function chanOpenTry( connectionIdentifier: Identifier, channelIdentifier: Identifier, counterpartyChannelIdentifier: Identifier, @@ -267,16 +244,6 @@ function chanOpenTry( The `chanOpenAck` is called by the handshake-originating module to acknowledge the acceptance of the initial request by the counterparty module on the other chain. -```typescript -interface ChanOpenAck { - connectionIdentifier: Identifier - channelIdentifier: Identifier - timeoutHeight: uint64 - nextTimeoutHeight: uint64 - proofTry: CommitmentProof -} -``` - ```typescript function chanOpenAck( connectionIdentifier: Identifier, channelIdentifier: Identifier, @@ -304,15 +271,6 @@ function chanOpenAck( The `chanOpenConfirm` function is called by the handshake-accepting module to acknowledge the acknowledgement of the handshake-originating module on the other chain and finish the channel opening handshake. -```typescript -interface ChanOpenConfirm { - connectionIdentifier: Identifier - channelIdentifier: Identifier - timeoutHeight: uint64 - proofAck: CommitmentProof -} -``` - ```typescript function chanOpenConfirm( connectionIdentifier: Identifier, channelIdentifier: Identifier, @@ -340,15 +298,6 @@ function chanOpenConfirm( The `chanOpenTimeout` function is called by either the handshake-originating module or the handshake-confirming module to prove that a timeout has occurred and reset the state. -```typescript -interface ChanOpenTimeout { - connectionIdentifier: Identifier - channelIdentifier: Identifier - timeoutHeight: uint64 - proofTimeout: CommitmentProof -} -``` - ```typescript function chanOpenTimeout( connectionIdentifier: Identifier, channelIdentifier: Identifier, @@ -396,14 +345,6 @@ function chanOpenTimeout( The `chanCloseInit` function is called by either module to initiate the channel-closing handshake. -```typescript -interface ChanCloseInit { - connectionIdentifier: Identifier - channelIdentifier: Identifier - nextTimeoutHeight: uint64 -} -``` - ```typescript function chanCloseInit( connectionIdentifier: Identifier, channelIdentifier: Identifier, nextTimeoutHeight: uint64) { @@ -457,15 +398,6 @@ function chanCloseTry( The `chanCloseAck` function is called by the handshake-originating module to acknowledge the closing acknowledgement and finalize channel closure. -```typescript -interface ChanCloseAck { - connectionIdentifier: Identifier - channelIdentifier: Identifier - timeoutHeight: uint64 - proofTry: CommitmentProof -} -``` - ```typescript function chanCloseAck( connectionIdentifier: Identifier, channelIdentifier: Identifier, @@ -493,15 +425,6 @@ function chanCloseAck( The `chanCloseTimeout` function is called by either the handshake-originating or handshake-accepting module to prove a timeout and reset state. -```typescript -interface ChanCloseTimeout { - connectionIdentifier: Identifier - channelIdentifier: Identifier - timeoutHeight: uint64 - proofTimeout: CommitmentProof -} -``` - ```typescript function chanCloseTimeout( connectionIdentifier: Identifier, channelIdentifier: Identifier, diff --git a/spec/ics-026-relayer-module/README.md b/spec/ics-026-relayer-module/README.md new file mode 100644 index 000000000000..6394816c91b3 --- /dev/null +++ b/spec/ics-026-relayer-module/README.md @@ -0,0 +1,226 @@ +--- +ics: 26 +title: Relayer Module +stage: Draft +category: ibc-core +author: Christopher Goes +created: 2019-06-09 +modified: 2019-06-09 +--- + +## Synopsis + +The relayer module is a default implementation of a secondary module which will accept external datagrams and call into the interblockchain communication protocol handler to deal with handshakes and packet relay. +The relayer module can keep a lookup table of modules, which it can use to look up and call a module when a packet is received, so that external relayers need only ever relay packets to the relayer module. + +### Motivation + +The default IBC handler uses a receiver call pattern, where modules must individually call the IBC handler in order to start handshakes, accept handshakes, send and receive packets, etc. This is flexible and simple (see [Design Patterns](../../ibc/5_IBC_DESIGN_PATTERNS.md)) +but is a bit tricky to understand and may require extra work on the part of relayer processes, who must track the state of many modules. This standard describes an IBC "relayer module" to automate most common functionality, route packets, and simplify the task of relayers. + +### Definitions + +All functions provided by the IBC handler interface are defined as in ICS 25. + +### Desired Properties + +- Modules should be able to own channels through the relayer module. +- No overhead should be added for packet sends and receives other than the layer of call indirection. + +## Technical Specification + +### Datagrams + +*Datagrams* are external data blobs accepted as transactions by the relayer module. + +#### Client lifecycle management + +(todo) + +#### Connection lifecycle management + +```typescript +interface ConnOpenInit { + identifier: Identifier + desiredCounterpartyIdentifier: Identifier + clientIdentifier: Identifier + counterpartyClientIdentifier: Identifier + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ConnOpenTry { + desiredIdentifier: Identifier + counterpartyIdentifier: Identifier + counterpartyClientIdentifier: Identifier + clientIdentifier: Identifier + proofInit: CommitmentProof + timeoutHeight: uint64 + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ConnOpenAck { + identifier: Identifier + proofTry: CommitmentProof + timeoutHeight: uint64 + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ConnOpenConfirm { + identifier: Identifier + proofAck: CommitmentProof + timeoutHeight: uint64 +} +``` + +```typescript +interface ConnOpenTimeout { + identifier: Identifier + proofTimeout: CommitmentProof + timeoutHeight: uint64 +} +``` + +```typescript +interface ConnCloseInit { + identifier: Identifier + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ConnCloseTry { + identifier: Identifier + proofInit: CommitmentProof + timeoutHeight: uint64 + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ConnCloseAck { + identifier: Identifier + proofTry: CommitmentProof + timeoutHeight: uint64 +} +``` + +```typescript +interface ConnCloseTimeout { + identifier: Identifier + proofTimeout: CommitmentProof + timeoutHeight: uint64 +} +``` + +#### Channel lifecycle management + +```typescript +interface ChanOpenInit { + connectionIdentifier: Identifier + channelIdentifier: Identifier + counterpartyChannelIdentifier: Identifier + counterpartyModuleIdentifier: Identifier + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ChanOpenTry { + connectionIdentifier: Identifier + channelIdentifier: Identifier + counterpartyChannelIdentifier: Identifier + moduleIdentifier: Identifier + counterpartyModuleIdentifier: Identifier + timeoutHeight: uint64 + nextTimeoutHeight: uint64 + proofInit: CommitmentProof +} +``` + +```typescript +interface ChanOpenAck { + connectionIdentifier: Identifier + channelIdentifier: Identifier + timeoutHeight: uint64 + nextTimeoutHeight: uint64 + proofTry: CommitmentProof +} +``` + +```typescript +interface ChanOpenConfirm { + connectionIdentifier: Identifier + channelIdentifier: Identifier + timeoutHeight: uint64 + proofAck: CommitmentProof +} +``` + +```typescript +interface ChanOpenTimeout { + connectionIdentifier: Identifier + channelIdentifier: Identifier + timeoutHeight: uint64 + proofTimeout: CommitmentProof +} +``` + +```typescript +interface ChanCloseInit { + connectionIdentifier: Identifier + channelIdentifier: Identifier + nextTimeoutHeight: uint64 +} +``` + +```typescript +interface ChanCloseAck { + connectionIdentifier: Identifier + channelIdentifier: Identifier + timeoutHeight: uint64 + proofTry: CommitmentProof +} +``` + +```typescript +interface ChanCloseTimeout { + connectionIdentifier: Identifier + channelIdentifier: Identifier + timeoutHeight: uint64 + proofTimeout: CommitmentProof +} +``` + +#### Packet relay + +### Subprotocols + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +Relayer modules are closely tied to the IBC handler interface. + +## Example Implementation + +Coming soon. + +## Other Implementations + +Coming soon. + +## History + +June 9 2019 - Draft submitted + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).