forked from cerc-io/laconicd-deprecated
docs: updates (#590)
* gas docs * add period * pending state docs * format * fix links * add more to pendingstate docs * add more to gas docs * add hardspoon doc * minor fix to pendingstate doc * note on rlp encoding * usecase doc * update encoding doc * gas docs * hard spoon and reorder * fix links * encoding * pending state * final touches * update intro * use cases and resources * typo Co-authored-by: Federico Kunze <federico.kunze94@gmail.com> Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com>
This commit is contained in:
Daniel Choi
co-authored by
Federico Kunze
Federico Kunze
Federico Kunze
Federico Kunze
parent
b2735dcd13
commit
71090323c0
@@ -9,5 +9,6 @@ parent:
|
||||
This repository contains reference documentation on the core concepts of Ethermint.
|
||||
|
||||
1. [Encoding](./encoding.md)
|
||||
2. [Pending State](./pending_state.md)
|
||||
|
||||
After reading the core concepts, head on to the [guides](../guides/README.md) to learn how to use Ethereum tooling with Ethermint.
|
||||
|
||||
+19
-50
@@ -4,70 +4,39 @@ order: 1
|
||||
|
||||
# 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}
|
||||
Learn about the encoding formats used on Ethermint. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Cosmos SDK Encoding](https://docs.cosmos.network/master/core/encoding.html) {prereq}
|
||||
- [Ethereum RLP](https://eth.wiki/en/fundamentals/rlp) {prereq}
|
||||
|
||||
## Encoding Formats
|
||||
|
||||
The Cosmos SDK utilizes two binary wire encoding protocols, [Amino](https://github.com/tendermint/go-amino/)
|
||||
and [Protocol Buffers](https://developers.google.com/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](https://developers.google.com/protocol-buffers/docs/proto3)
|
||||
for more information on Proto3, which Amino is largely compatible with (but not with Proto2).
|
||||
### Protocol Buffers
|
||||
|
||||
Due to Amino having significant performance drawbacks, being reflection-based, and
|
||||
not having any meaningful cross-language/client support, Protocol Buffers, specifically
|
||||
[gogoprotobuf](https://github.com/gogo/protobuf/), 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.
|
||||
The Cosmos [Stargate](https://stargate.cosmos.network/) release introduces
|
||||
[protobuf](https://developers.google.com/protocol-buffers) as the main encoding format for both
|
||||
client and state serialization. All the EVM module structs that are used for state and clients
|
||||
(transaction messages, genesis, query services, etc) will be implemented as protocol buffer messages.
|
||||
|
||||
### 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.
|
||||
The Cosmos SDK also supports the legacy Amino encoding format for backwards compatibility with
|
||||
previous versions, specially for client encoding. Ethermint will not support Amino in the EVM module
|
||||
once the migration to SDK `v0.40` is finalized.
|
||||
|
||||
### Protobuf
|
||||
### RLP
|
||||
|
||||
<!-- TODO: -->
|
||||
Recursive Length Prefix ([RLP](https://eth.wiki/en/fundamentals/rlp)), is an encoding/decoding algorithm that serializes a message and
|
||||
allows for quick reconstruction of encoded data. Ethermint uses RLP to encode/decode Ethereum
|
||||
messages for JSON-RPC handling to conform messages to the proper Ethereum format. This allows
|
||||
messages to be encoded and decoded in the exact format as Ethereum's.
|
||||
|
||||
## RLP
|
||||
|
||||
<!-- TODO: -->
|
||||
Each message type defined on the EVM module define the `EncodeRLP` and `DecodeRLP` methods which
|
||||
implement the `rlp.Encoder` and `rlp.Decoder` interfaces respectively. The RLP encode method is used
|
||||
to sign bytes and transactions in `RLPSignBytes` and `Sign`.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn how to deploy a Solidity smart contract on Ethermint using [Truffle](./../guides/truffle.md) {hide}
|
||||
Learn how [pending state](./pending_state.md) is handled on Ethermint. {hide}
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
<!--
|
||||
order: 2
|
||||
-->
|
||||
|
||||
# Pending State
|
||||
|
||||
Learn how Ethermint handles pending state queries. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Tendermint Mempool](https://docs.tendermint.com/master/tendermint-core/mempool.htm) {prereq}
|
||||
|
||||
## Ethermint vs Ethereum
|
||||
|
||||
In Ethereum, pending blocks are generated as they are queued for production by miners. These pending
|
||||
blocks include pending transactions that are picked out by miners, based on the highest reward paid
|
||||
in gas. This mechanism exists as block finality is not possible on the Ethereum network. Blocks are
|
||||
committed with probabilistic finality, which means that transactions and blocks become less likely
|
||||
to become reverted as more time (and blocks) passes.
|
||||
|
||||
Ethermint is designed quite differently on this front as there is no concept of a "pending state".
|
||||
Ethermint uses [Tendermint Core](https://docs.tendermint.com/) BFT consensus which provides instant
|
||||
finality for transaction. For this reason, Etheremint does not require a pending state mechanism, as
|
||||
all (if not most) of the transactions will be committed to the next block (avg. block time on Cosmos chains is ~8s). However, this causes a
|
||||
few hiccups in terms of the Ethereum Web3-compatible queries that can be made to pending state.
|
||||
|
||||
Another significant difference with Ethereum, is that blocks are produced by validators or block producers, who include transactions from their local mempool into blocks in a
|
||||
first-in-first-out (FIFO) fashion. Transactions on Ethermint cannot be ordered or cherry picked out from the Tendermint node [mempool](https://docs.tendermint.com/master/tendermint-core/mempool.html#transaction-ordering).
|
||||
|
||||
## Pending State Queries
|
||||
|
||||
Ethermint will make queries which will account for any unconfirmed transactions present in a node's
|
||||
transaction mempool. A pending state query made will be subjective and the query will be made on the
|
||||
target node's mempool. Thus, the pending state will not be the same for the same query to two
|
||||
different nodes.
|
||||
|
||||
### RPC Calls on Pending Transactions
|
||||
|
||||
- [`eth_getBalance`](./../basics/json_rpc.md#eth_getbalance)
|
||||
- [`eth_getTransactionCount`](./../basics/json_rpc.md#eth-gettransactioncount)
|
||||
- [`eth_getBlockTransactionCountByNumber`](./../basics/json_rpc.md#eth-getblocktransactioncountbynumber)
|
||||
- [`eth_getBlockByNumber`](./../basics/json_rpc.md#eth-getblockbynumber)
|
||||
- [`eth_getTransactionByHash`](./../basics/json_rpc.md#eth-gettransactionbyhash)
|
||||
- [`eth_getTransactionByBlockNumberAndIndex`](./../basics/json_rpc.html#eth-gettransactionbyblockhashandindex)
|
||||
- [`eth_sendTransaction`](./../basics/json_rpc.md#eth-sendtransaction)
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn how to deploy a Solidity smart contract on Ethermint using [Truffle](./../guides/truffle.md) {hide}
|
||||
Reference in New Issue
Block a user