Merge pull request 0xPolygon#159 from 0xPolygon/empieichO-docs-review

Update zkEVM - EVM vs. zkEVM equiv

Author: EmpieichO

docs/zkEVM/architecture/zknode/index.md

@@ -31,14 +31,14 @@ Any user can participate in this role, as an RPC node.
 
 Required services and components:
 
-- JSON RPC: can run in a separated instance, and can have multiple instances
-- Synchronizer: single instance that can run on a separate instance
-- Executor & Merkletree: service that can run on a separate instance
-- State DB: Postgres SQL that can be run in a separate instance
+- JSON RPC: can run on a separated instance, and can have multiple instances.
+- Synchronizer: single instance that can run on a separate instance.
+- Executor & Merkletree: service that can run on a separate instance.
+- State DB: Postgres SQL that can run on a separate instance.
 
 There must be only one synchronizer, and it's recommended that it must have exclusive access to an executor instance, though not necessarily.
 
- The synchronizer role can be run perfectly in a single instance, but the JSON RPC and executor services can benefit from running in multiple instances, if the performance decreases due to the number of received requests.
+ The synchronizer role can run perfectly in a single instance, but the JSON RPC and executor services can benefit from running in multiple instances, if the performance decreases due to the number of received requests.
 
 - [`zkEVM RPC endpoints`](https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/json-rpc-endpoints.md)
 - [`zkEVM RPC Custom endpoints documentation`](https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/zkEVM-custom-endpoints.md)
@@ -49,27 +49,26 @@ This role can only be performed by a single entity. This is enforced in the smar
 
 Required services and components:
 
-- JSON RPC: can run in a separated instance, and can have multiple instances
-- Sequencer & Synchronizer: single instance that needs to run together
-- Executor & Merkletree: service that can run on a separate instance
-- Pool DB: Postgres SQL that can be run in a separate instance
-- State DB: Postgres SQL that can be run in a separate instance
+- JSON RPC: can run on a separated instance, and can have multiple instances.
+- Sequencer & synchronizer: single instance that needs to run them together.
+- Executor & Merkletree: service that can run on a separate instance.
+- Pool DB: Postgres SQL that can run on a separate instance.
+- State DB: Postgres SQL that can run on a separate instance.
 
-Note that the JSON RPC is required to receive transactions. It's recommended that the JSON RPC runs on separated instances, and potentially more than one (depending on the load of the network). It's also recommended that the JSON RPC and the Sequencer don't share the same executor instance, to make sure that the sequencer has exclusive access to an executor
+Note that the JSON RPC is required to receive transactions. It's recommended that the JSON RPC runs on separated instances, and potentially more than one (depending on the load of the network). It's also recommended that the JSON RPC and the sequencer don't share the same executor instance, to make sure that the sequencer has exclusive access to an executor
 
 ### Aggregator
 
 This role can be performed by anyone.
 
 Required services and components:
 
-- Synchronizer: single instance that can run on a separated instance
-- Executor & Merkletree: service that can run on a separate instance
-- State DB: Postgres SQL that can be run in a separate instance
-- Aggregator: single instance that can run on a separated instance
-- Prover: single instance that can run on a separated instance
-- Executor: single instance that can run on a separated instance
+- Synchronizer: single instance that can run on a separate instance.
+- Executor & Merkletree: service that can run on a separate instance.
+- State DB: Postgres SQL that can be run on a separate instance.
+- Aggregator: single instance that can run on a separate instance.
+- Prover: single instance that can run on a separate instance.
+- Executor: single instance that can run on a separate instance.
 
 It's recommended that the prover is run on a separate instance, as it has important hardware requirements. On the other hand, all the other components can run on a single instance.
 
-

docs/zkEVM/spec/evm-differences.md

@@ -1,46 +1,81 @@
-This document provides a comprehensive list of differences between the Ethereum Virtual Machine (EVM) and the Polygon Zero-Knowledge Ethereum Virtual Machine (zkEVM). The list includes supported EIPs, opcodes, and additional changes made to build the zkEVM.
+This document provides a comprehensive list of differences between the EVM and the Polygon zkEVM. The list includes supported EIPs, opcodes, and additional changes made when building the Polygon zkEVM.
+
+### EVM-equivalence
+
+Polygon zkEVM is designed to be EVM-equivalent rather than just compatible.
+
+The difference between EVM-compatibility and EVM-equivalence is that;
+   
+   - Solutions that are compatible support most of the existing applications, but sometimes with code changes. Additionally, compatibility may lead to breaking developer tooling.
+
+   - Polygon zkEVM strives for EVM-equivalence which means most applications, tools, and infrastructure built on Ethereum can immediately port over to Polygon zkEVM, with limited to no changes needed. Things are designed to work 100% on day one. 
+
+EVM-equivalence is critical to Polygon zkEVM for several reasons, including the following:
+   
+   1. Development teams don't have to make changes to their code, and this eliminates the possibility of introducing new security vulnerabilities.
+
+   2. No code changes means no need for additional audits. This saves time and money.
+
+   3. Since consolidation of batches and finality of transactions is achieved via smart contracts on Ethereum, Polygon zkEVM benefits from the security of Ethereum.
+
+   4. EVM-equivalence allows Polygon zkEVM to benefit from the already vibrant and active Ethereum community.
+
+   5. It also allows for significant and quick dApp adoption, because applications built on Ethereum are automatically compatible.
+
+Ultimately, Polygon zkEVM offers developers the same UX as on Ethereum, with significantly improved scalability.
+
 
 !!!info
     No impact on developer experience
 
