Merge branch 'main' of https://github.com/0xPolygon/polygon-docs into cdk/erigon-setup

Author: kmurphypolygon

docs/cdk/agglayer/agglayer-go.md

@@ -0,0 +1,100 @@
+## 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
+    This service is being deprecated in favor of the more robust and efficient [Rust implementation](agglayer-rs.md).
+
+## Architecture
+
+The AggLayer Golang architecture supports interactions with multiple CDK chains for proof-verification. It uses a PostgreSQL database for storage and interacts with both L1 and L2 chains through configured RPC nodes.
+
+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)
+</center>
+
+## Get started
+
+### Run locally with Docker
+
+1. Clone the repository:
+
+    ```bash
+    git clone https://github.com/AggLayer/agglayer-go
+    ```
+
+2. Execute the following command:
+
+    ```bash
+    make run-docker
+    ```
+
+## Production set up
+
+1. Ensure only one instance of the AggLayer is running at a time.
+2. Use a containerized setup, or OS level service manager/monitoring system, for automatic restarts in the case of failures.
+
+### Prerequisites
+
+#### Hardware
+
+- For each CDK chain it's necessary to configure its corresponding RPC node, synced with the target CDK. 
+- This node is for checking the state root after executions of L2 batches.
+- We recommend a durable HA PostgresDB for storage, preferably AWS Aurora PostgreSQL or Cloud SQL for PostgreSQL in GCP.
+
+#### Software
+
+- Docker
+- Docker Compose
+
+### Installation
+
+1. Clone the repository:
+
+    ```bash
+    git clone https://github.com/AggLayer/agglayer-go
+    ```
+
+2. Install Golang dependencies:
+
+    ```bash
+    go install .
+    ```
+
+### Configure key signing 
+
+1. Install `polygon-cli`:
+
+    ```bash
+    go install github.com/maticnetwork/polygon-cli@latest
+    ```
+
+2. Create a new signature:
+
+    ```bash
+    polygon-cli signer create --kms GCP --gcp-project-id gcp-project --key-id mykey-tmp
+    ```
+
+3. Install `gcloud` CLI and set up ADC:
+
+    ```bash
+    gcloud auth application-default login
+    ```
+
+4. Configure `KMSKeyName` in `agglayer.toml`.
+
+### Configure `agglayer.toml`
+
+* `[FullNodeRPCs]` to point to the corresponding L2 full node.
+* `[L1]` to point to the corresponding L1 chain.
+* `[DB]` section with the managed database details.
+
+## API
+
+Refer to the `cmd` and `client` directories for API implementation details. Documentation and specific API routes can be generated from these sources.
+
+---
+
+For more information, visit the [AggLayer-go repository](https://github.com/AggLayer/agglayer-go).

docs/cdk/agglayer/agglayer-rs.md

@@ -0,0 +1,91 @@
+## 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. It replaces the previous [Golang implementation](agglayer-go.md).
+
+## Architecture
+
+The AggLayer Rust architecture supports interactions with multiple CDK chains for proof-verification. Its architecture is the same as `agglayer-go`, but without the PostgreSQL database for storage. 
+
+## Getting started
+
+### Prerequisites
+
+#### Hardware 
+
+- RPC nodes: Configure RPC nodes for each CDK chain, and synced with the target CDK, to check the state roots post L2 batch executions.
+
+#### Software
+
+- Rust
+
+### Installation
+
+1. Clone the repository:
+
+      ```sh
+      git clone https://github.com/AggLayer/agglayer-rs.git
+      cd agglayer-rs
+      ```
+
+2. Build and run:
+
+      ```sh
+      cargo build
+      cargo run
+      ```
+
+## How to
+
+### Configure the service
+
+Edit configuration by modifying the `agglayer.toml` file for service settings like RPC endpoints and network parameters. For example:
+
+```toml
+[network]
+rpc_url = "https://your_rpc_url"
+chain_id = "your_chain_id"
+```
+
+### Run tests
+
+1. Run unit tests:
+
+      ```sh
+      cargo test
+      ```
+
+2. Run integration tests by first ensuring all necessary services are running, then execute:
+
+      ```sh
+      cargo test -- --ignored
+      ```
+
+## API reference
+
+### Endpoints
+
+#### Submit proof
+
+- **Endpoint**: `/submit_zkp`
+- **Method**: POST
+- **Payload**: 
+
+     ```json
+     {
+       "zkp": "base64_encoded_zkp",
+       "chain_id": "cdk_chain_id"
+     }
+     ```
+
+- **Response**:
+
+     ```json
+     {
+       "status": "success",
+       "message": "ZKP submitted successfully"
+     }
+     ```
+
+---
+
+For more information, visit the [AggLayer Rust repository](https://github.com/AggLayer/agglayer-rs).

docs/cdk/agglayer/overview.md

@@ -0,0 +1,25 @@
+!!! info "Disclaimer"
+    - Some of the content in this section discusses technology in development and not ready for release.
+    - Please check against the main documentation site for any live releases.
+    - Feel free to experiment with any code in public repos.
+
+The AggLayer is an in-development interoperability protocol that allows for trustless, cross-chain token transfers and message-passing, as well as more complex operations. The safety of the AggLayer is provided by ZK proofs. 
+
+The AggLayer currently connects chains built with Polygon CDK, a developer toolkit for designing ZK-powered Layer 2s. The long term goal for the protocol is to be flexible enough to provide interoperability among a growing range of blockchain architectures, including L2s, appchains, and non-EVM chains. 
+ 
+## AggLayer components
+
+### Polygon CDK
+
+The AggLayer connects chains built with Polygon CDK, which use ZK proofs to generate state transitions that are cryptographically secure. 
+
+### Unified bridge
+
+The unified bridge is a single bridge contract for all AggLayer-connected chains, allowing for the cross-chain transfer of fungible (non-wrapped) tokens. It is the source of unified liquidity for the AggLayer. 
+
+!!! tip "More information"
+    See the [unified bridge documentation](unified-bridge.md) for details. 
+
+### AggLayer service
+
+The AggLayer service is a service designed to receive ZK proofs from various CDK chains and verify their validity before sending them to the L1 for final settlement. Currently, the AggLayer service has two implementations: [agglayer-go](agglayer-go.md) and [agglayer-rs](agglayer-rs.md).

docs/cdk/agglayer/token-flows.md

@@ -0,0 +1,43 @@
+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. 
+
+## L1 to L2
+
+1. If a call to `bridgeAsset` or `bridgeMessage` on L1 passes validation, the unified bridge contract appends an exit leaf to the L1 exit tree and computes the new L1 exit tree root.
+
+2. The global exit root manager appends the new L1 exit tree root to the global exit tree and computes the global exit root.
+
+3. The sequencer fetches the latest global exit root from the global exit root manager.
+
+4. At the start of the transaction batch, the sequencer stores the global exit root in special storage slots of the L2 global exit root manager smart contract, allowing L2 users to access it.
+
+5. A call to `claimAsset` or `claimMessage` provides a Merkle proof that validates the correct exit leaf in the global exit root.
+
+6. The unified bridge contract validates the caller's Merkle proof against the global exit root. If the proof is valid, the bridging process succeeds; otherwise, the transaction fails.
+
+## L2 to L1
+
+1. If a call to `bridgeAsset` or `bridgeMessage` on L2 passes validation, the unified bridge contract appends an exit leaf to the L2 exit tree and computes the new L2 exit tree root.
+
+2. The L2 global exit root manager appends the new L2 exit tree root to the global exit tree and computes the global exit root. At that point, the caller's bridge transaction is included in one of the batches selected and sequenced by the sequencer.
+
+3. The aggregator generates a zk-proof attesting to the computational integrity in the execution of sequenced batches which include the transaction.
+
+4. For verification purposes, the aggregator sends the zk-proof together with all relevant batch information that led to the new L2 exit tree root (computed in step 2), to the verifier contract.
+
+5. The verifier contract utilizes the `verifyBatches` function to verify validity of the received zk-proof. If valid, the contract sends the new L2 exit tree root to the global exit root manager in order to update the global exit tree.
+
+6. `claimMessage` or `claimAsset` is then called on the unified bridge contract with Merkle proofs for correct validation of exit leaves.
+
+7. The unified bridge contract retrieves the global exit root from the L1 global exit root manager and verifies validity of the Merkle proof. If the Merkle proof is valid, the settlement completes, otherwise, the transaction is reverted.
+
+## L2 to L2
+
+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.
+
+3. For proving and verification, the zk-proof-generating circuit obtains the L2 exit tree root from the L2 global exit root manager.
+
+4. Only after the batch has been successfully proved and verified does the L2 global exit root manager append the L2 exit tree root to the global exit tree. As a result, the global exit root is updated.
+
+5. The zk-proof-generating circuit also writes the L2 exit tree root to the mainnet. The L1 bridge contract can then finalize the transfer by using the `claim` function.

docs/cdk/agglayer/unified-bridge.md

@@ -0,0 +1,17 @@
+## 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/high-level/smart-contracts/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.