Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CDK PP Docs Review Env: DO NOT MERGE!!! #2459

Merged
merged 25 commits into from
Nov 21, 2024
Merged

CDK PP Docs Review Env: DO NOT MERGE!!! #2459

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
49d7747
CDK PP docs review env
EmpieichO Oct 23, 2024
dc6b842
Create pp-intro.components.md
EmpieichO Oct 23, 2024
5e111f3
Update nav ... mkdocs.yml
EmpieichO Oct 23, 2024
e0c1a09
Update mkdocs.yml
EmpieichO Oct 23, 2024
2739fe6
Update pp-intro.components.md
EmpieichO Oct 23, 2024
08d3d30
Update pp-intro.components.md
EmpieichO Oct 23, 2024
9f88432
Update pp-intro.components.md
EmpieichO Oct 24, 2024
f0a1347
Update resources.md
EmpieichO Oct 24, 2024
3f6f1f5
Create cdk-pp-highlevel-arch.md
EmpieichO Oct 24, 2024
78983f0
Add files via upload
EmpieichO Oct 24, 2024
c1dcfb4
Update mkdocs.yml
EmpieichO Oct 24, 2024
95bc789
Update high-level-views.md
EmpieichO Oct 24, 2024
1e477ab
Update cli-tool.md
EmpieichO Oct 24, 2024
cffe05f
Add files via upload
EmpieichO Oct 24, 2024
6cd106e
Update pp-intro.components.md
EmpieichO Oct 25, 2024
50fe59d
Update pp-intro.components.md
EmpieichO Oct 25, 2024
dab2f0d
Update docs/cdk/architecture/cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
fc11c3e
Update docs/cdk/architecture/cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
342775b
Update docs/cdk/architecture/cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
403945f
Update docs/cdk/architecture/cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
89dd66f
Update docs/cdk/architecture/cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
98b4573
Update cdk-pp-highlevel-arch.md
mitchpolygon Nov 21, 2024
c9ffa8d
Update pp-intro.components.md
mitchpolygon Nov 21, 2024
a43098a
Merge branch 'main' into hosted/cdk-pp-docs-review-env
mitchpolygon Nov 21, 2024
228e3d8
Update index.md
mitchpolygon Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions docs/cdk/architecture/cdk-pp-highlevel-arch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
The figure below depicts a simplified, high level view of the CDK PP chain architecture, as well as the flow of transactions through the system.

![Figure: CDK PP Architecture](../../img/cdk/cdk-pp-architecture-001.png)

## Transaction flow

Here is a step by step flow of transactions starting from when users submit transactions up to when the transactions are settled in L1.

1. A user connects to the chain via a CDK Erigon RPC node and submits a transaction.
2. CDK Erigon RPC node sends the transaction data to the transaction-pool manager.
3. The transaction-pool manager proxies all transaction data to the CDK Erigon sequencer.
4. CDK Erigon sequencer executes transactions, puts the transactions in blocks, and the blocks fill up batches.
5. CDK Erigon sequencer syncs all transaction data with any CDK Erigon RPC node.
6. AggSender gets batch data from the CDK Erigon sequencer, uses the data to generate certificates, and submits the certificates to the JSON-RPC API.
7. The JSON-RPC API checks validity of the certificates against the transaction data in the CDK Erigon RPC node.
8. After validating the certificates, the JSON-RPC API sends a request to generate a proof, together with the necessary data (including the certificates), to the SP1 prover.
9. Once the proof is received from the SP1 prover, the JSON-RPC API sends it to L1.



## Sequential diagram

The flow of data is depicted in the squential diagram below.

1. User submits a tx to the CDK Erigon RPC node.
2. The CDK Erigon RPC node sends tx data to the tx-pool man.
3. The tx-pool man proxies tx data to the CDK Erigon sequencer.
4. CDK Erigon sequencer executes transactions.
5. CDK Erigon sequencer syncs tx data with another CDK Erigon RPC node.
6. AggSender gets batch data from the CDK Erigon sequencer.
7. AggSender submits certificates to the JSON-RPC API.
8. JSON-RPC API checks validity of the certificates.
9. JSON-RPC API requests a proof from SP1 prover.
10. SP1 prover sends back a proof.
11. JSON-RPC API sends proof to L1.



```mermaid
sequenceDiagram
participant User
participant ErigonRPC1 as RPC node 1
participant tx-pool-man as tx-pool manager
participant Sequencer as Sequencer node
participant ErigonRPC2 as RPC node 2
participant AggSender as AggSender
participant API as JSON-RPC API
participant SP1-prover as SP1 prover
participant L1 as L1

User->>ErigonRPC1: submits tx
ErigonRPC1->>tx-pool-man: sends tx data
tx-pool-man->>Sequencer: proxies tx data
Sequencer->>Sequencer: sequences transactions
Sequencer->>ErigonRPC2: syncs data
AggSender->>Sequencer: reads batch data
AggSender->>API: sends certificates
API->>ErigonRPC2: checks validity
API->>SP1-prover: requests proof
SP1-prover->>API: returns proof
API->>L1: submits proof
```
2 changes: 0 additions & 2 deletions docs/cdk/architecture/high-level-views.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
## CDK full execution proof (FEP)

The diagram below depicts a simplified architectural layout of the CDK FEP stack and indicates at a high level how components communicate.

![High level view of CDK stack](../../img/cdk/cdk-stack.svg)
Expand Down
15 changes: 4 additions & 11 deletions docs/cdk/getting-started/cdk-erigon/resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,4 @@
## Networks