-    Note that the following differences have no impact on the developer experience with the zkEVM as compared to the EVM. Gas optimization techniques, interacting with libraries like Web3.js and Ethers.js, and deploying contracts works seamlessly on the zkEVM without any overhead.
+    Note that the following differences have no impact on the developer experience with the zkEVM as compared to the EVM. Gas optimization techniques, interacting with libraries like Web3.js and Ethers.js, and deploying contracts work seamlessly on the zkEVM without any overhead.
+
+The following differences have no impact on the developer's experience on the zkEVM compared to the EVM:
 
-## Opcodes
+   - Gas optimization techniques.
+   - Interacting with libraries, like Web3.js and Ethers.js.
+   - Deploying contracts seamlessly on the zkEVM without any overhead.
 
-This section lists the changes we have done with Opcodes in zKEVM as compared to the EVM.
 
-- **SELFDESTRUCT** → removed and replaced by **SENDALL**.
+### Opcodes
 
-- **EXTCODEHASH** → returns the hash of the contract bytecode from the zkEVM state tree without checking if the account is empty.
+Below is a list of the changes we have made to opcodes in zkEVM in comparison to the EVM.
+   
+   - **SELFDESTRUCT** → removed and replaced by **SENDALL**.
 
-- **DIFFICULTY** →  returns "0" instead of a random number as in the EVM.
+   - `EXTCODEHASH` returns the hash of the contract bytecode from the zkEVM state tree without checking if the account is empty.
 
-- **BLOCKHASH** → returns all previous block hashes instead of just the last 256 blocks.
+   - **DIFFICULTY** →  returns "0" instead of a random number as in the EVM.
 
-> **BLOCKHASH** is the state root at the end of a processable transaction and is stored on the system smart contract.
+   - **BLOCKHASH** → returns all previous block hashes instead of just the last 256 blocks.
 
-- **NUMBER** → returns the number of processable transactions.
+   > **BLOCKHASH** is the state root at the end of a processable transaction and is stored on the system smart contract.
 
-## Precompiled contracts
+   - **NUMBER** → returns the number of processable transactions.
 
-The following precompiled contracts are supported in the zkEVM:
 
-- [**ecRecover**](https://ethereum.github.io/execution-specs/autoapi/ethereum/frontier/vm/precompiled_contracts/ecrecover/index.html)
-- [**identity**](https://ethereum.github.io/execution-specs/autoapi/ethereum/frontier/vm/precompiled_contracts/identity/index.html)
+### Precompiled contracts
+
+Among Ethereum's precompiled contracts, the zkEVM currrently supports: [`ecRecover`](https://www.evm.codes/precompiled?fork=shanghai) and [`identity`](https://www.evm.codes/precompiled?fork=shanghai).
+
+Other precompiled contracts have no effect on the zkEVM state tree and are treated as reverts, returning all gas to the previous context and setting the `success` flag to "0".
 
-Other precompiled contracts have no effect on the zkEVM state tree and are treated as a `revert`, returning all gas to the previous context and setting the `success` flag to "0".
 
 ## Additions
 
 **zk-counters** → batch resources are available, linked to state-machine components, as a supplementary addition to gas computation.
 
+
 ## Other minor differences
+   
+   - zkEVM doesn't clean storage when a contract is deployed at an address due to the zkEVM state tree specification.
+
+   - `JUMPDEST` is allowed in push bytes to avoid runtime bytecode analysis.
 
-- zkEVM doesn't clean storage when a contract is deployed at an address due to the zkEVM state tree specification.
+   - The zkEVM implements [EIP-3541](https://eips.ethereum.org/EIPS/eip-3541) from the [London hardfork](https://ethereum.org/en/history/#london).
 
-- **JUMPDEST** opcode is allowed in push bytes to avoid runtime bytecode analysis.
+   - [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) which defines the Typed Transaction Envelope, is not supported
 
-- The zkEVM implements [EIP-3541](https://eips.ethereum.org/EIPS/eip-3541) from the [London hardfork](https://ethereum.org/en/history/#london).
+   - [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930), which defines the Optional Access Lists transaction type, is not supported.
 
-- [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) which defines **Typed Transaction Envelope**, is not supported
-- [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930), which defines the **Optional Access Lists** transaction type, is not supported.
+   - [`BASEFEE`](https://ethereum-org-fork.netlify.app/en/developers/docs/gas#base-fee) opcode is not supported. The zkEVM implements the Berlin hardfork, but not the London hardfork.