Merge remote-tracking branch 'origin/main' into cancun-main

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Changed
+
+- Refactor accessed lists as sorted linked lists ([#30](https://github.com/0xPolygonZero/zk_evm/pull/30))
+- Change visibility of `compact` mod ([#57](https://github.com/0xPolygonZero/zk_evm/pull/57))
+
+## [0.1.0] - 2024-02-21
+* Initial release.

Cargo.toml

@@ -5,19 +5,30 @@ resolver = "2"
 [workspace.dependencies]
 bytes = "1.5.0"
 enum-as-inner = "0.6.0"
+env_logger = "0.10.0"
 ethereum-types = "0.14.1"
 hex = "0.4.3"
 hex-literal = "0.4.1"
 keccak-hash = "0.10.0"
 log = "0.4.20"
 num = "0.4.1"
+rand = "0.8.5"
 rlp = "0.5.2"
 rlp-derive = "0.1.0"
 serde = "1.0.166"
+serde_json = "1.0.96"
+thiserror = "1.0.49"
+
+# plonky2-related dependencies
+plonky2 = "0.2.0"
+plonky2_maybe_rayon = "0.2.0"
+plonky2_util = "0.2.0"
+starky = "0.2.0"
+
 
 [workspace.package]
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/0xPolygonZero/zk_evm"
 homepage = "https://github.com/0xPolygonZero/zk_evm"
-keywords = ["cryptography", "SNARK", "PLONK", "FRI", "plonky2", "EVM", "ETHEREUM"]
+keywords = ["cryptography", "STARK", "plonky2", "ethereum", "zk"]

README.md

@@ -1,5 +1,38 @@
 # zk_evm
 
+A collection of libraries to prove Ethereum blocks with Polygon Zero Type 1 zkEVM,
+powered by [starky and plonky2](https://github.com/0xPolygonZero/plonky2) proving systems.
+
+
+## Directory structure
+
+This repository contains the following Rust crates:
+
+* [mpt_trie](./mpt_trie/README.md): A collection of types and functions to work with Ethereum Merkle Patricie Tries.
+
+* [trace_decoder](./trace_decoder/README.md): Flexible protocol designed to process Ethereum clients trace payloads into an IR format that can be
+understood by the zkEVM prover.
+
+* [evm_arithmetization](./evm_arithmetization/README.md): Defines all the STARK constraints and recursive circuits to generate succinct proofs of EVM execution.
+It uses starky and plonky2 as proving backend: https://github.com/0xPolygonZero/plonky2.
+
+* [proof_gen](./proof_gen/README.md): A convenience library for generating proofs from inputs already in Intermediate Representation (IR) format.
+
+
+## Documentation
+
+Documentation is still incomplete and will be improved over time, a lot of useful material can
+be found in the [docs](./docs/) section, including:
+
+* [sequence diagrams](./docs/usage_seq_diagrams.md) for the proof generation flow
+* [zkEVM specifications](./docs/arithmetization/zkevm.pdf), detailing the underlying EVM proving statement
+
+
+## Building
+
+The zkEVM stack currently requires the `nightly` toolchain, although we may transition to `stable` in the future.
+Note that the prover uses the [Jemalloc](http://jemalloc.net/) memory allocator due to its superior performance.
+
 ## License
 
 Licensed under either of
@@ -11,4 +44,5 @@ at your option.
 
 ### Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

SECURITY.md

@@ -0,0 +1,17 @@
+# Polygon Technology Security Information
+
+## Link to vulnerability disclosure details (Bug Bounty).
+- Websites and Applications: https://hackerone.com/polygon-technology
+- Smart Contracts: https://immunefi.com/bounty/polygon
+
+## Languages that our team speaks and understands.
+Preferred-Languages: en
+
+## Security-related job openings at Polygon.
+https://polygon.technology/careers
+
+## Polygon security contact details.
+security@polygon.technology
+
+## The URL for accessing the security.txt file.
+Canonical: https://polygon.technology/security.txt

docs/usage_seq_diagrams.md

@@ -1,14 +1,15 @@
 # Usage Diagrams
-These are some hacked together diagrams showing how the protocol will (likely) be used. Also included what the old Edge proof generation process looked like as a reference.
 
-## Proof Protocol
+These are some diagrams showing how the protocol is implemented.
+
+## Proof Generation
 
 ```mermaid
 sequenceDiagram
     proof protocol client->>proof scheduler: protocol_payload
-    proof scheduler->>protocol decoder (lib): protolcol_payload
-    Note over proof scheduler,protocol decoder (lib): "txn_proof_gen_ir" are the payloads sent to Paladin for a txn
-    protocol decoder (lib)->>proof scheduler: [txn_proof_gen_ir]
+    proof scheduler->>trace decoder (lib): protocol_payload
+    Note over proof scheduler,trace decoder (lib): "txn_proof_gen_ir" are the payloads sent to Paladin for a txn
+    trace decoder (lib)->>proof scheduler: [txn_proof_gen_ir]
     proof scheduler->>paladin: [txn_proof_gen_ir]
     Note over proof scheduler,paladin: Paladin schedules jobs on multiple machines and returns a block proof
     loop txn_proof_gen_ir
@@ -19,18 +20,3 @@ sequenceDiagram
     Note over proof scheduler,checkpoint contract: Note: Might send to an external service instead that compresses the proof
     proof scheduler->>checkpoint contract: block_proof
 ```
-
-## Edge Proof Generation
-
-```mermaid
-sequenceDiagram
-    edge->>zero provers (leader): block_trace
-    zero provers (leader)->>trace parsing lib: block_trace
-    Note over zero provers (leader),trace parsing lib: "txn_proof_gen_ir" are the payloads sent to each worker for a txn
-    trace parsing lib->>zero provers (leader): [txn_proof_gen_ir]
-    loop txn_proof_gen_ir
-        zero provers (leader)->>zero provers (worker): proof_gen_payload (txn, agg, block)
-        zero provers (worker)->>zero provers (leader): generated_proof (txn, agg, block)
-    end
-    zero provers (leader)->>checkpoint contract: block_proof
-```

evm_arithmetization/Cargo.toml

@@ -14,31 +14,31 @@ keywords.workspace = true
 [dependencies]
 anyhow = "1.0.40"
 bytes = { workspace = true }
-env_logger = "0.10.0"
-ethereum-types = "0.14.0"
+env_logger = { workspace = true }
+ethereum-types = { workspace = true }
 hex = { workspace = true, optional = true }
 hex-literal = { workspace = true }
 itertools = "0.11.0"
 keccak-hash = { workspace = true }
 log = { workspace = true }
-plonky2_maybe_rayon = { git = "https://github.com/0xPolygonZero/plonky2.git", rev = "710225c9e0ac5822b2965ce74951cf000bbb8a2c" }
+plonky2_maybe_rayon = { workspace = true }
 num = { workspace = true }
 num-bigint = "0.4.3"
 once_cell = "1.13.0"
 pest = "2.1.3"
 pest_derive = "2.1.0"
-plonky2 = { git = "https://github.com/0xPolygonZero/plonky2.git", rev = "710225c9e0ac5822b2965ce74951cf000bbb8a2c" }
-plonky2_util = { git = "https://github.com/0xPolygonZero/plonky2.git", rev = "710225c9e0ac5822b2965ce74951cf000bbb8a2c" }
-starky = { git = "https://github.com/0xPolygonZero/plonky2.git", rev = "710225c9e0ac5822b2965ce74951cf000bbb8a2c" }
-rand = "0.8.5"
+plonky2 = { workspace = true }
+plonky2_util = { workspace = true }
+starky = { workspace = true }
+rand = { workspace = true }
 rand_chacha = "0.3.1"
 rlp = { workspace = true }
 rlp-derive = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 static_assertions = "1.1.0"
 hashbrown = { version = "0.14.0" }
 tiny-keccak = "2.0.2"
-serde_json = "1.0"
+serde_json = { workspace = true }
 
 # Local dependencies
 mpt_trie = { version = "0.1.0", path = "../mpt_trie" }