Skip to content

Commit 51b1049

Browse files
EmpieichOEmpieichO
authored
Merge pull request 0xPolygon#2 from 0xPolygon/km/cdk_section_edit
First pass of CDK section
2 parents a0747cc + 04c7eb3 commit 51b1049

29 files changed

+270
-488
lines changed

‎docs/cdk/concepts/dac.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
A data availability committee (DAC) is an offchain network of nodes that provides data to a blockchain network. The advantages are:
2+
3+
- **Lower transaction fees**: Reduced computational requirements lead to lower fees.
4+
- **State privacy**: A secure copy of state transitions ensures data integrity and privacy.
5+
6+
DACs store the data required to reconstruct the state of the blockchain and make that data accessible so that, if the blockchain goes down, users can still access their assets and data.
7+
8+
Delegating blockchain data to a DAC in this way can be costly. However, a DAC improves finality and thus supports Enterprise use cases which require cheap and fast transactions with a private and secure data layer.
9+
10+
The CDK validium DAC is a secure consortium of nodes that ensures off-chain data access.
11+
12+
## DAC data flow
13+
14+
![CDK validium DAC dataflow](../../img/cdk/zksupernets-dac.png)
15+
16+
The DAC works together with the sequencer to control the flow of data. The process can be broken down as follows:
17+
18+
1. **Batch formation**: The sequencer collects user transactions and organizes them into batches.
19+
20+
2. **Batch authentication**: Once the batches are assembled, they are authenticated. The sequencer forwards the batch data and its corresponding hash to the DAC.
21+
22+
3. **Data validation and storage**: The DAC nodes independently validate the batch data. Once validated, the hash is stored in each node's local database for future reference.
23+
24+
4. **Signature generation**: Each DAC node generates a signature for the batch hash. This serves as an endorsement of the batch's integrity and authenticity.
25+
26+
5. **Communication with Ethereum**: The sequencer collects the DAC members' signatures and the original batch hash and submits them to the Ethereum network for verification.
27+
28+
6. **Verification on Ethereum**: A designated smart contract on Ethereum verifies the submitted signatures against a list of valid DAC members and confirms that sufficient approval has been provided for the batch hash.
29+
30+
7. **Final settlement with zero-knowledge proof**: The aggregator prepares a proof for the batch via the prover and submits it to Ethereum. This proof confirms the validity of the batch's transactions without revealing their details. The chain state updates on Ethereum.
31+

‎docs/cdk/edge-suggestion.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
So, we could put the whole thing https://wiki.polygon.technology/docs/edge/ here. However, there may be a better option.
2+
3+
Suggestion: migrate the whole of the current WIKI docs into the repo:
4+
5+
https://github.com/0xPolygon/polygon-edge
6+
7+
Into a `docs` directory which spins up how it looks currently in the wiki as a docusaurus site, or we can create a simpler static site if required. We can also review and edit like we're doing here but it might not be priority.
8+
9+
To discuss with Gabriel.
10+

‎docs/cdk/get-started/deploy-validium.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
!!! important "Recommendation"
2+
Follow the [Quickstart](quickstart.md) for a hands-on introduction to CDK in validium mode.
3+
4+
Follow the steps below to deploy a CDK validium instance.
5+
6+
## 1. Deploy validium-specific contracts
7+
8+
First, deploy the relevant contracts.
9+
10+
Follow the steps in the [CDK validium contracts repository's README</ins>](https://github.com/0xPolygon/cdk-validium-contracts).
11+
12+
## 2. Run the CDK validium node
13+
14+
Next, set up and run the CDK validium node.
15+
16+
Follow the instructions in the [CDK validium node repository's README](https://github.com/0xPolygon/cdk-validium-node).
17+
18+
19+
!!! danger "There are no instructions - awaiting feedback"
20+
## 3. Run the data availability (DA) node
21+
22+
Finally, once the CDK validium node is operational, set up and run the data availability node.
23+
24+
Instructions for this can be found in the [<ins>CDK DA Node GitHub repository's README</ins>](https://github.com/0xPolygon/cdk-data-availability).

‎docs/cdk/get-started/overview.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Polygon's Chain Development Kit (CDK) is a software tool for blockchain developers which allows easy install and configuration of a variety of chain architectures.
2+
3+
!!! warning
4+
- At the time of writing, the CDK only supports validium nodes. The CDK in validium mode is in active development, with ongoing feature enhancements and issue resolutions.
5+
6+
For the latest updates, follow our official GitHub repositories:
7+
8+
- [Node](https://github.com/0xPolygon/cdk-validium-node)
9+
- [Data availability](https://github.com/0xPolygon/cdk-data-availability)
10+
- [Contracts](https://github.com/0xPolygon/cdk-validium-contracts)
11+
- CDK zkEVM-rollup mode is in development.
12+
13+
![CDK flavors](../../img/cdk/cdk-modes.jpg)

docs/technology/cdk/quickstart.md renamed to docs/cdk/get-started/quickstart.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,12 @@
55

66
This tutorial will guide you through the process of setting up a CDK Validium on your local machine using the deployment guidance of [<ins>Snapchain</ins>](https://www.snapchain.dev/).
77

8-
:::info Polygon CDK is in public preview stage and subject to changes
9-
108
Please note that the current Data Availability (DA) configuration in Polygon CDK is using a Data Availability Committee (DAC) node with a local Geth client as the L1. However, the integration with Layer 1 testnets, including Sepoilla, is actively being pursued.
119

1210
The CDK Validium is actively being developed, with ongoing feature enhancements and issue resolutions. For the latest updates, follow our official GitHub repositories.
1311

1412
- [<ins>Node</ins>](https://github.com/0xPolygon/cdk-validium-node)
15-
- [<ins>Data Availability</ins>](https://github.com/0xPolygon/cdk-data-availability)
13+
- [<ins>Data availability</ins>](https://github.com/0xPolygon/cdk-data-availability)
1614
- [<ins>Contracts</ins>](https://github.com/0xPolygon/cdk-validium-contracts)
1715

1816
New features and refinements are designed to enhance user experience without disrupting ongoing activities.

docs/technology/cdk/allowlists.md renamed to docs/cdk/how-to/manage-policies.md

Lines changed: 38 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,52 @@
1-
---
2-
id: allowlists
3-
title: CDK Validium Allowlists
4-
sidebar_label: Allowlists
5-
description: "Learn about allowlists and access control in the Polygon CDK."
6-
keywords:
7-
- docs
8-
- polygon
9-
- layer 2
10-
- validium
11-
- allowlist
12-
- access
13-
- access control
14-
- acl
15-
---
16-
17-
The CDK Validium node offers policy management features, including allowlisting and Access Control Lists (ACLs). These features are particularly beneficial for Validium-based app-chains that require fine-grained control over transaction pools. It is the Sequencer node that enforces these policies, and any change operations should be applied directly through the Sequencer. This document provides an overview on these administrative capabilities and explains how to use them.
18-
19-
## Key Concepts
20-
21-
- **Policy**: A set of rules that govern what actions are allowed or denied in the transaction pool. Currently, there are two defined policies:
22-
- **SendTx**: Governs whether an address may send transactions to the pool.
23-
- **Deploy**: Governs whether an address may deploy a contract.
24-
- **ACL (Access Control List)**: A list of addresses that are exceptions to a given policy.
25-
- **Allowlisting**: The process of explicitly allowing addresses to perform certain actions.
26-
- **Denylisting**: The process of explicitly denying addresses from performing certain actions.
27-
28-
## Architecture
29-
30-
The architecture is divided into the following main components:
31-
32-
- **Policy Management Layer**: Defined in `policy.go`, this layer is responsible for the core logic of policy management.
33-
- **Data Layer**: Defined in `pgpoolstorage/policy.go`, this layer interacts with the data layer (PostgreSQL database) to store and retrieve policy and ACL data.
34-
- **Policy Definitions**: Defined in `pool/policy.go`, this layer contains the data structures and utility functions for policies and ACLs.
35-
- **Policy Interface**: Defined in `pool/interfaces.go`, this interface outlines the methods that any concrete type must implement to be considered a policy in the system.
36-
37-
## Capabilities
38-
39-
- **Fine-Grained Control**: Developers can specify policies at a granular level, allowing or denying specific actions for specific addresses.
40-
- **Dynamic Updates**: Policies and ACLs can be updated on-the-fly without requiring a node restart.
41-
- **Database-Backed**: All policy data is stored in a PostgreSQL database.
1+
## Policy overview
2+
3+
A **policy** is a set of rules that govern what actions are allowed or denied in the transaction pool.
4+
5+
- **Fine-grained control**: Developers can specify policies at a granular level, allowing or denying specific actions for specific addresses.
6+
- **Dynamic updates**: Policies and ACLs can be updated on-the-fly without requiring a node restart.
7+
- **Database-backed**: All policy data is stored in a PostgreSQL database.
428
- **Extensible**: New policies can be easily added to the system.
439

44-
## How to Use Policies
10+
## Validium node
11+
12+
### Policies
13+
14+
Currently, there are two defined policies:
15+
16+
- **SendTx**: governs whether an address may send transactions to the pool.
17+
- **Deploy**: governs whether an address may deploy a contract.
18+
19+
The CDK validium node offers policy management features that include allowlisting[^1], denylisting[^2], and access control lists (ACLs)[^3]. These features are beneficial for validium-based app-chains that require fine-grained control over transaction pools.
4520

46-
| Command Name | Description | Flags & Parameters |
21+
### Code definitions
22+
23+
- **Policy management**: [`cmd/policy.go`](https://github.com/0xPolygon/cdk-validium-node/blob/5399f8859af9ffb0eb693bf395e1f09b53b154de/cmd/policy.go) contains the core logic of policy management.
24+
- **Policy definitions**: [`pool/policy.go`](https://github.com/0xPolygon/cdk-validium-node/blob/5399f8859af9ffb0eb693bf395e1f09b53b154de/pool/policy.go) contains structs and utility functions for policies and ACLs.
25+
- **Data**: [`pgpoolstorage/policy.go`](https://github.com/0xPolygon/cdk-validium-node/blob/5399f8859af9ffb0eb693bf395e1f09b53b154de/pool/policy.go) interacts with the data layer (PostgreSQL database) to store and retrieve policy and ACL data.
26+
- **Policy interface**: [`pool/interfaces.go`](https://github.com/0xPolygon/cdk-validium-node/blob/5399f8859af9ffb0eb693bf395e1f09b53b154de/pool/interfaces.go#L42) contains a `policy` interface which defines the methods that policies must implement.
27+
28+
### How to use a policy
29+
30+
| Command name | Description | Flags & parameters |
4731
|--------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
4832
| `policy add` | Add address(es) to a policy exclusion list | `--policy` (or `-p`): Policy name<br/>`--csv`: CSV file with addresses |
4933
| `policy remove` | Remove address(es) from a policy exclusion list | `--policy` (or `-p`): Policy name<br/>`--csv`: CSV file with addresses to remove |
5034
| `policy clear` | Clear all addresses from a policy's exclusion list | `--policy` (or `-p`): Policy name |
5135
| `policy describe` | Describe the default actions for the policies or a specific policy | `--policy` (or `-p`): Policy name (optional)<br/>`--no-header`: Omit header in output (optional) |
5236
| `policy update` | Update the default action for a policy | `--policy` (or `-p`): Policy name<br/>`--allow`: Set policy to 'allow'<br/>`--deny`: Set policy to 'deny' |
5337

54-
We will use the "deploy" policy as an example.
38+
!!! note
39+
For the examples, we are using a `deploy` policy.
5540

56-
### Adding Addresses to a Policy
41+
#### Add addresses
5742

5843
To add one or more addresses to a specific policy, you can use the `policy add` command. If you have a CSV file containing the addresses, you can use the --csv` flag.
5944

6045
```bash
6146
docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy add --policy deploy 0xAddress1
6247
```
6348

64-
### Removing Addresses from a Policy
49+
#### Remove addresses
6550

6651
To remove addresses from a policy, you can use the `policy remove` command.
6752

@@ -73,15 +58,15 @@ docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy remove --p
7358
docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy remove --policy deploy --csv addresses.csv
7459
```
7560

76-
### Clearing All Addresses from a Policy
61+
#### Clear all addresses
7762

7863
To remove all addresses from a policy's ACL, you can use the `policy clear` command.
7964

8065
```bash
8166
docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy clear --policy deploy
8267
```
8368

84-
### Describing Policies
69+
#### Get information about a policy
8570

8671
To get information about a specific policy or all policies, you can use the `policy describe` command.
8772

@@ -92,3 +77,8 @@ docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy describe -
9277
# Describe all policies
9378
docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy describe
9479
```
80+
81+
82+
[^1]: **Allowlisting**: The process of explicitly allowing addresses to perform certain actions.
83+
[^2]: **Denylisting**: The process of explicitly denying addresses from performing certain actions.
84+
[^3]: **ACL (access control list)**: A list of addresses that are exceptions to a given policy.

docs/technology/cdk/index.md renamed to docs/cdk/index.md

File renamed without changes.

‎docs/cdk/specification/performance-benchmarks.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
[comment]: <> (data comes from here: https://www.notion.so/polygontechnology/CDK-Validium-TPS-Analysis-8aafda0d6b824c3781270cca30a8f70d#c6725ef8b93748ea8879d7e49e67c2fc and results are marked as OLD.. SME > @ruchawalawalkar)
2+
3+
## Strategy
4+
5+
The team calculated transactions-per-second, `tps`, for three transaction types:
6+
7+
- **EOA to EOA**: Simple value transfers between user accounts.
8+
- **ERC20**: Token transfers, simulating the exchange of tokens on the network.
9+
- **ERC721**: Non-fungible token (NFT) transfers representing the exchange of unique digital assets.
10+
11+
## Environment
12+
13+
The tests ran on the following configurations:
14+
15+
### CDK validium test
16+
17+
| Component (Service) | Instance Type | Instance Count | vCPUs | RAM (GB) | Disk Size (GB) | Disk Type |
18+
| --- | --- | --- | --- | --- | --- | --- |
19+
| Sequencer | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
20+
| RPC Node | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
21+
| Executor | c2-standard-16 | 1 | 16 | 64 | 100 | SSD persistent disk |
22+
| Aggregator | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
23+
| Prover | n2-highmem-128 | 1 | 128 | 864 | 500 | SSD persistent disk |
24+
| Synchronizer | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
25+
| SequenceSender | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
26+
| ETH TX Manager | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
27+
| L2 Gas Pricer | n2d-custom-8-16384 | 1 | 8 | 16 | 30 | Balanced persistent disk |
28+
| HashDB Node | c2-standard-16 | 1 | 16 | 64 | 100 | SSD persistent disk |
29+
| Data Availability | n2d-custom-8-16384 | 4 | 8 | 16 | 30 | Balanced persistent disk |
30+
31+
### Cloud SQL DB
32+
33+
| DB Instance | vCPUs | RAM (GB) | Size (GB) | Count |
34+
| --- | --- | --- | --- | --- |
35+
| zkEVM DB | 16 | 60 | 100 | 1 |
36+
| contains: | State DB | 100 (Shared) | | |
37+
| | Pool DB | 100 (Shared) | | |
38+
| | Prover DB | 100 (Shared) | | |
39+
40+
## Results
41+
42+
### Key
43+
44+
- `mode`: Type of transaction.
45+
- `concurrency`: Number of concurrent requests.
46+
- `requests`: Number of requests over the benchmarking session.
47+
- `rate-limit`: Overall limit to the number of requests per second.
48+
49+
### Results (OLD?)
50+
51+
| `tps` | `mode` | `concurrency` | `requests` | `rate-limit` | `total requests` | `notes` |
52+
| --- | --- | --- | --- | --- | --- | --- |
53+
| 6.269592476 | t (EOA Transactions) | 20 | 100 | 0 (disabled) | 2000 | |
54+
| 12.6984127 | t (EOA Transactions) | 20 | 200 | 0 (disabled) | 4000 | |
55+
| 0 | t (EOA Transactions) | 50 | 500 | 0 (disabled) | 25000 | ERRORED (see note) |
56+
| 17.27115717 | t (EOA Transactions) | 20 | 500 | 0 (disabled) | 10000 | |
57+
| 20.13422819 | t (EOA Transactions) | 30 | 500 | 0 (disabled) | 15000 | |
58+
| 24.8447205 | t (EOA Transactions) | 40 | 500 | 0 (disabled) | 20000 | |
59+
| 20.51983584 | t (EOA Transactions) | 30 | 1000 | 0 (disabled) | 30000 | |
60+
| 18.71804452 | t (EOA Transactions) | 30 | 100000 | 0 (disabled) | 3000000 | |
61+
| 14.82799526 | t (EOA Transactions) | 50 | 1000 | 0 (disabled) | 50000 | |
62+
| 8.650519031 | t (EOA Transactions) | 50 | 100 | 100 | 5000 | |
63+
| 16.20745543 | t (EOA Transactions) | 40 | 500 | 0 (disabled) | 20000 | DUPLICATE OF TEST10 |
64+
| 8.896797153 | t (EOA Transactions) | 20 | 2000 | 0 (disabled) | 40000 | |
65+
| 27.02702703 | t (EOA Transactions) | 10 | 100 | 50 | 1000 | Test ran on n2-standard-8 |
66+
| 29.19708029 | t (EOA Transactions) | 20 | 200 | 50 | 4000 | Test ran on n2-standard-8, with increase AccountQueue and GlobalQueue |
67+
| 36.86635945 | t (EOA Transactions) | 20 | 400 | 50 | 8000 | |
68+
| 29.19708029 | t (EOA Transactions) | 20 | 200 | 0 (disabled) | 4000 | |
69+
| 32.78688525 | t (EOA Transactions) | 50 | 200 | 0 (disabled) | 10000 | |
70+
| 29.19708029 | t (EOA Transactions) | 20 | 200 | 0 (disabled) | 4000 | |
71+
| 17.13062099 | t (EOA Transactions) | 20 | 400 | 50 | 8000 | |
72+
| 14.28571429 | 2 (ERC20 Transactions) | 10 | 100 | 0 (disabled) | 1000 | |
73+
| 18.01801802 | 2 (ERC20 Transactions) | 20 | 200 | 0 (disabled) | 4000 | |
74+
| 13.98601399 | 2 (ERC20 Transactions) | 30 | 200 | 40 | 6000 | |
75+
| 17.66004415 | 2 (ERC20 Transactions) | 20 | 400 | 30 | 8000 | |
76+
| 17.54385965 | 2 (ERC20 Transactions) | 20 | 500 | 30 | 10000 | |
77+
| 17.76198934 | 2 (ERC20 Transactions) | 20 | 500 | 40 | 10000 | |
78+
| 17.51313485 | 2 (ERC20 Transactions) | 20 | 500 | 50 | 10000 | |
79+
| 17.76198934 | 2 (ERC20 Transactions) | 20 | 500 | 100 | 10000 | |
80+
| 0 | 2 (ERC20 Transactions) | 30 | 500 | 100 | 15000 | ERRORED (resource exhausted) |
81+
| 17.36111111 | 2 (ERC20 Transactions) | 20 | 1000 | 0 (disabled) | 20000 | |
82+
| 17.33102253 | 2 (ERC20 Transactions) | 20 | 1500 | 0 (disabled) | 30000 | |
83+
| 18.61330852 | 2 (ERC20 Transactions) | 20 | 2000 | 0 (disabled) | 40000 | |
84+
| 17.24732666 | 2 (ERC20 Transactions) | 20 | 2500 | 0 (disabled) | 50000 | |
85+
| 4.545454545 | 7 (ERC721 Transactions) | 10 | 100 | 0 (disabled) | 1000 | |
86+
| 6.097560976 | 7 (ERC721 Transactions) | 10 | 200 | 0 (disabled) | 2000 | |
87+
| 12.86173633 | 7 (ERC721 Transactions) | 20 | 200 | 0 (disabled) | 4000 | |
88+
| 13.14060447 | 7 (ERC721 Transactions) | 20 | 500 | 0 (disabled) | 10000 | |
89+
| 0 | 7 (ERC721 Transactions) | 30 | 200 | 0 (disabled) | 6000 | ERRORED (resource exhausted) |
90+
| 14.18439716 | 7 (ERC721 Transactions) | 20 | 1000 | 0 (disabled) | 20000 | |
91+
| 12.39669421 | 7 (ERC721 Transactions) | 20 | 1500 | 0 (disabled) | 30000 | |
92+
| 13.81692573 | 7 (ERC721 Transactions) | 20 | 2000 | 0 (disabled) | 40000 | |
93+
| 13.49892009 | 7 (ERC721 Transactions) | 20 | 2500 | 0 (disabled) | 50000 | |
94+
95+
## Conclusions
96+
97+
TODO: summary of data results
98+
99+
## Comparison with competitors
100+
101+
TODO: in progress
102+
103+

0 commit comments

Comments
 (0)