laconicd/docs/core/encoding.md
Federico Kunze d4fe9b234c
docs: vuepress setup and section titles (#311)
* vuepress

* docs: vuepress setup and TODOs

* doc scripts

* update Makefile and gitignore

* more docs updates

* gitignore

* metamask instructions

* update image

* updates

* updates from call

* docs: vuepress config and home.vue (#350)

* update uncles return (#337)

* x/evm: fix EndBlock consensus failure (#334)

* add test for sending tx w/ 21000 gas

* improve rpc transfer test

* use ctx in EndBlock

* UpdateAccounts and ClearStateObjects with passed in context

* log ethereum address on error

Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com>
Co-authored-by: Federico Kunze <federico.kunze94@gmail.com>

* update Ethermint color variables

* add header and footer logo

* tweak config.js

* WIP custom homepage.vue

* add layout to docs/README

* update color variables

* add eth logo black and white

* tweak docs/README

* update logo and logo-bw svg

* bump 1.0.167

* homepage → home

* add icon-code, icon-rocket

* layout: home, remove configurable frontmatter: label, read, use

* clean up config.js

* bump 1.0.168

* fix missing comma from resolving conflicts

* update sidebar, config nav, path

* remove left whitespace on the header and footer logos

* clean up home.vue, docs/README

* update ethermint forum url in footer.links

* comment out custom true to enable searchbar in subpages

* remove external link icon for Guides

* comments, revert custom true

* clean up config.js, add specifications icon

Co-authored-by: noot <36753753+noot@users.noreply.github.com>
Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com>
Co-authored-by: Federico Kunze <federico.kunze94@gmail.com>

* final touches

Co-authored-by: Cyrus Goh <hello@lovincyrus.com>
Co-authored-by: noot <36753753+noot@users.noreply.github.com>
2020-07-02 04:22:45 -04:00

3.4 KiB

Encoding

The codec is used everywhere in the Cosmos SDK to encode and decode structs and interfaces. The specific codec used in the Cosmos SDK is called go-amino. {synopsis}

Pre-requisite Readings

Encoding Formats

The Cosmos SDK utilizes two binary wire encoding protocols, Amino and Protocol Buffers, where Amino is an object encoding specification. It is a subset of Proto3 with an extension for interface support. See the Proto3 spec for more information on Proto3, which Amino is largely compatible with (but not with Proto2).

Due to Amino having significant performance drawbacks, being reflection-based, and not having any meaningful cross-language/client support, Protocol Buffers, specifically gogoprotobuf, is being used in place of Amino. Note, this process of using Protocol Buffers over Amino is still an ongoing process.

Binary wire encoding of types in the Cosmos SDK can be broken down into two main categories, client encoding and store encoding. Client encoding mainly revolves around transaction processing and signing, whereas store encoding revolves around types used in state-machine transitions and what is ultimately stored in the Merkle tree.

For store encoding, protobuf definitions can exist for any type and will typically have an Amino-based "intermediary" type. Specifically, the protobuf-based type definition is used for serialization and persistence, whereas the Amino-based type is used for business logic in the state-machine where they may converted back-n-forth. Note, the Amino-based types may slowly be phased-out in the future so developers should take note to use the protobuf message definitions where possible.

In the codec package, there exists two core interfaces, Marshaler and ProtoMarshaler, where the former encapsulates the current Amino interface except it operates on types implementing the latter instead of generic interface{} types.

In addition, there exists three implementations of Marshaler. The first being AminoCodec, where both binary and JSON serialization is handled via Amino. The second being ProtoCodec, where both binary and JSON serialization is handled via Protobuf. Finally, HybridCodec, a codec that utilizes Protobuf for binary serialization and Amino for JSON serialization. The HybridCodec is typically the codec that used in majority in situations as it's easier to use for client and state serialization.

This means that modules may use Amino or Protobuf encoding but the types must implement ProtoMarshaler. If modules wish to avoid implementing this interface for their types, they may use an Amino codec directly.

Amino

Every module uses an Amino codec to serialize types and interfaces. This codec typically has types and interfaces registered in that module's domain only (e.g. messages), but there are exceptions like x/gov. Each module exposes a RegisterCodec function that allows a user to provide a codec and have all the types registered. An application will call this method for each necessary module.

Protobuf

RLP

Next {hide}

Learn about events {hide}