Merge pull request 0xPolygon#459 from 0xPolygon/zkevm/arch-menu

kmurphypolygon · web-flow · commit 4a6d04fe57dd · 2024-05-10T16:01:42.000+02:00
zkEVM: skeleton menu plus Overview section
diff --git a/docs/img/cdk/high-level-architecture/full-topology.png b/docs/img/cdk/high-level-architecture/full-topology.png
diff --git a/docs/zkEVM/architecture/high-level/bridge-service.md b/docs/zkEVM/architecture/high-level/bridge-service.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/aggregator.md b/docs/zkEVM/architecture/high-level/cdk-node/aggregator.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/dac.md b/docs/zkEVM/architecture/high-level/cdk-node/dac.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/etherman.md b/docs/zkEVM/architecture/high-level/cdk-node/etherman.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/json-rpc.md b/docs/zkEVM/architecture/high-level/cdk-node/json-rpc.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/pool-db.md b/docs/zkEVM/architecture/high-level/cdk-node/pool-db.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/prover.md b/docs/zkEVM/architecture/high-level/cdk-node/prover.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/sequencer.md b/docs/zkEVM/architecture/high-level/cdk-node/sequencer.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/state-db.md b/docs/zkEVM/architecture/high-level/cdk-node/state-db.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/cdk-node/synchronizer.md b/docs/zkEVM/architecture/high-level/cdk-node/synchronizer.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/aggregator.md b/docs/zkEVM/architecture/high-level/hermez-node/aggregator.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/dac.md b/docs/zkEVM/architecture/high-level/hermez-node/dac.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/etherman.md b/docs/zkEVM/architecture/high-level/hermez-node/etherman.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/json-rpc.md b/docs/zkEVM/architecture/high-level/hermez-node/json-rpc.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/pool-db.md b/docs/zkEVM/architecture/high-level/hermez-node/pool-db.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/prover.md b/docs/zkEVM/architecture/high-level/hermez-node/prover.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/sequencer.md b/docs/zkEVM/architecture/high-level/hermez-node/sequencer.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/state-db.md b/docs/zkEVM/architecture/high-level/hermez-node/state-db.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/hermez-node/synchronizer.md b/docs/zkEVM/architecture/high-level/hermez-node/synchronizer.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/overview.md b/docs/zkEVM/architecture/high-level/overview.md
@@ -0,0 +1,45 @@
+<!-- https://excalidraw.com/#json=JKZp9QEihifF_B7Z41Dfv,FVNhqQKi9PA1jM0kzUoCsQ" -->
+
+## Intro
+
+This section of the docs provides a detailed analysis of the full topology of the Polygon zero-knowledge system architecture. 
+
+Tailored for CDK stacks and using zkEVM technology, these documents explore the contents, layout, and interactions among component systems and functions. They offer in-depth descriptions of the components that constitute the larger system, with references to relevant code bases.
+
+The diagram below is a full and detailed topological overview of the entire Polygon zero-knowledge system architecture.
+
+## Architectural topology
+
+![Polygon systems topology](../../../img/cdk/high-level-architecture/full-topology.png)
+
+## Components 
+
+- Smart contracts: L1 and L2 Solidity smart contracts used for interacting with the whole stack. See the discussion on [zkEVM smart contracts](../../architecture/protocol/zkevm-bridge/smart-contracts.md) for more information.
+- Exit root trees: Append-only sparse Merkle trees which record the current and historical state of the system. See the discussion on [zkEVM exit trees](../../architecture/protocol/zkevm-bridge/exit-tree.md) for more information.
+- CDK and zkEVM nodes containing:
+    - JSON RPC client: Exposes the read/write interfaces for interacting with a node/chain.
+    - Pool database: The pool database records transaction requests coming in from the JSON RPC client and sends them to the sequencer.
+    - State database: The state database responds to read requests from the JSON RPC client.
+    - Sequencer: Does the complex job of carefully sequencing transactions as they come in before sending them to the aggregator for batching. See the discussion on [sequencers](../../architecture/index.md#sequencer) for more information.
+    - Aggregator: Used for aggregating transaction batches to send to the prover. See the discussion on [aggregators](../../architecture/index.md#aggregator) for more information.
+    - Synchronizer: This component ensures a synchronized state between the node's systems and the L1 outside-world via the Etherman component and the state database. 
+    - Etherman component: The Etherman helps the synchronizer maintain a synchronized state with L1 by communicating with the L1 Ethereum chain via smart contract methods.
+- Bridge service component: Provides an API to perform bridge claims, i.e. asset and message transfers between L1/L2 and L2/L2.
+- Prover component: System for calculating zero-knowledge proofs on transaction batches.
+
+## What to expect
+
+When complete, this section will include information on: 
+
+- The structure of a CDK node and how it interacts with L2 and L1 smart contracts.
+- The structure of a zkEVM node and how it interacts with L2 and L1 smart contracts.
+- The key components included in the nodes, how they function, and their interactions with other components, external dApps, and the L1/L2 environment.
+- Key similarities and differences between a CDK and zkEVM node.
+- CDK validium components, including the DAC and DAC sequencer.
+- Detailed description of the Polygon smart contract sets for L1 and L2.
+- The zkProver and how it interacts with a zkEVM node aggregator.
+
+### Currently out of scope
+
+- The bridge service.
+- AggLayer.
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/exit-root-trees.md b/docs/zkEVM/architecture/high-level/smart-contracts/exit-root-trees.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/overview.md b/docs/zkEVM/architecture/high-level/smart-contracts/overview.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/rollup.md b/docs/zkEVM/architecture/high-level/smart-contracts/rollup.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/validium.md b/docs/zkEVM/architecture/high-level/smart-contracts/validium.md
@@ -0,0 +1,2 @@
+!!! warning
+    Coming soon.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -93,7 +93,42 @@ nav:
         - Deploy a contract with Foundry: zkEVM/how-to/using-foundry.md
         - Deploy a contract with Hardhat: zkEVM/how-to/using-hardhat.md
         - Verify a contract: zkEVM/how-to/verify-contract.md
-      - Architecture:
+      - Architecture high-level:
+        - Overview: zkEVM/architecture/high-level/overview.md
+        #- Smart contracts: 
+        #  - Overview: zkEVM/architecture/high-level/smart-contracts/overview.md
+        #  - Rollup: zkEVM/architecture/high-level/smart-contracts/rollup.md
+        #  - Validium: zkEVM/architecture/high-level/smart-contracts/validium.md      
+        #  - Exit root trees: zkEVM/architecture/high-level/smart-contracts/exit-root-trees.md
+        # - AggLayer: https://potential-couscous-4gw6qyo.pages.github.io/index.html
+        #- CDK node:
+          #- JSON/RPC: zkEVM/architecture/high-level/cdk-node/json-rpc.md
+          #- Databases:
+            #- State: zkEVM/architecture/high-level/cdk-node/state-db.md
+            #- Pool: zkEVM/architecture/high-level/cdk-node/pool-db.md
+          #- Transaction flow:
+            #- Sequencer: zkEVM/architecture/high-level/cdk-node/sequencer.md
+            #- Aggregator: zkEVM/architecture/high-level/cdk-node/aggregator.md
+            #- Prover: zkEVM/architecture/high-level/cdk-node/prover.md
+          #- L1 comms:
+            #- Etherman: zkEVM/architecture/high-level/cdk-node/etherman.md
+            #- Synchronizer: zkEVM/architecture/high-level/cdk-node/synchronizer.md
+          #- DAC: zkEVM/architecture/high-level/cdk-node/dac.md
+        #- Hermez node:
+          #- JSON/RPC: zkEVM/architecture/high-level/hermez-node/json-rpc.md
+          #- Databases:
+            #- State: zkEVM/architecture/high-level/hermez-node/state-db.md
+            #- Pool: zkEVM/architecture/high-level/hermez-node/pool-db.md
+          #- Transaction flow:
+            #- Sequencer: zkEVM/architecture/high-level/hermez-node/sequencer.md
+            #- Aggregator: zkEVM/architecture/high-level/hermez-node/aggregator.md
+            #- Prover: zkEVM/architecture/high-level/hermez-node/prover.md
+          #- L1 comms:
+            #- Etherman: zkEVM/architecture/high-level/hermez-node/etherman.md
+            #- Synchronizer: zkEVM/architecture/high-level/hermez-node/synchronizer.md
+          #- DAC: zkEVM/architecture/high-level/hermez-node/dac.md
+        #- Bridge service: zkEVM/architecture/high-level/bridge-service.md
+      - Architecture low-level:
         - Architecture: zkEVM/architecture/index.md
         - Upgrades:
           - Etrog upgrade: zkEVM/architecture/protocol/etrog-upgrade.md
