Skip to content
This repository has been archived by the owner on Nov 30, 2021. It is now read-only.

evm: module specification #538

Merged
merged 25 commits into from
Dec 9, 2020
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
update parameters and genesis
  • Loading branch information
fedekunze committed Dec 7, 2020
commit 2189e71e7d8ed421481acf4040b6ae0fe99c3f11
14 changes: 7 additions & 7 deletions x/evm/spec/01_concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,14 @@ type GenesisState struct {
The `GenesisAccount` type corresponds to an adaptation of the Ethereum `GenesisAccount` type. Its
main difference is that the one on Ethermint uses a custom `Storage` type that uses a slice instead of maps for the evm `State`,and that it doesn't contain the private key field.

It is also important to note that since the `auth` and `bank` SDK modules manage the accounts and balance state, the `Address` must correspond to an `EthAccount` that is stored in the auth AccountKeeper and the balance must match the balance of the `EvmDenom` token denomination defined on the `GenesisState`'s `Param`.
It is also important to note that since the `auth` and `bank` SDK modules manage the accounts and balance state, the `Address` must correspond to an `EthAccount` that is stored in the `auth`'s module `AccountKeeper` and the balance must match the balance of the `EvmDenom` token denomination defined on the `GenesisState`'s `Param`. The values for the address and the balance amount maintain the same format as the ones from the SDK to make manual inspections easier on the genesis.json.

```go
type GenesisAccount struct {
Address ethcmn.Address `json:"address"`
Balance *big.Int `json:"balance"`
Code hexutil.Bytes `json:"code,omitempty"`
Storage Storage `json:"storage,omitempty"`
Address string `json:"address"`
Balance sdk.Int `json:"balance"`
Code hexutil.Bytes `json:"code,omitempty"`
Storage Storage `json:"storage,omitempty"`
}
```

Expand All @@ -68,7 +68,7 @@ type TransactionLogs struct {

### Chain Config

The `ChainConfig` is a custom type that contains the same fields as the go-ethereum ChainConfig
The `ChainConfig` is a custom type that contains the same fields as the go-ethereum `ChainConfig`
parameters, but using `sdk.Int` types instead of `*big.Int`. It also defines additional YAML tags
for pretty printing.

Expand Down Expand Up @@ -100,7 +100,7 @@ type ChainConfig struct {
IstanbulBlock sdk.Int `json:"istanbul_block" yaml:"istanbul_block"` // Istanbul switch block (< 0 no fork, 0 = already on istanbul)
MuirGlacierBlock sdk.Int `json:"muir_glacier_block" yaml:"muir_glacier_block"` // Eip-2384 (bomb delay) switch block (< 0 no fork, 0 = already activated)

YoloV1Block sdk.Int `json:"yoloV1_block" yaml:"yoloV1_block"` // YOLO v1: https://github.com/ethereum/EIPs/pull/2657 (Ephemeral testnet)
YoloV2Block sdk.Int `json:"yoloV2_block" yaml:"yoloV2_block"` // YOLO v2: https://github.com/ethereum/EIPs/pull/2657 (Ephemeral testnet)
EWASMBlock sdk.Int `json:"ewasm_block" yaml:"ewasm_block"` // EWASM switch block (< 0 no fork, 0 = already activated)
}
```
Expand Down
30 changes: 21 additions & 9 deletions x/evm/spec/05_abci.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,29 @@ order: 5

## BeginBlock

The EVM module `BeginBlock` logic is executed prior to handling the state transitions from the transactions. The main objective of this function is to:
The EVM module `BeginBlock` logic is executed prior to handling the state transitions from the
transactions. The main objective of this function is to:

* Set the block header hash to the module state. This workaround is due to the fact that until the `v0.34.0` Tendermint version it wasn't possible to query and subscribe to a block by hash.
* Set the block header hash to the module state. This workaround is due to the fact that until the
`v0.34.0` Tendermint version it wasn't possible to query and subscribe to a block by hash.

* Reset bloom filter and block transaction count. These variables, which are fields of the EVM `Keeper`, are updated on every EVM transaction.
* Reset bloom filter and block transaction count. These variables, which are fields of the EVM
`Keeper`, are updated on every EVM transaction.

## EndBlock

The EVM module `EndBlock` logic occurs after executing all the state transitions from the transactions. The main objective of this function is to:

* Update the accounts. This operation retrieves the current account and balance values for each state object and updates the account represented on the stateObject with the given values. This is done since the account might have been updated by transactions other than the ones defined by the `x/evm` module, such as bank send or IBC transfers.
* Commit dirty state objects and delete empty ones from the store. This operation writes the contract code to the key value store in the case of contracts and updates the account's balance, which is set to the the bank module's `Keeper`.
* Clear account cache. This clears cache of state objects to handle account changes outside of the EVM.
* Store the block bloom to state. This is due for Web3 compatibility as the Ethereum headers contain this type as a field. The Ethermint RPC uses this query to construct an Ethereum Header from a Tendermint Header.
The EVM module `EndBlock` logic occurs after executing all the state transitions from the
transactions. The main objective of this function is to:

* Update the accounts. This operation retrieves the current account and balance values for each
state object and updates the account represented on the stateObject with the given values. This is
done since the account might have been updated by transactions other than the ones defined by the
`x/evm` module, such as bank send or IBC transfers.
* Commit dirty state objects and delete empty ones from the store. This operation writes the
contract code to the key value store in the case of contracts and updates the account's balance,
which is set to the the bank module's `Keeper`.
* Clear account cache. This clears cache of state objects to handle account changes outside of the
EVM.
* Store the block bloom to state. This is due for Web3 compatibility as the Ethereum headers contain
this type as a field. The Ethermint RPC uses this query to construct an Ethereum Header from a
Tendermint Header.
20 changes: 16 additions & 4 deletions x/evm/spec/07_params.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@ order: 7

The evm module contains the following parameters:

| Key | Type | Default Value |
|------------|--------|---------------|
| `EVMDenom` | string | `aphoton` |
| Key | Type | Default Value |
|----------------|--------|---------------|
| `EVMDenom` | string | `aphoton` |
| `EnableCreate` | bool | `true` |
| `EnableCall` | bool | `true` |

## EVMDenom
## EVM denom

The evm denomination parameter defines the token denomination used on the EVM state transitions and
gas consumption for EVM messages.
Expand All @@ -27,3 +29,13 @@ For example, on Ethereum, the `evm_denom` would be `ETH`. In the case of Ethermi
::: danger
SDK applications that want to import the EVM module as a dependency will need to set their own `evm_denom` (i.e not `"aphoton"`).
:::

## Enable Create

The enable create parameter toggles state transitions that use the `vm.Create` function. When the
parameter is disabled, it will prevent all contract creation functionality.

## Enable Transfer

The enable transfer toggles state transitions that use the `vm.Call` function. When the parameter is
disabled, it will prevent transfers between accounts and executing a smart contract call.