Merge pull request 0xPolygon#651 from 0xPolygon/agglayer/review

kmurphypolygon · web-flow · commit 4c8e39c679c6 · 2024-09-06T09:25:27.000+02:00
AggLayer/Innovation &amp; Design: Updates after review
diff --git a/docs/agglayer/agglayer-go.md b/docs/agglayer/agglayer-go.md
@@ -1,5 +1,3 @@
-## Overview
-
 The AggLayer-go is a service designed to receive zero-knowledge (ZK) proofs  from various CDK chains and verify their validity before sending them to the L1 for final settlement.
 
 !!! warning
@@ -12,7 +10,7 @@ The AggLayer Golang architecture supports interactions with multiple CDK chains
 The diagram below shows the full start-up, running, and shutdown sequence for the application and its components.
 
 <center>
-![CDK architecture](../../img/cdk/agglayer/agglayer-go.png)
+![CDK architecture](../img/cdk/agglayer/agglayer-go.png)
 </center>
 
 ## Get started
diff --git a/docs/agglayer/agglayer-rs.md b/docs/agglayer/agglayer-rs.md
@@ -1,6 +1,6 @@
-## Overview
+AggLayer-rs is a Rust-based service designed to receive ZK proofs from various CDK chains and verify their validity before sending them to the L1 for final settlement. 
 
-AggLayer-rs is a Rust-based service designed to receive ZK proofs from various CDK chains and verify their validity before sending them to the L1 for final settlement. It replaces the previous [Golang implementation](agglayer-go.md).
+It replaces the previous [Golang implementation](agglayer-go.md).
 
 ## Architecture
 
diff --git a/docs/agglayer/overview.md b/docs/agglayer/overview.md
diff --git a/docs/agglayer/token-flows.md b/docs/agglayer/token-flows.md
@@ -1,4 +1,4 @@
-The following describes how token transfers and message passing are implemented by the unified bridge across various L1 and L2 permutations. While the examples provided describe only token transfers, the sequence is the same for arbitrary messages in this current implementation of the AggLayer. 
+The following workflows describe how token transfers and message passing are implemented by the unified bridge across various L1 and L2 permutations. While the descriptions refer only to token transfers in the current AggLayer implementation, the sequence of events is exactly the same for arbitrary messages. 
 
 ## L1 to L2
 
@@ -34,7 +34,7 @@ The following describes how token transfers and message passing are implemented
 
 1. When a batch of transactions is processed, the bridge contract appends the L2 exit tree with a new leaf containing the batch information. This updates the L2 exit tree root.
 
-2. The bridge contracts communicates the L2 exit tree root to the L2 global exit root manager. The L2 global exit root manager, however, does not update the global exit tree at this stage.
+2. The bridge contract communicates the L2 exit tree root to the L2 global exit root manager. The L2 global exit root manager, however, does not update the global exit tree at this stage.
 
 3. For proving and verification, the zk-proof-generating circuit obtains the L2 exit tree root from the L2 global exit root manager.
 
diff --git a/docs/agglayer/unified-bridge.md b/docs/agglayer/unified-bridge.md
@@ -1,17 +1,14 @@
-## Overview
-
 The unified bridge is a single bridge contract on Ethereum, providing a safe, common access point for the transfer of all native, never-wrapped tokens. Each chain has a local copy of the unified bridge root, enabling cross-chain interoperability that doesn’t require the security risks of third-party bridges.
 
