imp(docs): Add more info on replay protection and EVM access control (#…

…165) Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
evmos · Jul 26, 2024 · 7ea8525 · 7ea8525
1 parent 0fefce1
commit 7ea8525
Show file tree

Hide file tree

Showing 7 changed files with 118 additions and 23 deletions.
diff --git a/docs/protocol/concepts/chain-id.mdx b/docs/protocol/concepts/chain-id.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Chain ID
@@ -22,22 +22,22 @@ follows the format of `identifier_EIP155-version` format.
 
 ### Mainnet
 
-| Name                                            | Chain ID                                      | Identifier | EIP155 Number                         | Version Number                              | Active |
+| Name                                            | Chain ID                                      | Identifier | EIP-155 Number                         | Version Number                              | Active |
 | ----------------------------------------------- | --------------------------------------------- | ---------- | ------------------------------------- | ------------------------------------------- | -------|
 | Evmos <ProjectValue keyword="version_number" /> |  <Highlighter pretext="evmos_" keyword="chain_id" postText="-2" /> | `evmos`    | <Highlighter keyword="chain_id" /> |  <Highlighter keyword="version_number" /> | ✅ |
 | Evmos 1                                         | <Highlighter pretext="evmos_" keyword="chain_id" postText="-1" />  | `evmos`    | <Highlighter keyword="chain_id" /> | `1`                                         | 🚫 |
 
 ### Testnet
 
-| Name                              | Chain ID                                              | Identifier | EIP155 Number                                 | Version Number                                      | Active |
+| Name                              | Chain ID                                              | Identifier | EIP-155 Number                                 | Version Number                                      | Active |
 | --------------------------------- | ----------------------------------------------------- | ---------- | --------------------------------------------- | --------------------------------------------------- | ------- |
 | Evmos Public Testnet              |  <Highlighter pretext="evmos_" keyword="testnet_chain_id" postText="-4" /> | `evmos`    |  <Highlighter keyword="testnet_chain_id" /> |  <Highlighter keyword="testnet_version_number" /> | ✅ |
 | Evmos Public Testnet              | <Highlighter pretext="evmos_" keyword="testnet_chain_id" postText="-3" /> | `evmos`    |  <Highlighter keyword="testnet_chain_id" /> | `3`                                                 | 🚫 |
 | Olympus Mons Incentivized Testnet | <Highlighter pretext="evmos_" keyword="testnet_chain_id" postText="-2" /> | `evmos`    |  <Highlighter keyword="testnet_chain_id" /> | `2`                                                 | 🚫 |
 | Arsia Mons Testnet                | <Highlighter pretext="evmos_" keyword="testnet_chain_id" postText="-1" /> | `evmos`    |  <Highlighter keyword="testnet_chain_id" /> | `1`                                                 | 🚫 |
 
 :::tip
