Add documentation of overview, pallet-evm, pallet-ethereum (#234)

* Add documentation of overview, pallet-evm, pallet-ethereum

* Fix: inaccurate one-to-one mapping description

docs/.vuepress/config.js

@@ -15,8 +15,14 @@ module.exports = {
     docsDir: 'docs',
     editLinkText: '',
     lastUpdated: false,
-    nav: [],
-    sidebar: {}
+    nav: [
+      { text: 'API reference', link: 'https://paritytech.github.io/frontier/rustdocs/pallet_evm' }
+    ],
+    sidebar: [
+      'overview',
+      'frame/evm',
+      'frame/ethereum'
+    ]
   },
 
   plugins: [

docs/frame/ethereum.md

@@ -0,0 +1,4 @@
+# Ethereum pallet
+
+The Ethereum pallet enables full Ethereum block emulation, allowing
+Ethereum RPCs to be activated.

docs/frame/evm.md

@@ -0,0 +1,45 @@
+# EVM pallet
+
+The EVM module allows unmodified EVM code to be executed in a
+Substrate-based blockchain.
+
+## EVM engine
+
+The EVM module uses
+[`SputnikVM`](https://github.com/rust-blockchain/evm) as the
+underlying EVM engine.
+
+## Execution lifecycle
+
+There are a separate set of accounts managed by the EVM
+module. Substrate based accounts can call the EVM Module to deposit or
+withdraw balance from the Substrate base-currency into a different
+balance managed and used by the EVM module. Once a user has populated
+their balance, they can create and call smart contracts using this
+module.
+
+Substrate accounts and EVM external accounts are mapped via
+customizable conversion functions.
+
+## EVM module vs Ethereum network
+
+The EVM module should be able to produce nearly identical results
+compared to the Ethereum mainnet, including gas cost and balance
+changes.
+
+Observable differences include:
+
+* The available length of block hashes may not be 256 depending on the
+  configuration of the System module in the Substrate runtime.
+* Difficulty and coinbase, which do not make sense in this module and
+  is currently hard coded to zero.
+
+We currently do not aim to make unobservable behaviors, such as state
+root, to be the same. We also don't aim to follow the exact same
+transaction / receipt format. However, given one Ethereum transaction
+and one Substrate account's private key, one should be able to convert
+any Ethereum transaction into a transaction compatible with this
+module.
+
+The gas configurations are configurable. Right now, a pre-defined
+Istanbul hard fork configuration option is provided.

docs/index.md

@@ -2,8 +2,8 @@
 home: true
 heroImage: https://v1.vuepress.vuejs.org/hero.png
 tagline: Ethereum compatibility layer for Substrate.
-actionText: Code →
-actionLink: https://github.com/paritytech/frontier
+actionText: Overview →
+actionLink: overview.md
 features:
 - title: EVM Contract
   details: Frontier allows you to run EVM contracts natively in Substrate, tightly integrated with the rest of the Substrate ecosystem.

docs/overview.md

@@ -0,0 +1,59 @@
+# Overview
+
+The Frontier suite contains several crates that can be used
+independently.
+
+## EVM execution only
+
+In many situations, a Substrate blockchain may only want to include
+EVM execution capatibilities. In this way, it functions similarly to
+`pallet-contracts`, integrates with Substrate better and is less
+intrusive. The module, and its EVM execution capatibilties, can be
+added or removed at any moment via forkless upgrades. With EVM
+execution only, Substrate uses its account model fully and signs
+transactions on behalf of EVM accounts.
+
+In this model, however, Ethereum RPCs are not available, and dapps
+must rewrite their frontend using the Substrate API.
+
+If this is the intended way of usage, take a look at the
+[`pallet-evm`](./frame/evm.md) documentation.
+
+## Post-block generation
+
+On other situations, a full emulation of Ethereum may be desired so
+that Ethereum RPCs become available. In this model, a full Ethereum
+block is emulated within the Substrate runtime, and is generated
+post-block for the consumption rest of the APIs. In addition to
+Substrate account signing, traditional Ethereum transactions are also
+processed and validated.
+
+If this is the intended way of usage, take a look at the
+[`pallet-ethereum`](./frame/ethereum.md) documentation.
+
+## Pre-block feeding
+
+An Ethereum-based blockchain can use the pre-block feeding strategy to
+migrate to Substrate. In the post-block generation model, the Ethereum
+block is generated *after* runtime execution. In the pre-block feeding
+model, the Ethereum block is feeded in *before* runtime
+execution.
+
+A blockchain can first use pre-block feeding with empty extrinsic
+requirement. In this way, because no other external information is
+feeded, combined with a suitable consensus engine, one Ethereum block
+will have an exact corresponding Substrate block. This is called the
+**wrapper block** strategy, and it allows Frontier to function as a
+normal Ethereum client.
+
+With a sufficient number of the network running a Frontier node, the
+blockchain can then initiate a hard fork, allowing extrinsic to be
+added in. From there on, the blockchain is migrated to Substrate and
+can enjoy Substrate-specific features like on-chain governance and
+forkless upgrade.
+
+A complete in-storage pre-block feeding requires using Substrate's
+child storage. It can also be implemented using the stateless client
+strategy to eliminate that need.
+
+Pre-block feeding is still work-in-progress.