From 302ba17ca8bc794e7d50afd9c6236d9c4e8e1230 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Tue, 2 Feb 2021 13:38:16 +0100 Subject: [PATCH] Porting over structure selectively --- .gitattributes | 3 + LICENSE | 204 +++++++++++ archive/README.md | 6 + archive/papers/2020-05/Makefile | 28 ++ archive/papers/2020-05/README.md | 13 + archive/papers/2020-05/aspell_dict | 127 +++++++ archive/papers/2020-05/build/paper.pdf | Bin 0 -> 131 bytes archive/papers/2020-05/src/LICENSE | 21 ++ .../papers/2020-05/src/acknowledgements.md | 5 + archive/papers/2020-05/src/appendix-a.md | 115 ++++++ archive/papers/2020-05/src/appendix-b.md | 205 +++++++++++ archive/papers/2020-05/src/appendix-c.md | 212 +++++++++++ archive/papers/2020-05/src/bibliography.bib | 214 +++++++++++ archive/papers/2020-05/src/bibliography.csl | 339 ++++++++++++++++++ archive/papers/2020-05/src/channels.md | 319 ++++++++++++++++ archive/papers/2020-05/src/clients.md | 191 ++++++++++ archive/papers/2020-05/src/connections.md | 105 ++++++ .../2020-05/src/fungible-token-transfer.md | 85 +++++ .../papers/2020-05/src/host-requirements.md | 79 ++++ archive/papers/2020-05/src/introduction.md | 13 + archive/papers/2020-05/src/metadata.yaml | 22 ++ archive/papers/2020-05/src/paper.md | 63 ++++ archive/papers/2020-05/src/relayers.md | 110 ++++++ archive/papers/2020-05/src/structure.md | 71 ++++ archive/papers/2020-05/src/template.latex | 337 +++++++++++++++++ .../2020-05/src/testing-and-deployment.md | 3 + archive/papers/2020-05/src/usage-patterns.md | 47 +++ archive/v0_3_1_IBC.pdf | Bin 0 -> 131 bytes assets/interchain-standards-image.jpg | 3 + 29 files changed, 2940 insertions(+) create mode 100644 LICENSE create mode 100644 archive/README.md create mode 100644 archive/papers/2020-05/Makefile create mode 100644 archive/papers/2020-05/README.md create mode 100644 archive/papers/2020-05/aspell_dict create mode 100644 archive/papers/2020-05/build/paper.pdf create mode 100644 archive/papers/2020-05/src/LICENSE create mode 100644 archive/papers/2020-05/src/acknowledgements.md create mode 100644 archive/papers/2020-05/src/appendix-a.md create mode 100644 archive/papers/2020-05/src/appendix-b.md create mode 100644 archive/papers/2020-05/src/appendix-c.md create mode 100644 archive/papers/2020-05/src/bibliography.bib create mode 100644 archive/papers/2020-05/src/bibliography.csl create mode 100644 archive/papers/2020-05/src/channels.md create mode 100644 archive/papers/2020-05/src/clients.md create mode 100644 archive/papers/2020-05/src/connections.md create mode 100644 archive/papers/2020-05/src/fungible-token-transfer.md create mode 100644 archive/papers/2020-05/src/host-requirements.md create mode 100644 archive/papers/2020-05/src/introduction.md create mode 100644 archive/papers/2020-05/src/metadata.yaml create mode 100644 archive/papers/2020-05/src/paper.md create mode 100644 archive/papers/2020-05/src/relayers.md create mode 100644 archive/papers/2020-05/src/structure.md create mode 100644 archive/papers/2020-05/src/template.latex create mode 100644 archive/papers/2020-05/src/testing-and-deployment.md create mode 100644 archive/papers/2020-05/src/usage-patterns.md create mode 100644 archive/v0_3_1_IBC.pdf create mode 100755 assets/interchain-standards-image.jpg diff --git a/.gitattributes b/.gitattributes index b634d85f0..bfa69938a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,4 @@ +_layouts/* linguist-vendored *.pdf filter=lfs diff=lfs merge=lfs -text +*.png filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..6bbff54d6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,204 @@ +Interchain Standards +License: Apache2.0 + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2019 All in Bits, Inc + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/archive/README.md b/archive/README.md new file mode 100644 index 000000000..ecd8d4901 --- /dev/null +++ b/archive/README.md @@ -0,0 +1,6 @@ +# IBC archive + +This directory contains previous versions of the IBC specification that have been archived for further reference. + +1. [IBC v0.3.1](./v0_3_1_IBC.pdf) +1. [2020-05 IBC paper](./papers/2020-05/build/paper.pdf) diff --git a/archive/papers/2020-05/Makefile b/archive/papers/2020-05/Makefile new file mode 100644 index 000000000..bf1e02e7c --- /dev/null +++ b/archive/papers/2020-05/Makefile @@ -0,0 +1,28 @@ +FILES = src/paper.md \ + src/metadata.yaml + +OUTPUT = build + +FLAGS = --bibliography=src/bibliography.bib \ + --csl=src/bibliography.csl \ + --filter pandoc-include \ + -s \ + -f markdown + +FLAGS_PDF = --template=src/template.latex + +all: pdf + +pdf: + pandoc -o $(OUTPUT)/paper.pdf $(FLAGS) $(FLAGS_PDF) $(FILES) + +wc: + wc src/*.md + +spellcheck: + find ./src -type f -name "*.md" -exec aspell -p ./aspell_dict -x -d en_GB -c {} \; + +clean: + rm -rf build/* + +.PHONY: all pdf wc clean diff --git a/archive/papers/2020-05/README.md b/archive/papers/2020-05/README.md new file mode 100644 index 000000000..776e7f1b2 --- /dev/null +++ b/archive/papers/2020-05/README.md @@ -0,0 +1,13 @@ +Drafting an IBC paper. See [draft](./build/paper.pdf). + +Submission options: +- [CES CfP (May 2020)](https://cryptoeconomicsystems.pubpub.org/spring20-journalcfp) + - Up to 15,000 words + - A4 style, submitted as PDF + - Exclusive submission only + - Remove author names from paper + - Pre-prints OK + - Prior work: + - https://assets.pubpub.org/asuzx3df/11581974880753.pdf + - https://assets.pubpub.org/a7tcrzro/31581340169699.pdf + - https://assets.pubpub.org/g84cchsz/11581340329396.pdf diff --git a/archive/papers/2020-05/aspell_dict b/archive/papers/2020-05/aspell_dict new file mode 100644 index 000000000..30be6a0e2 --- /dev/null +++ b/archive/papers/2020-05/aspell_dict @@ -0,0 +1,127 @@ +personal_ws-1.1 en 126 +Adi +Aditya +Aggarwal +Agoric +Anca +Axner +BFT +Buchman +ChanCloseConfirm +ChanCloseInit +ChanOpenAck +ChanOpenConfirm +ChanOpenInit +ChanOpenTry +ConnOpenAck +ConnOpenConfirm +ConnOpenInit +ConnOpenTry +DNS +Datagram +Dev +Ethereum +GmbH +Hibbert +HotStuff +IAVL +IBC +INIT +Jae +Juwoon +Kunze +Kwon +Manian +Meher +Merkle +Merklized +Nakamoto +Ojha +Polkadot's +QUIC +SDK +Seredinschi +Sripal +TCP +TRYOPEN +Tendermint +Tribble +UDP +UX +WASM +XCMP +Yun +Zaki +Zamfir +Zampolin +Zarko +backend +blockchain +blockchains +bytestring +channelOnB +channelOnD +computable +counterintuitive +counterparty +cryptographic +dataflow +datagram +datagrams +datastream +dba +denom +encodings +escrowed +escrowing +exfiltration +fungibility +incentivisation +instantiations +interblockchain +interchain +interoperating +interoperation +introspectable +lifecycle +liveness +loopback +md +mempools +onecolumn +pagebreak +permissioned +permissioning +permissionless +permissionlessly +portOnB +portOnD +pseudocode +recv +relayer +relayers +ruleset +sharded +sig +src +stateful +statefulness +subprotocol +subprotocols +texttt +thresholding +tokenholder +tokenise +tokenised +tokenising +topologies +transactional +twocolumn +unbonding +unescrowed +unescrows +unreceived +validator +verifier +vspace +whitepaper diff --git a/archive/papers/2020-05/build/paper.pdf b/archive/papers/2020-05/build/paper.pdf new file mode 100644 index 0000000000000000000000000000000000000000..5334266831305a0cdbff31b32f521b026fd9e639 GIT binary patch literal 131 zcmWN?OA^8$3;@u5Pr(H&<s8%RKyQRx`$!qe;9ysNyWkC$q5o^oh?@ALMkvi@(M zywZ4TISc8_ETglMmMrW?2E$A~gyPW$w>b(nSz 0 || channel.order === UNORDERED) + provableStore.set( + packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence), + hash(acknowledgement) + ) + if (channel.order === ORDERED) { + nextSequenceRecv = provableStore.get(nextSequenceRecvPath(packet.destPort, packet.destChannel)) + abortTransactionUnless(packet.sequence === nextSequenceRecv) + nextSequenceRecv = nextSequenceRecv + 1 + provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv) + } + return packet +} +``` + +### Acknowledging a packet + +\vspace{3mm} + +```typescript +function acknowledgePacket( + packet: OpaquePacket, + acknowledgement: bytes, + proof: CommitmentProof, + proofHeight: uint64): Packet { + channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) + abortTransactionUnless(channel !== null) + abortTransactionUnless(channel.state === OPEN) + abortTransactionUnless(authenticateCapability( + channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) + abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) + abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) + connection = provableStore.get(connectionPath(channel.connectionHops[0])) + abortTransactionUnless(connection !== null) + abortTransactionUnless(connection.state === OPEN) + abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, + packet.sourceChannel, packet.sequence)) + === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) + abortTransactionUnless(connection.verifyPacketAcknowledgement( + proofHeight, + proof, + packet.destPort, + packet.destChannel, + packet.sequence, + acknowledgement + )) + if (channel.order === ORDERED) { + nextSequenceAck = provableStore.get(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel)) + abortTransactionUnless(packet.sequence === nextSequenceAck) + nextSequenceAck = nextSequenceAck + 1 + provableStore.set(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel), nextSequenceAck) + } + provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) + return packet +} +``` + +### Handling a timed-out packet + +\vspace{3mm} + +```typescript +function timeoutPacket( + packet: OpaquePacket, + proof: CommitmentProof, + proofHeight: uint64, + nextSequenceRecv: Maybe): Packet { + channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) + abortTransactionUnless(channel !== null) + abortTransactionUnless(channel.state === OPEN) + abortTransactionUnless(authenticateCapability( + channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) + abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) + connection = provableStore.get(connectionPath(channel.connectionHops[0])) + abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) + abortTransactionUnless( + (packet.timeoutHeight > 0 && proofHeight >= packet.timeoutHeight) || + (packet.timeoutTimestamp > 0 && + connection.getTimestampAtHeight(proofHeight) > packet.timeoutTimestamp)) + abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, + packet.sourceChannel, packet.sequence)) + === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) + if channel.order === ORDERED { + abortTransactionUnless(nextSequenceRecv <= packet.sequence) + abortTransactionUnless(connection.verifyNextSequenceRecv( + proofHeight, + proof, + packet.destPort, + packet.destChannel, + nextSequenceRecv + )) + } else + abortTransactionUnless(connection.verifyPacketAcknowledgementAbsence( + proofHeight, + proof, + packet.destPort, + packet.destChannel, + packet.sequence + )) + provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) + if channel.order === ORDERED { + channel.state = CLOSED + provableStore.set(channelPath(packet.sourcePort, packet.sourceChannel), channel) + } + return packet +} +``` + +### Cleaning up packet data + +\vspace{3mm} + +```typescript +function cleanupPacket( + packet: OpaquePacket, + proof: CommitmentProof, + proofHeight: uint64, + nextSequenceRecvOrAcknowledgement: Either): Packet { + channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) + abortTransactionUnless(channel !== null) + abortTransactionUnless(channel.state === OPEN) + abortTransactionUnless(authenticateCapability( + channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) + abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) + connection = provableStore.get(connectionPath(channel.connectionHops[0])) + abortTransactionUnless(connection !== null) + abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) + abortTransactionUnless(nextSequenceRecv > packet.sequence) + abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, + packet.sourceChannel, packet.sequence)) + === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) + if channel.order === ORDERED + abortTransactionUnless(connection.verifyNextSequenceRecv( + proofHeight, + proof, + packet.destPort, + packet.destChannel, + nextSequenceRecvOrAcknowledgement + )) + else + abortTransactionUnless(connection.verifyPacketAcknowledgement( + proofHeight, + proof, + packet.destPort, + packet.destChannel, + packet.sequence, + nextSequenceRecvOrAcknowledgement + )) + provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) + return packet +} +``` diff --git a/archive/papers/2020-05/src/bibliography.bib b/archive/papers/2020-05/src/bibliography.bib new file mode 100644 index 000000000..7e6d2c970 --- /dev/null +++ b/archive/papers/2020-05/src/bibliography.bib @@ -0,0 +1,214 @@ +@misc{cosmos_whitepaper, + title = {Cosmos: A Network of Distributed Ledgers}, + timestamp = {2016-09-21T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://cosmos.network/cosmos-whitepaper.pdf}}, + author = {{Jae Kwon, Ethan Buchman}}, + month = sep, + year = {2016} +} + +@misc{tendermint_consensus_without_mining, + title = {Tendermint: Consensus without Mining}, + timestamp = {}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://tendermint.com/static/docs/tendermint.pdf}}, + author = {{Jae Kwon}}, + month = sep, + year = {2014} +} + +@misc{tendermint_latest_gossip, + title = {The latest gossip on BFT consensus}, + timestamp = {2019-10-22T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://arxiv.org/pdf/1807.04938}}, + author = {{Ethan Buchman, Jae Kwon, Zarko Milosevic}}, + month = nov, + year = {2019} +} + +@misc{ethan_frey_ibc_spec, + title = {IBC Protocol Specification v0.3.1}, + timestamp = {2017-10-30T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/cosmos/ics/blob/master/archive/v0_3_1_IBC.pdf}}, + author = {{Ethan Frey}}, + month = nov, + year = {2017} +} + +@misc{hard_problems_sharding_part_one, + title = {The Authoritative Guide to Blockchain Sharding: Part 1}, + timestamp = {2018-12-05T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://medium.com/nearprotocol/the-authoritative-guide-to-blockchain-sharding-part-1-1b53ed31e060}}, + author = {{Near Protocol}}, + month = {dec}, + year = {2018} +} + +@misc{hard_problems_sharding_part_two, + title = {The Authoritative Guide to Blockchain Sharding: Part 2}, + timestamp = {2018-12-12T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://medium.com/nearprotocol/unsolved-problems-in-blockchain-sharding-2327d6517f43}}, + author = {{Near Protocol}}, + month = {dec}, + year = {2018} +} + +@misc{ibc_cosmos_sdk, + title = {The Cosmos SDK: x/ibc}, + timestamp = {2020-05-25T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc}}, + author = {{Cosmos SDK Contributors}}, + month = {may}, + year = {2020} +} + +@misc{ibc_rust, + title = {Rust implementation of IBC modules and relayer}, + timestamp = {2020-05-25T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/informalsystems/ibc-rs}}, + author = {{Informal Systems}}, + month = {may}, + year = {2020} +} + +@misc{relayer_go, + title = {Server-side IBC relayer}, + timestamp = {2020-05-25T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/iqlusioninc/relayer}}, + author = {{Iqlusion}}, + month = {may}, + year = {2020} +} + +@misc{game_of_zones, + title = {Game of Zones}, + timestamp = {2020-05-25T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://goz.cosmosnetwork.dev/}}, + author = {{GoZ Contributors}}, + month = {may}, + year = {2020} +} + +@misc{map_of_zones, + title = {Map of Zones}, + timestamp = {2020-05-25T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://mapofzones.com/}}, + author = {{Bitquasar & Ztake}}, + month = {may}, + year = {2020} +} + +@misc{grandpa_consensus, + title = {GRANDPA Finality Gadget}, + timestamp = {2020-05-02T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/w3f/consensus/blob/master/pdf/grandpa.pdf}}, + author = {{Alistair Stewart}}, + month = {may}, + year = {2020} +} + +@misc{polkadot_xcmp, + title = {Web3 Foundation Research: XCMP}, + timestamp = {2020-05-01T00:00:00Z}, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://research.web3.foundation/en/latest/polkadot/XCMP.html}}, + author = {{Alistair Stewart and Fatemeh Shirazi and Leon Groot Bruinderink}}, + month = {may}, + year = {2020} +} + +@misc{hotstuff_consensus, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://arxiv.org/pdf/1803.05069}}, + author = {Maofan Yin and Dahlia Malkhi and Michael K. Reiter and Guy Golan Gueta and Ittai Abraham}, + title = {HotStuff: BFT Consensus in the Lens of Blockchain}, + year = {2018}, + eprint = {arXiv:1803.05069}, +} + +@misc{iavl_plus_tree, + urldate = {2020-05-25T00:00:00Z}, + howpublished = {\url{https://github.com/tendermint/iavl}}, + author = {Tendermint}, + title = {IAVL+ Tree: A versioned, snapshottable (immutable) AVL+ tree for persistent data.}, + year = {2020} +} + +@misc{patricia_tree, + urldate = {2020-05-25T00:00:00Z}, + author = {Ethereum}, + howpublished = {\url{https://github.com/ethereum/wiki/wiki/Patricia-Tree}}, + title = {Ethereum Modified Merkle Patricia Trie Specification}, + year = {2020} +} + +@misc{object_capabilities, + author = {Chip Morningstar}, + howpublished = {\url{http://habitatchronicles.com/2017/05/what-are-capabilities/}}, + title = {What Are Capabilities?}, + year = {2017}, + urldate = {2020-05-25T00:00:00Z} +} + +@misc{coda_protocol, + author = {Izaak Meckler and Evan Shapiro}, + howpublished = {\url{https://cdn.codaprotocol.com/v2/static/coda-whitepaper-05-10-2018-0.pdf}}, + title = {Coda: Decentralized cryptocurrency at scale}, + year = {2018}, + urldate = {2020-05-25T00:00:00Z} +} + +@misc{substrate, + author = {Parity Technologies}, + howpublished = {\url{https://github.com/paritytech/substrate}}, + title = {Substrate: The platform for blockchain innovators}, + year = {2020}, + urldate = {2020-05-25T00:00:00Z} +} + +@misc{bitcoin, + added-at = {2014-04-17T08:33:06.000+0200}, + author = {Nakamoto, Satoshi}, + biburl = {https://www.bibsonomy.org/bibtex/23db66df0fc9fa2b5033f096a901f1c36/ngnn}, + interhash = {423c2cdff70ba0cd0bca55ebb164d770}, + intrahash = {3db66df0fc9fa2b5033f096a901f1c36}, + keywords = {imported}, + timestamp = {2014-04-17T08:33:06.000+0200}, + title = {Bitcoin: A peer-to-peer electronic cash system}, + url = {http://www.bitcoin.org/bitcoin.pdf}, + year = 2009 +} + +@misc{rfc793, + series = {Request for Comments}, + number = 793, + howpublished = {RFC 793}, + publisher = {RFC Editor}, + doi = {10.17487/RFC0793}, + url = {https://rfc-editor.org/rfc/rfc793.txt}, + author = {}, + title = {{Transmission Control Protocol}}, + pagetotal = 91, + year = 1981, + month = sep, + abstract = {}, +} + +@misc{ethereum_2_cross_shard, + title = {Ethereum Sharding Research Compendium: Cross-shard communication}, + year = 2020, + month = march, + author = {Ethereum 2.0 Contributors}, + howpublished = {\url{https://notes.ethereum.org/@serenity/H1PGqDhpm?type=view#Cross-shard-communication}} +} diff --git a/archive/papers/2020-05/src/bibliography.csl b/archive/papers/2020-05/src/bibliography.csl new file mode 100644 index 000000000..9d967b0bf --- /dev/null +++ b/archive/papers/2020-05/src/bibliography.csl @@ -0,0 +1,339 @@ + + \ No newline at end of file diff --git a/archive/papers/2020-05/src/channels.md b/archive/papers/2020-05/src/channels.md new file mode 100644 index 000000000..5d70071dc --- /dev/null +++ b/archive/papers/2020-05/src/channels.md @@ -0,0 +1,319 @@ +The *channel* abstraction provides message delivery semantics to the interblockchain communication protocol in three categories: ordering, exactly-once delivery, and module permissioning. A channel serves as a conduit for packets passing between a module on one ledger and a module on another, ensuring that packets are executed only once, delivered in the order in which they were sent (if necessary), and delivered only to the corresponding module owning the other end of the channel on the destination ledger. Each channel is associated with a particular connection, and a connection may have any number of associated channels, allowing the use of common identifiers and amortising the cost of header verification across all the channels utilising a connection and light client. + +Channels are payload-agnostic. The modules which send and receive IBC packets decide how to construct packet data and how to act upon the incoming packet data, and must utilise their own application logic to determine which state transactions to apply according to what data the packet contains. + +\vspace{3mm} + +### Motivation + +\vspace{3mm} + +The interblockchain communication protocol uses a cross-ledger message passing model. IBC *packets* are relayed from one ledger to the other by external relayer processes. Two ledgers, A and B, confirm new blocks independently, and packets from one ledger to the other may be delayed, censored, or re-ordered arbitrarily. Packets are visible to relayers and can be read from a ledger by any relayer process and submitted to any other ledger. + +The IBC protocol must provide ordering (for ordered channels) and exactly-once delivery guarantees to allow applications to reason about the combined state of connected modules on two ledgers. For example, an application may wish to allow a single tokenised asset to be transferred between and held on multiple ledgers while preserving fungibility and conservation of supply. The application can mint asset vouchers on ledger B when a particular IBC packet is committed to ledger B, and require outgoing sends of that packet on ledger A to escrow an equal amount of the asset on ledger A until the vouchers are later redeemed back to ledger A with an IBC packet in the reverse direction. This ordering guarantee along with correct application logic can ensure that total supply is preserved across both ledgers and that any vouchers minted on ledger B can later be redeemed back to ledger A. A more detailed explanation of this example is provided later on. + +\vspace{3mm} + +### Definitions + +\vspace{3mm} + +A *channel* is a pipeline for exactly-once packet delivery between specific modules on separate ledgers, which has at least one end capable of sending packets and one end capable of receiving packets. + +An *ordered* channel is a channel where packets are delivered exactly in the order which they were sent. + +An *unordered* channel is a channel where packets can be delivered in any order, which may differ from the order in which they were sent. + +All channels provide exactly-once packet delivery, meaning that a packet sent on one end of a channel is delivered no more and no less than once, eventually, to the other end. + +A *channel end* is a data structure storing metadata associated with one end of a channel on one of the participating ledgers, defined as follows: + +```typescript +interface ChannelEnd { + state: ChannelState + ordering: ChannelOrder + counterpartyPortIdentifier: Identifier + counterpartyChannelIdentifier: Identifier + nextSequenceSend: uint64 + nextSequenceRecv: uint64 + nextSequenceAck: uint64 + connectionHops: [Identifier] + version: string +} +``` + +- The `state` is the current state of the channel end. +- The `ordering` field indicates whether the channel is ordered or unordered. This is an enumeration instead of a boolean in order to allow additional kinds of ordering to be easily supported in the future. +- The `counterpartyPortIdentifier` identifies the port on the counterparty ledger which owns the other end of the channel. +- The `counterpartyChannelIdentifier` identifies the channel end on the counterparty ledger. +- The `nextSequenceSend`, stored separately, tracks the sequence number for the next packet to be sent. +- The `nextSequenceRecv`, stored separately, tracks the sequence number for the next packet to be received. +- The `nextSequenceAck`, stored separately, tracks the sequence number for the next packet to be acknowledged. +- The `connectionHops` stores the list of connection identifiers, in order, along which packets sent on this channel will travel. At the moment this list must be of length 1. In the future multi-hop channels may be supported. +- The `version` string stores an opaque channel version, which is agreed upon during the handshake. This can determine module-level configuration such as which packet encoding is used for the channel. This version is not used by the core IBC protocol. + +Channel ends have a *state*: + +```typescript +enum ChannelState { + INIT, + TRYOPEN, + OPEN, + CLOSED, +} +``` + +- A channel end in `INIT` state has just started the opening handshake. +- A channel end in `TRYOPEN` state has acknowledged the handshake step on the counterparty ledger. +- A channel end in `OPEN` state has completed the handshake and is ready to send and receive packets. +- A channel end in `CLOSED` state has been closed and can no longer be used to send or receive packets. + +A `Packet`, encapsulating opaque data to be transferred from one module to another over a channel, is a particular interface defined as follows: + +```typescript +interface Packet { + sequence: uint64 + timeoutHeight: uint64 + timeoutTimestamp: uint64 + sourcePort: Identifier + sourceChannel: Identifier + destPort: Identifier + destChannel: Identifier + data: bytes +} +``` + +- The `sequence` number corresponds to the order of sends and receives, where a packet with an earlier sequence number must be sent and received before a packet with a later sequence number. +- The `timeoutHeight` indicates a consensus height on the destination ledger after which the packet will no longer be processed, and will instead count as having timed-out. +- The `timeoutTimestamp` indicates a timestamp on the destination ledger after which the packet will no longer be processed, and will instead count as having timed-out. +- The `sourcePort` identifies the port on the sending ledger. +- The `sourceChannel` identifies the channel end on the sending ledger. +- The `destPort` identifies the port on the receiving ledger. +- The `destChannel` identifies the channel end on the receiving ledger. +- The `data` is an opaque value which can be defined by the application logic of the associated modules. + +Note that a `Packet` is never directly serialised. Rather it is an intermediary structure used in certain function calls that may need to be created or processed by modules calling the IBC handler. + +\vspace{3mm} + +### Properties + +\vspace{3mm} + +#### Efficiency + +As channels impose no flow control of their own, the speed of packet transmission and confirmation is limited only by the speed of the underlying ledgers. + +\vspace{3mm} + +#### Exactly-once delivery + +IBC packets sent on one end of a channel are delivered no more than exactly once to the other end. +No network synchrony assumptions are required for exactly-once safety. +If one or both of the ledgers halt, packets may be delivered no more than once, and once the ledgers resume packets will be able to flow again. + +\vspace{3mm} + +#### Ordering + +On ordered channels, packets are be sent and received in the same order: if packet `x` is sent before packet `y` by a channel end on ledger A, packet `x` will be received before packet `y` by the corresponding channel end on ledger B. + +On unordered channels, packets may be sent and received in any order. Unordered packets, like ordered packets, have individual timeouts specified in terms of the destination ledger's height or timestamp. + +\vspace{3mm} + +#### Permissioning + +Channels are permissioned to one module on each end, determined during the handshake and immutable afterwards (higher-level logic could tokenise channel ownership by tokenising ownership of the port). +Only the module which owns the port associated with a channel end is able to send or receive on the channel. + +\vspace{3mm} + +### Channel lifecycle management + +\vspace{3mm} + +#### Opening handshake + +The channel opening handshake, between two ledgers `A` and `B`, with state formatted as `(A, B)`, flows as follows: + +| Datagram | Prior state | Posterior state | +| ---------------- | --------------- | ---------------- | +| `ChanOpenInit` | `(-, -)` | `(INIT, -)` | +| `ChanOpenTry` | `(INIT, -)` | `(INIT, TRYOPEN)` | +| `ChanOpenAck` | `(INIT, TRYOPEN)` | `(OPEN, TRYOPEN)` | +| `ChanOpenConfirm` | `(OPEN, TRYOPEN)` | `(OPEN, OPEN)` | + +`ChanOpenInit`, executed on ledger A, initiates a channel opening handshake from a module on ledger A to a module on ledger B, +providing the identifiers of the local channel identifier, local port, remote port, and remote channel identifier. ledger A +stores a channel end object in its state. + +`ChanOpenTry`, executed on ledger B, relays notice of a channel handshake attempt to the module on ledger B, providing the +pair of channel identifiers, a pair of port identifiers, and a desired version. ledger B verifies a proof that ledger A has stored these identifiers +as claimed, looks up the module which owns the destination port, calls that module to check that the version requested is compatible, +and stores a channel end object in its state. + +`ChanOpenAck`, executed on ledger A, relays acceptance of a channel handshake attempt back to the module on ledger A, +providing the identifier which can now be used to look up the channel end. ledger A verifies a proof that ledger B +has stored the channel metadata as claimed and marks its end of the channel as `OPEN`. + +`ChanOpenConfirm`, executed on ledger B, confirms opening of a channel from ledger A to ledger B. +Ledger B simply checks that ledger A has executed `ChanOpenAck` and marked the channel as `OPEN`. +Ledger B subsequently marks its end of the channel as `OPEN`. After execution of `ChanOpenConfirm`, +the channel is open on both ends and can be used immediately. + +When the opening handshake is complete, the module which initiates the handshake will own the end of the created channel on the host ledger, and the counterparty module which +it specifies will own the other end of the created channel on the counterparty ledger. Once a channel is created, ownership can only be changed by changing ownership of the associated ports. + +\vspace{3mm} + +#### Versioning + +During the handshake process, two ends of a channel come to agreement on a version bytestring associated +with that channel. The contents of this version bytestring are opaque to the IBC core protocol. +Host ledgers may utilise the version data to indicate supported application-layer protocols, agree on packet +encoding formats, or negotiate other channel-related metadata related to custom logic on top of IBC. +Host ledgers may also safely ignore the version data or specify an empty string. + +\vspace{3mm} + +#### Closing handshake + +The channel closing handshake, between two ledgers `A` and `B`, with state formatted as `(A, B)`, flows as follows: + +| Datagram | Prior state | Posterior state | +| ---------------- | -------------- | ----------------- | +| `ChanCloseInit` | \texttt{\small{(OPEN, OPEN)}} | \texttt{\small{(CLOSED, OPEN)}} | +| `ChanCloseConfirm` | \texttt{\small{(CLOSED, OPEN)}} | \texttt{\small{(CLOSED, CLOSED)}} | + +`ChanCloseInit`, executed on ledger A, closes the end of the channel on ledger A. + +`ChanCloseInit`, executed on ledger B, simply verifies that the channel has been +marked as closed on ledger A and closes the end on ledger B. + +Any in-flight packets can be timed-out as soon as a channel is closed. + +Once closed, channels cannot be reopened and identifiers cannot be reused. Identifier reuse is prevented because +we want to prevent potential replay of previously sent packets. The replay problem is analogous to using sequence +numbers with signed messages, except where the light client algorithm "signs" the messages (IBC packets), and the replay +prevention sequence is the combination of port identifier, channel identifier, and packet sequence — hence we cannot +allow the same port identifier and channel identifier to be reused again with a sequence reset to zero, since this +might allow packets to be replayed. It would be possible to safely reuse identifiers if timeouts of a particular +maximum height/time were mandated and tracked, and future protocol versions may incorporate this feature. + +\vspace{3mm} + +### Sending packets + +\vspace{3mm} + +The `sendPacket` function is called by a module in order to send an IBC packet on a channel end owned by the calling module to the corresponding module on the counterparty ledger. + +Calling modules must execute application logic atomically in conjunction with calling `sendPacket`. + +The IBC handler performs the following steps in order: + +- Checks that the channel and connection are open to send packets +- Checks that the calling module owns the sending port +- Checks that the packet metadata matches the channel and connection information +- Checks that the timeout height specified has not already passed on the destination ledger +- Increments the send sequence counter associated with the channel (in the case of ordered channels) +- Stores a constant-size commitment to the packet data and packet timeout + +Note that the full packet is not stored in the state of the ledger — merely a short hash-commitment to the data and timeout value. The packet data can be calculated from the transaction execution and possibly returned as log output which relayers can index. + +\vspace{3mm} + +### Receiving packets + +\vspace{3mm} + +The `recvPacket` function is called by a module in order to receive and process an IBC packet sent on the corresponding channel end on the counterparty ledger. + +Calling modules must execute application logic atomically in conjunction with calling `recvPacket`, likely beforehand to calculate the acknowledgement value. + +The IBC handler performs the following steps in order: + +- Checks that the channel and connection are open to receive packets +- Checks that the calling module owns the receiving port +- Checks that the packet metadata matches the channel and connection information +- Checks that the packet sequence is the next sequence the channel end expects to receive (for ordered channels) +- Checks that the timeout height has not yet passed +- Checks the inclusion proof of packet data commitment in the outgoing ledger's state +- Sets the opaque acknowledgement value at a store path unique to the packet (if the acknowledgement is non-empty or the channel is unordered) +- Increments the packet receive sequence associated with the channel end (for ordered channels) + +\vspace{3mm} + +#### Acknowledgements + +\vspace{3mm} + +The `acknowledgePacket` function is called by a module to process the acknowledgement of a packet previously sent by +the calling module on a channel to a counterparty module on the counterparty ledger. `acknowledgePacket` also cleans up the packet commitment, +which is no longer necessary since the packet has been received and acted upon. + +Calling modules may atomically execute appropriate application acknowledgement-handling logic in conjunction with calling `acknowledgePacket`. + +The IBC handler performs the following steps in order: + +- Checks that the channel and connection are open to acknowledge packets +- Checks that the calling module owns the sending port +- Checks that the packet metadata matches the channel and connection information +- Checks that the packet was actually sent on this channel +- Checks that the packet sequence is the next sequence the channel end expects to acknowledge (for ordered channels) +- Checks the inclusion proof of the packet acknowledgement data in the receiving ledger's state +- Deletes the packet commitment (cleaning up state and preventing replay) +- Increments the next acknowledgement sequence (for ordered channels) + +\vspace{3mm} + +### Timeouts + +\vspace{3mm} + +Application semantics may require some timeout: an upper limit to how long the ledger will wait for a transaction to be processed before considering it an error. Since the two ledgers have different local clocks, this is an obvious attack vector for a double spend — an attacker may delay the relay of the receipt or wait to send the packet until right after the timeout — so applications cannot safely implement naive timeout logic themselves. In order to avoid any possible "double-spend" attacks, the timeout algorithm requires that the destination ledger is running and reachable. The timeout must be proven on the recipient ledger, not simply the absence of a response on the sending ledger. + +\vspace{3mm} + +#### Sending end + +The `timeoutPacket` function is called by a module which originally attempted to send a packet to a counterparty module, +where the timeout height or timeout timestamp has passed on the counterparty ledger without the packet being committed, to prove that the packet +can no longer be executed and to allow the calling module to safely perform appropriate state transitions. + +Calling modules may atomically execute appropriate application timeout-handling logic in conjunction with calling `timeoutPacket`. + +The IBC handler performs the following steps in order: + +- Checks that the channel and connection are open to timeout packets +- Checks that the calling module owns the sending port +- Checks that the packet metadata matches the channel and connection information +- Checks that the packet was actually sent on this channel +- Checks a proof that the packet has not been confirmed on the destination ledger +- Checks a proof that the destination ledger has exceeded the timeout height or timestamp +- Deletes the packet commitment (cleaning up state and preventing replay) + +In the case of an ordered channel, `timeoutPacket` additionally closes the channel if a packet has timed out. Unordered channels are expected to continue in the face of timed-out packets. + +If relations are enforced between timeout heights of subsequent packets, safe bulk timeouts of all packets prior to a timed-out packet can be performed. + +\vspace{3mm} + +#### Timing-out on close + +If a channel is closed, in-flight packets can never be received and thus can be safely timed-out. +The `timeoutOnClose` function is called by a module in order to prove that the channel +to which an unreceived packet was addressed has been closed, so the packet will never be received +(even if the `timeoutHeight` or `timeoutTimestamp` has not yet been reached). Appropriate +application-specific logic may then safely be executed. + +\vspace{3mm} + +#### Cleaning up state + +If an acknowledgement is not written (as handling the acknowledgement would clean up state in that case), `cleanupPacket` may be called by a module in order to remove a received packet commitment from storage. The receiving end must have already processed the packet (whether regularly or past timeout). + +In the ordered channel case, `cleanupPacket` cleans-up a packet on an ordered channel by proving that the receive sequence has passed the packet's sequence on the other end. + +In the unordered channel case, `cleanupPacket` cleans-up a packet on an unordered channel by proving that the associated acknowledgement has been written. diff --git a/archive/papers/2020-05/src/clients.md b/archive/papers/2020-05/src/clients.md new file mode 100644 index 000000000..def79fb41 --- /dev/null +++ b/archive/papers/2020-05/src/clients.md @@ -0,0 +1,191 @@ +The *client* abstraction encapsulates the properties that consensus algorithms of ledgers implementing the interblockchain +communication protocol are required to satisfy. These properties are necessary for efficient and safe +state verification in the higher-level protocol abstractions. The algorithm utilised in IBC to verify the +consensus transcript and state sub-components of another ledger is referred to as a "validity predicate", +and pairing it with a state that the verifier assumes to be correct forms a "light client" (colloquially shortened to "client"). + +\vspace{3mm} + +### Motivation + +\vspace{3mm} + +In the IBC protocol, an actor, which may be an end user, an off-ledger process, or ledger, +needs to be able to verify updates to the state of another ledger +which the other ledger's consensus algorithm has agreed upon, and reject any possible updates +which the other ledger's consensus algorithm has not agreed upon. A light client is the algorithm +with which an actor can do so. The client abstraction formalises this model's interface and requirements, +so that the IBC protocol can easily integrate with new ledgers which are running new consensus algorithms +as long as associated light client algorithms fulfilling the listed requirements are provided. + +Beyond the properties described in this specification, IBC does not impose any requirements on +the internal operation of ledgers and their consensus algorithms. A ledger may consist of a +single process signing operations with a private key, a quorum of processes signing in unison, +many processes operating a Byzantine fault-tolerant consensus algorithm (a replicated, or distributed, ledger), or other configurations yet to be invented +— from the perspective of IBC, a ledger is defined entirely by its light client validation and equivocation detection logic. +Clients will generally not include validation of the state transition logic in general +(as that would be equivalent to simply executing the other state machine), but may +elect to validate parts of state transitions in particular cases, and can validate +the entire state transition if doing so is asymptotically efficient, perhaps through compression using a SNARK [@coda_protocol]. + +Externally, however, the light client verification functions used by IBC clients +must have *finality*, such that verified blocks (subject to the usual consensus safety assumptions), +once verified, cannot be reverted. The safety of higher abstraction layers of the IBC protocol +and guarantees provided to the applications using the protocol depend on this property of finality. + +In order to graft finality onto Nakamoto consensus algorithms, such as used in Bitcoin [@bitcoin], +clients can act as thresholding views of internal, non-finalising clients. In the case where +modules utilising the IBC protocol to interact with probabilistic-finality consensus algorithms +which might require different finality thresholds for different applications, one write-only +client could be created to track headers and many read-only clients with different finality +thresholds (confirmation depths after which state roots are considered final) could use that same state. +Of course, this will introduce different security assumptions than those required of full nodes running the consensus algorithm, +and trade-offs which must be balanced by the user on the basis of their application-specific security needs. + +The client protocol is designed to support third-party introduction. Consider the general example: +Alice, a module on a ledger, wants to introduce Bob, a second module on a second ledger who Alice knows (and who knows Alice), +to Carol, a third module on a third ledger, who Alice knows but Bob does not. Alice must utilise +an existing channel to Bob to communicate the canonically-serialisable validity predicate for +Carol, with which Bob can then open a connection and channel so that Bob and Carol can talk directly. +If necessary, Alice may also communicate to Carol the validity predicate for Bob, prior to Bob's +connection attempt, so that Carol knows to accept the incoming request. + +Client interfaces are constructed so that custom validation logic can be provided safely +to define a custom client at runtime, as long as the underlying ledger can provide an +appropriate gas metering mechanism to charge for compute and storage. On a host ledger +which supports WASM execution, for example, the validity predicate and equivocation predicate +could be provided as executable WASM functions when the client instance is created. + +\vspace{3mm} + +### Definitions + +\vspace{3mm} + +A *validity predicate* is an opaque function defined by a client type to verify headers depending on the current consensus state. Using the validity predicate should be far more computationally efficient than replaying the full consensus algorithm and state machine for the given parent header and the list of network messages. + +A *consensus state* is an opaque type representing the state of a validity predicate. +The light client validity predicate algorithm in combination with a particular consensus state must be able to verify state updates agreed upon by the associated consensus algorithm. +The consensus state must also be serialisable in a canonical fashion so that third parties, such as counterparty ledgers, +can check that a particular ledger has stored a particular state. It must also be +introspectable by the ledger which it is for, such that the ledger can look up its +own consensus state at a past height and compare it to a stored consensus state in another ledger's client. + +A *commitment root* is an inexpensive way for downstream logic to verify whether key/value +pairs are present or absent in a state at a particular height. Often this will be instantiated as the root of a Merkle tree. + +A *header* is an opaque data structure defined by a client type which provides information to update a consensus state. +Headers can be submitted to an associated client to update the stored consensus state. They likely contain a height, a proof, +a new commitment root, and possibly updates to the validity predicate. + +A *misbehaviour predicate* is an opaque function defined by a client type, used to check if data constitutes a violation of the consensus protocol. This might be two signed headers with different state roots but the same height, a signed header containing invalid state transitions, or other evidence of malfeasance as defined by the consensus algorithm. + +\vspace{3mm} + +### Desired properties + +\vspace{3mm} + +Light clients must provide a secure algorithm to verify other ledgers' canonical headers, +using the existing consensus state. The higher level abstractions will then be able to verify +sub-components of the state with the commitment roots stored in the consensus state, which are +guaranteed to have been committed by the other ledger's consensus algorithm. + +Validity predicates are expected to reflect the behaviour of the full nodes which are running the +corresponding consensus algorithm. Given a consensus state and a list of messages, if a full node +accepts a new header, then the light client must also accept it, and if a full node rejects it, +then the light client must also reject it. + +Light clients are not replaying the whole message transcript, so it is possible under cases of +consensus misbehaviour that the light clients' behaviour differs from the full nodes'. +In this case, a misbehaviour proof which proves the divergence between the validity predicate +and the full node can be generated and submitted to the ledger so that the ledger can safely deactivate the +light client, invalidate past state roots, and await higher-level intervention. + +The validity of the validity predicate is dependent on the security model of the +consensus algorithm. For example, the consensus algorithm could be BFT proof-of-authority +with a trusted operator set, or BFT proof-of-stake with a tokenholder set, each of which +have a defined threshold above which Byzantine behaviour may result in divergence. + +Clients may have time-sensitive validity predicates, such that if no header is provided for a period of time +(e.g. an unbonding period of three weeks in a proof-of-stake system) it will no longer be possible to update the client. + +\vspace{3mm} + +### State verification + +\vspace{3mm} + +Client types must define functions to authenticate internal state of the ledger which the client tracks. +Internal implementation details may differ (for example, a loopback client could simply read directly from the state and require no proofs). +Externally-facing clients will likely verify signature or vector commitment proofs. + +\vspace{3mm} + +### Example client instantiations + +\vspace{3mm} + +#### Loopback + +A loopback client of a local ledger merely reads from the local state, to which it must have access. This is analogous to `localhost` or `127.0.0.1` in TCP/IP. + +\vspace{3mm} + +#### Simple signatures + +A client of a solo machine running a non-replicated ledger with a known public key checks signatures on messages sent by that local machine. +Multi-signature or threshold signature schemes can also be used in such a fashion. + +\vspace{3mm} + +#### Proxy clients + +Proxy clients verify another (proxy) ledger's verification of the target ledger, by including in the +proof first a proof of the client state on the proxy ledger, and then a secondary proof of the sub-state of +the target ledger with respect to the client state on the proxy ledger. This allows the proxy client to +avoid storing and tracking the consensus state of the target ledger itself, at the cost of adding +security assumptions of proxy ledger correctness. + +\vspace{3mm} + +#### BFT consensus and verifiable state + +For the immediate application of interoperability between sovereign, fault-tolerant distributed ledgers, the most common and most useful client type will be light clients for instances of BFT consensus algorithms such as Tendermint [@tendermint_consensus_without_mining], GRANDPA [@grandpa_consensus], or HotStuff [@hotstuff_consensus], with ledgers utilising Merklized state trees such as an IAVL+ tree [@iavl_plus_tree] or a Merkle Patricia tree [@patricia_tree]. The client algorithm for such instances will utilise the BFT consensus algorithm's light client validity predicate and treat at minimum consensus equivocation (double-signing) as misbehaviour, along with other possible misbehaviour types specific to the proof-of-authority or proof-of-stake system involved. + +\vspace{3mm} + +### Client lifecycle + +\vspace{3mm} + +#### Creation + +Clients can be created permissionlessly by anyone at any time by specifying an identifier, +client type, and initial consensus state. + +\vspace{3mm} + +#### Update + +Updating a client is done by submitting a new header. When a new header is verified +with the stored client state's validity predicate and consensus state, the client will +update its internal state accordingly, possibly finalising commitment roots and +updating the signature authority logic in the stored consensus state. + +If a client can no longer be updated (if, for example, the unbonding period has passed), +it will no longer be possible to send any packets over connections and channels associated +with that client, or timeout any packets in-flight (since the height and timestamp on the +destination ledger can no longer be verified). Manual intervention must take place to +reset the client state or migrate the connections and channels to another client. This +cannot safely be done automatically, but ledgers implementing IBC could elect +to allow governance mechanisms to perform these actions +(perhaps even per-client/connection/channel with a controlling multi-signature or contract). + +\vspace{3mm} + +#### Misbehaviour + +If the client detects evidence of misbehaviour, the client can be take appropriate action, possibly invalidating +previously valid commitment roots and preventing future updates. What precisely constitutes misbehaviour will +depend on the consensus algorithm which the validity predicate is validating the output of. diff --git a/archive/papers/2020-05/src/connections.md b/archive/papers/2020-05/src/connections.md new file mode 100644 index 000000000..5ca388d8e --- /dev/null +++ b/archive/papers/2020-05/src/connections.md @@ -0,0 +1,105 @@ +The *connection* abstraction encapsulates two stateful objects (*connection ends*) on two separate ledgers, each associated with a light client of the other ledger, which together facilitate cross-ledger sub-state verification and packet relay (through channels). Connections are safely established in an unknown, dynamic topology using a handshake subprotocol. + +\vspace{3mm} + +### Motivation + +\vspace{3mm} + +The IBC protocol provides *authorisation* and *ordering* semantics for packets: guarantees, respectively, that packets have been committed on the sending ledger (and according state transitions executed, such as escrowing tokens), and that they have been committed exactly once in a particular order and can be delivered exactly once in that same order. The *connection* abstraction in conjunction with the *client* abstraction defines the *authorisation* semantics of IBC. Ordering semantics are provided by channels. + +\vspace{3mm} + +### Definitions + +\vspace{3mm} + +A *connection end* is state tracked for an end of a connection on one ledger, defined as follows: + +```typescript +enum ConnectionState { + INIT, + TRYOPEN, + OPEN, +} +``` + +```typescript +interface ConnectionEnd { + state: ConnectionState + counterpartyConnectionIdentifier: Identifier + counterpartyPrefix: CommitmentPrefix + clientIdentifier: Identifier + counterpartyClientIdentifier: Identifier + version: string +} +``` + +- The `state` field describes the current state of the connection end. +- The `counterpartyConnectionIdentifier` field identifies the connection end on the counterparty ledger associated with this connection. +- The `counterpartyPrefix` field contains the prefix used for state verification on the counterparty ledger associated with this connection. +- The `clientIdentifier` field identifies the client associated with this connection. +- The `counterpartyClientIdentifier` field identifies the client on the counterparty ledger associated with this connection. +- The `version` field is an opaque string which can be utilised to determine encodings or protocols for channels or packets utilising this connection. + +\vspace{3mm} + +### Opening handshake + +\vspace{3mm} + +The opening handshake subprotocol allows each ledger to verify the identifier used to reference the connection on the other ledger, enabling modules on each ledger to reason about the reference on the other ledger. + +The opening handshake consists of four datagrams: `ConnOpenInit`, `ConnOpenTry`, `ConnOpenAck`, and `ConnOpenConfirm`. + +A correct protocol execution, between two ledgers `A` and `B`, with connection states formatted as `(A, B)`, flows as follows: + +| Datagram | Prior state | Posterior state | +| ----------------- | ----------------- | ----------------- | +| `ConnOpenInit` | `(-, -)` | `(INIT, -)` | +| `ConnOpenTry` | `(INIT, none)` | `(INIT, TRYOPEN)` | +| `ConnOpenAck` | `(INIT, TRYOPEN)` | `(OPEN, TRYOPEN)` | +| `ConnOpenConfirm` | `(OPEN, TRYOPEN)` | `(OPEN, OPEN)` | + +At the end of an opening handshake between two ledgers implementing the subprotocol, the following properties hold: + +- Each ledger has each other's correct consensus state as originally specified by the initiating actor. +- Each ledger has knowledge of and has agreed to its identifier on the other ledger. +- Each ledger knows that the other ledger has agreed to the same data. + +Connection handshakes can safely be performed permissionlessly, modulo anti-spam measures (paying gas). + +`ConnOpenInit`, executed on ledger A, initialises a connection attempt on ledger A, specifying a pair of identifiers +for the connection on both ledgers and a pair of identifiers for existing light clients (one for +each ledger). ledger A stores a connection end object in its state. + +`ConnOpenTry`, executed on ledger B, relays notice of a connection attempt on ledger A to ledger B, +providing the pair of connection identifiers, the pair of client identifiers, and a desired version. +Ledger B verifies that these identifiers are valid, checks that the version is compatible, verifies +a proof that ledger A has stored these identifiers, and verifies a proof that the light client ledger A +is using to validate ledger B has the correct consensus state for ledger B. ledger B stores a connection +end object in its state. + +`ConnOpenAck`, executed on ledger A, relays acceptance of a connection open attempt from ledger B back to ledger A, +providing the identifier which can now be used to look up the connection end object. ledger A verifies +that the version requested is compatible, verifies a proof that ledger B has stored the same identifiers +ledger A has stored, and verifies a proof that the light client ledger B is using to validate ledger A has the +correct consensus state for ledger A. + +`ConnOpenConfirm`, executed on ledger B, confirms opening of a connection on ledger A to ledger B. +Ledger B simply checks that ledger A has executed `ConnOpenAck` and marked the connection as `OPEN`. +Ledger B subsequently marks its end of the connection as `OPEN`. After execution of `ConnOpenConfirm` +the connection is open on both ends and can be used immediately. + +\vspace{3mm} + +### Versioning + +\vspace{3mm} + +During the handshake process, two ends of a connection come to agreement on a version bytestring associated +with that connection. At the moment, the contents of this version bytestring are opaque to the IBC core protocol. +In the future, it might be used to indicate what kinds of channels can utilise the connection in question, or +what encoding formats channel-related datagrams will use. Host ledgers may utilise the version data +to negotiate encodings, priorities, or connection-specific metadata related to custom logic on top of IBC. +Host ledgers may also safely ignore the version data or specify an empty string. diff --git a/archive/papers/2020-05/src/fungible-token-transfer.md b/archive/papers/2020-05/src/fungible-token-transfer.md new file mode 100644 index 000000000..9a0e50ff9 --- /dev/null +++ b/archive/papers/2020-05/src/fungible-token-transfer.md @@ -0,0 +1,85 @@ +The section specifies packet data structure and state machine handling logic for the transfer of fungible tokens over an IBC channel between two modules on separate ledgers. The state machine logic presented allows for safe multi-ledger denomination handling with permissionless channel opening. This logic constitutes a "fungible token transfer bridge module", interfacing between the IBC routing module and an existing asset tracking module on the host ledger. + +\vspace{3mm} + +### Motivation + +\vspace{3mm} + +Users of a set of ledgers connected over the IBC protocol might wish to utilise an asset issued on one ledger on another ledger, perhaps to make use of additional features such as exchange or privacy protection, while retaining fungibility with the original asset on the issuing ledger. This application-layer protocol allows for transferring fungible tokens between ledgers connected with IBC in a way which preserves asset fungibility, preserves asset ownership, limits the impact of Byzantine faults, and requires no additional permissioning. + +\vspace{3mm} + +### Properties + +\vspace{3mm} + +- Preservation of fungibility (two-way peg) +- Preservation of total supply (constant or inflationary on a single source ledger and module) +- Permissionless token transfers, no need to whitelist connections, modules, or denominations +- Symmetric (all ledgers implement the same logic) +- Fault containment: prevents Byzantine-inflation of tokens originating on ledger A, as a result of ledger B's Byzantine behaviour (though any users who sent tokens to ledger B may be at risk) + +\vspace{3mm} + +### Packet definition + +\vspace{3mm} + +Only one packet data type, `FungibleTokenPacketData`, which specifies the denomination, amount, sending account, receiving account, and whether the sending ledger is the source of the asset, is required: + +```typescript +interface FungibleTokenPacketData { + denomination: string + amount: uint256 + sender: string + receiver: string +} +``` + +The acknowledgement data type describes whether the transfer succeeded or failed, and the reason for failure (if any): + + +```typescript +interface FungibleTokenPacketAcknowledgement { + success: boolean + error: Maybe +} +``` + +\vspace{3mm} + +### Packet handling semantics + +\vspace{3mm} + +The protocol logic is symmetric, so that denominations originating on either ledger can be converted to vouchers on the other, and then redeemed back again later. + +- When acting as the source ledger, the bridge module escrows an existing local asset denomination on the sending ledger and mints vouchers on the receiving ledger. +- When acting as the sink ledger, the bridge module burns local vouchers on the sending ledgers and unescrows the local asset denomination on the receiving ledger. +- When a packet times-out, local assets are unescrowed back to the sender or vouchers minted back to the sender appropriately. +- Acknowledgement data is used to handle failures, such as invalid denominations or invalid destination accounts. Returning + an acknowledgement of failure is preferable to aborting the transaction since it more easily enables the sending ledger + to take appropriate action based on the nature of the failure. + +This implementation preserves both fungibility and supply. If tokens have been sent to the counterparty ledger, they can be redeemed back in the same denomination and amount on the source ledger. +The combined supply of unlocked tokens of a particular on both ledgers is constant, since each send-receive packet pair locks and mints the same amount (although the source ledger of a particular +asset could change the supply outside of the scope of this protocol). + +\vspace{3mm} + +### Fault containment + +\vspace{3mm} + +Ledgers could fail to follow the fungible transfer token protocol outlined here in one of two ways: the full nodes running the consensus algorithm could diverge from the light client, or the ledger's state machine could incorrectly implement the escrow & voucher logic (whether inadvertently or intentionally). Consensus divergence should eventually result in evidence of misbehaviour which can be used to freeze the client, but may not immediately do so (and no guarantee can be made that such evidence would be submitted before more packets), so from the perspective of the protocol's goal of isolating faults these cases must be handled in the same way. No guarantees can be made about asset recovery — users electing to transfer tokens to a ledger take on the risk of that ledger failing — but containment logic can easily be implemented on the interface boundary by tracking incoming and outgoing supply of each asset, and ensuring that no ledger is allowed to redeem vouchers for more tokens than it had initially escrowed. In essence, particular channels can be treated as accounts, where a module on the other end of a channel cannot spend more than it has received. Since isolated Byzantine sub-graphs of a multi-ledger fungible token transfer system will be unable to transfer out any more tokens than they had initially received, this prevents any supply inflation of source assets, and ensures that users only take on the consensus risk of ledgers they intentionally connect to. + +\vspace{3mm} + +### Multi-ledger transfer paths + +\vspace{3mm} + +This protocol does not directly handle the "diamond problem", where a user sends a token originating on ledger A to ledger B, then to ledger D, and wants to return it through the path `D -> C -> A` — since the supply is tracked as owned by ledger B (and the voucher denomination will be `"{portD}/{channelD}/{portB}/{channelB}/denom"`), ledger C cannot serve as the intermediary. This is necessary due to the fault containment desiderata outlined above. Complexities arising from long redemption paths may lead to the emergence of central ledgers in the network topology or automated markets to exchange assets with different redemption paths. + +In order to track all of the denominations moving around the network of ledgers in various paths, it may be helpful for a particular ledger to implement a registry which will track the "global" source ledger for each denomination. End-user service providers (such as wallet authors) may want to integrate such a registry or keep their own mapping of canonical source ledgers and human-readable names in order to improve UX. diff --git a/archive/papers/2020-05/src/host-requirements.md b/archive/papers/2020-05/src/host-requirements.md new file mode 100644 index 000000000..0e74cc513 --- /dev/null +++ b/archive/papers/2020-05/src/host-requirements.md @@ -0,0 +1,79 @@ +### Module system + +\vspace{3mm} + +The host ledger must support a module system, whereby self-contained, potentially mutually distrusted packages of code can safely execute on the same ledger, control how and when they allow other modules to communicate with them, and be identified and manipulated by a controller module or execution environment. + +\vspace{3mm} + +### Key/value Store + +\vspace{3mm} + +The host ledger must provide a key/value store interface allowing values to be read, written, and deleted. + +These functions must be permissioned to the IBC handler module so that only the IBC handler module can write or delete a certain subset of paths. +This will likely be implemented as a sub-store (prefixed key-space) of a larger key/value store used by the entire ledger. + +Host ledgers must provide an instance of this interface which is provable, such that the light client algorithm for the host ledger +can verify presence or absence of particular key-value pairs which have been written to it. + +This interface does not necessitate any particular storage backend or backend data layout. ledgers may elect to use a storage backend configured in accordance with their needs, as long as the store on top fulfils the specified interface and provides commitment proofs. + +\vspace{3mm} + +### Consensus state introspection + +\vspace{3mm} + +Host ledgers must provide the ability to introspect their current height, current +consensus state (as utilised by the host ledger's light client algorithm), and a bounded +number of recent consensus states (e.g. past headers). These are used to prevent man-in-the-middle +attacks during handshakes to set up connections with other ledgers — each ledger checks that the other +ledger is in fact authenticating data using its consensus state. + +\vspace{3mm} + +### Timestamp access + +\vspace{3mm} + +In order to support timestamp-based timeouts, host ledgers must provide a current Unix-style timestamp. +Timeouts in subsequent headers must be non-decreasing. + +\vspace{3mm} + +### Port system + +\vspace{3mm} + +Host ledgers must implement a port system, where the IBC handler can allow different modules in the host ledger to bind to uniquely named ports. Ports are identified by an identifier, and must be permissioned so that: + +- Once a module has bound to a port, no other modules can use that port until the module releases it +- A single module can bind to multiple ports +- Ports are allocated first-come first-serve +- "Reserved" ports for known modules can be bound when the ledger is first started + +This permissioning can be implemented with unique references (object capabilities [@object_capabilities]) for each port, with source-based authentication(a la `msg.sender` in Ethereum contracts), or with some other method of access control, in any case enforced by the host ledger. + +Ports are not generally intended to be human-readable identifiers — just as DNS name resolution and standardised port numbers for particular applications exist to abstract away the details of IP addresses and ports from TCP/IP users, ledger name resolution and standardised ports for particular applications may be created in order to abstract away the details of ledger identification and port selection. Such an addressing system could easily be built on top of IBC itself, such that an initial connection to the addressing system over IBC would then enable name resolution for subsequent connections to other ledgers and applications. + +\vspace{3mm} + +### Exception/rollback system + +\vspace{3mm} + +Host ledgers must support an exception or rollback system, whereby a transaction can abort execution and revert any previously made state changes (including state changes in other modules happening within the same transaction), excluding gas consumed and fee payments as appropriate. + +\vspace{3mm} + +### Data availability + +\vspace{3mm} + +For deliver-or-timeout safety, host ledgers must have eventual data availability, such that any key/value pairs in state can be eventually retrieved by relayers. For exactly-once safety, data availability is not required. + +For liveness of packet relay, host ledgers must have bounded transactional liveness, such that incoming transactions are confirmed within a block height or timestamp bound (in particular, less than the timeouts assigned to the packets). + +IBC packet data, and other data which is not directly stored in the Merklized state but is relied upon by relayers, must be available to and efficiently computable by relayer processes. diff --git a/archive/papers/2020-05/src/introduction.md b/archive/papers/2020-05/src/introduction.md new file mode 100644 index 000000000..eea9febd2 --- /dev/null +++ b/archive/papers/2020-05/src/introduction.md @@ -0,0 +1,13 @@ +By virtue of their nature as replicated state machines across which deterministic execution and thus continued agreement on an exact deterministic ruleset must be maintained, individual distributed ledgers are limited in their throughput & flexibility, must trade off application-specific optimisations for general-purpose capabilities, and can only offer a single security model to applications built on top of them. In order to support the transaction throughput, application diversity, cost efficiency, and fault tolerance required to facilitate wide deployment of distributed ledger applications, execution and storage must be split across many independent ledgers which can run concurrently, upgrade independently, and each specialise in different ways, in a manner such that the ability of different applications to communicate with one another, essential for permissionless innovation and complex multi-part contracts, is maintained. + +One multi-ledger design direction is to shard a single logical ledger across separate consensus instances, referred to as "shards", which execute concurrently and store disjoint partitions of the state. In order to reason globally about safety and liveness, and in order to correctly route data and code between shards, these designs must take a "top-down approach" — constructing a particular network topology, usually a single root ledger and a star or tree of shards, and engineering protocol rules and incentives to enforce that topology. Message passing can then be implemented on top of such a sharded topology by systems such as Polkadot's XCMP [@polkadot_xcmp] and Ethereum 2.0's cross-shard communication [@ethereum_2_cross_shard]. This approach possesses advantages in simplicity and predictability, but faces hard technical problems in assuring the validity of state transitions [@hard_problems_sharding_part_two], requires the adherence of all shards to a single validator set (or randomly elected subset thereof) and a single virtual machine, and faces challenges in upgrading itself over time due to the necessity of reaching global consensus on alterations to the network topology or ledger ruleset. Additionally, such sharded systems are brittle: if the fault tolerance threshold is exceeded, the system needs to coordinate a global halt & restart, and possibly initiate complex state transition rollback procedures — it is not possible to safely isolate Byzantine portions of the network graph and continue operation. + +The *interblockchain communication protocol* (IBC) provides a mechanism by which separate, sovereign replicated ledgers can safely, voluntarily interact while sharing only a minimum requisite common interface. The protocol design approaches a differently formulated version of the scaling and interoperability problem: enabling safe, reliable interoperation of a network of heterogeneous distributed ledgers, arranged in an unknown topology, preserving data secrecy where possible, where the ledgers can diversify, develop, and rearrange independently of each other or of a particular imposed topology or ledger design. In a wide, dynamic network of interoperating ledgers, sporadic Byzantine faults are expected, so the protocol must also detect, mitigate, and contain the potential damage of Byzantine faults in accordance with the requirements of the applications and ledgers involved without requiring the use of additional trusted parties or global coordination. + +To facilitate this heterogeneous interoperation, the interblockchain communication protocol utilises a bottom-up approach, specifying the set of requirements, functions, and properties necessary to implement interoperation between two ledgers, and then specifying different ways in which multiple interoperating ledgers might be composed which preserve the requirements of higher-level protocols. IBC thus presumes nothing about and requires nothing of the overall network topology, and of the implementing ledgers requires only that a known, minimal set of functions with specified properties are available. Ledgers within IBC are defined as their light client consensus validation functions, thus expanding the range of what a "ledger" can be to include single machines and complex consensus algorithms alike. IBC implementations are expected to be co-resident with higher-level modules and protocols on the host ledger. Ledgers hosting IBC must provide a certain set of functions for consensus transcript verification and cryptographic commitment proof generation, and IBC packet relayers (off-ledger processes) are expected to have access to network protocols and physical data-links as required to read the state of one ledger and submit data to another. + +The data payloads in IBC packets are opaque to the protocol itself — modules on each ledger determine the semantics of the packets which are sent between them. For cross-ledger token transfer, packets could contain fungible token information, where assets are locked on one ledger to mint corresponding vouchers on another. For cross-ledger governance, packets could contain vote information, where accounts on one ledger could vote in the governance system of another. For cross-ledger account delegation, packets could contain transaction authorisation information, allowing an account on one ledger to be controlled by an account on another. For a cross-ledger decentralised exchange, packets could contain order intent information or trade settlement information, such that assets on different ledgers could be exchanged without leaving their host ledgers by transitory escrow and a sequence of packets. + +This bottom-up approach is quite similar to, and directly inspired by, the TCP/IP specification [@rfc793] for interoperability between hosts in packet-switched computer networks. Just as TCP/IP defines the protocol by which two hosts communicate, and higher-level protocols knit many bidirectional host-to-host links into complex topologies, IBC defines the protocol by which two ledgers communicate, and higher-level protocols knit many bidirectional ledger-to-ledger links into gestalt multi-ledger applications. Just as TCP/IP packets contain opaque payload data with semantics interpreted by the processes on each host, IBC packets contain opaque payload data with semantics interpreted by the modules on each ledger. Just as TCP/IP provides reliable, ordered data transmission between processes, allowing a process on one host to reason about the state of a process on another, IBC provides reliable, ordered data transmission between modules, allowing a module on one ledger to reason about the state of a module on another. + +This paper is intended as an overview of the abstractions defined by the IBC protocol and the mechanisms by which they are composed. We first outline the structure of the protocol, including scope, interfaces, and operational requirements. Subsequently, we detail the abstractions defined by the protocol, including modules, ports, clients, connections, channels, packets, and relayers, and describe the subprotocols for opening and closing handshakes, packet relay, edge-case handling, and relayer operations. After explaining the internal structure of the protocol, we define the interface by which applications can utilise IBC, and sketch an example application-level protocol for fungible token transfer. Finally, we recount testing and deployment efforts of the protocol thus far. Appendices include pseudocode for the connection handshake, channel handshake, and packet relay algorithms. diff --git a/archive/papers/2020-05/src/metadata.yaml b/archive/papers/2020-05/src/metadata.yaml new file mode 100644 index 000000000..380415788 --- /dev/null +++ b/archive/papers/2020-05/src/metadata.yaml @@ -0,0 +1,22 @@ +--- +title: 'The Interblockchain Communication Protocol: An Overview' +author: + - name: Christopher Goes + affiliation: Interchain GmbH + location: Berlin, Germany + email: cwgoes@interchain.berlin +keywords: + - ibc + - interblockchain + - dlt +numbersections: yes +lang: en +babel-lang: english +abstract: | + The interblockchain communication protocol (IBC) is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, and authenticated communication between modules on separate distributed ledgers. + IBC is designed for interoperation between heterogenous ledgers arranged in an unknown, dynamic topology, operating with varied consensus algorithms and state machines. The protocol realises this by specifying + the sufficient set of data structures, abstractions, and semantics of a communication protocol which once implemented by participating ledgers will allow them to safely communicate. IBC is payload-agnostic + and provides a cross-ledger asynchronous communication primitive which can be used as a constituent building block by a wide variety of applications. + +... + diff --git a/archive/papers/2020-05/src/paper.md b/archive/papers/2020-05/src/paper.md new file mode 100644 index 000000000..878db392d --- /dev/null +++ b/archive/papers/2020-05/src/paper.md @@ -0,0 +1,63 @@ +# Introduction + +!include src/introduction.md + +# Protocol scope & properties + +!include src/structure.md + +# Host ledger requirements + +!include src/host-requirements.md + +# Protocol structure + +## Clients + +!include src/clients.md + +## Connections + +!include src/connections.md + +## Channels + +!include src/channels.md + +## Relayers + +!include src/relayers.md + +# Usage patterns + +!include src/usage-patterns.md + +# Example application-level module + +!include src/fungible-token-transfer.md + +# Testing & deployment + +!include src/testing-and-deployment.md + +# Acknowledgements + +!include src/acknowledgements.md + +\onecolumn + +# Appendices + +!include src/appendix-a.md + +!include src/appendix-b.md + +!include src/appendix-c.md + +\pagebreak + +\twocolumn + +# References + + diff --git a/archive/papers/2020-05/src/relayers.md b/archive/papers/2020-05/src/relayers.md new file mode 100644 index 000000000..8fb325d4c --- /dev/null +++ b/archive/papers/2020-05/src/relayers.md @@ -0,0 +1,110 @@ +Relayer algorithms are the "physical" connection layer of IBC — off-ledger processes responsible for relaying data between two ledgers running the IBC protocol by scanning the state of each ledger, constructing appropriate datagrams, and executing them on the opposite ledger as allowed by the protocol. + +\vspace{3mm} + +### Motivation + +\vspace{3mm} + +In the IBC protocol, one ledger can only record the intention to send particular data to another ledger — it does not have direct access to a network transport layer. Physical datagram relay must be performed by off-ledger infrastructure with access to a transport layer such as TCP/IP. This standard defines the concept of a *relayer* algorithm, executable by an off-ledger process with the ability to query ledger state, to perform this relay. + +A *relayer* is an off-ledger process with the ability to read the state of and submit transactions to some set of ledgers utilising the IBC protocol. + +\vspace{3mm} + +### Properties + +\vspace{3mm} + +- No exactly-once or deliver-or-timeout safety properties of IBC depend on relayer behaviour (Byzantine relayers are assumed) +- Packet relay liveness properties of IBC depend only on the existence of at least one correct, live relayer +- Relaying can safely be permissionless, all requisite verification is performed by the ledger itself +- Requisite communication between the IBC user and the relayer is minimised +- Provision for relayer incentivisation are not included in the core protocol, but are possible at the application layer + +\vspace{3mm} + +### Basic relayer algorithm + +\vspace{3mm} + +The relayer algorithm is defined over a set of ledgers implementing the IBC protocol. Each relayer may not necessarily have access to read state from and write datagrams to all ledgers in the multi-ledger network (especially in the case of permissioned or private ledgers) — different relayers may relay between different subsets. + +Every so often, although no more frequently than once per block on either ledger, a relayer calculates the set of all valid datagrams to be relayed from one ledger to another based on the state of both ledgers. The relayer must possess prior knowledge of what subset of the IBC protocol is implemented by the ledgers in the set for which they are relaying (e.g. by reading the source code). Datagrams can be submitted individually as single transactions or atomically as a single transaction if the ledger supports it. + +Different relayers may relay between different ledgers — as long as each pair of ledgers has at least one correct and live relayer and the ledgers remain live, all packets flowing between ledgers in the network will eventually be relayed. + +\vspace{3mm} + +### Packets, acknowledgements, timeouts + +\vspace{3mm} + +#### Relaying packets in an ordered channel + +Packets in an ordered channel can be relayed in either an event-based fashion or a query-based fashion. +For the former, the relayer should watch the source ledger for events emitted whenever packets are sent, +then compose the packet using the data in the event log. For the latter, the relayer should periodically +query the send sequence on the source ledger, and keep the last sequence number relayed, so that any sequences +in between the two are packets that need to be queried and then relayed. In either case, subsequently, the relayer process +should check that the destination ledger has not yet received the packet by checking the receive sequence, and then relay it. + +\vspace{3mm} + +#### Relaying packets in an unordered channel + +Packets in an unordered channel can most easily be relayed in an event-based fashion. +The relayer should watch the source ledger for events emitted whenever packets +are send, then compose the packet using the data in the event log. Subsequently, +the relayer should check whether the destination ledger has received the packet +already by querying for the presence of an acknowledgement at the packet's sequence +number, and if one is not yet present the relayer should relay the packet. + +\vspace{3mm} + +#### Relaying acknowledgements + +Acknowledgements can most easily be relayed in an event-based fashion. The relayer should +watch the destination ledger for events emitted whenever packets are received and acknowledgements +are written, then compose the acknowledgement using the data in the event log, +check whether the packet commitment still exists on the source ledger (it will be +deleted once the acknowledgement is relayed), and if so relay the acknowledgement to +the source ledger. + +\vspace{3mm} + +#### Relaying timeouts + +Timeout relay is slightly more complex since there is no specific event emitted when +a packet times-out — it is simply the case that the packet can no longer be relayed, +since the timeout height or timestamp has passed on the destination ledger. The relayer +process must elect to track a set of packets (which can be constructed by scanning event logs), +and as soon as the height or timestamp of the destination ledger exceeds that of a tracked +packet, check whether the packet commitment still exists on the source ledger (it will +be deleted once the timeout is relayed), and if so relay a timeout to the source ledger. + +\vspace{3mm} + +#### Ordering constraints + +There are implicit ordering constraints imposed on the relayer process determining which datagrams must be submitted in what order. For example, a header must be submitted to finalise the stored consensus state and commitment root for a particular height in a light client before a packet can be relayed. The relayer process is responsible for frequently querying the state of the ledgers between which they are relaying in order to determine what must be relayed when. + +\vspace{3mm} + +#### Bundling + +If the host ledger supports it, the relayer process can bundle many datagrams into a single transaction, which will cause them to be executed in sequence, and amortise any overhead costs (e.g. signature checks for fee payment). + +\vspace{3mm} + +#### Race conditions + +Multiple relayers relaying between the same pair of modules and ledgers may attempt to relay the same packet (or submit the same header) at the same time. If two relayers do so, the first transaction will succeed and the second will fail. Out-of-band coordination between the relayers or between the actors who sent the original packets and the relayers is necessary to mitigate this. + +\vspace{3mm} + +#### Incentivisation + +The relay process must have access to accounts on both ledgers with sufficient balance to pay for transaction fees. Relayers may employ application-level methods to recoup these fees, such by including a small payment to themselves in the packet data. + +Any number of relayer processes may be safely run in parallel (and indeed, it is expected that separate relayers will serve separate subsets of the multi-ledger network). However, they may consume unnecessary fees if they submit the same proof multiple times, so some minimal coordination may be ideal (such as assigning particular relayers to particular packets or scanning mempools for pending transactions). diff --git a/archive/papers/2020-05/src/structure.md b/archive/papers/2020-05/src/structure.md new file mode 100644 index 000000000..9ac9f52ce --- /dev/null +++ b/archive/papers/2020-05/src/structure.md @@ -0,0 +1,71 @@ +## Scope + +IBC handles authentication, transport, and ordering of opaque data packets relayed between modules on separate ledgers — ledgers can be run on solo machines, replicated by many nodes running a consensus algorithm, or constructed by any process whose state can be verified. The protocol is defined between modules on two ledgers, but designed for safe simultaneous use between any number of modules on any number of ledgers connected in arbitrary topologies. + +## Interfaces + +IBC sits between modules — smart contracts, other ledger components, or otherwise independently executed pieces of application logic on ledgers — on one side, and underlying consensus protocols, blockchains, and network infrastructure (e.g. TCP/IP), on the other side. + +IBC provides to modules a set of functions much like the functions which might be provided to a module for interacting with another module on the same ledger: sending data packets and receiving data packets on an established connection and channel, in addition to calls to manage the protocol state: opening and closing connections and channels, choosing connection, channel, and packet delivery options, and inspecting connection and channel status. + +IBC requires certain functionalities and properties of the underlying ledgers, primarily finality (or thresholding finality gadgets), cheaply-verifiable consensus transcripts (such that a light client algorithm can verify the results of the consensus process with much less computation & storage than a full node), and simple key/value store functionality. On the network side, IBC requires only eventual data delivery — no authentication, synchrony, or ordering properties are assumed. + +## Operation + +The primary purpose of IBC is to provide reliable, authenticated, ordered communication between modules running on independent host ledgers. This requires protocol logic in the areas of data relay, data confidentiality and legibility, reliability, flow control, authentication, statefulness, and multiplexing. + +\vspace{3mm} + +### Data relay + +\vspace{3mm} + +In the IBC architecture, modules are not directly sending messages to each other over networking infrastructure, but rather are creating messages to be sent which are then physically relayed from one ledger to another by monitoring "relayer processes". IBC assumes the existence of a set of relayer processes with access to an underlying network protocol stack (likely TCP/IP, UDP/IP, or QUIC/IP) and physical interconnect infrastructure. These relayer processes monitor a set of ledgers implementing the IBC protocol, continuously scanning the state of each ledger and requesting transaction execution on another ledger when outgoing packets have been committed. For correct operation and progress in a connection between two ledgers, IBC requires only that at least one correct and live relayer process exists which can relay between the ledgers. + +\vspace{3mm} + +### Data confidentiality and legibility + +\vspace{3mm} + +The IBC protocol requires only that the minimum data necessary for correct operation of the IBC protocol be made available and legible (serialised in a standardised format) to relayer processes, and the ledger may elect to make that data available only to specific relayers. This data consists of consensus state, client, connection, channel, and packet information, and any auxiliary state structure necessary to construct proofs of inclusion or exclusion of particular key/value pairs in state. All data which must be proved to another ledger must also be legible; i.e., it must be serialised in a standardised format agreed upon by the two ledgers. + +\vspace{3mm} + +### Reliability + +\vspace{3mm} + +The network layer and relayer processes may behave in arbitrary ways, dropping, reordering, or duplicating packets, purposely attempting to send invalid transactions, or otherwise acting in a Byzantine fashion, without compromising the safety or liveness of IBC. This is achieved by assigning a sequence number to each packet sent over an IBC channel, which is checked by the IBC handler (the part of the ledger implementing the IBC protocol) on the receiving ledger, and providing a method for the sending ledger to check that the receiving ledger has in fact received and handled a packet before sending more packets or taking further action. Cryptographic commitments are used to prevent datagram forgery: the sending ledger commits to outgoing packets, and the receiving ledger checks these commitments, so datagrams altered in transit by a relayer will be rejected. IBC also supports unordered channels, which do not enforce ordering of packet receives relative to sends but still enforce exactly-once delivery. + +\vspace{3mm} + +### Flow control + +\vspace{3mm} + +IBC does not provide specific protocol-level provisions for compute-level or economic-level flow control. The underlying ledgers are expected to have compute throughput limiting devices and flow control mechanisms of their own such as gas markets. Application-level economic flow control — limiting the rate of particular packets according to their content — may be useful to ensure security properties and contain damage from Byzantine faults. For example, an application transferring value over an IBC channel might want to limit the rate of value transfer per block to limit damage from potential Byzantine behaviour. IBC provides facilities for modules to reject packets and leaves particulars up to the higher-level application protocols. + +\vspace{3mm} + +### Authentication + +\vspace{3mm} + +All data sent over IBC are authenticated: a block finalised by the consensus algorithm of the sending ledger must commit to the outgoing packet via a cryptographic commitment, and the receiving ledger's IBC handler must verify both the consensus transcript and the cryptographic commitment proof that the datagram was sent before acting upon it. + +\vspace{3mm} + +### Statefulness + +\vspace{3mm} + +Reliability, flow control, and authentication as described above require that IBC initialises and maintains certain status information for each datastream. This information is split between three abstractions: clients, connections, and channels. Each client object contains information about the consensus state of the counterparty ledger. Each connection object contains a specific pair of named identifiers agreed to by both ledgers in a handshake protocol, which uniquely identifies a connection between the two ledgers. Each channel, specific to a pair of modules, contains information concerning negotiated encoding and multiplexing options and state and sequence numbers. When two modules wish to communicate, they must locate an existing connection and channel between their two ledgers, or initialise a new connection and channel(s) if none yet exist. Initialising connections and channels requires a multi-step handshake which, once complete, ensures that only the two intended ledgers are connected, in the case of connections, and ensures that two modules are connected and that future datagrams relayed will be authenticated, encoded, and sequenced as desired, in the case of channels. + +\vspace{3mm} + +### Multiplexing + +\vspace{3mm} + +To allow for many modules within a single host ledger to use an IBC connection simultaneously, IBC allows any number of channels to be associated with a single connection. Each channel uniquely identifies a datastream over which packets can be sent in order (in the case of an ordered channel), and always exactly once, to a destination module on the receiving ledger. Channels are usually expected to be associated with a single module on each ledger, but one-to-many and many-to-one channels are also possible. The number of channels per connection is unbounded, facilitating concurrent throughput limited only by the throughput of the underlying ledgers with only a single connection and pair of clients necessary to track consensus information (and consensus transcript verification cost thus amortised across all channels using the connection). diff --git a/archive/papers/2020-05/src/template.latex b/archive/papers/2020-05/src/template.latex new file mode 100644 index 000000000..e30763d58 --- /dev/null +++ b/archive/papers/2020-05/src/template.latex @@ -0,0 +1,337 @@ +\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$babel-lang$,$endif$$if(papersize)$$papersize$paper,$endif$$for(classoption)$$classoption$$sep$,$endfor$,conference]{IEEEtran} +$if(beamerarticle)$ +\usepackage{beamerarticle} % needs to be loaded first +$endif$ + +\usepackage{titlesec} +\titleformat*{\subsection}{\sc} +\titlespacing*{\paragraph}{0pt}{-0.5ex}{-3ex} + +\usepackage{graphicx} +\usepackage{subcaption} +\usepackage{listings} +\lstdefinelanguage{JavaScript}{ + basicstyle=\ttfamily\small, + morekeywords=[1]{break, continue, delete, else, for, function, if, in, + new, return, this, typeof, var, void, while, with}, + % Literals, primitive types, and reference types. + morekeywords=[2]{false, null, true, boolean, number, undefined, + Array, Boolean, Date, Math, Number, String, Object}, + % Built-ins. + morekeywords=[3]{eval, parseInt, parseFloat, escape, unescape}, + sensitive, + morecomment=[s]{/*}{*/}, + morecomment=[l]//, + morecomment=[s]{/**}{*/}, % JavaDoc style comments + morestring=[b]', + morestring=[b]" +}[keywords, comments, strings] + + + +$if(csl-refs)$ +\newlength{\cslhangindent} +\setlength{\cslhangindent}{1.5em} +\newenvironment{cslreferences}% + {$if(csl-hanging-indent)$\setlength{\parindent}{0pt}% + \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}% + {\par} +$endif$ +$if(fontfamily)$ +\usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} +$else$ +\usepackage{lmodern} +$endif$ +$if(linestretch)$ +\usepackage{setspace} +\setstretch{$linestretch$} +$endif$ +\usepackage{amssymb,amsmath} +\usepackage{ifxetex,ifluatex} +\usepackage{fixltx2e} % provides \textsubscript +\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex + \usepackage[$if(fontenc)$$fontenc$$else$T1$endif$]{fontenc} + \usepackage[utf8]{inputenc} +$if(euro)$ + \usepackage{eurosym} +$endif$ +\else % if luatex or xelatex + \ifxetex + \usepackage{mathspec} + \else + \usepackage{fontspec} + \fi + \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase} +$for(fontfamilies)$ + \newfontfamily{$fontfamilies.name$}[$fontfamilies.options$]{$fontfamilies.font$} +$endfor$ +$if(euro)$ + \newcommand{\euro}{€} +$endif$ +$if(mainfont)$ + \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$]{$mainfont$} +$endif$ +$if(sansfont)$ + \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$]{$sansfont$} +$endif$ +$if(monofont)$ + \setmonofont[Mapping=tex-ansi$if(monofontoptions)$,$for(monofontoptions)$$monofontoptions$$sep$,$endfor$$endif$]{$monofont$} +$endif$ +$if(mathfont)$ + \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} +$endif$ +$if(CJKmainfont)$ + \usepackage{xeCJK} + \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} +$endif$ +\fi +% use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +% use microtype if available +\IfFileExists{microtype.sty}{% +\usepackage{microtype} +\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +$if(geometry)$ +\usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} +$endif$ +\usepackage[unicode=true]{hyperref} +$if(colorlinks)$ +\PassOptionsToPackage{usenames,dvipsnames}{color} % color is loaded by hyperref +$endif$ +\hypersetup{ +$if(title-meta)$ + pdftitle={$title-meta$}, +$endif$ +$if(author-meta)$ + pdfauthor={$author-meta$}, +$endif$ +$if(keywords)$ + pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, +$endif$ +$if(colorlinks)$ + colorlinks=true, + linkcolor=$if(linkcolor)$$linkcolor$$else$Maroon$endif$, + citecolor=$if(citecolor)$$citecolor$$else$Blue$endif$, + urlcolor=$if(urlcolor)$$urlcolor$$else$Blue$endif$, +$else$ + pdfborder={0 0 0}, +$endif$ + breaklinks=true} +\urlstyle{same} % don't use monospace font for urls +$if(lang)$ +\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex + \usepackage[shorthands=off,$for(babel-otherlangs)$$babel-otherlangs$,$endfor$main=$babel-lang$]{babel} +$if(babel-newcommands)$ + $babel-newcommands$ +$endif$ +\else + \usepackage{polyglossia} + \setmainlanguage[$polyglossia-lang.options$]{$polyglossia-lang.name$} +$for(polyglossia-otherlangs)$ + \setotherlanguage[$polyglossia-otherlangs.options$]{$polyglossia-otherlangs.name$} +$endfor$ +\fi +$endif$ +$if(natbib)$ +\usepackage{natbib} +\bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} +$endif$ +$if(biblatex)$ +\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} +$for(bibliography)$ +\addbibresource{$bibliography$} +$endfor$ +$endif$ +$if(listings)$ +\usepackage{listings} +$endif$ +$if(lhs)$ +\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} +$endif$ +$if(highlighting-macros)$ +$highlighting-macros$ +$endif$ +$if(verbatim-in-note)$ +\usepackage{fancyvrb} +\VerbatimFootnotes % allows verbatim text in footnotes +$endif$ +$if(tables)$ +\usepackage{longtable,booktabs} +\usepackage{supertabular} +\let\longtable\supertabular +\let\endlongtable\endsupertabular +\let\endhead\relax +% Fix footnotes in tables (requires footnote package) +\IfFileExists{footnote.sty}{\usepackage{footnote}\makesavenoteenv{long table}}{} +$endif$ +$if(graphics)$ +\usepackage{graphicx,grffile} +\makeatletter +\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} +\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} +\makeatother +% Scale images if necessary, so that they will not overflow the page +% margins by default, and it is still possible to overwrite the defaults +% using explicit options in \includegraphics[width, height, ...]{} +\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +$endif$ +$if(links-as-notes)$ +% Make links footnotes instead of hotlinks: +\renewcommand{\href}[2]{#2\footnote{\url{#1}}} +$endif$ +$if(strikeout)$ +\usepackage[normalem]{ulem} +% avoid problems with \sout in headers with hyperref: +\pdfstringdefDisableCommands{\renewcommand{\sout}{}} +$endif$ +$if(indent)$ +$else$ +\IfFileExists{parskip.sty}{% +\usepackage{parskip} +}{% else +\setlength{\parindent}{0pt} +\setlength{\parskip}{6pt plus 2pt minus 1pt} +} +$endif$ +\setlength{\emergencystretch}{3em} % prevent overfull lines +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +$if(numbersections)$ +\setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} +$else$ +\setcounter{secnumdepth}{0} +$endif$ +$if(subparagraph)$ +$else$ +% Redefines (sub)paragraphs to behave more like sections +\ifx\paragraph\undefined\else +\let\oldparagraph\paragraph +\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} +\fi +\ifx\subparagraph\undefined\else +\let\oldsubparagraph\subparagraph +\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} +\fi +$endif$ +$if(dir)$ +\ifxetex + % load bidi as late as possible as it modifies e.g. graphicx + $if(latex-dir-rtl)$ + \usepackage[RTLdocument]{bidi} + $else$ + \usepackage{bidi} + $endif$ +\fi +\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex + \TeXXeTstate=1 + \newcommand{\RL}[1]{\beginR #1\endR} + \newcommand{\LR}[1]{\beginL #1\endL} + \newenvironment{RTL}{\beginR}{\endR} + \newenvironment{LTR}{\beginL}{\endL} +\fi +$endif$ + +% set default figure placement to htbp +\makeatletter +\def\fps@figure{htbp} +\makeatother + +$for(header-includes)$ +$header-includes$ +$endfor$ + +\newcommand*{\TitleFont}{% + \usefont{\encodingdefault}{\rmdefault}{b}{n}% + \fontsize{18}{20}% + \selectfont} + +$if(title)$ +\title{\TitleFont $title$$if(thanks)$\thanks{$thanks$}$endif$} +$endif$ +$if(subtitle)$ +\providecommand{\subtitle}[1]{} +\subtitle{$subtitle$} +$endif$ + +$if(author)$ +\author{ + $for(author)$ + \IEEEauthorblockN{$author.name$} + \IEEEauthorblockA{% + $author.affiliation$ \\ + $author.location$ \\ + $author.email$} + $sep$ \and + $endfor$ +} +$endif$ + +$if(institute)$ +\providecommand{\institute}[1]{} +\institute{$for(institute)$$institute$$sep$ \and $endfor$} +$endif$ +\date{$date$} + +\begin{document} +$if(title)$ +\maketitle +$endif$ +$if(abstract)$ +\begin{abstract} +$abstract$ +\end{abstract} +$endif$ + +$if(keywords)$ +\begin{IEEEkeywords} +$for(keywords)$ + $keywords$$sep$; +$endfor$ +\end{IEEEkeywords} +$endif$ + +$for(include-before)$ +$include-before$ + +$endfor$ +$if(toc)$ +{ +$if(colorlinks)$ +\hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$} +$endif$ +\setcounter{tocdepth}{$toc-depth$} +\tableofcontents +} +$endif$ +$if(lot)$ +\listoftables +$endif$ +$if(lof)$ +\listoffigures +$endif$ +$body$ + +$if(natbib)$ +$if(bibliography)$ +$if(biblio-title)$ +$if(book-class)$ +\renewcommand\bibname{$biblio-title$} +$else$ +\renewcommand\refname{$biblio-title$} +$endif$ +$endif$ +\bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} + +$endif$ +$endif$ +$if(biblatex)$ +\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ + +$endif$ +$for(include-after)$ +$include-after$ + +$endfor$ +\end{document} + diff --git a/archive/papers/2020-05/src/testing-and-deployment.md b/archive/papers/2020-05/src/testing-and-deployment.md new file mode 100644 index 000000000..355dd9154 --- /dev/null +++ b/archive/papers/2020-05/src/testing-and-deployment.md @@ -0,0 +1,3 @@ +A full version of the interblockchain protocol has been implemented in Go in the Cosmos SDK [@ibc_cosmos_sdk], an implementation is in progress in Rust [@ibc_rust], and implementations are planned for other languages in the future. An off-ledger relayer daemon has also been implemented in Go [@relayer_go]. Game of Zones [@game_of_zones], a live test of the initial software release, is currently in progress. Over one hundred simulated zones (separate consensus instances and ledgers) have been successfully linked together [@map_of_zones]. + +Production release and deployment to the Cosmos Network is planned for later this summer. As IBC is a permissionless, opt-in protocol, adoption will be dependent on ledgers voluntarily electing to support the specification, in full or in part. Adoption of IBC does not require connection to the Cosmos Hub, usage of any particular token, or even usage of any other piece of Cosmos software — IBC can be implemented on top of other state machine frameworks such as Substrate [@substrate], or by standalone ledgers using custom logic — adherence to the correct protocol is both necessary and sufficient for successful interoperation. diff --git a/archive/papers/2020-05/src/usage-patterns.md b/archive/papers/2020-05/src/usage-patterns.md new file mode 100644 index 000000000..b7f18582f --- /dev/null +++ b/archive/papers/2020-05/src/usage-patterns.md @@ -0,0 +1,47 @@ +## Call receiver + +Essential to the functionality of the IBC handler is an interface to other modules +running on the same ledger, so that it can accept requests to send packets and can +route incoming packets to modules. This interface should be as minimal as possible +in order to reduce implementation complexity and requirements imposed on host ledgers. + +For this reason, the core IBC logic uses a receive-only call pattern that differs +slightly from the intuitive dataflow. As one might expect, modules call into the IBC handler to create +connections, channels, and send packets. However, instead of the IBC handler, upon receipt +of a packet from another ledger, selecting and calling into the appropriate module, +the module itself must call `recvPacket` on the IBC handler (likewise for accepting +channel creation handshakes). When `recvPacket` is called, the IBC handler will check +that the calling module is authorised to receive and process the packet (based on included proofs and +known state of connections / channels), perform appropriate state updates (incrementing +sequence numbers to prevent replay), and return control to the module or throw on error. +The IBC handler never calls into modules directly. + +Although a bit counterintuitive to reason about at first, this pattern has a few notable advantages: + +- It minimises requirements of the host ledger, since the IBC handler need not understand how to call + into other modules or store any references to them. +- It avoids the necessity of managing a module lookup table in the handler state. +- It avoids the necessity of dealing with module return data or failures. If a module does not want to + receive a packet (perhaps having implemented additional authorisation on top), it simply never calls + `recvPacket`. If the routing logic were implemented in the IBC handler, the handler would need to deal + with the failure of the module, which is tricky to interpret. + +It also has one notable disadvantage: without an additional abstraction, the relayer logic becomes more complex, since off-ledger +relayer processes will need to track the state of multiple modules to determine when packets +can be submitted. + +For this reason, ledgers may implement an additional IBC "routing module" which exposes a call dispatch interface. + +## Call dispatch + +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 ledger) are relayed directly +to the routing module, which then looks up the appropriate module (owning the channel and 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 routing module upon receipt of a valid packet). + +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/archive/v0_3_1_IBC.pdf b/archive/v0_3_1_IBC.pdf new file mode 100644 index 0000000000000000000000000000000000000000..4a73eeb340c0b00c7e3392bd0d5ea3e207613f2a GIT binary patch literal 131 zcmWN`yAi`63;@ucDOe!Jd}P4e2myh+B={oiBGbp!E8bPU+{Z_@IS<~IdiMEvRbFn} znHCyv#YZ7^X)$`1+|aB6Bj23?~YbcBW literal 0 HcmV?d00001 diff --git a/assets/interchain-standards-image.jpg b/assets/interchain-standards-image.jpg new file mode 100755 index 000000000..ae610b28a --- /dev/null +++ b/assets/interchain-standards-image.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:948d72f8ce9f7758316c8ecd11c8045cf3a4918514b4077e2e37d8f5f4e1f301 +size 373917