Skip to content

Commit c58376f

Browse files
kmurphypolygonkmurphypolygon
committed
updating structure and content
1 parent ae67fee commit c58376f

25 files changed

+456
-29
lines changed

‎docs/cdk/agglayer/agglayer-go.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
## Overview
2+
3+
The Agglayer Golang service is a web service designed to receive zero-knowledge proofs from various CDK chains, verify their soundness, and send them to L1 for final verification.
4+
5+
!!! warning
6+
This service is now deprecating in favor of the more robust and efficient [Rust implementation](agglayer-rs.md).
7+
8+
## Get started
9+
10+
### Run locally with Docker
11+
12+
1. Clone the repository:
13+
14+
```bash
15+
git clone https://github.com/AggLayer/agglayer-go
16+
```
17+
18+
2. Execute the following command:
19+
20+
```bash
21+
make run-docker
22+
```
23+
24+
### Configure key signing
25+
26+
1. Install `polygon-cli`:
27+
28+
```bash
29+
go install github.com/maticnetwork/polygon-cli@latest
30+
```
31+
32+
2. Create a new signature:
33+
34+
```bash
35+
polygon-cli signer create --kms GCP --gcp-project-id gcp-project --key-id mykey-tmp
36+
```
37+
38+
3. Install `gcloud` CLI and set up ADC:
39+
40+
```bash
41+
gcloud auth application-default login
42+
```
43+
44+
4. Configure `KMSKeyName` in `agglayer.toml`.
45+
46+
## Production set up
47+
48+
1. Ensure only one instance of Agglayer is running at a time.
49+
2. Use a containerized setup, or OS level service manager/monitoring system, for automatic restarts in the case of failures.
50+
51+
### Prerequisites
52+
53+
#### Hardware
54+
55+
- For each CDK chain it's necessary to configure it's corresponding RPC node, synced with the target CDK.
56+
- This node is for checking the state root after executions of L2 batches.
57+
- We recommend a durable HA PostgresDB for storage, preferably AWS Aurora PostgreSQL or Cloud SQL for PostgreSQL in GCP.
58+
59+
#### Software
60+
61+
- Docker
62+
- Docker Compose
63+
64+
### Installation
65+
66+
1. Clone the repository:
67+
68+
```bash
69+
git clone https://github.com/AggLayer/agglayer-go
70+
```
71+
72+
2. Install Golang dependencies:
73+
74+
```bash
75+
go install .
76+
```
77+
78+
### Configure `agglayer.toml`
79+
80+
* `[FullNodeRPCs]` to point to the corresponding L2 full node.
81+
* `[L1]` to point to the corresponding L1 chain.
82+
* `[DB]` section with the managed database details.
83+
84+
## Architecture
85+
86+
Agglayer's architecture includes interactions with multiple CDK chains for ZKP verification. It uses PostgresDB for storage and interacts with both L1 and L2 chains through configured RPC nodes.
87+
88+
## API
89+
90+
Refer to the `cmd` and `client` directories for API implementation details. Documentation and specific API routes can be generated from these sources.
91+
92+
---
93+
94+
For more information, visit the [AggLayer Golang repository](https://github.com/AggLayer/agglayer-go).

‎docs/cdk/agglayer/agglayer-rs.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
## Overview
2+
3+
AggLayer is a Rust-based web service designed to enhance interoperability among heterogeneous blockchain networks by securely handling zero-knowledge proofs.
4+
5+
The service verifies the soundness of proofs from various CDK chains before forwarding them to L1 for verification.
6+
7+
It replaces the previous [Golang implementation](agglayer-go.md)
8+
9+
## Architecture
10+
11+
### Components
12+
13+
1. Aggregator: Receives and verifies zk-proofs.
14+
15+
2. Verifier: Confirms the soundness of proofs before submitting them to L1.
16+
17+
### Data flow
18+
19+
1. Input: Proofs from various CDK chains.
20+
2. Processing: Verification of proofs.
21+
3. Output: Verified proofs sent to L1.
22+
23+
## Getting started
24+
25+
### Prerequisites
26+
27+
#### Hardware
28+
29+
- RPC nodes: Configure RPC nodes for each CDK chain, and synced with the target CDK, to check the state roots post L2 batch executions.
30+
31+
#### Software
32+
33+
- Rust
34+
35+
### Installation
36+
37+
1. Clone the repository:
38+
39+
```sh
40+
git clone https://github.com/AggLayer/agglayer-rs.git
41+
cd agglayer-rs
42+
```
43+
44+
2. Build and run:
45+
46+
```sh
47+
cargo build
48+
cargo run
49+
```
50+
51+
## How to
52+
53+
### Configure the service
54+
55+
Edit configuration by modifying the `agglayer.toml` file for service settings like RPC endpoints and network parameters. For example:
56+
57+
```toml
58+
[network]
59+
rpc_url = "https://your_rpc_url"
60+
chain_id = "your_chain_id"
61+
```
62+
63+
### Run tests
64+
65+
1. Run unit tests:
66+
67+
```sh
68+
cargo test
69+
```
70+
71+
2. Run integration tests by first ensuring all necessary services are running, then execute:
72+
73+
```sh
74+
cargo test -- --ignored
75+
```
76+
77+
## API reference
78+
79+
### Endpoints
80+
81+
1. **Submit proof**:
82+
- **Endpoint**: `/submit_zkp`
83+
- **Method**: POST
84+
- **Payload**:
85+
86+
```json
87+
{
88+
"zkp": "base64_encoded_zkp",
89+
"chain_id": "cdk_chain_id"
90+
}
91+
```
92+
- **Response**:
93+
94+
```json
95+
{
96+
"status": "success",
97+
"message": "ZKP submitted successfully"
98+
}
99+
```
100+
101+
---
102+
103+
For more information, visit the [AggLayer Rust repository](https://github.com/AggLayer/agglayer-rs).

docs/innovation-design/agglayer/balance-tracking.md renamed to docs/cdk/agglayer/balance-tracking.md

File renamed without changes.

‎docs/cdk/agglayer/bridge-and-call.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
https://github.com/AggLayer/lxly-bridge-and-call

docs/innovation-design/agglayer/current-state-func.md renamed to docs/cdk/agglayer/current-state-func.md

File renamed without changes.

‎docs/cdk/agglayer/overview.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
2+
## Welcome to AggLayer documentation
3+
4+
AggLayer is an evolving ecosystem of zk-based (zero-knowledge) interacting chains. It addresses the current industry focus on interoperability and shared liquidity.
5+
6+
AggLayer is a culmination of Polygon innovation and design. While most rollup environments follow a modular approach, where developers pick-and-choose components such as execution and data availability layers for example, the Agglayer vision is uniquely centered around zk-proof technology.
7+
8+
## AggLayer components
9+
10+
<center>
11+
![CDK architecture](../../img/cdk/cdk-architecture.png)
12+
</center>
13+
14+
### Chain development kit (CDK)
15+
16+
- CDK chains connect to AggLayer.
17+
- CDK chains are similar to other rollup stacks but enforce unique zk-based cryptographic proofs for transaction validation to ensure robust security and efficiency.
18+
- Non-CDK chains will also eventually connect to AggLayer.
19+
20+
### AggLayer
21+
22+
<center>
23+
![AggLayer overview](../../img/cdk/agglayer/agg-layer-overview.png)
24+
</center>
25+
26+
- Evolving from the unified bridge technology, AggLayer takes a many-to-many approach to CDK chain interactions which focuses on validity, interoperability, and security.
27+
- It aggregates and batches proofs from multiple CDK chains into a single proof, significantly lowering the verification cost across chains as the ecosystem grows.
28+
- AggLayer ensures seamless and correct ordering of cross-chain transaction execution.
29+
- Implements securely shared liquidity across zk-based chains.
30+
31+
### Provers
32+
33+
- Provers generate cryptographic proofs for zk-based chains that verify the validity of transactions.
34+
- Ethereum smart contracts then validate those proofs.
35+
- The cost of proof validation on Ethereum remains fixed regardless of the number of transactions.
36+
- AggLayer offers a modular approach to provers. Options include the Polygon zkEVM prover technology and the SP1/Plonky 3 prover currently in development.
37+
38+
<center>
39+
![AggLayer overview](../../img/cdk/agglayer/prover.png)
40+
</center>
41+
42+
These documents introduce you to the current unified bridge technology that inspires and underpins AggLayer. We also document some of AggLayer's key technology in development now; such as the Go and Rust libraries, and Plonky prover technology. We also document a little about what the future has in store.

‎docs/cdk/agglayer/pessimistic-proof.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
## Overview
2+
Pessimistic Proof is a Rust-based project for the AggLayer, focusing on performance-optimized proof generation using AVX512 instructions. It leverages Zero-Knowledge Proof (ZKP) technology for secure computations in Web3 applications.
3+
4+
## Get Started
5+
6+
### Prerequisites
7+
- Rust installed
8+
- AVX512 enabled CPU
9+
10+
### Installation
11+
Clone the repository:
12+
```sh
13+
git clone https://github.com/AggLayer/pessimistic-proof.git
14+
cd pessimistic-proof
15+
```
16+
17+
### Running the Project
18+
```sh
19+
RUST_LOG=info RUSTFLAGS='-C target-cpu=native -C target_feature=+avx512ifma,+avx512vl --cfg curve25519_dalek_backend="simd"' cargo run --release
20+
```
21+
22+
## How To's
23+
24+
### How to Compile
25+
Ensure you have the required Rust version and run:
26+
```sh
27+
cargo build --release
28+
```
29+
30+
### How to Run Tests
31+
Run the following command to execute tests:
32+
```sh
33+
cargo test
34+
```
35+
36+
## Architectural Information
37+
38+
### Directory Structure
39+
- `pessimistic_proof/`: Core library for proof generation.
40+
- `program/`: Contains the main program logic.
41+
- `script/`: Helper scripts.
42+
43+
### Core Components
44+
- **Proof Generation**: Utilizes curve25519_dalek for cryptographic operations.
45+
- **SIMD Optimization**: Employs SIMD (Single Instruction, Multiple Data) for performance improvements using AVX512.
46+
47+
## API Reference
48+
49+
### Key Functions
50+
- **generate_proof**: Generates a proof for given inputs.
51+
```rust
52+
fn generate_proof(input: &Input) -> Proof
53+
```
54+
- **verify_proof**: Verifies the generated proof.
55+
```rust
56+
fn verify_proof(proof: &Proof) -> bool
57+
```
58+
59+
### Data Structures
60+
- **Input**: Represents the input data structure for proof generation.
61+
- **Proof**: Represents the generated proof structure.
62+
63+
---
64+
65+
For more details, visit the [GitHub repository](https://github.com/AggLayer/pessimistic-proof).

‎docs/cdk/agglayer/roadmap.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
hide:
3+
- toc
4+
---
5+
6+
7+
| AggLayer version | AggLayer: Unified bridge | AggLayer: Go implementation | AggLayer: Rust implementation | AggLayer: Rust with pessimistic proof | AggLayer: Multi-chain |
8+
|------------------------|--------------------------|-----------------------------|-------------------------------|---------------------------------------|-----------------------|
9+
| Initial sync time | | | | | |
10+
| Snapshots available | | | | | |
11+
| Finality L1 to L2 | | | | | |
12+
| Finality L2 to L1 | | | | | |
13+
| Finality L2 to L2 | | | | | |
14+
| Transaction fees | | | | | |
15+
| Transaction per second | | | | | |
16+
| Prover type | | | | | |

docs/innovation-design/agglayer/current-state-dev.md renamed to docs/cdk/agglayer/specifications.md

File renamed without changes.

‎docs/cdk/agglayer/unified-bridge.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
AggLayer's beginnings lie in the Polygon zkEVM unified bridge technology which was originally implemented for Polygon zkEVM.
2+
3+
The unified bridge supports Ethereum scalability and interoperability by using advanced cryptographic techniques and Solidity smart contracts on L1 and L2. It facilitates secure cross-chain interactions and asset transfers, ensuring transaction throughput and integrity.
4+
5+
An Ethereum scalability solution, the unified bridge facilitates seamless L1-L2 interaction and relies on robust and secure zero-knowledge proofs.
6+
7+
!!! important "AggLayer smart contracts"
8+
- The [AggLayer smart contract repo](https://github.com/AggLayer/ulxly-contracts) differs in minor ways only to the [unified bridge smart contract rep](https://github.com/0xPolygonHermez/zkevm-contracts).
9+
10+
## Unified bridge architecture
11+
12+
The following class diagram depicts where the unified bridge functionality sits within the wider smart contract environment.
13+
14+
![Solidity contract class diagram](../../img/cdk/high-level-architecture/smart-contract-full-view-plus-bridge.png)
15+
16+
## Bridging mechanism
17+
18+
The bridging mechanism enables asset and data transfer between Ethereum (L1) and Polygon zkEVM (L2) 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.
19+
20+
![Unified bridge class diagram](../../img/cdk/high-level-architecture/bridging-class-diagram.png)
21+
22+
## Exit roots
23+
24+
Exit roots, cryptographic commitments representing system states, ensure integrity of the system as a whole. Refer to the [exit root documentation](../../zkEVM/architecture/high-level/smart-contracts/exit-roots.md) to understand the role of exit roots in state synchronization and fraud proofing.
25+
26+
![Exit root class diagram](../../img/cdk/high-level-architecture/exit-root-class-diagram.png)
27+
28+
## Main contracts
29+
30+
Critical to the zkEVM bridge, the consensus contracts govern core operations such as sequencing and verification. Learn more in the [main contract documentation](../../zkEVM/architecture/high-level/smart-contracts/main-contracts.md) where you can find more information on the consensus contracts and rollup manager, as well as unified bridge and exit root contracts.
31+
32+
### Sequencing
33+
34+
Sequencing maintains transaction order and integrity, encompassing transaction ordering and batch processing. Dive into the details via [smart contract sequencing documentation](../../zkEVM/architecture/high-level/smart-contracts/sequencing.md).
35+
36+
![Smart contract sequencing flow](../../img/cdk/high-level-architecture/sequencing-flow.png)
37+
38+
### Verification
39+
40+
Security is ensured through zk-proofs, verifying transaction correctness. Understand proof generation and validation in the [smart contract verification documentation](https://docs.polygon.technology/zkEVM/architecture/high-level/smart-contracts/verification/).
41+
42+
![Smart contract sequencing flow](../../img/cdk/high-level-architecture/verification-flow.png)
43+
44+
!!! tip "More information"
45+
Explore the unified bridge components and releases in some of the historical [zkEVM unified bridge documentation](../../zkEVM/architecture/protocol/unified-LxLy/lxly-bridge.md).
46+

0 commit comments

Comments
 (0)