-
 !!! important "AggLayer smart contracts"
     - The current version of the unified bridge uses the contracts in the [PolygonzkEVM smart contract repo](https://github.com/0xPolygonHermez/zkevm-contracts).
 
 ## Bridging mechanism
 
-The bridging mechanism enables token transfers and message-passing between Ethereum (L1) and CDK chains via smart contracts. Detailed in the [zkEVM bridging documentation](../../zkEVM/architecture/unified-LxLy/bridging.md), core components include the bridge and exit root Solidity smart contracts.
+The bridging mechanism enables token transfers and message-passing between Ethereum (L1) and CDK chains via smart contracts. Detailed in the [zkEVM bridging documentation](../zkEVM/architecture/unified-LxLy/bridging.md), core components include the bridge and exit root Solidity smart contracts.
 
 ## Data structures 
 
 Each chain holds a single data structure which stores a record of all token withdrawals and messages that originated from that chain. This “exit tree” is an append-only Merkle trie, similar in structure to the Ethereum deposit trie. The latest state of each chain and the unified bridge is represented by the root of this Merkle tree, referred to as the “exit root.”
 
-As cryptographic commitments, exit roots ensure the integrity of the network as a whole.  Refer to the [exit root documentation](../../zkEVM/architecture/high-level/smart-contracts/exit-roots.md) for greater detail about the role of exit roots in the system.
+As cryptographic commitments, exit roots ensure the integrity of the network as a whole.  Refer to the [exit root documentation](../zkEVM/architecture/high-level/smart-contracts/exit-roots.md) for greater detail about the role of exit roots in the system.
diff --git a/docs/cdk/concepts/bridging.md b/docs/cdk/concepts/bridging.md
@@ -10,15 +10,15 @@ The LxLy bridge contracts carry out deposit and withdrawal of assets between L2
 
 Chains looking to run their own bridge infrastructure can choose to deploy a new instance of the [LxLy bridge](../../zkEVM/architecture/unified-LxLy/index.md) that allows users to move assets (both native and [ERC20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) tokens) from L1 to the L2 and vice versa.
 
-Deploying an individual instance of the LxLy means interoperability with other L2 chains via the [AggLayer](../../innovation-design/agglayer/overview.md) is not possible. To enable cross-chain interoperability (i.e. L2-to-L2 cross-chain transactions), chains can opt-in to the AggLayer and use the [unified bridge](../../innovation-design/agglayer/unified-bridge.md).
+Deploying an individual instance of the LxLy means interoperability with other L2 chains via the [AggLayer](../../agglayer/overview.md) is not possible. To enable cross-chain interoperability (i.e. L2-to-L2 cross-chain transactions), chains can opt-in to the AggLayer and use the [unified bridge](../../agglayer/unified-bridge.md).
 
 This option is suited to chains that may want to customize how the bridge is managed and operated, or maintain control of the bridge's funds; as the [upgradeability](./admin-upgradeability.md) of the bridge contracts are managed by the chain operator.
 
 ![LxLy bridge](../../img/cdk/lxly.png)
 
 ## Unified bridge
 
-A single, shared instance of the LxLy bridge, called the [unified bridge](../../innovation-design/agglayer/unified-bridge.md) is available to use for all CDK chains that opt-in to the AggLayer. 
+A single, shared instance of the LxLy bridge, called the [unified bridge](../../agglayer/unified-bridge.md) is available to use for all CDK chains that opt-in to the AggLayer. 
 
 It is a shared smart contract deployed on Ethereum, responsible for enabling interoperability between chains in the form of cross-chain transactions and L2-to-L2 transfers.
 
@@ -32,4 +32,4 @@ This option is suited to chains that want a standard bridging experience and do
 
 - [Aggregated blockchains: A new thesis](https://polygon.technology/blog/aggregated-blockchains-a-new-thesis).
 - [LxLy bridge](../../zkEVM/architecture/unified-LxLy/index.md).
-- [Unified bridge overview](../../innovation-design/agglayer/unified-bridge.md).
+- [Unified bridge overview](../../agglayer/unified-bridge.md).
diff --git a/docs/cdk/overview.md b/docs/cdk/overview.md
@@ -16,7 +16,7 @@ Polygon CDK provides the components necessary to build a layer 2 blockchain that
 
 - Modularity: CDK modular components allow developers to easily customize their L2 environment and build a chain that meets their specific needs.
 
-- Interoperability: Opt-in to the [AggLayer](../innovation-design/agglayer/overview.md) to bootstrap your chain's ecosystem, enable cross-chain transactions expanding your reach and user base, while attracting users and liquidity from other established chains.
+- Interoperability: Opt-in to the [AggLayer](../agglayer/overview.md) to bootstrap your chain's ecosystem, enable cross-chain transactions expanding your reach and user base, while attracting users and liquidity from other established chains.
 
 - Sovereignty: Maintain full control over your chain's revenue, governance, security, economic policies, and more.
 
diff --git a/docs/index.md b/docs/index.md
@@ -100,7 +100,7 @@ hide:
 							</div>
 							<p class="feature-paragraph">Deep dives only. Further your understanding of Polygon scaling technology.</p></br>
 						</div>
-						<a href="innovation-design/agglayer/overview" class="flex-card-item w-inline-block">
+						<a href="agglayer/overview" class="flex-card-item w-inline-block">
 							<div class="product-list-item-header">
 								<div class="feature-card-heading">AggLayer</div>
 								<div class="arrow-embed w-embed"><svg xmlns="http://www.w3.org/2000/svg" display="block" width="100%" height="auto" viewbox="0 0 16 17" fill="none">
diff --git a/docs/innovation-design/index.md b/docs/innovation-design/index.md
@@ -32,12 +32,20 @@ hide:
 </div>
 <div class="grid-container">
    <div class="grid-item">
-      <a href="../innovation-design/agglayer/overview">
+      <a href="../agglayer/overview">
          <div class="product-list-item-header">
             <div class="feature-card-heading">AggLayer documentation</div>
          </div>
          <p class="feature-paragraph">AggLayer solves blockchain fragmentation by enabling sovereign chains to securely share liquidity, users, and state.</p>
       </a>
+   </div>
+    <div class="grid-item">
+      <a href="./polygon-protocols">
+         <div class="product-list-item-header">
+            <div class="feature-card-heading">The future of Polygon network</div>
+         </div>
+         <p class="feature-paragraph">Upcoming updates and iterations across Polygon network</p>
+      </a>
    </div>
    <div class="grid-item">
       <a href="../cdk/architecture/type-1-prover/intro-t1-prover">
@@ -62,14 +70,6 @@ hide:
          </div>
          <p class="feature-paragraph">State-of-the-art cryptography libraries for developers.</p>
       </a>
-   </div>
-    <div class="grid-item">
-      <a href="./polygon-protocols">
-         <div class="product-list-item-header">
-            <div class="feature-card-heading">The future of Polygon network</div>
-         </div>
-         <p class="feature-paragraph">Upcoming updates and iterations across Polygon network</p>
-      </a>
    </div>
    <div class="grid-item">
       <a href="https://polygon.technology/blog/reorgs-demystified-insights-from-monitoring-with-a-sensor-network">
diff --git a/docs/pos/overview.md b/docs/pos/overview.md
@@ -36,6 +36,6 @@ The role of these nodes is crucial as they act as a bridge between the Ethereum
 
 ## Upcoming developments
 
-Originally launched as Matic Network in June 2020, Polygon PoS has undergone numerous upgrades since its inception. Initially designed to scale Ethereum through a sidechain, a new proposal on the Polygon forum suggests upgrading Polygon PoS into a zero-knowledge (ZK)-based validium on Ethereum. Polygon PoS will soon adopt the execution environment of Polygon zkEVM along with a dedicated data availability layer. This new architecture would be inherently interoperable with a broader network of ZK-powered Ethereum L2s via the [AggLayer](../innovation-design/agglayer/overview.md).
+Originally launched as Matic Network in June 2020, Polygon PoS has undergone numerous upgrades since its inception. Initially designed to scale Ethereum through a sidechain, a new proposal on the Polygon forum suggests upgrading Polygon PoS into a zero-knowledge (ZK)-based validium on Ethereum. Polygon PoS will soon adopt the execution environment of Polygon zkEVM along with a dedicated data availability layer. This new architecture would be inherently interoperable with a broader network of ZK-powered Ethereum L2s via the [AggLayer](../agglayer/overview.md).
 
 Polygon PoS will continue to be the foundational infrastructure for a wide array of decentralized applications and services. More details about the overarching vision of a unified ecosystem of L2s on Ethereum can be found in [the innovation & design space](../innovation-design/index.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -568,11 +568,11 @@ nav:
       - Innovation & design: innovation-design/index.md
       - Welcome: innovation-design/welcome.md
       - AggLayer:
-        - Overview: innovation-design/agglayer/overview.md
-        - AggLayer | Unified bridge: innovation-design/agglayer/unified-bridge.md
-        - AggLayer | Go: innovation-design/agglayer/agglayer-go.md
-        - AggLayer | Rust: innovation-design/agglayer/agglayer-rs.md
-        - AggLayer | Token flows: innovation-design/agglayer/token-flows.md
+        - Overview: agglayer/overview.md
+        - AggLayer | Unified bridge: agglayer/unified-bridge.md
+        - AggLayer | Go: agglayer/agglayer-go.md
+        - AggLayer | Rust: agglayer/agglayer-rs.md
+        - AggLayer | Token flows: agglayer/token-flows.md
       - Polygon type 1 prover:
           - Introduction and definitions: cdk/architecture/type-1-prover/intro-t1-prover.md
           - How to:
