From 8f58d23a99e39984986ab86bd6710d10a31ef27d Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 16 Aug 2018 12:05:14 -0400 Subject: [PATCH 1/5] Implement into documentation --- docs/intro/README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/intro/README.md diff --git a/docs/intro/README.md b/docs/intro/README.md new file mode 100644 index 000000000..0fac0cee3 --- /dev/null +++ b/docs/intro/README.md @@ -0,0 +1,46 @@ +# Introduction + +## Preliminary + +### Tendermint Core & the Application Blockchain Interface (ABCI) + +Tendermint consists of two chief technical components: a blockchain consensus +engine and a generic application interface. The consensus engine, called +Tendermint Core, ensures that the same transactions are recorded on every machine +in the same order. The application interface, called the Application Blockchain +Interface (ABCI), enables the transactions to be processed in any programming +language. + +Tendermint has evolved to be a general purpose blockchain consensus engine that +can host arbitrary application states. Since Tendermint can replicate arbitrary +applications, it can be used as a plug-and-play replacement for the consensus +engines of other blockchains. Ethermint is such an example of an ABCI application +replacing Ethereum's PoW via Tendermint's consensus engine. + +Another example of a cryptocurrency application built on Tendermint is the Cosmos +network. Tendermint is able to decompose the blockchain design by offering a very +simple API (ie. the ABCI) between the application process and consensus process. + +## What is Ethermint + +Ethermint is a high throughput PoS blockchain that is fully compatible and +interoperable with Ethereum. In other words, it allows for running vanilla Ethereum +on top of [Tendermint](https://github.com/tendermint/tendermint) consensus via +the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/). This allows developers +to have all the desired features of Ethereum, while at the same time benefit +from Tendermint’s PoS implementation. + +Here’s a glance at some of the key features of Ethermint: + +* Web3 compatibility +* High throughput +* Horizontal scalability +* Transaction finality + +Ethermint achieves these key features by implementing Tendermint's ABCI application +interface, leveraging modules and mechanisms implemented by the Cosmos SDK, utilizing +[Geth](https://github.com/ethereum/go-ethereum) as a library by implementing all +necessary interfaces, and finally by exposing a fully compatible Web3 RPC layer +allowing developers to leverage existing Ethereum ecosystem tooling and software +to seamlessly deploy smart contracts and interact with the rest of the Cosmos +ecosystem! From 63c160977bd78da23180b92221258984bd3f55ef Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Mon, 20 Aug 2018 08:33:08 -0400 Subject: [PATCH 2/5] Add transaction doc/spec --- docs/spec/transactions/README.md | 67 ++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/spec/transactions/README.md diff --git a/docs/spec/transactions/README.md b/docs/spec/transactions/README.md new file mode 100644 index 000000000..924bc787f --- /dev/null +++ b/docs/spec/transactions/README.md @@ -0,0 +1,67 @@ +# Transactions + +> NOTE: The specification documented below is still highly active in development +and subject to change. + +## Routing + +Ethermint needs to parse and handle transactions routed for both the EVM and for +the Cosmos hub. We attempt to achieve this by mimicking [Geth's](https://github.com/ethereum/go-ethereum) `Transaction` structure and utilizing +the `Payload` as the potential encoding of a Cosmos-routed transaction. What +designates this encoding, and ultimately routing, is the `Transaction.Recipient` +address -- if this address matches some global unique predefined and configured +address, we regard it as a transaction meant for Cosmos, otherwise, the transaction +is a pure Ethereum transaction and will be executed in the EVM. + +For Cosmos routed transactions, the `Transaction.Payload` will contain an +embedded encoded type: `EmbeddedTx`. This structure is analogous to the Cosmos +SDK `sdk.StdTx`. If a client wishes to send an `EmbeddedTx`, it must first encode +the embedded transaction, and then encode the embedding `Transaction`. + +__Note__: The `Transaction` and `EmbeddedTx` types utilize the [Amino](https://github.com/tendermint/go-amino) object serialization protocol and as such, +the `Transaction` is not an exact replica of what will be found in Ethereum. Our +goal is to utilize Geth as a library, at least as much as possible, so it should +be expected that these types and the operations you may perform on them will keep +in line with Ethereum. + +Being that Ethermint implements the ABCI application interface, as transactions +are sent they are passed through a series of handlers. Once such handler, `runTx`, +is responsible for invoking the `TxDecoder` which performs the business logic of +properly deserializing raw transaction bytes into either an Ethereum transaction +or a Cosmos transaction. + +## Transactions & Messages + +The SDK distinguishes between transactions (`sdk.Tx`) and messages (`sdk.Msg`). +A `sdk.Tx` is a list of `sdk.Msg`s wrapped with authentication and fee data. Users +can create messages containing arbitrary information by implementing the `sdk.Msg` +interface. + +In Ethermint, the `Transaction` type implements the Cosmos SDK `sdk.Tx` interface. +It addition, it implements the Cosmos SDK `sdk.Msg` interface for the sole purpose +of being to perform basic validation checks in the `BaseApp`. It, however, has +no distinction between transactions and messages. + +The `EmbeddedTx`, being analogous to the Cosmos SDK `sdk.StdTx`, implements the +Cosmos SDK `sdk.Tx` interface. + +## Signatures + +Ethermint supports [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) +signatures. However, just as in Cosmos, Ethermint will support multiple signers. +A client is expected to sign the `Transaction` just as in Ethereum, however, the +`EmbeddedTx` contains a canonical signature structure that itself contains the +signature and other information such as an account's sequence number. The sequence +number is expected to increment every time a message is signed by a given account. +This prevents "replay attacks", where the same message could be executed over and +over again. + +An `EmbeddedTx` list of signatures must much the unique list of addresses returned by +each message's `GetSigners` call. In addition, the address of first signer of the +`EmbeddedTx` is responsible for paying the fees and must also match the address of +the signer of the embedding `Transaction`. As such, there will be one duplicate +signature. + +## Gas & Fees + +TODO From 94b84b484c2fcbb42daf99b209c710c227ea9538 Mon Sep 17 00:00:00 2001 From: Jack Zampolin Date: Mon, 20 Aug 2018 19:21:02 -0700 Subject: [PATCH 3/5] Change copy in intro/README --- docs/intro/README.md | 54 ++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/intro/README.md b/docs/intro/README.md index 0fac0cee3..61ef3acb3 100644 --- a/docs/intro/README.md +++ b/docs/intro/README.md @@ -1,6 +1,34 @@ # Introduction -## Preliminary +## What is Ethermint + +Ethermint is a high throughput PoS blockchain that is fully compatible and +interoperable with Ethereum. In other words, it allows for running vanilla Ethereum +on top of [Tendermint](https://github.com/tendermint/tendermint) consensus via +the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/). This allows developers +to have all the desired features of Ethereum, while at the same time benefit +from Tendermint’s PoS implementation. Also, because it is built on top of the +Cosmos SDK, it will be able to exchange value with the rest of the Cosmos Ecosystem. + +Here’s a glance at some of the key features of Ethermint: + +* Web3 compatibility +* High throughput +* Horizontal scalability +* Transaction finality + +Ethermint enables these key features through: + +* Implementing Tendermint's ABCI application interface to manage the base Blockchain +* Leveraging [modules](https://github.com/cosmos/cosmos-sdk/tree/master/x/) and other mechanisms implemented by the Cosmos SDK +* Utilizing [`geth`](https://github.com/ethereum/go-ethereum) as a library to avoid code reuse and improve maintainability +* Exposing a fully compatible Web3 RPC layer for interacting with the system + +The sum of these features allows developers to leverage existing Ethereum ecosystem +tooling and software to seamlessly deploy smart contracts which interact with the rest of the Cosmos +ecosystem! + +## In-depth Topics ### Tendermint Core & the Application Blockchain Interface (ABCI) @@ -20,27 +48,3 @@ replacing Ethereum's PoW via Tendermint's consensus engine. Another example of a cryptocurrency application built on Tendermint is the Cosmos network. Tendermint is able to decompose the blockchain design by offering a very simple API (ie. the ABCI) between the application process and consensus process. - -## What is Ethermint - -Ethermint is a high throughput PoS blockchain that is fully compatible and -interoperable with Ethereum. In other words, it allows for running vanilla Ethereum -on top of [Tendermint](https://github.com/tendermint/tendermint) consensus via -the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/). This allows developers -to have all the desired features of Ethereum, while at the same time benefit -from Tendermint’s PoS implementation. - -Here’s a glance at some of the key features of Ethermint: - -* Web3 compatibility -* High throughput -* Horizontal scalability -* Transaction finality - -Ethermint achieves these key features by implementing Tendermint's ABCI application -interface, leveraging modules and mechanisms implemented by the Cosmos SDK, utilizing -[Geth](https://github.com/ethereum/go-ethereum) as a library by implementing all -necessary interfaces, and finally by exposing a fully compatible Web3 RPC layer -allowing developers to leverage existing Ethereum ecosystem tooling and software -to seamlessly deploy smart contracts and interact with the rest of the Cosmos -ecosystem! From 712d1d7c34b2c10e272c1fc685dd237edb616002 Mon Sep 17 00:00:00 2001 From: Jack Zampolin Date: Tue, 21 Aug 2018 15:22:50 -0700 Subject: [PATCH 4/5] Update README --- README.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 854683bd0..25731bd0b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -[![](https://godoc.org/github.com/cosmos/ethermint?status.svg)](http://godoc.org/github.com/cosmos/ethermint) [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/ethermint)](https://goreportcard.com/report/github.com/cosmos/ethermint) [![CircleCI](https://circleci.com/gh/cosmos/ethermint.svg?style=svg)](https://circleci.com/gh/cosmos/ethermint) - +[![CircleCI](https://circleci.com/gh/cosmos/ethermint.svg?style=svg)](https://circleci.com/gh/cosmos/ethermint) +[![](https://godoc.org/github.com/cosmos/ethermint?status.svg)](http://godoc.org/github.com/cosmos/ethermint) [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/ethermint)](https://goreportcard.com/report/github.com/cosmos/ethermint) # Ethermint __**WARNING:**__ Ethermint is under VERY ACTIVE DEVELOPMENT and should be treated as pre-alpha software. This means it is not meant to be run in production, its APIs are subject to change without warning and should not be relied upon, and it should not be used to hold any value. We will remove this warning when we have a release that is stable, secure, and properly tested. @@ -13,18 +13,26 @@ __**WARNING:**__ Ethermint is under VERY ACTIVE DEVELOPMENT and should be treate ### Implementation -- [x] Have a working implementation that can parse and validate the existing ETH Chain and persist it in a Tendermint store -- [ ] Benchmark this implementation to ensure performance -- [ ] Allow the Ethermint EVM to interact with other [Cosmos SDK modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/app3.md) -- [ ] Implement the Web3 APIs as a Cosmos Light Client for Ethermint -- [ ] Ethermint is a full Cosmos SDK application and can be deployed as it's own zone +#### Completed +- Have a working implementation that can parse and validate the existing ETH Chain and persist it in a Tendermint store +- Implement Ethereum transactions in the CosmosSDK + +#### Current Work +- Implement web3 compatible API layer +- Implement the EVM as a CosmosSDK module +- Allow the Ethermint EVM to interact with other [Cosmos SDK modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/app3.md) + +#### Next Steps +- Hard spoon enablement: The ability to export state from `geth` and import token balances into Ethermint +- Ethermint is a functioning Cosmos SDK application and can be deployed as its own zone +- Full web3 compatibility will enable existing Ethereum applications to use Ethermint ### Building Ethermint To build, execute the following commands: ```bash -# To build the binary and put the results in ./build +# To build the binary and put the resulting binary in ./build $ make tools deps build # To build the project and install it in $GOBIN From 38c228cc1a2b238270a46a2ca3f452e7912a9fa8 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Wed, 22 Aug 2018 09:53:27 -0400 Subject: [PATCH 5/5] Address PR reviews in regards to transaction sigs --- docs/spec/transactions/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/spec/transactions/README.md b/docs/spec/transactions/README.md index 924bc787f..2121cee42 100644 --- a/docs/spec/transactions/README.md +++ b/docs/spec/transactions/README.md @@ -48,19 +48,19 @@ Cosmos SDK `sdk.Tx` interface. ## Signatures Ethermint supports [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) -signatures. However, just as in Cosmos, Ethermint will support multiple signers. -A client is expected to sign the `Transaction` just as in Ethereum, however, the -`EmbeddedTx` contains a canonical signature structure that itself contains the -signature and other information such as an account's sequence number. The sequence -number is expected to increment every time a message is signed by a given account. -This prevents "replay attacks", where the same message could be executed over and -over again. +signatures. A `Transaction` is expected to have a single signature for Ethereum +routed transactions. However, just as in Cosmos, Ethermint will support multiple +signers for `EmbeddedTx` Cosmos routed transactions. Signatures over the +`Transaction` type are identical to Ethereum. However, the `EmbeddedTx` contains +a canonical signature structure that contains the signature itself and other +information such as an account's sequence number. The sequence number is expected +to increment every time a message is signed by a given account. This, in addition +to the chain ID, prevents "replay attacks", where the same message could be +executed over and over again. -An `EmbeddedTx` list of signatures must much the unique list of addresses returned by -each message's `GetSigners` call. In addition, the address of first signer of the -`EmbeddedTx` is responsible for paying the fees and must also match the address of -the signer of the embedding `Transaction`. As such, there will be one duplicate -signature. +An `EmbeddedTx` list of signatures must much the unique list of addresses returned +by each message's `GetSigners` call. In addition, the address of first signer of +the `EmbeddedTx` is responsible for paying the fees. ## Gas & Fees