Skip to content

Commit 32300a8

Browse files
kmurphypolygonkmurphypolygon
committed
add DA doc
1 parent 516f314 commit 32300a8

File tree

2 files changed

+193
-0
lines changed

2 files changed

+193
-0
lines changed

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

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
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. Create a branch off `develop` in the [zkevm-contracts](https://github.com/0xPolygonHermez/zkevm-contracts) repo and `cd` into it.
15+
16+
3. Run `npm i` from the root.
17+
18+
4. Go to the [validium smart contracts directory](https://github.com/0xPolygonHermez/zkevm-contracts/tree/feature/etrog/contracts/v2/consensus/validium).
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/feature/Optimizations/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/feature/etrog/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/feature/Optimizations/contracts/v2/consensus/validium/PolygonDataCommittee.sol) implementation.
30+
31+
```solidity
32+
// Name of the data availability protocol
33+
string internal constant _PROTOCOL_NAME = "DataAvailabilityCommittee";
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/feature/Optimizations/deployment/v2/4_createRollup.ts#L76) script to add your protocol 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/feature/Optimizations/deployment/v2/4_createRollup.ts#L251) node creation script.
52+
53+
!!! info "`PolygonValidiumEtrog.sol` solution"
54+
55+
The [Etrog DAC integration contract](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/etrog/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. Check [lines 215-220](https://github.com/0xPolygonHermez/zkevm-contracts/blob/b2a62e6af5738366e7494e8312184b1d6fdf287c/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol#L215C1-L220C15):
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. Check [lines 250-260](https://github.com/0xPolygonHermez/zkevm-contracts/blob/b2a62e6af5738366e7494e8312184b1d6fdf287c/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol#L250C1-L260C6) 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/feature/Optimizations/docker/scripts/v2/create_rollup_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/feature/Optimizations/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/feature/Optimizations/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/feature/Optimizations/deployment/v2/4_createRollup.ts) file, uncomment the following:
116+
117+
```ts
118+
// // Setup data committee to 0
119+
// await (await polygonDataCommittee?.setupCommittee(0, [], "0x")).wait();
120+
```
121+
122+
6. Build the image with the following commands:
123+
124+
```sh
125+
npx hardhat compile
126+
npm run docker:contracts
127+
```
128+
129+
7. Tag the image with the following command, where `XXXX` is custom:
130+
131+
```sh
132+
docker image tag hermeznetwork/geth-zkevm-contracts hermeznetwork/geth-cdk-validium-contracts:XXXX
133+
```
134+
135+
## Set up the node
136+
137+
This section shows you how to set up your CDK node that sends and receives data from the DAC.
138+
139+
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.
140+
141+
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.
142+
143+
```go
144+
const (
145+
// DataAvailabilityCommittee is the DAC protocol backend
146+
DataAvailabilityCommittee DABackendType = "DataAvailabilityCommittee"
147+
DataAvailabilityCommittee DABackendType = "MyAvailabilityProtocol"
148+
)
149+
```
150+
151+
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.
152+
153+
4. Instantiate your package and use it to create the main data availability instance, as done in the Polygon implementation.
154+
155+
## Test the integration
156+
157+
!!! tip
158+
- By default, all E2E tests run using the DAC.
159+
- It is possible to run the E2E tests using other DAC backends by amending the `test.node.config.toml` file.
160+
161+
To test your DAC integration, follow the steps below.
162+
163+
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.
164+
165+
2. Generate a docker image containing the changes to the node:
166+
167+
```sh
168+
make build-docker
169+
```
170+
171+
3. Build the genesis file for the node:
172+
173+
- First, clone the [cdk-validium-node](https://github.com/0xPolygon/cdk-validium-node) repo and checkout v0.6.4-cdk.5.
174+
- 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:
175+
176+
!!! info "Parameters to change"
177+
`l1Config.polygonZkEVMAddres`s ==> `rollupAddress` @ `create_rollup_output.json`
178+
`l1Config.polygonRollupManagerAddress` ==> `polygonRollupManager` @ `deploy_output.json`
179+
`l1Config.polTokenAddress` ==> `polTokenAddress` @ `deploy_output.json`
180+
`l1Config.polygonZkEVMGlobalExitRootAddress` ==> `polygonZkEVMGlobalExitRootAddress` @ `deploy_output.json`
181+
`rollupCreationBlockNumber` ==> `createRollupBlock` @ `create_rollup_output.json`
182+
`rollupManagerCreationBlockNumber` ==> `deploymentBlockNumber` @ `deploy_output.json`
183+
`root` ==> `root` @ `genesis.json`
184+
`genesis` ==> `genesis` @ `genesis.json`
185+
186+
!!! important
187+
- You should follow this step every time you build a new Docker image.
188+
189+
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).
190+
191+
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.
192+

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ nav:
8383
- Start services: cdk/get-started/deploy-rollup/start-services.md
8484
- Connect to CDK testnets: cdk/get-started/connect-testnet.md
8585
- How to:
86+
- Integrate a DAC: cdk/how-to/integrate-da.md
8687
- Migrate:
8788
- Fork migration: cdk/how-to/migrate/fork.md
8889
- Use a native token: cdk/how-to/use-native-token.md

0 commit comments

Comments
 (0)