Skip to content

Commit 4b1f197

Browse files
kmurphypolygonkmurphypolygon
authored
Merge pull request 0xPolygon#360 from 0xPolygon/cdk/da-int
CDK: data availability committee integration how to
2 parents e2b32f6 + 48c8b53 commit 4b1f197

File tree

2 files changed

+195
-0
lines changed

2 files changed

+195
-0
lines changed

‎docs/cdk/how-to/integrate-da.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
This document shows you how to integrate a third-party data availability (DAC) solution into your CDK stack.
2+
3+
## Prerequisites
4+
5+
!!! tip
6+
Make sure you have [upgraded your CDK stack](migrate/fork.md) if necessary.
7+
8+
## Set up contracts
9+
10+
This section shows you how to create a custom CDK validium DAC contract.
11+
12+
1. Clone [zkevm-contracts](https://github.com/0xPolygonHermez/zkevm-contracts).
13+
14+
2. `cd` into `zkevm-contracts` and checkout tag `v6.0.0-rc.1-fork.9`.
15+
16+
3. Run `npm i` from the root.
17+
18+
4. `cd` to the `contracts/v2/consensus/validium` directory.
19+
20+
!!! tip
21+
- Until further notice, these contracts run on the [etrog release](https://polygon.technology/blog/polygon-zkevm-the-etrog-upgrade-is-live-on-mainnet).
22+
23+
5. Create your custom contract in the same directory, and make sure it implements the [IDataAvailabilityProtocol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/contracts/v2/interfaces/IDataAvailabilityProtocol.sol) interface.
24+
25+
!!! tip
26+
- Use the Polygon DAC implementation contract: [PolygonDataCommittee.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/contracts/v2/consensus/validium/PolygonDataCommittee.sol) as a guide.
27+
- The contract supports custom smart contract implementation and, through this, DACs can add their custom on-chain verification logic.
28+
29+
6. You can leave the `verifyMessage` function empty but make sure the `getProcotolName` function returns a unique name (such as Avail, Celestia, etc). The following example code comes from the [PolygonDataCommitee.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/contracts/v2/consensus/validium/PolygonDataCommittee.sol) implementation.
30+
31+
```solidity
32+
// Name of the data availability protocol
33+
string internal constant _PROTOCOL_NAME = "<MY_PROTOCOL_NAME>";
34+
35+
...
36+
37+
/**
38+
* @notice Return the protocol name
39+
*/
40+
function getProcotolName() external pure override returns (string memory) {
41+
return _PROTOCOL_NAME;
42+
}
43+
```
44+
45+
7. Update the [/deployment/v2/4_createRollup.ts](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/deployment/v2/4_createRollup.ts#L77) script to add your contract name.
46+
47+
```ts
48+
const supporteDataAvailabilityProtocols = ["<CONTRACT_NAME>"];
49+
```
50+
51+
8. Make your contract deployable by copying, editing for your custom implementation, and pasting back in, the `if` statement from the [/deployment/v2/4_createRollup.ts#L251](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/deployment/v2/4_createRollup.ts#L260) node creation script.
52+
53+
!!! info "`PolygonValidiumEtrog.sol` solution"
54+
55+
The [Etrog DAC integration contract](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol) is still work-in-progress at the time of writing but there are some interesting things to note.
56+
57+
1. It implements the function [`verifyMessage` function](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol#L231):
58+
59+
```solidity
60+
// Validate that the data availability protocol accepts the dataAvailabilityMessage
61+
// note This is a view function, so there's not much risk even if this contract was vulnerable to reentrant attacks
62+
dataAvailabilityProtocol.verifyMessage(
63+
accumulatedNonForcedTransactionsHash,
64+
dataAvailabilityMessage
65+
);
66+
```
67+
68+
where `accumulatedNonForcedTransactionsHash` is used for verification against the protocol and `dataAvailabilityMessage` is a byte array containing the signature and addresses of the committee in ascending order.
69+
70+
2. It also implements a function to set the data availability protocol at [line 287](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol#L287) to see how they do this.
71+
72+
```solidity
73+
/**
74+
* @notice Allow the admin to set a new data availability protocol
75+
* @param newDataAvailabilityProtocol Address of the new data availability protocol
76+
*/
77+
function setDataAvailabilityProtocol(
78+
IDataAvailabilityProtocol newDataAvailabilityProtocol
79+
) external onlyAdmin {
80+
dataAvailabilityProtocol = newDataAvailabilityProtocol;
81+
82+
emit SetDataAvailabilityProtocol(address(newDataAvailabilityProtocol));
83+
}
84+
```
85+
86+
## Deploy Docker image
87+
88+
This section shows you how to deploy the Docker image containing your custom DAC contract.
89+
90+
1. Edit the following parameters in the [`docker/scripts/v2/deploy_parameters_docker.json`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/docker/scripts/v2/deploy_parameters_docker.json) file:
91+
92+
```json
93+
"minDelayTimelock": 3600, // BECOMES "minDelayTimelock": 1,
94+
```
95+
96+
2. Edit the following parameters in the [`/docker/scripts/v2/create_rollup_parameters_docker.json`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/docker/scripts/v2/create_rollup_parameters_docker.json) file:
97+
98+
```json
99+
"consensusContract": "PolygonValidiumEtrog", // CHANGE THIS TO YOUR CONTRACT NAME
100+
"dataAvailabilityProtocol": "PolygonDataCommittee", // ADD THIS PARAMETER
101+
```
102+
103+
3. Run the following command:
104+
105+
```sh
106+
cp docker/scripts/v2/hardhat.example.paris hardhat.config.ts
107+
```
108+
109+
4. Edit [docker/scripts/v2/deploy-docker.sh](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v6.0.0-rc.1-fork.9/docker/scripts/v2/deploy-docker.sh) to add the following line:
110+
111+
```sh
112+
sudo chmod -R go+rxw docker/gethData before docker build -t hermeznetwork/geth-zkevm-contracts -f docker/Dockerfile .
113+
```
114+
115+
5. In the [deployment/v2/4_createRollup.ts](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/deployment/v2/4_createRollup.ts#L290) file, uncomment the 290-291, and add a `console.log` output that grabs the address of the DAC:
116+
117+
```ts
118+
// Setup data committee to 0
119+
await (await polygonDataCommittee?.setupCommittee(0, [], "0x")).wait();
120+
console.log(dataAvailabilityProtocol, "deployed to:", polygonDataCommittee.target);
121+
```
122+
123+
6. Build the image with the following commands:
124+
125+
```sh
126+
sudo npx hardhat compile
127+
sudo npm run docker:contracts
128+
```
129+
130+
7. Tag the image with the following command, where `XXXX` is custom:
131+
132+
```sh
133+
docker image tag hermeznetwork/geth-zkevm-contracts hermeznetwork/geth-cdk-validium-contracts:XXXX
134+
```
135+
136+
## Set up the node
137+
138+
This section shows you how to set up your CDK node that sends and receives data from the DAC.
139+
140+
1. Create a package that implements the [`DABackender`](https://github.com/0xPolygon/cdk-validium-node/blob/b6ee6cb087099c2e97f3e596f84672fc021b517a/dataavailability/interfaces.go#L14) interface and place it under the [`cdk-validium-node/tree/develop/dataavailability`](https://github.com/0xPolygon/cdk-validium-node/tree/develop/dataavailability) directory.
141+
142+
2. Add a new constant to the [/dataavailability/config.go](https://github.com/0xPolygon/cdk-validium-node/blob/b6ee6cb087099c2e97f3e596f84672fc021b517a/dataavailability/config.go) file that represents the DAC.
143+
144+
```go
145+
const (
146+
// DataAvailabilityCommittee is the DAC protocol backend
147+
DataAvailabilityCommittee DABackendType = "DataAvailabilityCommittee"
148+
)
149+
```
150+
151+
where `DataAvailabilityCommittee` matches the `_PROTOCOL_NAME` see in the [Set up contracts](#set-up-contracts) section.
152+
153+
3. _OPTIONAL_: Add a config struct to the new package inside the main config.go file so that your package can receive custom configurations using the node’s main config file.
154+
155+
4. Instantiate your package and use it to create the main data availability instance, as done in the Polygon implementation.
156+
157+
## Test the integration
158+
159+
!!! tip
160+
- By default, all E2E tests run using the DAC.
161+
- It is possible to run the E2E tests using other DAC backends by amending the `test.node.config.toml` file.
162+
163+
To test your DAC integration, follow the steps below.
164+
165+
1. Create an E2E test that uses your protocol by following the [test/e2e/datacommittee_test.go](https://github.com/0xPolygon/cdk-validium-node/blob/develop/test/e2e/datacommittee_test.go) example.
166+
167+
2. Generate a docker image containing the changes to the node:
168+
169+
```sh
170+
make build-docker
171+
```
172+
173+
3. Build the genesis file for the node:
174+
175+
- First, clone the [cdk-validium-node](https://github.com/0xPolygon/cdk-validium-node) repo and checkout v0.6.4-cdk.5.
176+
- Edit the `test/config/test.genesis.config.json` file taking values in the generated output files created previously in the contract repo's `docker/deploymentOutputs` folder:
177+
178+
!!! info "Parameters to change"
179+
`l1Config.polygonZkEVMAddres`s ==> `rollupAddress` @ `create_rollup_output.json`
180+
`l1Config.polygonRollupManagerAddress` ==> `polygonRollupManager` @ `deploy_output.json`
181+
`l1Config.polTokenAddress` ==> `polTokenAddress` @ `deploy_output.json`
182+
`l1Config.polygonZkEVMGlobalExitRootAddress` ==> `polygonZkEVMGlobalExitRootAddress` @ `deploy_output.json`
183+
`rollupCreationBlockNumber` ==> `createRollupBlock` @ `create_rollup_output.json`
184+
`rollupManagerCreationBlockNumber` ==> `deploymentBlockNumber` @ `deploy_output.json`
185+
`root` ==> `root` @ `genesis.json`
186+
`genesis` ==> `genesis` @ `genesis.json`
187+
188+
!!! important
189+
- You should follow this step every time you build a new Docker image.
190+
191+
4. Update the contracts Docker image tag with the custom tag you created at the [deploy Docker image](#deploy-docker-image) section, step 7, by amending the node's [Docker compose file](https://github.com/0xPolygon/cdk-validium-node/blob/develop/test/docker-compose.yml).
192+
193+
5. Modify the Makefile so it can run your test. Use the [Polygon DAC Makefile](https://github.com/0xPolygon/cdk-validium-node/blob/develop/test/Makefile) as an example.
194+

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ nav:
8484
- Kurtosis [EXPERIMENTAL]: '!import https://github.com/0xPolygon/kurtosis-cdk?branch=main'
8585
- Connect to CDK testnets: cdk/get-started/connect-testnet.md
8686
- How to:
87+
- Integrate a DAC: cdk/how-to/integrate-da.md
8788
- Migrate:
8889
- Fork migration: cdk/how-to/migrate/fork.md
8990
- Use a native token: cdk/how-to/use-native-token.md

0 commit comments

Comments
 (0)