From af01c3188308534686f91fad743b55fead02d0f9 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Fri, 20 Sep 2019 12:44:38 +0200 Subject: [PATCH] Rename ICS 26 (closes #274) --- README.md | 2 +- ibc/1_IBC_TERMINOLOGY.md | 6 +-- ibc/5_IBC_DESIGN_PATTERNS.md | 12 +++--- misc/aspell_dict | 2 +- spec.pdc | 4 +- spec.pdf | Bin 132 -> 132 bytes .../README.md | 2 +- spec/ics-005-port-allocation/README.md | 4 +- .../ics-020-fungible-token-transfer/README.md | 18 ++++----- spec/ics-024-host-requirements/README.md | 10 ++--- spec/ics-025-handler-interface/README.md | 6 +-- .../Makefile | 0 .../README.md | 38 +++++++++--------- .../datagrams.proto | 0 14 files changed, 52 insertions(+), 52 deletions(-) rename spec/{ics-026-relayer-module => ics-026-routing-module}/Makefile (100%) rename spec/{ics-026-relayer-module => ics-026-routing-module}/README.md (93%) rename spec/{ics-026-relayer-module => ics-026-routing-module}/datagrams.proto (100%) diff --git a/README.md b/README.md index da3d665ede9f..b57851ec3198 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ All standards at or past the "Draft" stage are listed here in order of their ICS | [23](spec/ics-023-vector-commitments) | Vector Commitments | Draft | | [24](spec/ics-024-host-requirements) | Host Requirements | Draft | | [25](spec/ics-025-handler-interface) | Handler Interface | Draft | -| [26](spec/ics-026-relayer-module) | Relayer Module | Draft | +| [26](spec/ics-026-routing-module) | Routing Module | Draft | ### IBC/APP diff --git a/ibc/1_IBC_TERMINOLOGY.md b/ibc/1_IBC_TERMINOLOGY.md index fdd0b8f523b5..d4e99d2e3372 100644 --- a/ibc/1_IBC_TERMINOLOGY.md +++ b/ibc/1_IBC_TERMINOLOGY.md @@ -54,13 +54,13 @@ A *commitment proof* is the proof structure which proves whether a particular ke The IBC *handler module* is the module within the state machine which implements [ICS 25](../spec/ics-025-handler-module), managing clients, connections, & channels, verifying proofs, and storing appropriate commitments for packets. -### Relayer Module +### Routing Module -The IBC *relayer module* is the module within the state machine which implements [ICS 26](../spec/ics-026-relayer-module), routing packets between the handler module and other modules on the host state machine which utilise the relayer module's external interface. +The IBC *routing module* is the module within the state machine which implements [ICS 26](../spec/ics-026-routing-module), routing packets between the handler module and other modules on the host state machine which utilise the routing module's external interface. ### Datagram -A *datagram* is an opaque bytestring transmitted over some physical network, and handled by the IBC relayer module implemented in the ledger's state machine. In some implementations, the datagram may be a field in a ledger-specific transaction or message data structure which also contains other information (e.g. a fee for spam prevention, nonce for replay prevention, type identifier to route to the IBC handler, etc.). All IBC sub-protocols (such as opening a connection, creating a channel, sending a packet) are defined in terms of sets of datagrams and protocols for handling them through the relayer module. +A *datagram* is an opaque bytestring transmitted over some physical network, and handled by the IBC routing module implemented in the ledger's state machine. In some implementations, the datagram may be a field in a ledger-specific transaction or message data structure which also contains other information (e.g. a fee for spam prevention, nonce for replay prevention, type identifier to route to the IBC handler, etc.). All IBC sub-protocols (such as opening a connection, creating a channel, sending a packet) are defined in terms of sets of datagrams and protocols for handling them through the routing module. ### Connection diff --git a/ibc/5_IBC_DESIGN_PATTERNS.md b/ibc/5_IBC_DESIGN_PATTERNS.md index 1104a30b5de6..ef10a7ef0fff 100644 --- a/ibc/5_IBC_DESIGN_PATTERNS.md +++ b/ibc/5_IBC_DESIGN_PATTERNS.md @@ -61,18 +61,18 @@ It also has one notable disadvantage: relayer processes will need to track the state of multiple modules to determine when packets can be submitted. -For this reason, there is an additional IBC "relayer module" which exposes a call dispatch interface. +For this reason, there is an additional IBC "routing module" which exposes a call dispatch interface. ## Call dispatch -For common relay patterns, an "IBC relayer module" can be implemented which maintains a module dispatch table and simplifies the job of relayers. +For common relay patterns, an "IBC routing module" can be implemented which maintains a module dispatch table and simplifies the job of relayers. In the call dispatch pattern, datagrams (contained within transaction types defined by the host state machine) are relayed directly -to the relayer module, which then looks up the appropriate module (owning the channel & port to which the datagram was addressed) -and calls an appropriate function (which must have been previously registered with the relayer module). This allows modules to +to the routing module, which then looks up the appropriate module (owning the channel & port to which the datagram was addressed) +and calls an appropriate function (which must have been previously registered with the routing module). This allows modules to avoid handling datagrams directly, and makes it harder to accidentally screw-up the atomic state transition execution which must happen in conjunction with sending or receiving a packet (since the module never handles packets directly, but rather exposes -functions which are called by the relayer module upon receipt of a valid packet). +functions which are called by the routing module upon receipt of a valid packet). -Additionally, the relayer module can implement default logic for handshake datagram handling (accepting incoming handshakes +Additionally, the routing module can implement default logic for handshake datagram handling (accepting incoming handshakes on behalf of modules), which is convenient for modules which do not need to implement their own custom logic. diff --git a/misc/aspell_dict b/misc/aspell_dict index 734854b7bc25..a5ae9dee1ef0 100644 --- a/misc/aspell_dict +++ b/misc/aspell_dict @@ -127,7 +127,6 @@ runtime connOpenConfirm mempools whitelist -relayerModule Ojha updateConsensusState consensusStateKey @@ -258,6 +257,7 @@ Sig portKey computable TCP +routingModule counterpartyVersion portPath createClient diff --git a/spec.pdc b/spec.pdc index c1099cf4136c..845de72f46a6 100644 --- a/spec.pdc +++ b/spec.pdc @@ -85,9 +85,9 @@ header-includes: !include spec/ics-025-handler-interface/README.md.xfm -# ICS 026 - Relayer Module +# ICS 026 - Routing Module -!include spec/ics-026-relayer-module/README.md.xfm +!include spec/ics-026-routing-module/README.md.xfm # ICS 018 - Relayer Algorithms diff --git a/spec.pdf b/spec.pdf index 822982c95bce249f16595c02962ea85adf3fd4aa..49b27596c4d261653da6ae282698805a459bb141 100644 GIT binary patch delta 85 zcmV~$xe4zFaWA!r?Z fu`5uEjI|nPMec?)BdWRRfClBc-#BTCAW8WFEm0Tx delta 85 zcmV~$yA6Oa3 | IBC Relayer Module | | IBC Handler Module | | +| | Module Aardvark | <--> | IBC Routing Module | | IBC Handler Module | | | +-------------------+ | | | | | | | Implements ICS 26. | | Implements ICS 2, 3, | | | | | | 4, 5 internally. | | @@ -199,13 +199,13 @@ Modules that wish to make use of particular IBC features MAY implement certain h ### Datagram submission -Host state machines which implement the relayer module MAY define a `submitDatagram` function to submit [datagrams](../../docs/ibc/2_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the relayer module (defined in [ICS 26](../ics-026-relayer-module): +Host state machines which implement the routing module MAY define a `submitDatagram` function to submit [datagrams](../../docs/ibc/2_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the routing module (defined in [ICS 26](../ics-026-routing-module): ```typescript type submitDatagram = (datagram: Datagram) => void ``` -`submitDatagram` allows relayer processes to submit IBC datagrams directly to the relayer module on the host state machine. Host state machines MAY require that the relayer process submitting the datagram has an account to pay transaction fees, signs over the datagram in a larger transaction structure, etc — `submitDatagram` MUST define & construct any such packaging required. +`submitDatagram` allows relayer processes to submit IBC datagrams directly to the routing module on the host state machine. Host state machines MAY require that the relayer process submitting the datagram has an account to pay transaction fees, signs over the datagram in a larger transaction structure, etc — `submitDatagram` MUST define & construct any such packaging required. ### Exception system diff --git a/spec/ics-025-handler-interface/README.md b/spec/ics-025-handler-interface/README.md index 343813bec1f7..285272954a76 100644 --- a/spec/ics-025-handler-interface/README.md +++ b/spec/ics-025-handler-interface/README.md @@ -41,7 +41,7 @@ The handler interface exposes `createClient`, `updateClient`, `queryClientConsen The handler interface exposes `connOpenInit`, `connOpenTry`, `connOpenAck`, `connOpenConfirm`, and `queryConnection`, as defined in [ICS 3](../ics-003-connection-semantics). -The default IBC relayer module SHALL allow external calls to `connOpenTry`, `connOpenAck`, and `connOpenConfirm`. +The default IBC routing module SHALL allow external calls to `connOpenTry`, `connOpenAck`, and `connOpenConfirm`. ### Channel lifecycle management @@ -49,7 +49,7 @@ By default, channels are owned by the creating port, meaning only the module bou The handler interface exposes `chanOpenInit`, `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, `chanCloseInit`, `chanCloseConfirm`, and `queryChannel`, as defined in [ICS 4](../ics-004-channel-and-packet-semantics). -The default IBC relayer module SHALL allow external calls to `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, and `chanCloseConfirm`. +The default IBC routing module SHALL allow external calls to `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, and `chanCloseConfirm`. ### Packet relay @@ -57,7 +57,7 @@ Packets are permissioned by channel (only a port which owns a channel can send o The handler interface exposes `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, `timeoutOnClose`, and `cleanupPacket` as defined in [ICS 4](../ics-004-channel-and-packet-semantics). -The default IBC relayer module SHALL allow external calls to `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, `timeoutOnClose`, and `cleanupPacket`. +The default IBC routing module SHALL allow external calls to `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, `timeoutOnClose`, and `cleanupPacket`. ### Properties & Invariants diff --git a/spec/ics-026-relayer-module/Makefile b/spec/ics-026-routing-module/Makefile similarity index 100% rename from spec/ics-026-relayer-module/Makefile rename to spec/ics-026-routing-module/Makefile diff --git a/spec/ics-026-relayer-module/README.md b/spec/ics-026-routing-module/README.md similarity index 93% rename from spec/ics-026-relayer-module/README.md rename to spec/ics-026-routing-module/README.md index 1e7704f84c63..d4b66685f547 100644 --- a/spec/ics-026-relayer-module/README.md +++ b/spec/ics-026-routing-module/README.md @@ -1,6 +1,6 @@ --- ics: 26 -title: Relayer Module +title: Routing Module stage: Draft category: IBC/TAO author: Christopher Goes @@ -10,15 +10,15 @@ modified: 2019-08-25 ## 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 keeps 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. +The routing 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 routing module keeps 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 routing module. ### Motivation The default IBC handler uses a receiver call pattern, where modules must individually call the IBC handler in order to bind to ports, 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. +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 "routing module" to automate most common functionality, route packets, and simplify the task of relayers. -The relayer module can also play the role of the module manager as discussed in [ICS 5](../ics-005-port-allocation) and implement +The routing module can also play the role of the module manager as discussed in [ICS 5](../ics-005-port-allocation) and implement logic to determine when modules are allowed to bind to ports and what those ports can be named. ### Definitions @@ -29,9 +29,9 @@ The functions `generate` & `authenticate` are defined as in [ICS 5](../ics-005-p ### Desired Properties -- Modules should be able to bind to ports and own channels through the relayer module. +- Modules should be able to bind to ports and own channels through the routing module. - No overhead should be added for packet sends and receives other than the layer of call indirection. -- The relayer module should call specified handler functions on modules when they need to act upon packets. +- The routing module should call specified handler functions on modules when they need to act upon packets. ## Technical Specification @@ -39,7 +39,7 @@ The functions `generate` & `authenticate` are defined as in [ICS 5](../ics-005-p ### Module callback interface -Modules must expose the following function signatures to the relayer module, which are called upon the receipt of various datagrams: +Modules must expose the following function signatures to the routing module, which are called upon the receipt of various datagrams: ```typescript function onChanOpenInit( @@ -143,17 +143,17 @@ function authenticationPath(portIdentifier: Identifier): Path { ### Port binding as module manager -The IBC relayer module sits in-between the handler module ([ICS 25](../ics-025-handler-interface)) and individual modules on the host state machine. +The IBC routing module sits in-between the handler module ([ICS 25](../ics-025-handler-interface)) and individual modules on the host state machine. -The relayer module, acting as a module manager, differentiates between two kinds of ports: +The routing module, acting as a module manager, differentiates between two kinds of ports: - "Existing name” ports: e.g. “bank”, with standardised prior meanings, which should not be first-come-first-serve - “Fresh name” ports: new identity (perhaps a smart contract) w/no prior relationships, new random number port, post-generation port name can be communicated over another channel -A set of existing names are allocated, along with corresponding modules, when the relayer module is instantiated by the host state machine. -The relayer module then allows allocation of fresh ports at any time by modules, but they must use a specific standardised prefix. +A set of existing names are allocated, along with corresponding modules, when the routing module is instantiated by the host state machine. +The routing module then allows allocation of fresh ports at any time by modules, but they must use a specific standardised prefix. -The function `bindPort` can be called by a module in order to bind to a port, through the relayer module, and set up callbacks. +The function `bindPort` can be called by a module in order to bind to a port, through the routing module, and set up callbacks. ```typescript function bindPort( @@ -191,7 +191,7 @@ function releasePort(id: Identifier) { } ``` -The function `lookupModule` can be used by the relayer module to lookup the callbacks bound to a particular port. +The function `lookupModule` can be used by the routing module to lookup the callbacks bound to a particular port. ```typescript function lookupModule(portId: Identifier) { @@ -201,10 +201,10 @@ function lookupModule(portId: Identifier) { ### Datagram handlers (write) -*Datagrams* are external data blobs accepted as transactions by the relayer module. This section defines a *handler function* for each datagram, -which is executed when the associated datagram is submitted to the relayer module in a transaction. +*Datagrams* are external data blobs accepted as transactions by the routing module. This section defines a *handler function* for each datagram, +which is executed when the associated datagram is submitted to the routing module in a transaction. -All datagrams can also be safely submitted by other modules to the relayer module. +All datagrams can also be safely submitted by other modules to the routing module. No message signatures or data validity checks are assumed beyond those which are explicitly indicated. @@ -663,7 +663,7 @@ See [ICS 20](../ics-020-fungible-token-transfer) for a usage example. ### Properties & Invariants -- Proxy port binding is first-come-first-serve: once a module binds to a port through the IBC relayer module, only that module can utilise that port until the module releases it. +- Proxy port binding is first-come-first-serve: once a module binds to a port through the IBC routing module, only that module can utilise that port until the module releases it. ## Backwards Compatibility @@ -671,7 +671,7 @@ Not applicable. ## Forwards Compatibility -Relayer modules are closely tied to the IBC handler interface. +routing modules are closely tied to the IBC handler interface. ## Example Implementation diff --git a/spec/ics-026-relayer-module/datagrams.proto b/spec/ics-026-routing-module/datagrams.proto similarity index 100% rename from spec/ics-026-relayer-module/datagrams.proto rename to spec/ics-026-routing-module/datagrams.proto