Merge pull request 0xPolygon#321 from 0xPolygon/unified-lxly-bridge

CDK: add unified bridge STB, glossary

Author: hsutaiyu

docs/cdk/architecture/staking-the-bridge.md

@@ -0,0 +1,122 @@
+The LxLy bridge is the native bridging infrastructure for all CDK chains. The way it works is each individual CDK chain deploys an instance of the LxLy bridge that connects to an L1 (Ethereum by default) by deploying contracts that carry out deposit and withdrawal of assets, along with escrow management. These contracts are managed by node operators corresponding to the respective CDK chains.
+
+This changes as the AggLayer v1 goes online, and introduces an upgrade to the existing LxLy architecture in the form of a _unified instance_ of the LxLy bridge that multiple chains can connect to.
+
+## What's "unified" bridge?
+
+Polygon AggLayer envisions a scalability solution that leverages shared state and unified liquidity across multiple ZK-powered chains within the Polygon ecosystem, all powered by the CDK infrastructure.
+
+!!! tip "What's AggLayer?"
+
+    Want to learn more about what AggLayer is and what it looks to achieve? Check out [the AggLayer documentation in the Learn space](../../learn/agglayer.md).
+
+All of this cool infrastructure needs a unified channel for easy transmission of assets and messages between the multiple chains connected via the AggLayer. And this is where the unified bridge comes into play. It allows all chains to take advantage of the AggLayer's unified liquidity, lower transaction costs, and more.
+
+!!! tip "Lxly vs unified bridging TL;DR"
+
+    - **LxLy bridge:** A ZK bridge that supports asset and message transfers between a zkEVM system and the L1, typically Ethereum.
+    - **Unified bridge:** A specific instance of an LxLy bridge that allows several chains to connect to it. This instance is specific to the AggLayer v1.  
+
+The new unified model of the LxLy bridge introduced as a part of the AggLayer v1 infrastructure has one significant difference from the existing LxLy bridge: any asset bridged onto a CDK chain using the unified bridge is held by the the **Unified Escrow** (also referred to as the **Master Escrow**) contract instead of a dedicated bridge contract.
+
+!!! info
+
+    The master escrow contract is managed and governed by the Polygon zkEVM team.
+
+Due to the shared nature of the bridge, chain operators will not have admin access to the funds locked in the master escrow contract, including the funds that belong to their own network. 
+
+The ability to manage bridge reserves is crucial to implement restaking for yield generation and other similar use cases. How does the unified bridge address this?
+
+## Introducing "Stake the Bridge"
+
+Stake the Bridge, or **STB**, is a feature that lets CDK chain operators maintain control over the assets that are deposited to their respective networks.
+
+### Design and implementation
+
+On L1, CDK chains enable STB for an asset by deploying STB contracts on L1 to create an alternative [`L1Escrow`](https://github.com/pyk/zkevm-stb/blob/main/src/L1Escrow.sol) account that holds the asset, and allows the CDK chain operator to manage this token reserve.
+
+On L2 (the CDK chain), there are three components needed to make this work:
+
+- [`L2Token`](https://github.com/pyk/zkevm-stb/blob/main/src/L2Token.sol), which is a natively deployed ERC20 contract.
+- [`L2Escrow`](https://github.com/pyk/zkevm-stb/blob/main/src/L2Escrow.sol), a contract that manages the L2Token's supply.
+- [`L2TokenConverter`](https://github.com/pyk/zkevm-stb/blob/main/src/L2TokenConverter.sol), the contract that enables converting bridge-wrapped tokens to natively-minted tokens on L2.
+
+!!! info
+
+    Each token needs to have its own set of STB contracts that perform the functions described above.
+
+Let's briefly go over the specific actions and characteristics of each STB contract on L1 and L2.
+
+#### `L1Escrow`
+
+- Defines investment strategies.
+- Sending token issuance messages to `L2Escrow`.
+- Fulfilling redemption messages from `L2Escrow`.
+
+#### `L2Escrow`
+
+- Receives minting instructions from `L1Escrow` via the unified bridge upon token deposit, and prompts `L2Token` contract to mint assets to a given address on L2.
+- Burns the native asset on L2 and sends minting instructions to `L1Escrow` to release assets on L1.
+
+#### `L2Token`
+
+- Natively mints L2 tokens and sends them to a designated address.
+- Interfaces with the `L2TokenConverter` contract.
+
+#### `L2TokenConverter`
+
+- Supports 1:1 conversion between the STB minted native tokens, and the bridged tokens minted by depositing tokens to LxLy bridge directly on L1.
+- Doesn't have a default cap on the token volume that can be converted, can be added by chain operators as necessary.
+- An asset can have multiple token converters that can have different properties.
+
+## Roles and responsibilities
+
+There are three roles, each of which performs specific actions to manage the STB system:
+
+- Admin: Can upgrade and pause the system.
+- Escrow manager: Can withdraw token backing from the respective escrow contract to invest using the `managerWithdraw()` function.
+- Risk manager: Can invoke `setIssuanceCap()` multiple times to increase or reduce the issuance cap.
+
+## STB transaction flow vs. existing LxLy flow
+
+With the STB contracts set up on L1 and L2 for a particular CDK chain, the bridging UX for a user doesn't differ from what it would be if they were carrying it out using the existing LxLy bridge. Let's consider an example using the following tokens:
+
+- USDC - L1
+- USDC.e - L2
+- LxLy USDC
+
+![](../../img/cdk/stb-1.png)
+
+The diagram above illustrates the following flow:
+
+1. A user initiates a USDC deposit from L1 to L2.
+2. Instead of being deposited directly to the unified bridge, the USDC is deposited into the STB `L1Escrow` contract.  
+3. The STB `L1Escrow` locks the USDC and passes a message to the unified messenger containing the user’s address and amount of USDC being bridged.  
+4. The `Messenger` contract validates the message and then sends it to the STB `L2Escrow`.    
+5. The STB `L2Escrow` receives the message and mints USDC.e from the `L2Token` contract. 
+6. The USDC.e is sent to the user's address on L2. 
+
+### Native token conversion
+
+With the introduction of STB, there are now two ways to deposit tokens to an L2 CDK chain, and two distinct resultant tokens:
+
+- The STB flow involves locking tokens in the L1Escrow contract, which is followed by the minting of USDC.e on L2.
+- On the other hand, if the tokens are deposited directly into the LxLy bridge contract, it results in the minting of LxLy USDC on L2.
+
+The `L2TokenConverter` facilitates conversion between USDC.e and LxLy USDC. The way it works is by locking (`Deposit` function) either of the tokens in the converter contract, and then sending (`Withdraw` function) the equivalent amount of the other token to the user's wallet.
+
+## Using the STB contracts
+
+The STB contracts grant chain operators control over the token backing in the escrow contracts for all the chains that connect to the Polygon ecosystem via the AggLayer.
+
+!!! warning
+
+    Polygon Labs **does not** manage or facilitate the investing of the funds locked in the escrow contracts. The management of funds to implement any investment strategies and risk profiles is completely at the discretion of the chain operators and owners.
+
+Bridging tokens to L2 CDK chains using the STB contracts is ideal for the following use cases:
+
+- Coins that need to implement staking and yield generation mechanisms.
+- Coins that need to implement custom L2 functionality.
+- Coins that possess native issuance capabilities.
+
+Want to start testing with STB? The contracts are still being audited, but are ready to use on testnets, and can be found here: https://github.com/pyk/zkevm-stb. 

docs/cdk/concepts/dac.md

@@ -0,0 +1,42 @@
+This glossary provides definitions for technical terminology and concepts that commonly occur throughout the CDK docs space.
+
+### AggLayer v1 (AL1)
+The AggLayer is the interoperability layer at the heart of Polygon 2.0. All CDK chains connect to the AggLayer to enable features such as seamless and efficient cross-chain communication, unified liquidity, and more. AggLayer v1 (AL1), is the first version of many planned iterations that relies on ZK checks to ensure operational soundness, and a unified bridge infrastructure.
+Read more on the AggLayer [here](../../learn/agglayer.md).
+
+### Chain operator
+The IP, or individual(s), who own a chain and are responsible for chain operation and maintenance. This includes tasks such as transaction validation, block production, and ensuring the security and integrity of the chain, etc., any combination of which a chain operator may perform personally in varying degrees.
+
+### Data availability
+Data availability in the context of modular rollups refers to the idea that transaction callback data needs to be available to L1 network actors where transactions are settled and finalized, so it can be used to verify transaction execution if necessary. 
+
+### Data Availability Committee (DAC)
+Polygon CDK validiums connect to a DAC to guarantee data availability. The DAC nodes fetch tx data from the sequencer, validate it independently, and then sign it guaranteeing its validity before storing it in the local database. The data remains available to be fetched by other networks actors across all DAC nodes.
+
+### LxLy bridge
+The native bridge infrastructure of CDK chains that allows transfer of assets and messages between L2 and L1 (typically Ethereum).
+
+### LxLy messenger
+A contract on the LxLy bridge utilizes its message passing capabilities to pass arbitrary messages between L1 and L2.  This is not a separate component, and is part of the LxLy bridge's architecture.
+
+### POL (Token)
+The POL token powers the Polygon 2.0 ecosystem through a native re-staking protocol that allows token holders to validate multiple chains, and perform multiple roles on each of those chains (sequencing, ZK proof generation, participation in data availability committees, etc.) 
+
+### Rollups
+Rollups refer to blockchain scaling solutions (in the context of Ethereum) that carry out transaction execution on L2, and then post updated state data to a contract on L1. There are different types rollups, two of the most popular being optimistic, and zero-knowledge (ZK) rollups. Follow the links below to learn more:
+
+- [Optimistic rollups](https://ethereum.org/en/developers/docs/scaling/optimistic-rollups/)
+- [ZK rollups](https://ethereum.org/en/developers/docs/scaling/zk-rollups/)
+
+### Stake the Bridge (STB)
+A feature of the [unified bridge](#unified-bridge) that lets CDK chain operators maintain control over the assets that are deposited to their respective networks, enabling them to implement staking mechanisms, investment strategies, and other custom features on L2.
+
+### Unified bridge
+A specific instance of an LxLy bridge that allows several chains to connect to it.  This instance is specific to the [AggLayer v1](#agglayer-v1-al1).
+
+### Unified escrow (Master Escrow)
+The unified bridge's escrow contract that holds all the tokens that bridged (locked on L1), and natively minted on L2.
+
+### Validiums
+Validiums are a special kind of ZK rollup protocol that handles data availability off-chain instead of posting callback data to base layer Ethereum. CDK chains support deploying and running validium using a Data Availability Committee (DAC) as the DA solution.
+Learn more about validiums [here](https://ethereum.org/en/developers/docs/scaling/validium/).

docs/cdk/concepts/rollup.md

@@ -51,4 +51,12 @@ hide:
          <p class="feature-paragraph">Discover the key differences between the rollup and validium infrastructure options.</p>
       </a>
    </div>
+   <div class="grid-item">
+      <a href="./glossary">
+         <div class="product-list-item-header">
+            <div class="feature-card-heading">Glossary</div>
+         </div>
+         <p class="feature-paragraph">Learn about commonly used terminology and concepts relevant to the CDK tech stack.</p>
+      </a>
+   </div>
 </div>

docs/cdk/concepts/validium.md

@@ -1,11 +1,11 @@
-Polygon CDK running in validium mode inherits the core functionalities of a zkEVM rollup node and adds a [data availability layer](../concepts/dac.md).
+Polygon CDK running in validium mode inherits the core functionalities of a zkEVM rollup node and adds a [data availability layer](../glossary/index.md#data-availability-committee-dac).
 
 ## Key differences
 
 |        | Rollup                                                    | Validium                                                                           |
 | ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | **Node type**            | [zkEVM node](https://github.com/0xPolygonHermez/zkevm-node) | [Validium node](https://github.com/0xPolygon/cdk-validium-node): zkEVM node with validium extensions                  |
-| **Data availability**    | On-chain via L1                                            | Off-chain via a local option, or a [DAC](../concepts/dac.md) + [DA node](https://github.com/0xPolygon/cdk-data-availability) |
+| **Data availability**    | On-chain via L1                                            | Off-chain via a local option, or a [DAC](../glossary/index.md#data-availability-committee-dac) + [DA node](https://github.com/0xPolygon/cdk-data-availability) |
 | **Components**           | zkEVM components\*                                        | zkEVM components\* + PostgreSQL database + on-chain committees                   |
 | **Contracts** | [zkEVM smart contracts](https://github.com/0xPolygonHermez/zkevm-contracts)  <ul><li>`PolygonZkEVM` (main rollup contract)</li> <li> `PolygonZkEVMBridge`</li> <li>`PolygonZkEVMGlobalExitRoot`</li></ul>  | [Validium-specific DAC contract](https://github.com/0xPolygon/cdk-validium-contracts) <ul><li>`CDKDataCommittee.sol`</li><li> `CDKValidium.sol` </li></ul> |
 | **Infrastructure** | Standard infrastructure                                     | Dedicated infrastructure for data availability layer and DACs                      |

docs/cdk/glossary/index.md

@@ -89,12 +89,11 @@ nav:
       - Architecture:
         - CDK rollup: cdk/architecture/cdk-zkevm.md
         - CDK validium: cdk/architecture/cdk-validium.md
+        - Unified bridge - STB: cdk/architecture/staking-the-bridge.md
       - Specification:
         - Validium vs rollup: cdk/spec/validium-vs-rollup.md
-      - Concepts:
-        - Rollup: cdk/concepts/rollup.md
-        - Validium: cdk/concepts/validium.md
-        - Data availability: cdk/concepts/dac.md
+      - Glossary:
+        - Glossary: cdk/glossary/index.md
       - Additional resources:
         - Third-party guides: cdk/resources/third-party-guides.md
         - CDK repos: cdk/resources/cdk-repo-reference.md