Merge pull request #471 from cosmos/bez/468-initial-docs

R4R: Implement Initial Spec/Documentation

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

docs/intro/README.md

@@ -0,0 +1,50 @@
+# Introduction
+
+## 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)
+
+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.

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. 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.
+
+## Gas & Fees
+
+TODO