# EVMOS research

- https://evmos.org
- https://docs.evmos.org/about/intro/overview.html
- https://github.com/evmos/evmos
___

## What is Evmos

Evmos is a scalable, high-throughput Proof-of-Stake blockchain that is fully compatible and interoperable with Ethereum.
It's built using the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/) which runs on top of [Tendermint Core](https://github.com/tendermint/tendermint) consensus engine.

### Features

- Web3 and EVM compatibility
- High throughput via [Tendermint Core](https://github.com/tendermint/tendermint)
- Horizontal scalability via [IBC](https://cosmos.network/ibc)
- Fast transaction finality

### Evmos enables these key features by:

- Implementing Tendermint Core's Application Blockchain Interface ([ABCI](https://github.com/tendermint/tendermint/blob/v0.34.x/spec/abci/README.md)) to manage the blockchain
- [Leveraging modules](https://docs.cosmos.network/main/building-modules/intro.html) and other mechanisms implemented by the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/)
- Utilizing **geth** as a library to promote code reuse and improve maintainability
- Exposing a fully compatible Web3 JSON-RPC layer for interacting with existing Ethereum clients and tooling (Metamask, Remix, Truffle, etc)

___

## Tendermint

**Tendermint** is software for securely and consistently replicating an application on many machines.
Securely mean that Tendermint works even if up to 1/3 of machines fail in arbitrary ways.
Consistently mean that every non-faulty machine sees the same transaction log and computes the same state.
Secure and consistent replication is a fundamental problem in distributed systems.

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.
Evmos is such an example of an ABCI application replacing Ethereum's PoW via Tendermint's consensus engine.

## BFT Consensus

> BFT - [Byzantine-Fault Tolerant](https://en.wikipedia.org/wiki/Byzantine_fault)

The ability to tolerate machines failing in arbitrary ways, including becoming malicious, is known as Byzantine fault tolerance (BFT).
It can only tolerate up to a 1/3 of failures, but those failures can include arbitrary behaviour - including hacking and malicious attacks.

The theory of **BFT** is decades old, but software implementations have only became popular recently.
Blockchain technology is just a reformalization of **BFT** in a more modern setting, with emphasis on peer-to-peer networking and cryptographic authentication.

## Consensus Overview

Tendermint is an easy-to-understand, mostly asynchronous, BFT consensus protocol. The protocol follows a simple state machine that looks like this:


Participants in the protocol are called **validators**; they take turns proposing blocks of transactions and voting on them.

Blocks are committed in a chain, with one block at each **height**.
A block may fail to be committed, in which case the protocol moves to the next round, and a new validator gets to propose a block for that height.
Two stages of voting are required to successfully commit a block; it called **pre-vote** and **pre-commit**.
A block is committed when more than 2/3 of validators pre-commit for the same block in the same round.

Validators may fail to commit a block for a number of reasons; the current proposer may be offline, or the network may be slow.
Tendermint allows them to establish that a validator should be skipped.
Validators wait a small amount of time to receive a complete proposal block from the proposer before voting to move to the next round.

## Stake

In many systems, not all validators will have the same "weight" in the consensus protocol.
Thus, we are not so much interested in one-third or two-thirds of the validators, but in those proportions of the total voting power, which may not be uniformly distributed across individual validators.

Since Tendermint can replicate arbitrary applications, it is possible to define a currency, and denominate the voting power in that currency.
When voting power is denominated in a native currency, the system is often referred to as Proof-of-Stake.
Validators can be forced, by logic in the application, to "bond" their currency holdings in a security deposit that can be destroyed if they're found to misbehave in the consensus protocol.
This adds an economic element to the security of the protocol, allowing one to quantify the cost of violating the assumption that less than one-third of voting power is Byzantine.

**The Cosmos Network** is designed to use this Proof-of-Stake mechanism across an array of cryptocurrencies implemented as ABCI applications.

The following diagram is Tendermint in a (technical) nutshell.


___

## Cosmos SDK

- https://docs.cosmos.network/main
- Cosmos Whitepaper (https://cosmos.network/about/whitepaper)
- https://tutorials.cosmos.network/academy/2-cosmos-concepts/

The Cosmos SDK is an open-source framework for building multi-asset public Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as permissioned Proof-of-Authority (PoA) blockchains. Blockchains built with the Cosmos SDK are generally referred to as application-specific blockchains.

                ^  +-------------------------------+  ^
                |  |                               |  |
                |  |  State-machine = Application  |  |
                |  |                               |  |   Built with Cosmos SDK
                |  |            ^      +           |  |
                |  +----------- | ABCI | ----------+  v
                |  |            +      v           |  ^
                |  |                               |  |
Blockchain Node |  |           Consensus           |  |
                |  |                               |  |
                |  +-------------------------------+  |   Tendermint Core
                |  |                               |  |
                |  |           Networking          |  |
                |  |                               |  |
                v  +-------------------------------+  v

Here is a simplified view of how a transaction is processed by the application of each full-node when it is received in a valid block:

                                      +
                                      |
                                      |  Transaction relayed from the full-node's
                                      |  Tendermint engine to the node's application
                                      |  via DeliverTx
                                      |
                                      |
                +---------------------v--------------------------+
                |                 APPLICATION                    |
                |                                                |
                |     Using baseapp's methods: Decode the Tx,    |
                |     extract and route the message(s)           |
                |                                                |
                +---------------------+--------------------------+
                                      |
                                      |
                                      |
                                      +---------------------------+
                                                                  |
                                                                  |
                                                                  |  Message routed to
                                                                  |  the correct module
                                                                  |  to be processed
                                                                  |
                                                                  |
+----------------+  +---------------+  +----------------+  +------v----------+
|                |  |               |  |                |  |                 |
|  AUTH MODULE   |  |  BANK MODULE  |  | STAKING MODULE |  |   GOV MODULE    |
|                |  |               |  |                |  |                 |
|                |  |               |  |                |  | Handles message,|
|                |  |               |  |                |  | Updates state   |
|                |  |               |  |                |  |                 |
+----------------+  +---------------+  +----------------+  +------+----------+
                                                                  |
                                                                  |
                                                                  |
                                                                  |
                                       +--------------------------+
                                       |
                                       | Return result to Tendermint
                                       | (0=Ok, 1=Err)
                                       v

___

## List of Modules

https://docs.cosmos.network/main/modules

Here are some production-grade modules that can be used in Cosmos SDK applications, along with their respective documentation:

- [Auth](https://docs.cosmos.network/main/modules/auth) - Authentication of accounts and transactions for Cosmos SDK applications.
- [Authz](https://docs.cosmos.network/main/modules/authz) - Authorization for accounts to perform actions on behalf of other accounts.
- [Bank](https://docs.cosmos.network/main/modules/bank) - Token transfer functionalities.
- [Capability](https://docs.cosmos.network/main/modules/capability) - Object capability implementation.
- [Crisis](https://docs.cosmos.network/main/modules/crisis) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).
- [Distribution](https://docs.cosmos.network/main/modules/distribution) - Fee distribution, and staking token provision distribution.
- [Evidence](https://docs.cosmos.network/main/modules/evidence) - Evidence handling for double signing, misbehaviour, etc.
- [Feegrant](https://docs.cosmos.network/main/modules/feegrant) - Grant fee allowances for executing transactions.
- [Governance](https://docs.cosmos.network/main/modules/gov) - On-chain proposals and voting.
- [Mint](https://docs.cosmos.network/main/modules/mint) - Creation of new units of staking token.
- [Params](https://docs.cosmos.network/main/modules/params) - Globally available parameter store.
- [Slashing](https://docs.cosmos.network/main/modules/slashing) - Validator punishment mechanisms.
- [Staking](https://docs.cosmos.network/main/modules/staking) - Proof-of-Stake layer for public blockchains.
- [Upgrade](https://docs.cosmos.network/main/modules/upgrade) - Software upgrades handling and coordination.
- [NFT](https://docs.cosmos.network/main/modules/nft) - NFT module implemented based on [ADR43](https://docs.cosmos.network/main/architecture/adr-043-nft-module.html).
- [Consensus](https://docs.cosmos.network/main/modules/consensus) - Consensus module for modifying Tendermint's ABCI consensus params.

## Evmos Modules

- [claims](https://docs.evmos.org/modules/claims/) - Rewards status and claiming process for the mainnet release.
- [epochs](https://docs.evmos.org/modules/epochs/) - Executes custom state transitions every period (aka epoch).
- [erc20](https://docs.evmos.org/modules/erc20/) - Trustless, on-chain bidirectional internal conversion of tokens between Evmos' EVM and Cosmos runtimes.
- [evm](https://docs.evmos.org/modules/evm/) (opens new window) - Smart Contract deployment and execution on Cosmos
- [feemarket](https://docs.evmos.org/modules/feemarket/) (opens new window) - Fee market implementation based on the EIP1559 specification.
- [revenue](https://docs.evmos.org/modules/revenue/) - Split EVM transaction fees between block proposer and smart contract developers.
- [incentives](https://docs.evmos.org/modules/incentives/) - Incentivize user interaction with governance-approved smart contracts.
- [inflation](https://docs.evmos.org/modules/inflation/) - Mint tokens and allocate them to staking rewards, usage incentives and community pool.
- [vesting](https://docs.evmos.org/modules/vesting/) - Vesting accounts with lockup and clawback capabilities.

## x/staking

> The module enables **Cosmos SDK**-based blockchain to support an **advanced Proof-of-Stake** (**PoS**) system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system.

## States

### [Pool](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L285-L306)

Pool is used for tracking bonded and not-bonded token supply of the bond denomination.

### [Validator](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L78-L127)

Validators can have one of three statuses

- **Unbonded**: The validator is not in the active set. They cannot sign blocks and do not earn rewards. They can receive delegations.
- **Bonded**: Once the validator receives sufficient bonded tokens they automatically join the active set during EndBlock and their status is updated to Bonded.
- **Unbonding**: When a validator leaves the active set, either by choice or due to slashing, jailing or tombstoning, an unbonding of all their delegations begins.

### [Delegation](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L187-L205)

Delegations are identified by combining DelegatorAddr (the address of the delegator) with the ValidatorAddr

### [UnbondingDelegation](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L207-L220)

Shares in a Delegation can be unbonded, but they must for some time exist as an UnbondingDelegation, where shares can be reduced if Byzantine behavior is detected.

### [Redelegation](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L245-L283)

The bonded tokens worth of a Delegation may be instantly redelegated from a source validator to a different validator (destination validator). However when this occurs they must be tracked in a Redelegation object, whereby their shares can be slashed if their tokens have contributed to a Byzantine fault committed by the source validator.

## State Transitions

### Validators

State transitions in validators are performed on every EndBlock in order to check for changes in the active ValidatorSet.

A validator can be **Unbonded**, **Unbonding** or **Bonded**. **Unbonded** and **Unbonding** are collectively called **Not Bonded**.
A validator can move directly between all the states, except for from **Bonded** to **Unbonded**.

#### Not bonded to Bonded

The following transition occurs when a validator's ranking in the ValidatorPowerIndex surpasses that of the LastValidator.

#### Bonded to Unbonding

When a validator begins the unbonding process

#### Unbonding to Unbonded

A validator moves from unbonding to unbonded when the ValidatorQueue object moves from bonded to unbonded

#### Jail/Unjail

When a validator is jailed it is effectively removed from the Tendermint set. this process may be also be reversed. the following operations occur:

### Messages
- MsgCreateValidator
- MsgEditValidator
- MsgDelegate
- MsgUndelegate
- MsgCancelUnbondingDelegation
- MsgBeginRedelegate
- MsgUpdateParams

## x/erc20

The x/erc20 module enables the Evmos Hub to support a trustless, on-chain bidirectional internal conversion of tokens between Evmos' EVM and Cosmos runtimes, specifically the x/evm and x/bank modules. This allows token holders on Evmos to instantaneously convert their native Cosmos sdk.Coins (in this document referred to as "Coin(s)") to ERC-20 (aka "Token(s)") and vice versa, while retaining fungibility with the original asset on the issuing environment/runtime (EVM or Cosmos) and preserving ownership of the ERC-20 contract.