-You can also lookup the [EIP155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) `Chain ID` by referring
+You can also look up the [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) `Chain ID` by referring
 to [chainlist.org](https://chainlist.org/).
 :::
 
@@ -47,18 +47,18 @@ to [chainlist.org](https://chainlist.org/).
 
 Every chain must have a unique identifier or `chain-id`. Tendermint requires each application to
 define its own `chain-id` in the [genesis.json fields](https://docs.tendermint.com/master/spec/core/genesis.html#genesis-fields).
- However, in order to comply with both EIP155 and Cosmos standard for chain upgrades, Evmos-compatible chains must implement
+ However, to comply with both EIP-155 and Cosmos standard for chain upgrades, Evmos-compatible chains must implement
   a special structure for their chain identifiers.
 
 ## Structure
 
 The Evmos Chain ID contains 3 main components
 
 - **Identifier**: Unstructured string that defines the name of the application.
-- **EIP155 Number**: Immutable [EIP155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) `CHAIN_ID` that
+- **EIP-155 Number**: Immutable [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) `CHAIN_ID` that
  defines the replay attack protection number.
 - **Version Number**: Is the version number (always positive) that the chain is currently running.
-This number **MUST** be incremented every time the chain is upgraded or forked in order to avoid network or consensus errors.
+This number **MUST** be incremented every time the chain is upgraded or forked to avoid network or consensus errors.
 
 ### Format
 
@@ -70,7 +70,7 @@ The format for specifying and Evmos compatible chain-id in genesis is the follow
 
 The following table provides an example where the second row corresponds to an upgrade from the first one:
 
-| ChainID        | Identifier | EIP155 Number | Version Number |
+| ChainID        | Identifier | EIP-155 Number | Version Number |
 | -------------- | ---------- | ------------- | -------------- |
 | `evmos_9000-1` | evmos      | 9000          | 1              |
 | `evmos_9000-2` | evmos      | 9000          | 2              |

diff --git a/docs/protocol/concepts/gas-and-fees.md b/docs/protocol/concepts/gas-and-fees.md
@@ -11,7 +11,7 @@ that is compatible with the Cosmos SDK.
 
 Therefore this overview explains the basics of gas calculation,
 how to provide fees for transactions
-and how the Ethereum-type fee calculation uses a fee market (EIP1559)
+and how the Ethereum-type fee calculation uses a fee market (EIP-1559)
 for prioritizing transactions.
 
 ## Prerequisite Readings

diff --git a/docs/protocol/concepts/replay-protection.md b/docs/protocol/concepts/replay-protection.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+---
+
+# EIP-155: Replay Protection
+
+[EIP-155](https://eips.ethereum.org/EIPS/eip-155) is an Ethereum Improvement Proposal,
+that has introduced a simple replay protection mechanism,
+by including the chain ID information into the signed transaction data.
+This was necessary, because Ethereum-based transactions rely on the Hex representation of addresses,
+which are not necessarily unique to a given network.
+This means that single signed transaction could be valid on multiple networks,
+as the same addresses are involved e.g. in a token transfer.
+This holds the potential for exploits and is addressed by enforcing the EIP-155 replay protection.
+
+Cosmos SDK-based blockchains use Bech32 representations for addresses, which contain a unique prefix per chain.
+This means, that for Cosmos transactions, replay protection is inherently present as addresses of a given chain
+are not valid addresses on other chains.
+However, as Evmos also accepts EVM transactions, handling only those transactions that conform to EIP-155
+becomes a requirement again.
+
+This requires special care to be taken when selecting an EIP-155 compliant [chain ID](./chain-id.mdx)
+to avoid duplication amongst chains.
+
+## Configuring Replay Protection
+
+By default, replay protection is enabled on any Evmos node.
+There are two distinct steps required to accept unprotected transactions, i.e. those that do not contain the chain ID
+in the signed transaction data:
+
+1. **Disable Module Parameter**:
+The [EVM module](../modules/evm.md#parameters) contains a governance controlled parameter,
+that globally dictates if unprotected transactions are supported.
+This has to be disabled via a governance vote or
+by setting the `allow_unprotected_txs` field to `true` in the genesis of a [local node](../evmos-cli/single-node.mdx).
+
+2. **Adjust Node Configuration**:
+When the global parameter is set accordingly, each node operator has the option to individually opt into allowing
+unprotected transactions to be sent to their nodes.
+This configuration is explained in the section on
+[node configuration](../../validate/setup-and-configuration/configuration.md#eip-155-replay-protection).
diff --git a/docs/protocol/modules/evm.md b/docs/protocol/modules/evm.md
@@ -504,7 +504,7 @@ To support the interface functionality, it imports 4 module Keepers:
 - `auth`: CRUD accounts
 - `bank`: accounting (supply) and CRUD of balances
 - `staking`: query historical headers
-- `fee market`: EIP1559 base fee for processing `DynamicFeeTx`
+- `fee market`: EIP-1559 base fee for processing `DynamicFeeTx`
   after the `London` hard fork has been activated on the `ChainConfig` parameters
 
 ```go
@@ -793,15 +793,15 @@ func (tx *Transaction) AsMessage(s Signer, baseFee *big.Int) (Message, error) {
 
 In order for the signature verification to be valid, the  `TxData` must contain the `v | r | s` values from the `Signer`.
 Sign calculates a secp256k1 ECDSA signature and signs the transaction.
-It takes a keyring signer and the chainID to sign an Ethereum transaction according to EIP155 standard.
+It takes a keyring signer and the chainID to sign an Ethereum transaction according to EIP-155 standard.
 This method mutates the transaction as it populates the V, R, S fields of the Transaction's Signature.
 The function will fail if the sender address is not defined for the msg
 or if the sender is not registered on the keyring.
 
 ```go
 // Sign calculates a secp256k1 ECDSA signature and signs the transaction. It
 // takes a keyring signer and the chainID to sign an Ethereum transaction according to
-// EIP155 standard.
+// EIP-155 standard.
 // This method mutates the transaction as it populates the V, R, S
 // fields of the Transaction's Signature.
 // The function will fail if the sender address is not defined for the msg or if
@@ -985,7 +985,7 @@ The main objective of this function is to:
 
 - Set the context for the current block so that the block header, store, gas meter, etc.
   are available to the `Keeper` once one of the `StateDB` functions are called during EVM state transitions.
-- Set the EIP155 `ChainID` number (obtained from the full chain-id),
+- Set the EIP-155 `ChainID` number (obtained from the full chain-id),
   in case it hasn't been set before during `InitChain`
 
 ### EndBlock
@@ -1239,10 +1239,13 @@ The evm module contains the following parameters:
 | Key            | Type        | Default Value   |
 |----------------|-------------|-----------------|
 | `EVMDenom`     | string      | `"aevmos"`      |
-| `EnableCreate` | bool        | `true`          |
-| `EnableCall`   | bool        | `true`          |
+| ~~`EnableCreate`~~ | bool        | `true`          |
+| ~~`EnableCall`~~   | bool        | `true`          |
 | `ExtraEIPs`    | []int       | TBD             |
 | `ChainConfig`  | ChainConfig | See ChainConfig |
+| `AllowUnprotectedTxs`  | bool |  false |
+| `ActivePrecompiles`  | []string | [] |
+| `AccessControl`  | AccessControl | Permissionless EVM |
 
 ### EVM denom
 
@@ -1261,11 +1264,13 @@ will need to set their own `evm_denom` (i.e not `"aevmos"`).
 
 ### Enable Create
 
+**(deprecated in v19.0.0)**
 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
 
+**(deprecated in v19.0.0)**
 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.
 
@@ -1287,6 +1292,7 @@ The supported activateable EIPS are:
 - **[EIP 2929](https://eips.ethereum.org/EIPS/eip-2929)**
 - **[EIP 3198](https://eips.ethereum.org/EIPS/eip-3198)**
 - **[EIP 3529](https://eips.ethereum.org/EIPS/eip-3529)**
+- **[EIP 3855](https://eips.ethereum.org/EIPS/eip-3855)**
 
 ### Chain Config
 
@@ -1320,6 +1326,38 @@ By default, all block configuration fields but `ConstantinopleBlock`, are enable
 | ShanghaiBlock       | 0                                                                    |
 | CancunBlock.        | 0                                                                    |
 
+### Allow Unprotected Transactions
+
+This parameter enforces [EIP-155 replay protection](../concepts/replay-protection.md) globally for all nodes
+partaking in consensus.
+If disabled, this delegates control of replay protection to the individual nodes
+(read more [here](../../validate/setup-and-configuration/configuration.md#eip-155-replay-protection)).
+
+### Active Precompiles
+
+This parameter governs which [EVM Extensions](../../develop/smart-contracts/evm-extensions/evm-extensions.md)
+are enabled on the given network.
+It accepts a list of addresses in Hex format,
+which is evaluated in EVM transactions to only allow interactions
+with the selected precompiled contracts.
+
+### Access Control
+
+(added in v19.0.0) This parameter enables detailed control of the EVM.
+The former parameters `enable_create` and `enable_call` have been extended
+to give exact control of who can access these features.
+
+By default, the EVM is *permissionless*, meaning that everyone can deploy smart contracts
+and send EVM transaction unless they have specifically been blacklisted.
+The blacklisted addresses can be defined in the corresponding `AccessControlList`.
+
+By setting the individual `AccessControlType` for either the create or call functionality as *restricted*,
+the EVM does not accept further interactions with the specific functionality.
+
+When defining the control type as being *permissioned*, the given list of addresses is
+interpreted as a collection of whitelisted addresses, which are the only ones capable of
+deploying contracts or calling the EVM respectively.
+
 ## Client
 
 A user can query and interact with the `evm` module using the CLI, JSON-RPC, gRPC or REST.

diff --git a/docs/protocol/modules/feemarket.md b/docs/protocol/modules/feemarket.md
@@ -2,9 +2,9 @@
 
 ## Abstract
 
-This document specifies the feemarket module which allows to define a global transaction fee for the network.
+This document specifies the feemarket module, which allows defining a global transaction fee for the network.
 
-This module has been designed to support EIP1559 in cosmos-sdk.
+This module has been designed to support EIP-1559 in cosmos-sdk.
 
 The `MempoolFeeDecorator` in `x/auth` module needs to be overwritten
 to check the `baseFee` along with the `minimal-gas-prices` allowing
@@ -179,13 +179,13 @@ Those parameters allow us to introduce a static base fee or activate the base fe
 
 #### Enabling base fee
 
-To enable EIP1559 with the EVM, the following parameters should be set :
+To enable EIP-1559 with the EVM, the following parameters should be set :
 
 - NoBaseFee should be false
 - EnableHeight should be set to a positive integer >= upgrade height.
   It defines at which height the chain starts the base fee adjustment
 - LondonBlock evm's param should be set to a positive integer >= upgrade height.
-  It defines at which height the chain start to accept EIP1559 transactions
+  It defines at which height the chain starts to accept EIP-1559 transactions.
 
 #### Calculation
 

diff --git a/docs/protocol/modules/index.md b/docs/protocol/modules/index.md
@@ -10,7 +10,7 @@ Here is a list of all production-grade modules that can be used on the Evmos blo
 - [erc20](erc20.md) - Trustless, on-chain bidirectional internal conversion of tokens
   between Evmos' EVM and Cosmos runtimes.
 - [evm](evm.md) - Smart Contract deployment and execution on Cosmos
-- [feemarket](feemarket.md) - Fee market implementation based on the EIP1559 specification.
+- [feemarket](feemarket.md) - Fee market implementation based on the EIP-1559 specification.
 - [inflation](inflation.md) - Mint tokens and allocate them to staking rewards and the community pool.
 - [vesting](vesting.md) - Vesting accounts with lockup and clawback capabilities.
 

diff --git a/docs/validate/setup-and-configuration/configuration.md b/docs/validate/setup-and-configuration/configuration.md
@@ -50,7 +50,7 @@ In `~/.evmosd/config/config.toml` you can set your peers.
 See the [Add persistent peers section](./../testnet#add-persistent-peers) in our docs for an automated method, but
 field should look something like a comma separated string of peers (do not copy this, just an example):
 
-```bash
+```toml
 persistent_peers = "[email protected]:24656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656"
 ```
 
@@ -68,13 +68,29 @@ ac29d21d0a6885465048a4481d16c12f59b2e58b
 
 ### Healthy peers
 
-If you are relying on just seed node and no persistent peers or a low amount of them,
+If you are relying on just a seed node and no persistent peers or a low amount of them,
 please increase the following params in the `config.toml`:
 
-```bash
+```toml
 # Maximum number of inbound peers
 max_num_inbound_peers = 120
 
 # Maximum number of outbound peers to connect to, excluding persistent peers
 max_num_outbound_peers = 60
 ```
+
+## EIP-155 Replay Protection
+
+The EIP-155 replay protection is enabled globally in the EVM module parameters.
+In case this is disabled as a global requirement, node operators can opt into supporting unprotected transactions
+by adjusting the corresponding setting in the [node configuration](https://github.com/evmos/evmos/blob/v18.1.0/server/config/toml.go#L74-L76):
+
+```toml
+# in $HOME/.evmosd/config/config.toml
+
+# AllowUnprotectedTxs restricts unprotected (non EIP-155 signed) transactions to be submitted via
+# the node's RPC when the global parameter is disabled.
+allow-unprotected-txs = true  # false by default
+```
+
+More information about EIP-155 can be found here: [EIP-155: Replay Protection](../../protocol/concepts/replay-protection.md).