commit the overview section

kmurphypolygon · kmurphypolygon · commit f40d8a2a82e4 · 2024-05-09T12:51:19.000+02:00
diff --git a/docs/img/cdk/high-level-architecture/full-topology b/docs/img/cdk/high-level-architecture/full-topology
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/img/cdk/high-level-architecture/smart-contracts-full-view.png b/docs/img/cdk/high-level-architecture/smart-contracts-full-view.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
@@ -1 +1,43 @@
-https://excalidraw.com/#json=EB5wC0QEVpCCZZAqgwSG9,9rUF_xzn-6t2U-gbFjiMLA
+<!-- https://excalidraw.com/#json=JKZp9QEihifF_B7Z41Dfv,FVNhqQKi9PA1jM0kzUoCsQ" -->
+
+## Intro
+
+This section of the docs looks more closely at the full topology of Polygon's zero-knowledge system architecture. 
+
+Built for CDK stacks and using zkEVM technology, these documents explain the contents, layout, and interactions between component systems and functions, drilling down into detailed descriptions of the components that make up the wider system with reference to the 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.
+- Aggregator: Used for aggregating transactions into batches for proving. See the discussion on [aggregators](../../architecture/index.md#aggregator) for more information.
+- 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.
+- 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.
+- JSON RPC client: Allows computational read/write access to the system via published methods which, when called, interact with the pool and state databases.
+- 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.
+- Bridge service component: Main facility for transferring tokens from L1 to L2 and back again.
+
+## 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 developers, and the L1/L2 environment.
+- Key similarities and differences between a CDK and zkEVM node set up.
+- 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/overview.md b/docs/zkEVM/architecture/high-level/smart-contracts/overview.md
@@ -1,7 +1,13 @@
 Omnificent diagram of component
 
-       Detailed description
+Detailed description
 
-        Sequence diagram and any other helpful UML to connect the code base.
+Sequence diagram and any other helpful UML to connect the code base.
 
-        Important code/db schemas/etc
+Important code/db schemas/etc
+
+Explanation of how they interact relating to the code and behaviour
+
+How they interact with the wider architecture and specific components
+
+Exit root trees
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/rollup.md b/docs/zkEVM/architecture/high-level/smart-contracts/rollup.md
@@ -1,7 +1,5 @@
 Omnificent diagram of component
 
-       Detailed description
+Detailed description of rollup contracts
 
-        Sequence diagram and any other helpful UML to connect the code base.
-
-        Important code/db schemas/etc
+L2 vs L1
diff --git a/docs/zkEVM/architecture/high-level/smart-contracts/validium.md b/docs/zkEVM/architecture/high-level/smart-contracts/validium.md
@@ -1,7 +1,5 @@
 Omnificent diagram of component
 
-       Detailed description
+Detailed description of validium sc contracts
 
-        Sequence diagram and any other helpful UML to connect the code base.
-
-        Important code/db schemas/etc
+L2 vs L1
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -100,34 +100,34 @@ nav:
           - 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
+        # - 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:
