CDK PP Docs Review Env: DO NOT MERGE!!! #2459
There are no files selected for viewing
| 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. | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ## 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. | ||||||
|
There was a problem hiding this comment.
Suggested change
batches are irrelevant for PP chains... I'm not even sure if the cdk-erigon version we're using for PP deals with batches at all |
||||||
| 5. CDK Erigon sequencer syncs all transaction data with any CDK Erigon RPC node. | ||||||
|
There was a problem hiding this comment. It's the opposite, any node syncs from sequencer. Otherwise I'd change |
||||||
| 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. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 7. The JSON-RPC API checks validity of the certificates against the transaction data in the CDK Erigon RPC node. | ||||||
|
There was a problem hiding this comment.
Suggested change
Not sure how to write this, but:
|
||||||
| 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. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 9. Once the proof is received from the SP1 prover, the JSON-RPC API sends it to L1. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
| ## Sequential diagram | ||||||
|
There was a problem hiding this comment. I'd remove this entire section, feels redundant to what's already explained. And the picture diagram looks way better than the mermaid 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 | ||||||
| ``` | ||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,4 @@ | ||
| | 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` | |
| 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. | ||
|
There was a problem hiding this comment. I see what this sentence isa trying to cover, but I find the wording confusing... For starters, 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? |
||
|
|
||
| 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. | ||
|
Comment on lines
+3
to
+7
There was a problem hiding this comment. This is confusing to me... The idea is that:
I wouldn't talk about prover stacks because:
|
||
|
|
||
| ## 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. | ||
|
There was a problem hiding this comment. 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 PP stack | ||
|
There was a problem hiding this comment. 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 | | ||
|
There was a problem hiding this comment. The AggSender is just a sub-component of the |
||
| | 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. | ||
|
There was a problem hiding this comment. I don't like the idea of |
||
| - Transaction pool manager: For storing transactions submitted by users. | ||
|
|
||
| ### AggLayer-side components | ||
|
There was a problem hiding this comment. 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. | ||
|
There was a problem hiding this comment. Wouldnt it be better to talk about |
||
|
|
||
| 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) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
rename
JSON-RPC APIforAggLayer RPCjson RPC is known to be the api of the execution clients such as erigon...