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>

docs/basics/README.md

@@ -13,5 +13,6 @@ This repository contains reference documentation on the basic concepts of Etherm
 3. [Lifecycle of a transaction](./transactions.md)
 4. [Photon](./photon.md)
 5. [JSON-RPC Server](./json_rpc.md)
+6. [Hard Spoon](./hard_spoon.md)
 
 After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material.

docs/basics/accounts.md

@@ -73,7 +73,7 @@ curl -X GET "<NODE_IP>/auth/accounts/eth1f8rqrfwut7ngkxwth0gt99h0lxnxsp09ngvzwl"
 The Cosmos SDK Keyring output (i.e `ethermintcli keys`) only supports addresses and public keys in Bech32 format.
 :::
 
-To retrieve the Ethereum hex address using Web3, use the JSON-RPC `eth_accounts` endpoint:
+To retrieve the Ethereum hex address using Web3, use the JSON-RPC [`eth_accounts`](./json_rpc.md#eth-accounts) endpoint:
 
 ```bash
 # query against a local node

docs/basics/gas.md

@@ -6,23 +6,88 @@ order: 3
 
 Learn about the differences between `Gas` and `Fees` in Ethereum and Cosmos. {synopsis}
 
-## Introduction to `Gas` in the SDK
+## Pre-requisite Readings
 
-<!-- TODO: -->
+- [Cosmos SDK Gas](https://docs.cosmos.network/master/basics/gas-fees.html) {prereq}
+- [Ethereum Gas](https://ethereum.org/en/developers/docs/gas/) {prereq}
+
+The concept of Gas represents the amount of computational effort required to execute specific operations on the state machine.
+
+Gas was created on Ethereum to disallow the EVM (Ethereum Virtual Machine) from running infinite
+loops by allocating a small amount of monetary value into the system. A unit of gas, usually in a
+form as a fraction of the native coin, is consumed for every operation on the EVM and requires a
+user to pay for these operations. These operations consist in state transitions such as sending a
+transaction or calling a contract.
+
+Exactly like Ethereum, Cosmos utilizes the concept of gas and this is how Cosmos tracks the resource
+usage of operations during execution. Operations on Cosmos are represented as read or writes done to the chain's store.
+
+In Cosmos, a fee is calculated and charged to the user during a message execution. This fee is
+calculated from the sum of all gas consumed in an message execution:
+
+```
+fee = gas * gas price
+```
+
+In both networks, gas is used to make sure that operations do not require an excess amount of
+computational power to complete and as a way to deter bad-acting users from spamming the network.
+
+## Cosmos SDK `Gas`
+
+In the Cosmos SDK, gas is tracked in the main `GasMeter` and the `BlockGasMeter`:
+
+- `GasMeter`: keeps track of the gas consumed during executions that lead to state transitions. It is reset on every transaction  execution.
+- `BlockGasMeter`: keeps track of the gas consumed in a block and enforces that the gas does not go over a predefined limit. This limit is defined in the Tendermint consensus parameters and can be changed via governance parameter change proposals.
+
+More information regarding gas in Cosmos SDK can be found [here](https://docs.cosmos.network/master/basics/gas-fees.html).
 
 ## Matching EVM Gas consumption
 
-<!-- TODO: -->
+Ethermint is an EVM-compatible chain that supports Ethereum Web3 tooling. For this reason, gas
+consumption must be equitable in order to accurately calculate the state transition hashes and exact
+the behaviour that would be seen on the main Ethereum network (main net).
 
-## Gas refunds
+In Cosmos, there are types of operations that are not triggered by transactions that can also result in state transitions. Concrete examples are the  `BeginBlock` and `EndBlock` operations and the `AnteHandler` checks, which might also read and write to the store before running the state transition from a transaction.
 
-<!-- TODO: -->
+### `BeginBlock` and `EndBlock`
 
-## AnteHandler
+These operations are defined by the Tendermint Core's Application Blockchain Interface (ABCI) and are defined by each Cosmos SDK module. As their name suggest, they are executed at the beginning and at the end of each block processing respectively (i.e pre and post transaction execution). Since these operations are not reflected on Ethereum, to match the the gas consumption we reset the main `GasMeter` to 0 on Ethermint's EVM module.
 
-The `AnteHandler` is a special `handler` that is run for every transaction during `CheckTx` and `DeliverTx`, before the `handler` of each `message` in the transaction. `AnteHandler`s have a different signature than `handler`s
+### `AnteHandler`
 
-<!-- TODO: -->
+The Cosmos SDK [`AnteHandler`](https://docs.cosmos.network/master/basics/gas-fees.html#antehandler)
+performs basic checks prior to transaction execution. These checks are usually signature
+verification, transaction field validation, transaction fees, etc.
+
+Because the gas calculated in Ethermint is done by the `IntrinsicGas` method from go-ethereum, a
+special `AnteHandler` that is customized for EVM transaction fee verification is required. This
+allows Ethermint to generate the expected gas costs for operations done in the network and scale the
+gas costs as it would in the Ethereum network.
+
+## Gas Refunds
+
+In Ethereum, gas can be specified prior to execution and the remaining gas will be refunded back to
+the user if any gas is left over - should fail with out of gas if not enough gas was provided. In
+Ethermint, the concept of gas refunds does not exist and the fees paid is not refunded in part back
+to the user. The fees exacted on a transaction will be collected by the validator and no refunds are
+issued. Thus, it is extremely important to use the correct gas.
+
+To prevent overspending on fees, providing the `--gas-adjustment` flag for a cosmos transactions
+will determine the fees automatically. Also the `eth_estimateGas` rpc call can be used to manually
+get the correct gas costs for a transaction.
+
+## 0 Fee Transactions
+
+In Cosmos, a minimum gas price is not enforced by the `AnteHandler` as the `min-gas-prices` is
+checked against the local node/validator. In other words, the minimum fees accepted are determined
+by the validators of the network, and each validator can specify a different value for their fees.
+This potentially allows end users to submit 0 fee transactions if there is at least one single
+validator that is willing to include transactions with `0` gas price in their blocks proposed.
+
+For this same reason, in Ethermint it is possible to send transactions with `0` fees for transaction
+types other than the ones defined by the `evm` module. EVM module transactions cannot have `0` fees
+as gas is required inherently by Ethereum. This check is done by the evm transactions
+`ValidateBasic` function as well as on the custom `AnteHandler` defined by Ethermint.
 
 ## Next {hide}
 

docs/basics/hard_spoon.md

@@ -0,0 +1,17 @@
+<!--
+order: 6
+-->
+
+# Hard Spoon
+
+Learn about Ethermint's Hard Spoon functionality. {synopsis}
+
+## Hard Spoon on Ethermint
+
+A [hard spoon](https://blog.cosmos.network/introducing-the-hard-spoon-4a9288d3f0df) is the migration of the snapshot of a target blockchain's state into a new chain. The state of a network can be imported (or "scooped") onto a separate chain to accurately replicate the account balances and other information from the state.
+
+Ethermint's Hard Spoon tool (currently under specification) is targeted to import the state of the Ethereum mainnet to replicate the state for the given accounts. This will allow anyone on the Ethereum network to import their contracts into Ethermint.
+
+## Next {hide}
+
+Learn about the [encoding](./../core/encoding.md) formats used on Ethermint {hide}

docs/basics/json_rpc.md

@@ -895,4 +895,4 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"personal_ecRecover","params":["0
 
 ## Next {hide}
 
-Learn about the [encoding](./../core/encoding.md) formats used on Ethermint {hide}
+Learn about the Ethermint [Hard Spoon](./hard_spoon.md) functionality {hide}

docs/basics/transactions.md

@@ -20,9 +20,9 @@ responsible for performing preliminary message execution business logic such as
 signature verification, etc. This is particular to Cosmos SDK routed transactions. Ethereum routed
 transactions will bypass this as the EVM handles the same business logic.
 
-Ethereum routed transactions coming from a web3 source are expected to be RLP encoded, however all
+Ethereum routed transactions coming from a Web3 source are expected to be [RLP](./../core/encoding.md#rlp) encoded, however all
 internal interaction between Ethermint and Tendermint will utilize one of the supported encoding
-formats: Protobuf, Amino or Hybrid of the previous two.
+formats: [Protobuf](./../core/encoding.md#protocol-buffers) and [Amino](./../core/encoding.md#amino).
 
 ## Transaction formats