| Network Name | Chain ID | ForkID | Genesis File | RPC URL | Rootchain | Rollup Address |
|---------------|----------|--------|--------------|--------------------------------------------------|------------------|----------------------------------------------|
| zkEVM Mainnet | 1101 | 9 | [Link](https://hackmd.io/bpmxb5QaSFafV0nB4i-KZA) | [Mainnet RPC](https://zkevm-rpc.com/) | Ethereum Mainnet | `0x5132A183E9F3CB7C848b0AAC5Ae0c4f0491B7aB2` |
| zkEVM Cardona | 2442 | 9 | [Link](https://hackmd.io/Ug9pB613SvevJgnXRC4YJA) | [Cardona RPC](https://rpc.cardona.zkevm-rpc.com/) | Sepolia | `0x32d33D5137a7cFFb54c5Bf8371172bcEc5f310ff` |

## Block explorers

- Mainnet: [PolygonScan mainnet](https://zkevm.polygonscan.com/)
- Cardona: [PolygonScan Cardona](https://cardona-zkevm.polygonscan.com/)
| Network | Chain ID | Genesis file | RPC URL | Block explorer | Rootchain | Rollup Address |
|---------------|----------|--------------------------------------------------|---------------------------------------------------|-------------------------------------------------------------------|------------------|----------------------------------------------|
| zkEVM mainnet | 1101 | [Link to genesis.json](https://ipfs.io/ipfs/QmUXnRoPbUmZuEZCGyiHjEsoNcFVu3hLtSvhpnfBS2mAYU) | `https://zkevm-rpc.com/` | [ PolygonScan mainnet ]( https://zkevm.polygonscan.com/ ) | Ethereum Mainnet | `0x5132A183E9F3CB7C848b0AAC5Ae0c4f0491B7aB2` |
| zkEVM Cardona | 2442 | [Link to genesis.json](https://ipfs.io/ipfs/QmZVxfDG5SbeFT2Zb3BLhf48GmFLyweAnxpPty6Wa8a2YU) | `https://rpc.cardona.zkevm-rpc.com/` | [ PolygonScan Cardona ]( https://cardona-zkevm.polygonscan.com/ ) | Sepolia | `0x32d33D5137a7cFFb54c5Bf8371172bcEc5f310ff` |
8 changes: 6 additions & 2 deletions docs/cdk/getting-started/cli-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ Options:
* `-g, --chain <CHAIN>` - The path to a chain specification file [env: `CDK_GENESIS_PATH=`]
* `-h, --help` - Print help

```
cdk erigon --config /etc/cdk/cdk-node-config.toml --chain genesis.json
```

### `cdk versions`

The above command generates all the required configuration files for cdk-erigon on the fly and runs the node.
Expand All @@ -75,5 +79,5 @@ Options:
Example:

```
cdk erigon --config /etc/cdk/cdk-node-config.toml --chain genesis.json
```
cdk versions
```
61 changes: 61 additions & 0 deletions docs/cdk/releases/pp-intro.components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
Developers can use CDK to configure custom ZK-rollups by choosing which components should run the Polygon zkEVM protocol. We refer to these chains as CDK sovereign chains.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what this sentence isa trying to cover, but I find the wording confusing... For starters, Polygon zkEVM protocol shoul be out of the question. Maybe use AggLayer or uLxLy instead.

OTOH, I think that we need more clarity on what we mean by "sovereign chains". IMO, Sovereign chains should refer to chains that are governed by other means rather than the AL (aka existing chains such as base to give an example), and yet those chains can be integrated to the AL. Then we have the "AL native chains" or "CDK native" chains, which are chains that were built inside the protocol since it's genesis (the chains that this doc tries to explain)

Also on the naming, the protocol team has been using the term zkChains to refer to FEP and sovereign to refer to PP. But I think we also need to differentiate native/foreign chains?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@arnaubennassar this is a good point/question and will need further work in general, but I think for now we are going with sovereign when referring to the proverless config (PP chains) and we can update the terminology everywhere once we all agree on final naming


Developers can, for instance, configure their chains to use provers that are outside the Polygon zkEVM stack.

Specifically, instead of deploying a Polygon zkEVM prover, developers can configure their CDK sovereign chains to utilize Succinct's SP1 prover.

Since CDK sovereign chains are designed to easily connect to the AggLayer, they use a type of ZK-proof called a _pessimistic proof_ to reach finality of transactions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing to me... The idea is that:

  • Everything is part of the AL protocol
  • Today, there are two paths: PP or FEP. And it's true that new chains need to chose one or the other
  • It's important to communicate that moving forward, PP will be mandatory and chains will have the ability to extend the security of the PP by adding other proofs such as FEP, consensus, ...

I wouldn't talk about prover stacks because:

  • It's not like we offer flexibility, people just need to go with whatever is configured
  • It's a implementation detail... To deep for an intro. Like we're not talking about if we're using sqlite, mdbx, or whatever DB here


## What is a pessimistic proof?

A *pessimistic proof* (PP) is a zero-knowledge proof attesting to the fact that a chain's bridge transitions were correctly executed and that all withdrawals are collateralized.

Therefore, pessimistic proofs enable CDK-built chains that interoperate via the [unified bridge](../../zkEVM/architecture/unified-LxLy/index.md) to achieve trustless cross-chain security.

Pessimistic proofs allow CDK sovereign chains connected to the [AggLayer](../../agglayer/overview.md) interoperate securely.

We henceforth refer to CDK sovereign chains as CDK PP chains.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

going back to the first comment left on this file: we need to be extremely careful with naming. This line makes it feel that we're quite inconsistent with naming... Is it CDK sovereign chains or PP chains? What will happen when we have chains that use PP and FEP?


## CDK PP stack
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, there is a weird level of detail... We list the CLI, but not the syncers? Most importantly, the aggSender looks like a standalone piece of software, when it's clearly just a functionality of the cdk client. I've been talking with some non Polygon folks and they're super confused with what's the CDK / AggLayer. We need to be very careful on how we articulate this things...


Next, we detail the architectural components of the CDK PP chains.

The table below lists the components of a CDK PP chain and where you can find them.

| Component | CDK PP stack | Notes |
| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| Node = RPC and sequencer | [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) | Customizable, commonly:<br/>\- Sequencer = 1 node<br/>\- RPC = multiple nodes |
| Contracts | <a href=https://github.com/0xPolygonHermez/zkevm-contracts>zkevm-contracts</a> | |
| CLI | [cdk](https://github.com/0xPolygon/cdk) | Included in [CDK](https://github.com/0xPolygon/cdk) repo |
| AggSender | <a href=https://github.com/0xPolygon/cdk>cdk</a> | Included in [CDK](https://github.com/0xPolygon/cdk) repo |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The AggSender is just a sub-component of the cdk client. I think that we should be talking about cdk client or cdk node more in the doc... Although it's ok to specify that the AggSender is the specific sub-component that sends the certs to the AL. But note that the AggSender works in conjunction with other sub-components of the cdk such as the bridge syncer and others...

| Tx pool manager | <a href=https://github.com/0xPolygon/zkevm-pool-manager> zkevm-pool-manager</a> | |

## Component descriptions

Here are brief descriptions for each CDK FEP component.

- CDK Erigon node, a fork of [erigon](https://github.com/ledgerwatch/erigon), that manages the following:
- Multiple RPC nodes that provide common APIs for sending transactions.
- Sequencer for executing transactions, and creating blocks and batches.
- Contracts: Various smart contracts deployed on L1 for the full implementation and complete functionality of the Polygon zkEVM protocol:
- `PolygonRollupManager`
- `PolygonZkEVMBridgeV2`
- `PolygonZkEVMGlobalExitRootV2`
- `FflonkVerifier`
- `PolygonZkEVMDeployer`
- `PolygonZkEVMTimelock`
- CLI tool: A single command line interface tool for abstracting away the complexity of deploying or configuring CDK components.
- AggSender is the CDK PP component that accumulates all necessary info in order to generate certificates, which are sent to the SP1 prover via the JSON-RPC API for the generation of pessimistic proofs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the idea of CDK PP. No, there is the cdk. And the cdk happens to be used to give PP functionality, but there is no CDK PP... Again, once we've FEP+PP the same cdk will be used, and in this case we will have the aggsender as well as other components

- Transaction pool manager: For storing transactions submitted by users.

### AggLayer-side components
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It feels a bit odd to have a sub section for AL, and not for CDK


- Succinct's SP1 prover: A simplified cryptographic tool designed to take Rust-written inputs in order to generate ZK-proofs.

Unlike in the CDK FEP chain, the prover in a CDK PP chain is not directly connected to the chain. It in fact resides in the AggLayer.

- JSON-RPC API: A component provided by the AggLayer to interface between the CDK PP chain and the SP1 prover.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldnt it be better to talk about AggLayer node similar to the aggsender, the RPC is just a part of the AL node... but for sure avoid JSON-RPC it's extremely confusing, people will think about the API of the Ethereum execution clients when they see this, and it has nothing to do with it


In reality, the AggSender sends certificates to the JSON-RPC API, which in turn requests the SP1 prover to generate ZK-proofs. On receipt of the ZK-proofs, it sends the ZK-proofs to L1.

See the high level view of the CDK PP chain architecture [here](../architecture/cdk-pp-highlevel-arch.md)
Binary file added docs/img/cdk/cdk-pp-architecture-001.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ hide:
<div class="section-wrapper">
<div class="hero-content-flex">
<div class="hero-left">
<h1 class="hero-heading">The Polygon Knowledge Layer</h1>
<h1 class="hero-heading">CDK PP Docs Review Environment</h1>
<p class="hero-subtext">Welcome to the technical documentation and knowledge resources for Polygon protocols and scaling technologies.</p>
<p class="hero-subtext"> Learn how to build and deploy dApps, launch ZK rollups and validiums as Layer 2s on Ethereum, spin up nodes, and find out about the latest in zero-knowledge research.</p>
</div>
Expand Down
4 changes: 3 additions & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ nav:
- Overview: cdk/overview.md
- Releases:
- Full execution proofs (FEP): cdk/releases/stack-components.md
- Pessimistic proofs (PP): cdk/releases/pp-intro.components.md
- Get started:
- Local deployment guide: cdk/getting-started/local-deployment.md
- CLI tool: cdk/getting-started/cli-tool.md
Expand Down Expand Up @@ -88,7 +89,8 @@ nav:
- Quickly test a running stack: cdk/how-to/quick-test-stack.md
- Connect to CDK testnets: cdk/how-to/connect-testnet.md
- Architecture:
- High level views: cdk/architecture/high-level-views.md
- CDK FEP high level view: cdk/architecture/high-level-views.md
- CDK PP high level view: cdk/architecture/cdk-pp-highlevel-arch.md
- CDK rollup: cdk/architecture/cdk-zkevm.md
- CDK validium: cdk/architecture/cdk-validium.md
- Staking the Bridge (STB): cdk/architecture/staking-the-bridge.md
Expand Down
Loading