diff --git a/docs/protocol/concepts/chain-id.mdx b/docs/protocol/concepts/chain-id.mdx index 8277ce8..c14b1fb 100644 --- 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,14 +22,14 @@ 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 | | `evmos` | | | ✅ | | Evmos 1 | | `evmos` | | `1` | 🚫 | ### Testnet -| Name | Chain ID | Identifier | EIP155 Number | Version Number | Active | +| Name | Chain ID | Identifier | EIP-155 Number | Version Number | Active | | --------------------------------- | ----------------------------------------------------- | ---------- | --------------------------------------------- | --------------------------------------------------- | ------- | | Evmos Public Testnet | | `evmos` | | | ✅ | | Evmos Public Testnet | | `evmos` | | `3` | 🚫 | @@ -37,7 +37,7 @@ follows the format of `identifier_EIP155-version` format. | Arsia Mons Testnet | | `evmos` | | `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,7 +47,7 @@ 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 @@ -55,10 +55,10 @@ define its own `chain-id` in the [genesis.json fields](https://docs.tendermint.c 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 index 0768377..838ebec 100644 --- 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 new file mode 100644 index 0000000..5c696f5 --- /dev/null +++ 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 index ac7bcbf..e927897 100644 --- 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,7 +793,7 @@ 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. @@ -801,7 +801,7 @@ 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 index 5545f2c..0b9af51 100644 --- 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 index 737b26d..0e88ef0 100644 --- 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 index afec19b..2d86d73 100644 --- 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 = "5576b0160761fe81ccdf88e06031a01bc8643d51@195.201.108.97:24656,13e850d14610f966de38fc2f925f6dc35c7f4bf4@176.9.60.27:26656,38eb4984f89899a5d8d1f04a79b356f15681bb78@18.169.155.159:26656,59c4351009223b3652674bd5ee4324926a5a11aa@51.15.133.26:26656,3a5a9022c8aa2214a7af26ebbfac49b77e34e5c5@65.108.1.46:26656,4fc0bea2044c9fd1ea8cc987119bb8bdff91aaf3@65.21.246.124:26656,6624238168de05893ca74c2b0270553189810aa7@95.216.100.80:26656,9d247286cd407dc8d07502240245f836e18c0517@149.248.32.208:26656,37d59371f7578101dee74d5a26c86128a229b8bf@194.163.172.168:26656,b607050b4e5b06e52c12fcf2db6930fd0937ef3b@95.217.107.96:26656,7a6bbbb6f6146cb11aebf77039089cd038003964@94.130.54.247: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).