From 8e9615a40313e78dcf320c3b07e15954982778bd Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Tue, 17 Apr 2018 12:59:09 +0200 Subject: [PATCH] Pluralize --- docs/spec/ibc/README.md | 16 ++++++---------- docs/spec/ibc/{appendix.md => appendices.md} | 10 ++++++++++ 2 files changed, 16 insertions(+), 10 deletions(-) rename docs/spec/ibc/{appendix.md => appendices.md} (98%) diff --git a/docs/spec/ibc/README.md b/docs/spec/ibc/README.md index 9378ba93c..e542b8b1a 100644 --- a/docs/spec/ibc/README.md +++ b/docs/spec/ibc/README.md @@ -30,13 +30,9 @@ IBC was first outlined in the [Cosmos Whitepaper](https://github.com/cosmos/cosm 1. Timeout 1. Handling Byzantine Failures 1. **[Conclusion](conclusion.md)** - -**[Appendix A: Encoding Libraries](appendix.md#appendix-a-encoding-libraries)** - -**[Appendix B: IBC Queue Format](appendix.md#appendix-b-ibc-queue-format)** - -**[Appendix C: Merkle Proof Format](appendix.md#appendix-c-merkle-proof-formats)** - -**[Appendix D: Universal IBC Packets](appendix.md#appendix-d-universal-ibc-packets)** - -**[Appendix E: Tendermint Header Proofs](appendix.md#appendix-e-tendermint-header-proofs)** +1. **[Appendices](appendices.md)** + 1. [Appendix A: Encoding Libraries](appendices.md#appendix-a-encoding-libraries) + 1. [Appendix B: IBC Queue Format](appendices.md#appendix-b-ibc-queue-format) + 1. [Appendix C: Merkle Proof Format](appendices.md#appendix-c-merkle-proof-formats) + 1. [Appendix D: Universal IBC Packets](appendices.md#appendix-d-universal-ibc-packets) + 1. [Appendix E: Tendermint Header Proofs](appendices.md#appendix-e-tendermint-header-proofs) diff --git a/docs/spec/ibc/appendix.md b/docs/spec/ibc/appendices.md similarity index 98% rename from docs/spec/ibc/appendix.md rename to docs/spec/ibc/appendices.md index bd277ff70..2a19e4368 100644 --- a/docs/spec/ibc/appendix.md +++ b/docs/spec/ibc/appendices.md @@ -4,6 +4,8 @@ ## Appendix A: Encoding Libraries +{ figure out what encoding IBC actually uses } + The specification has focused on semantics and functionality of the IBC protocol. However in order to facilitate the communication between multiple implementations of the protocol, we seek to define a standard syntax, or binary encoding, of the data structures defined above. Many structures are universal and for these, we provide one standard syntax. Other structures, such as _Hh , Uh , _and _Xh_ are tied to the consensus engine and we can define the standard encoding for tendermint, but support for additional consensus engines must be added separately. Finally, there are some aspects of the messaging, such as the envelope to post this data (fees, nonce, signatures, etc.), which is different for every chain, and must be known to the relay, but are not important to the IBC algorithm itself and left undefined. In defining a standard binary encoding for all the "universal" components, we wish to make use of a standardized library, with efficient serialization and support in multiple languages. We considered two main formats: ethereum's rlp[[6](./footnotes.md#6)] and google's protobuf[[7](./footnotes.md#7)]. We decided for protobuf, as it is more widely supported, is more expressive for different data types, and supports code generation for very efficient (de)serialization codecs. It does have a learning curve and more setup to generate the code from the type specifications, but the ibc data types should not change often and this code generation setup only needs to happen once per language (and can be exposed in a common repo), so this is not a strong counter-argument. Efficiency, expressiveness, and wider support rule in its favor. It is also widely used in gRPC and in many microservice architectures. @@ -14,6 +16,8 @@ For the following appendixes, the data structure specifications will be in proto ## Appendix B: IBC Queue Format +{ include queue details here instead of in the other section } + The foundational data structure of the IBC protocol are the message queues stored inside each chain. We start with a well-defined binary representation of the keys and values used in these queues. The encodings mirror the semantics defined above: _key = _(_remote id, [send|receipt], [head|tail|index])_ @@ -28,6 +32,8 @@ See [binary format as protobuf specification](./protobuf/queue.proto) ## Appendix C: Merkle Proof Formats +{ link to the implementation } + A merkle tree (or a trie) generates one hash that can prove every element of the tree. Generating this hash starts with hashing the leaf nodes. Then hashing multiple leaf nodes together to get the hash of an inner node (two or more, based on degree k of the k-ary tree). And continue hashing together the inner nodes at each level of the tree, until it reaches a root hash. Once you have a known root hash, you can prove key/value belongs to this tree by tracing the path to the value and revealing the (k-1) hashes for all the paths we did not take on each level. If this is new to you, you can read a basic introduction[[10](./footnotes.md#10)]. There are a number of different implementations of this basic idea, using different hash functions, as well as prefixes to prevent second preimage attacks (differentiating leaf nodes from inner nodes). Rather than force all chains that wish to participate in IBC to use the same data store, we provide a data structure that can represent merkle proofs from a variety of data stores, and provide for chaining proofs to allow for sub-trees. While searching for a solution, we did find the chainpoint proof format[[11](./footnotes.md#11)], which inspired this design significantly, but didn't (yet) offer the flexibility we needed. @@ -44,12 +50,16 @@ See [binary format as protobuf specification](./protobuf/merkle.proto) ## Appendix D: Universal IBC Packets +{ what is this } + The structures above can be used to define standard encodings for the basic IBC transactions that must be exposed by a blockchain: _IBCreceive_, _IBCreceipt_,_ IBCtimeout_, and _IBCcleanup_. As mentioned above, these are not complete transactions to be posted as is to a blockchain, but rather the "data" content of a transaction, which must also contain fees, nonce, and signatures. The other IBC transaction types _IBCregisterChain_, _IBCupdateHeader_, and _IBCchangeValidators_ are specific to the consensus engine and use unique encodings. We define the tendermint-specific format in the next section. See [binary format as protobuf specification](./protobuf/messages.proto) ## Appendix E: Tendermint Header Proofs +{ is this finalized? } + **TODO: clean this all up** This is a mess now, we need to figure out what formats we use, define go-wire, etc. or just point to the source???? Will do more later, need help here from the tendermint core team.