diff --git a/doc-drafts/fork-id-migration.org b/doc-drafts/fork-id-migration.org deleted file mode 100644 index f8e404816..000000000 --- a/doc-drafts/fork-id-migration.org +++ /dev/null @@ -1,307 +0,0 @@ -#+TITLE: Fork ID 7 to 9 Migration Process -#+DATE: -#+AUTHOR: John Hilliard -#+EMAIL: jhilliard@polygon.technology -#+CREATOR: John Hilliard -#+DESCRIPTION: - - -#+OPTIONS: toc:nil -#+LATEX_HEADER: \usepackage{geometry} -#+LATEX_HEADER: \usepackage{lmodern} -#+LATEX_HEADER: \geometry{left=1in,right=1in,top=1in,bottom=1in} -#+LaTeX_CLASS_OPTIONS: [letterpaper] - -Let's document the process of upgrading from fork 7 to fork 9 using -our Kurtosis package. These steps would more or less be the same in -production except we would be using a [[https://github.com/0xPolygonHermez/zkevm-contracts/blob/v5.0.1-rc.2-fork.8/contracts/PolygonZkEVMTimelock.sol][timelock]] contract to make the -calls. - -Just to make sure I don't have any lingering state, I'm going to run a -clean: - -#+begin_src bash -kurtosis clean -a -#+end_src - -Now, we need to downgrade all of the necessary params in order to -switch back to fork 7: - -#+begin_src diff -diff --git a/params.yml b/params.yml -index c2dd446..4caf2d0 100644 ---- a/params.yml -+++ b/params.yml -@@ -11,14 +11,14 @@ deployment_suffix: "-001" - stages: [1, 2, 3, 4, 5] - - # Docker images and repositories used to spin up services. --zkevm_prover_image: hermeznetwork/zkevm-prover:v6.0.0 --zkevm_node_image: 0xpolygon/cdk-validium-node:0.6.4-cdk --zkevm_da_image: 0xpolygon/cdk-data-availability:0.0.7 -+zkevm_prover_image: hermeznetwork/zkevm-prover:v4.0.19 -+zkevm_node_image: 0xpolygon/cdk-validium-node:0.5.13-cdk.3 -+zkevm_da_image: 0xpolygon/cdk-data-availability:0.0.6 - zkevm_agglayer_image: nulyjkdhthz/agglayer:v0.1.0 - # a38e68b5466d1997cea8466dbd4fc8dacd4e11d8 --zkevm_contracts_branch: develop # v5.0.1-rc.2-fork.8 -+zkevm_contracts_branch: v4.0.0-fork.7 # v5.0.1-rc.2-fork.8 --zkevm_rollup_fork_id: 9 -+zkevm_rollup_fork_id: 7 - zkevm_bridge_service_image: hermeznetwork/zkevm-bridge-service:v0.4.2 - zkevm_bridge_ui_image: hermeznetwork/zkevm-bridge-ui:latest # TODO: better tags for the bridge ui -#+end_src - -After making those changes we should be able to kick off a full redeployment: - -#+begin_src bash -kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always . -#+end_src - -After running this command, let's confirm onchain that this is running -fork 7. -#+begin_src bash -kurtosis files download cdk-v1 genesis /tmp/fork-7-test -jq -r '.L1Config.polygonRollupManagerAddress' /tmp/fork-7-test/genesis.json -cast call --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - "$(jq -r '.L1Config.polygonRollupManagerAddress' /tmp/fork-7-test/genesis.json)" \ - "rollupIDToRollupData(uint32)(address,uint64,address,uint64,bytes32,uint64,uint64,uint64,uint64,uint64,uint64,uint8)" 1 -#+end_src - -In my case, this is showing a ~7~ as the 4th parameter so I think -we're in good shape. We should also perform some test transactions and -ensure batches are being verified as expected. - -#+begin_src bash -export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" -cast send --legacy --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 --value 0.01ether 0x0000000000000000000000000000000000000000 -cast rpc zkevm_batchNumber -cast rpc zkevm_virtualBatchNumber -cast rpc zkevm_verifiedBatchNumber -#+end_src - -* Clean stop of the sequencer - -Before attempting the upgrade, we need to ensure there is a clean stop -of the sequencer. In order to do this, we'll pick a halting batch -number like this: - -#+begin_src diff -diff --git a/templates/trusted-node/node-config.toml b/templates/trusted-node/node-config.toml -index 6c9b9fa..372d904 100644 ---- a/templates/trusted-node/node-config.toml -+++ b/templates/trusted-node/node-config.toml -@@ -117,7 +117,7 @@ StateConsistencyCheckInterval = "5s" - BatchMaxDeltaTimestamp = "20s" - L2BlockMaxDeltaTimestamp = "4s" - ResourceExhaustedMarginPct = 10 -- HaltOnBatchNumber = 0 -+ HaltOnBatchNumber = 64 - SequentialBatchSanityCheck = false - SequentialProcessL2Block = true - [Sequencer.StreamServer] -#+end_src - -After making that change and re-running ~kurtosis run~, we'll need to -wait for the sequencer to halt and for the verified batch to equal the -latest batch. After making that change, there should be some error logs that look like this: - -#+begin_example -{"level":"error","ts":1711481674.517157,"caller":"sequencer/finalizer.go:806","msg":"halting finalizer, error: finalizer reached stop sequencer on batch number: 64%!(EXTRA string=\n/home/runner/work/cdk-validium-node/cdk-validium-node/log/log.go:142 github.com/0xPolygonHermez/zkevm-node/log.appendStackTraceMaybeArgs()\n/home/runner/work/cdk-validium-node/cdk-validium-node/log/log.go:251 github.com/0xPolygonHermez/zkevm-node/log.Errorf()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:806 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Halt()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:221 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).closeAndOpenNewWIPBatch()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:163 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeWIPBatch()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:330 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeBatches()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:166 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Start()\n)","pid":7,"version":"v0.1.0","stacktrace":"github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Halt\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:806\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).closeAndOpenNewWIPBatch\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:221\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeWIPBatch\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:163\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeBatches\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:330\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Start\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:166"} -#+end_example - -Now we need to wait for the verified batch number to catch up to the -trusted batch number: -#+begin_src bash -export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" -cast rpc zkevm_batchNumber -cast rpc zkevm_verifiedBatchNumber -#+end_src - -Once those two numbers are the same, we should be in a good position -to stop the services that are going to be upgraded - -#+begin_src bash -kurtosis service stop cdk-v1 zkevm-executor-pless-001 -kurtosis service stop cdk-v1 zkevm-node-aggregator-001 -kurtosis service stop cdk-v1 zkevm-node-eth-tx-manager-001 -kurtosis service stop cdk-v1 zkevm-node-l2-gas-pricer-001 -kurtosis service stop cdk-v1 zkevm-node-rpc-001 -kurtosis service stop cdk-v1 zkevm-node-rpc-pless-001 -kurtosis service stop cdk-v1 zkevm-node-sequence-sender-001 -kurtosis service stop cdk-v1 zkevm-node-sequencer-001 -kurtosis service stop cdk-v1 zkevm-node-synchronizer-001 -kurtosis service stop cdk-v1 zkevm-node-synchronizer-pless-001 -kurtosis service stop cdk-v1 zkevm-prover-001 -#+end_src - -* Smart Contract Calls - -In order to upgrade, we're going to need to make a few smart contract -calls. - -#+begin_src bash -git clone git@github.com:0xPolygonHermez/zkevm-contracts.git -pushd zkevm-contracts/ -git reset --hard a38e68b5466d1997cea8466dbd4fc8dacd4e11d8 -npm i -printf "[profile.default]\nsrc = 'contracts'\nout = 'out'\nlibs = ['node_modules']\n" > foundry.toml -forge build -#+end_src - -Okay so now we have the contracts from a (hopefully) working version -of the repo. We can deploy a new verifier. This isn't strictly -necessary but good to do because in some cases you would need a new -verifier contract. - -#+begin_src bash -forge create --json \ - --rpc-url "http://$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ - contracts/mocks/VerifierRollupHelperMock.sol:VerifierRollupHelperMock > verifier-out.json -#+end_src - -Okay so we'll first try to create a new rollup type for our upgraded -network. In order to configure this file, we'll need a bunch of values -from the l1 setup. - -#+begin_src bash -kurtosis service exec cdk-v1 contracts-001 "cat /opt/zkevm/combined.json" -#+end_src - -Let's try forge to create the contracts: - -#+begin_src bash -ger="0x1f7ad7caA53e35b4f0D138dC5CBF91aC108a2674" -pol="0xEdE9cf798E0fE25D35469493f43E88FeA4a5da0E" -bridge="0xD71f8F956AD979Cc2988381B8A743a2fE280537D" -mngr="0x2F50ef6b8e8Ee4E579B17619A92dE3E2ffbD8AD2" -forge create --json \ - --rpc-url "http://$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ - contracts/v2/consensus/validium/migration/PolygonValidiumStorageMigration.sol:PolygonValidiumStorageMigration \ - --constructor-args $ger $pol $bridge $mngr > new-consensus-out.json - -genesis="0xd619a27d32e3050f2265a3f58dd74c8998572812da4874aa052f0886d0dfaf47" -cast send -j --rpc-url "http://$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ - $mngr \ - 'addNewRollupType(address,address,uint64,uint8,bytes32,string)' \ - "$(jq -r '.deployedTo' new-consensus-out.json)" \ - "$(jq -r '.deployedTo' verifier-out.json)" \ - 9 0 "$genesis" "test!!!" > add-rollup-type-out.json -#+end_src - - -Assuming that all worked somehow, you should be able to get your new -rollup type id: - -#+begin_src bash -cat add-rollup-type-out.json | jq -r '.logs[0].topics[1]' -#+end_src - -Taking that id, we should be able to update our rollup: - -#+begin_src bash -rollup="0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91" -cast send -j --rpc-url "http://$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ - $mngr \ - 'updateRollup(address,uint32,bytes)' \ - "$rollup" 2 0x > update-rollup-type-out.json -#+end_src - -Now we should also be able to verify that our rollupid has been -updated. Previously the 4th value was a ~7~ and now it should be a -~9~. - -#+begin_src bash -cast call --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - "$(jq -r '.L1Config.polygonRollupManagerAddress' /tmp/fork-7-test/genesis.json)" \ - "rollupIDToRollupData(uint32)(address,uint64,address,uint64,bytes32,uint64,uint64,uint64,uint64,uint64,uint64,uint8)" 1 -#+end_src - -After updating the rollup it seems like the DA Protcol needs to be -setup again: - -#+begin_src bash -rollup="0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91" -dac="0x5A6896A98c4B7C7E8f16d177C719a1d856b9154c" -cast send -j \ - --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625" \ - --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ - "$rollup" 'setDataAvailabilityProtocol(address)' $dac > set-dac-out.json -#+end_src - - -* Node Upgrade - -In terms of the smart contracts, the upgrade should more or less be -done, but we need to start the nodes back up. This procedure is very -sensitive and we must ensure that the synchronizer starts first. The -main thing we'll do is revert the parameters back to the versions of -the node that worked with fork 9 specify that ONLY stage 3 should run. - -#+begin_src diff -diff --git a/params.yml b/params.yml -index c2dd446..cdb8338 100644 ---- a/params.yml -+++ b/params.yml -@@ -8,7 +8,7 @@ deployment_suffix: "-001" - # The deployment process is divided into various stages. - # The `stages` parameter indicates the specific stages you wish the deployment to proceed through. - # By default, it will execute all the stages. --stages: [1, 2, 3, 4, 5] -+stages: [3] - - # Docker images and repositories used to spin up services. - zkevm_prover_image: hermeznetwork/zkevm-prover:v6.0.0 -#+end_src - -At this point, we should be able to run Kurtosis and ideally bring -back up the main node components. Before starting the node backup, be -sure to remove the ~HaltOnBatchNumber~ setting that we added earlier -in the process - -#+begin_src bash -kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always . -#+end_src - -At this point, the core services are running and if everything went -well, we should be able to send a transaction and see that the batche -numbers are moving through their normal progression. - -#+begin_src bash -export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" -cast send --legacy --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 --value 0.01ether 0x0000000000000000000000000000000000000000 -cast rpc zkevm_batchNumber -cast rpc zkevm_virtualBatchNumber -cast rpc zkevm_verifiedBatchNumber -#+end_src - -* Random Notes - -After starting the nodes back up I'm seeing a decent amount of errors -in the synchronizer like this, it doesn't seem like it actually causes -an issue, but it's a little odd. - -#+begin_example -{"level":"warn","ts":1711502381.03938,"caller":"etherman/etherman.go:661","msg":"Event not registered: {Address:0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91 Topics:[0xd331bd4c4cd1afecb94a225184bded161ff3213624ba4fb58c4f30c5a861144a] Data:[0 0 0 0 0 0 0 0 0 0 0 0 90 104 150 169 140 75 124 126 143 22 209 119 199 25 161 216 86 185 21 76] BlockNumber:108 TxHash:0x1bb5e714dd96434ded2d818458cc517cf7b30f5787dbb3aedb667e5e3e96808e TxIndex:0 BlockHash:0xdf5850cd5a8975859595649a05ce245f02953e84af627e9b22a1f8381077f057 Index:0 Removed:false}","pid":7,"version":"0.6.4+cdk"} -#+end_example - -We can check this event directly from the rpc as well: - -#+begin_src bash -cast logs --rpc-url "http://$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" --address 0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91 --from-block 108 --to-block 108 -#+end_src - -We can reverse which event this is with the following script: - -#+begin_src bash -cat compiled-contracts/*.json | jq '.abi[] | select(.type == "event") | .type = "function"' | jq -s | polycli abi decode | grep d33 -cast sig-event 'SetDataAvailabilityProtocol(address)' -#+end_src - -It looks like the unregistered event is a call to -~SetDataAvailabilityProtocol(address)~, but unclear why that -particular event is not recognized. diff --git a/docs/how-to/integrate-da.md b/docs/how-to/integrate-da.md new file mode 100644 index 000000000..9c2a64234 --- /dev/null +++ b/docs/how-to/integrate-da.md @@ -0,0 +1,198 @@ +--- +comments: true +--- + +This document shows you how to integrate a third-party data availability (DAC) solution into your CDK stack. + +## Prerequisites + +!!! tip + Make sure you have upgraded your CDK stack if necessary. + +## Set up contracts + +This section shows you how to create a custom CDK validium DAC contract. + +1. Clone [zkevm-contracts](https://github.com/0xPolygonHermez/zkevm-contracts). + +2. `cd` into `zkevm-contracts` and checkout tag `v6.0.0-rc.1-fork.9`. + +3. Run `npm install` from the root. + +4. `cd` to the `contracts/v2/consensus/validium` directory. + + !!! tip + - Until further notice, these contracts run on the [etrog release](https://polygon.technology/blog/polygon-zkevm-the-etrog-upgrade-is-live-on-mainnet). + +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. + + !!! tip + - 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. + - The contract supports custom smart contract implementation and, through this, DACs can add their custom on-chain verification logic. + +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. + + ```solidity + // Name of the data availability protocol + string internal constant _PROTOCOL_NAME = ""; + + ... + + /** + * @notice Return the protocol name + */ + function getProcotolName() external pure override returns (string memory) { + return _PROTOCOL_NAME; + } + ``` + +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. + + ```ts + const supporteDataAvailabilityProtocols = [""]; + ``` + +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. + +!!! info "`PolygonValidiumEtrog.sol` solution" + + 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. + + 1. It implements the function [`verifyMessage` function](https://github.com/0xPolygonHermez/zkevm-contracts/blob/54f58c8b64806429bc4d5c52248f29cf80ba401c/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol#L231): + + ```solidity + // Validate that the data availability protocol accepts the dataAvailabilityMessage + // note This is a view function, so there's not much risk even if this contract was vulnerable to reentrant attacks + dataAvailabilityProtocol.verifyMessage( + accumulatedNonForcedTransactionsHash, + dataAvailabilityMessage + ); + ``` + + 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. + + 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. + + ```solidity + /** + * @notice Allow the admin to set a new data availability protocol + * @param newDataAvailabilityProtocol Address of the new data availability protocol + */ + function setDataAvailabilityProtocol( + IDataAvailabilityProtocol newDataAvailabilityProtocol + ) external onlyAdmin { + dataAvailabilityProtocol = newDataAvailabilityProtocol; + + emit SetDataAvailabilityProtocol(address(newDataAvailabilityProtocol)); + } + ``` + +## Deploy Docker image + +This section shows you how to deploy the Docker image containing your custom DAC contract. + +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: + + ```json + "minDelayTimelock": 3600, // BECOMES "minDelayTimelock": 1, + ``` + +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: + + ```json + "consensusContract": "PolygonValidiumEtrog", // CHANGE THIS TO YOUR CONTRACT NAME + "dataAvailabilityProtocol": "PolygonDataCommittee", // ADD THIS PARAMETER + ``` + +3. Run the following command: + + ```sh + cp docker/scripts/v2/hardhat.example.paris hardhat.config.ts + ``` + +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: + + ```sh + sudo chmod -R go+rxw docker/gethData before docker build -t hermeznetwork/geth-zkevm-contracts -f docker/Dockerfile . + ``` + +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: + + ```ts + // Setup data committee to 0 + await (await polygonDataCommittee?.setupCommittee(0, [], "0x")).wait(); + console.log(dataAvailabilityProtocol, "deployed to:", polygonDataCommittee.target); + ``` + +6. Build the image with the following commands: + + ```sh + sudo npx hardhat compile + sudo npm run docker:contracts + ``` + +7. Tag the image with the following command, where `XXXX` is custom: + + ```sh + docker image tag hermeznetwork/geth-zkevm-contracts hermeznetwork/geth-cdk-validium-contracts:XXXX + ``` + +## Set up the node + +This section shows you how to set up your CDK node that sends and receives data from the DAC. + +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. + +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. + + ```go + const ( + // DataAvailabilityCommittee is the DAC protocol backend + DataAvailabilityCommittee DABackendType = "DataAvailabilityCommittee" + ) + ``` + + where `DataAvailabilityCommittee` matches the `_PROTOCOL_NAME` see in the [Set up contracts](#set-up-contracts) section. + +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. + +4. Instantiate your package and use it to create the main data availability instance, as done in the Polygon implementation. + +## Test the integration + +!!! tip + - By default, all E2E tests run using the DAC. + - It is possible to run the E2E tests using other DAC backends by amending the `test.node.config.toml` file. + +To test your DAC integration, follow the steps below. + +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. + +2. Generate a docker image containing the changes to the node: + + ```sh + make build-docker + ``` + +3. Build the genesis file for the node: + + - First, clone the [cdk-validium-node](https://github.com/0xPolygon/cdk-validium-node) repo and checkout v0.6.4-cdk.5. + - 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: + + !!! info "Parameters to change" + `l1Config.polygonZkEVMAddres`s ==> `rollupAddress` @ `create_rollup_output.json` + `l1Config.polygonRollupManagerAddress` ==> `polygonRollupManager` @ `deploy_output.json` + `l1Config.polTokenAddress` ==> `polTokenAddress` @ `deploy_output.json` + `l1Config.polygonZkEVMGlobalExitRootAddress` ==> `polygonZkEVMGlobalExitRootAddress` @ `deploy_output.json` + `rollupCreationBlockNumber` ==> `createRollupBlock` @ `create_rollup_output.json` + `rollupManagerCreationBlockNumber` ==> `deploymentBlockNumber` @ `deploy_output.json` + `root` ==> `root` @ `genesis.json` + `genesis` ==> `genesis` @ `genesis.json` + + !!! important + - You should follow this step every time you build a new Docker image. + +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). + +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. + diff --git a/docs/how-to/manage-policies.md b/docs/how-to/manage-policies.md new file mode 100644 index 000000000..c2305fb65 --- /dev/null +++ b/docs/how-to/manage-policies.md @@ -0,0 +1,94 @@ +--- +comments: true +--- + +# Manage allowlists, and more, with policies + +!!! important + Policies are currently only available in validium mode. + +Managing allowlists, denylists, and ACLs is done with policies. + +## Policy overview + +A **policy** is a set of rules that govern what actions are allowed or denied in the transaction pool. + +- **Fine-grained control**: Developers can specify policies at a granular level, allowing or denying specific actions for specific addresses. +- **Dynamic updates**: Policies and ACLs can be updated on-the-fly without requiring a node restart. +- **Database-backed**: All policy data is stored in a PostgreSQL database. +- **Extensible**: New policies can be easily added to the system. + +## Validium node + +### Policies + +Currently, there are two defined policies: + +- **SendTx**: governs whether an address may send transactions to the pool. +- **Deploy**: governs whether an address may deploy a contract. + +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. + +### Code definitions + +- **Policy management**: [`cmd/policy.go`](https://github.com/0xPolygon/cdk-validium-node/blob/5399f8859af9ffb0eb693bf395e1f09b53b154de/cmd/policy.go) contains the core logic of policy management. +- **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. +- **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. +- **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. + +### How to use a policy + +| Command name | Description | Flags & parameters | +|--------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| `policy add` | Add address(es) to a policy exclusion list | `--policy` (or `-p`): Policy name
`--csv`: CSV file with addresses | +| `policy remove` | Remove address(es) from a policy exclusion list | `--policy` (or `-p`): Policy name
`--csv`: CSV file with addresses to remove | +| `policy clear` | Clear all addresses from a policy's exclusion list | `--policy` (or `-p`): Policy name | +| `policy describe` | Describe the default actions for the policies or a specific policy | `--policy` (or `-p`): Policy name (optional)
`--no-header`: Omit header in output (optional) | +| `policy update` | Update the default action for a policy | `--policy` (or `-p`): Policy name
`--allow`: Set policy to 'allow'
`--deny`: Set policy to 'deny' | + +!!! note + The examples demonstrate a `deploy` policy. + +#### Add addresses + +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. + +```bash +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy add --policy deploy 0xAddress1 +``` + +#### Remove addresses + +To remove addresses from a policy, you can use the `policy remove` command. + +```bash +# Remove a single address from the 'deploy' policy +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy remove --policy deploy 0xAddress1 + +# Remove multiple addresses from the 'deploy' policy using a CSV file +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy remove --policy deploy --csv addresses.csv +``` + +#### Clear all addresses + +To remove all addresses from a policy's ACL, you can use the `policy clear` command. + +```bash +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy clear --policy deploy +``` + +#### Get information about a policy + +To get information about a specific policy or all policies, you can use the `policy describe` command. + +```bash +# Describe a specific policy +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy describe --policy deploy + +# Describe all policies +docker exec -it cdk-validium-aggregator /app/cdk-validium-node policy describe +``` + +[^1]: **Allowlisting**: The process of explicitly allowing addresses to perform certain actions. +[^2]: **Denylisting**: The process of explicitly denying addresses from performing certain actions. +[^3]: **ACL (access control list)**: A list of addresses that are exceptions to a given policy. diff --git a/docs/how-to/migrate/forkid-7-to-9 b/docs/how-to/migrate/forkid-7-to-9 deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/how-to/migrate/forkid-7-to-9.md b/docs/how-to/migrate/forkid-7-to-9.md new file mode 100644 index 000000000..a7e0544e2 --- /dev/null +++ b/docs/how-to/migrate/forkid-7-to-9.md @@ -0,0 +1,313 @@ +--- +comments: true +--- + +This document shows you how to migrate from fork 7 to fork 9 using the Kurtosis package. + +!!! tip + These steps are similar a production build, except you have to use a [timelock](https://github.com/0xPolygonHermez/zkevm-contracts/blob/v5.0.1-rc.2-fork.8/contracts/PolygonZkEVMTimelock.sol) contract to make the calls. + +## Prequisite steps and set up + +1. Run a clean command to remove any lingering state: + + ```sh + kurtosis clean --all + ``` + +2. Downgrade all the necessary parameters to switch back to fork 7. Open the `params.yml` file and make the following changes: + + ```diff + diff --git a/params.yml b/params.yml + index 175619f..a72d452 100644 + --- a/params.yml + +++ b/params.yml + @@ -29,13 +29,13 @@ args: + deployment_suffix: "-001" + + # Docker images and repositories used to spin up services. + - zkevm_prover_image: hermeznetwork/zkevm-prover:v6.0.0 + + zkevm_prover_image: hermeznetwork/zkevm-prover:v4.0.19 + + - zkevm_node_image: 0xpolygon/cdk-validium-node:0.6.4-cdk.2 + + zkevm_node_image: 0xpolygon/cdk-validium-node:0.5.13-cdk.3 + + - zkevm_da_image: 0xpolygon/cdk-data-availability:0.0.7 + + zkevm_da_image: 0xpolygon/cdk-data-availability:0.0.6 + + zkevm_contracts_image: leovct/zkevm-contracts # the tag is automatically replaced by the value of /zkevm_rollup_fork_id/ + @@ -160,7 +160,7 @@ args: + zkevm_rollup_chain_id: 10101 + + # The fork id of the new rollup. It indicates the prover (zkROM/executor) version. + - zkevm_rollup_fork_id: 9 + + zkevm_rollup_fork_id: 7 + + # The consensus contract name of the new rollup. + zkevm_rollup_consensus: PolygonValidiumEtrog + ``` + +3. Now kick-off a full redeploy: + + ```sh + kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always . + ``` + +4. Confirm onchain that fork 7 is running: + + ```sh + kurtosis files download cdk-v1 genesis /tmp/fork-7-test + cast call \ + --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ + "$(jq -r '.L1Config.polygonRollupManagerAddress' /tmp/fork-7-test/genesis.json)" \ + "rollupIDToRollupData(uint32)(address,uint64,address,uint64,bytes32,uint64,uint64,uint64,uint64,uint64,uint64,uint8)" 1 + ``` + + Should you see `7` showing as the 4th parameter. + +5. Send some test transactions to ensure batches are verified as expected. + + ```sh + export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" + cast send --legacy --private-key "$(yq -r .args.zkevm_l2_admin_private_key params.yml)" --value 0.01ether 0x0000000000000000000000000000000000000000 + cast rpc zkevm_batchNumber + cast rpc zkevm_virtualBatchNumber + cast rpc zkevm_verifiedBatchNumber + ``` + +After a few minutes, the number of verified batches should increase (the first batch checked does not count). + +## Make a clean stop of the sequencer + +1. Before attempting the upgrade, we need to make a clean stop of the sequencer. To do this, pick a halting batch number by updating the `node-config.toml` file like this. Make sure to pick a batch number higher than the current batch number! + + ```sh + cast to-dec $(cast rpc zkevm_batchNumber | sed 's/"//g') + ``` + + ```diff + diff --git a/templates/trusted-node/node-config.toml b/templates/trusted-node/node-config.toml + index 6c9b9fa..372d904 100644 + --- a/templates/trusted-node/node-config.toml + +++ b/templates/trusted-node/node-config.toml + @@ -117,7 +117,7 @@ StateConsistencyCheckInterval = "5s" + BatchMaxDeltaTimestamp = "20s" + L2BlockMaxDeltaTimestamp = "4s" + ResourceExhaustedMarginPct = 10 + - HaltOnBatchNumber = 0 + + HaltOnBatchNumber = 64 + SequentialBatchSanityCheck = false + SequentialProcessL2Block = true + [Sequencer.StreamServer] + ``` + +2. Re-run Kurtosis: + + ```sh + kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always . + ``` + +3. Wait for the sequencer to halt and the verified batch to equal the latest batch and check the logs. + + ```sh + kurtosis service logs cdk-v1 zkevm-node-sequencer-001 --follow + ``` + + You should see error logs that look like this: + + ```json + {"level":"error","ts":1711481674.517157,"caller":"sequencer/finalizer.go:806","msg":"halting finalizer, error: finalizer reached stop sequencer on batch number: 64%!(EXTRA string=\n/home/runner/work/cdk-validium-node/cdk-validium-node/log/log.go:142 github.com/0xPolygonHermez/zkevm-node/log.appendStackTraceMaybeArgs()\n/home/runner/work/cdk-validium-node/cdk-validium-node/log/log.go:251 github.com/0xPolygonHermez/zkevm-node/log.Errorf()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:806 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Halt()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:221 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).closeAndOpenNewWIPBatch()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:163 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeWIPBatch()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:330 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeBatches()\n/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:166 github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Start()\n)","pid":7,"version":"v0.1.0","stacktrace":"github.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Halt\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:806\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).closeAndOpenNewWIPBatch\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:221\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeWIPBatch\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/batch.go:163\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).finalizeBatches\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:330\ngithub.com/0xPolygonHermez/zkevm-node/sequencer.(*finalizer).Start\n\t/home/runner/work/cdk-validium-node/cdk-validium-node/sequencer/finalizer.go:166"} + ``` + +4. Wait for the verified batch number to catch up to the trusted batch number: + + ```sh + export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" + cast rpc zkevm_batchNumber + cast rpc zkevm_verifiedBatchNumber + ``` + +5. When those two numbers are the same, stop the services that are going to be upgraded: + + ```sh + kurtosis service stop cdk-v1 zkevm-executor-pless-001 + kurtosis service stop cdk-v1 zkevm-node-aggregator-001 + kurtosis service stop cdk-v1 zkevm-node-eth-tx-manager-001 + kurtosis service stop cdk-v1 zkevm-node-l2-gas-pricer-001 + kurtosis service stop cdk-v1 zkevm-node-rpc-001 + kurtosis service stop cdk-v1 zkevm-node-rpc-pless-001 + kurtosis service stop cdk-v1 zkevm-node-sequence-sender-001 + kurtosis service stop cdk-v1 zkevm-node-sequencer-001 + kurtosis service stop cdk-v1 zkevm-node-synchronizer-001 + kurtosis service stop cdk-v1 zkevm-node-synchronizer-pless-001 + kurtosis service stop cdk-v1 zkevm-prover-001 + ``` + +## Smart contract calls + +1. From another directory, make the required smart contract calls (this should not be done from the `kurtosis-cdk` directory): + + ```sh + git clone git@github.com:0xPolygonHermez/zkevm-contracts.git + pushd zkevm-contracts/ + git reset --hard a38e68b5466d1997cea8466dbd4fc8dacd4e11d8 + npm install + printf "[profile.default]\nsrc = 'contracts'\nout = 'out'\nlibs = ['node_modules']\n" > foundry.toml + forge build + ``` + +2. Deploy a new verifier. + + !!! tip + This step isn't strictly necessary but good to do because in some cases you need a new verifier contract. + + ```sh + forge create \ + --json \ + --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ + --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ + contracts/mocks/VerifierRollupHelperMock.sol:VerifierRollupHelperMock > verifier-out.json + ``` + +3. Create the `PolygonValidiumStorageMigration` contract: + + ```sh + export ETH_RPC_URL="$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" + ger="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .polygonZkEVMGlobalExitRootAddress /opt/zkevm/combined.json" | tail -n +2)" + pol="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .polTokenAddress /opt/zkevm/combined.json" | tail -n +2)" + bridge="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .polygonZkEVMBridgeAddress /opt/zkevm/combined.json" | tail -n +2)" + mngr="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .polygonRollupManager /opt/zkevm/combined.json" | tail -n +2)" + forge create \ + --json \ + --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ + contracts/v2/consensus/validium/migration/PolygonValidiumStorageMigration.sol:PolygonValidiumStorageMigration \ + --constructor-args $ger $pol $bridge $mngr > new-consensus-out.json + ``` + +4. Add a new rollup type to the rollup manager: + + ```sh + genesis="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .genesis /opt/zkevm/combined.json" | tail -n +2)" + cast send \ + --json \ + --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ + $mngr \ + 'addNewRollupType(address,address,uint64,uint8,bytes32,string)' \ + "$(jq -r '.deployedTo' new-consensus-out.json)" \ + "$(jq -r '.deployedTo' verifier-out.json)" \ + 9 0 "$genesis" 'test!!!' > add-rollup-type-out.json + ``` + +5. Get your new rollup type id: + + ```sh + jq -r '.logs[0].topics[1]' add-rollup-type-out.json + ``` + +6. Update the rollup with the id: + + ```sh + rollup="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .rollupAddress /opt/zkevm/combined.json" | tail -n +2)" + cast send \ + --json \ + --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \ + $mngr \ + 'updateRollup(address,uint32,bytes)' \ + "$rollup" 2 0x > update-rollup-type-out.json + ``` + +7. Verify the updated rollupid. Previously the 4th value was a `7` and now it should be a `9`. + + ```sh + cast call \ + "$(jq -r '.L1Config.polygonRollupManagerAddress' /tmp/fork-7-test/genesis.json)" \ + "rollupIDToRollupData(uint32)(address,uint64,address,uint64,bytes32,uint64,uint64,uint64,uint64,uint64,uint64,uint8)" 1 + ``` + +8. Set up the data availability protcol again: + + ```sh + dac="$(kurtosis service exec cdk-v1 contracts-001 "jq -r .polygonDataCommittee /opt/zkevm/combined.json" | tail -n +2)" + cast send \ + --json \ + --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625" \ + "$rollup" 'setDataAvailabilityProtocol(address)' $dac > set-dac-out.json + ``` + +## Node upgrade + +At this stage, the smart contracts are upgraded. However, we still need to start the nodes again. + +!!! warning + - This procedure is very sensitive. + - Ensure the synchronizer starts first. + +We're going to revert the parameters back to the versions of the node that worked with fork 9, and specify that _ONLY_ stage 3 should run. + +1. Update the `params.yml` file as follows: + + ```sh + yq -Y --in-place '.deploy_l1 = false' params.yml + yq -Y --in-place '.deploy_zkevm_contracts_on_l1 = false' params.yml + yq -Y --in-place '.deploy_databases = false' params.yml + yq -Y --in-place '.deploy_cdk_bridge_infra = false' params.yml + yq -Y --in-place '.deploy_zkevm_permissionless_node = false' params.yml + yq -Y --in-place '.deploy_observability = false' params.yml + ``` + +2. Remove the `HaltOnBatchNumber` setting that we added earlier. + +3. Run Kurtosis to bring up the main node components. + + ```sh + kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always . + ``` + +4. The core services are now running and we should be able to send a transaction and see the batch numbers moving through their normal progression. + + ```sh + export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)" + cast send --legacy --private-key "$(yq -r .args.zkevm_l2_admin_private_key params.yml)" --value 0.01ether 0x0000000000000000000000000000000000000000 + cast rpc zkevm_batchNumber + cast rpc zkevm_virtualBatchNumber + cast rpc zkevm_verifiedBatchNumber + ``` + +## Troubleshooting + +1. If you clone the `zkevm-contracts` repo in the same folder as `kurtosis-cdk`, you may see this error when you try to deploy the stack: + + ```sh + Error: An error occurred running command 'run' + Caused by: An error occurred calling the run function for command 'run' + Caused by: An error starting the Kurtosis code execution '.' + Caused by: Error uploading package '.' prior to executing it + Caused by: There was an error compressing module '.' before upload + Caused by: An error occurred creating the archive from the files at '.' + Caused by: The files you are trying to upload, which are now compressed, exceed or reach 100mb. Manipulation (i.e. uploads or downloads) of files larger than 100mb is currently disallowed in Kurtosis. + ``` + +2. You may also see errors like these: + + ```json + {"level":"warn","ts":1711502381.03938,"caller":"etherman/etherman.go:661","msg":"Event not registered: {Address:0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91 Topics:[0xd331bd4c4cd1afecb94a225184bded161ff3213624ba4fb58c4f30c5a861144a] Data:[0 0 0 0 0 0 0 0 0 0 0 0 90 104 150 169 140 75 124 126 143 22 209 119 199 25 161 216 86 185 21 76] BlockNumber:108 TxHash:0x1bb5e714dd96434ded2d818458cc517cf7b30f5787dbb3aedb667e5e3e96808e TxIndex:0 BlockHash:0xdf5850cd5a8975859595649a05ce245f02953e84af627e9b22a1f8381077f057 Index:0 Removed:false}","pid":7,"version":"0.6.4+cdk"} + ``` + + You can check them directly from the rpc: + + ```sh + cast logs \ + --rpc-url "$(kurtosis port print cdk-v1 el-1-geth-lighthouse rpc)" \ + --address 0x1Fe038B54aeBf558638CA51C91bC8cCa06609e91 \ + --from-block 108 \ + --to-block 108 + ``` + + You can reverse an event with the following script: + + ```sh + cat compiled-contracts/*.json | jq '.abi[] | select(.type == "event") | .type = "function"' | jq -s | polycli abi decode | grep d33 + cast sig-event 'SetDataAvailabilityProtocol(address)' + ``` + +3. In the above example, it looks like the unregistered event is a call to `SetDataAvailabilityProtocol(address)`. diff --git a/docs/how-to/quick-test-stack.md b/docs/how-to/quick-test-stack.md new file mode 100644 index 000000000..0d1e39ac8 --- /dev/null +++ b/docs/how-to/quick-test-stack.md @@ -0,0 +1,59 @@ +--- +comments: true +--- + +A quick and easy method for testing a running CDK stack, whether in validium or rollup mode, is by sending a zero-value transaction and examining the result. + +First inspect the logs to find the `zkevm-node-rpc` details. For example, in the Kurtosis stack you should see something like: + + ```sh + zkevm-node-rpc-001 http-rpc: 8123/tcp -> http://127.0.0.1:32803 + ``` + +## Send transaction with cast + +In a terminal window, run the following command where the mnemonic is used just for testing and the address can be any valid account address. + +```sh +cast send --legacy --mnemonic 'code code code code code code code code code code code quality' --value 0 --gas-price 0 --rpc-url http://127.0.0.1:8123 0x0bb7AA0b4FdC2D2862c088424260e99ed6299148 +``` + +You should see something like this as output: + +```sh +blockHash 0x5d6d45f46e54c5d0890dd8a4ede989dc8042d7d3aeada375ea11d2e77c91a298 +blockNumber 1 +contractAddress +cumulativeGasUsed 21000 +effectiveGasPrice 0 +from 0x85dA99c8a7C2C95964c8EfD687E95E632Fc533D6 +gasUsed 21000 +logs [] +logsBloom 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 +root 0x97b15537641583db08f1e3db15cb1e89212ed8d147670a11f93f368d5960e72f +status 1 +transactionHash 0xd5443cff8dcc1147ead09d978d3abe9179615aa3eecbe4819c6768390bc467a3 +transactionIndex 0 +type 0 +to 0x66ec…89fd +``` + +Status `1` signifies a successful transaction. + +## Send transaction with MetaMask + +1. Add the network details manually to MetaMask and accept the defaults and auto-populating fields. + + ![MetaMask manual network entry](../img/how-to/manual-network-entry.png) + +2. In local/test setup you will find a pre-funded account with private key: `0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625`. Import the account into MetaMask. + +
+ ![Import pre-funded account](../img/how-to/account.png){ width=45% } +
+ +3. Send a transaction to another MetaMask account. + + ![Transaction sending success](../img/how-to/tx-success.png) + +
\ No newline at end of file diff --git a/docs/img/how-to/account.png b/docs/img/how-to/account.png new file mode 100644 index 000000000..2af19c340 Binary files /dev/null and b/docs/img/how-to/account.png differ diff --git a/docs/img/how-to/manual-network-entry.png b/docs/img/how-to/manual-network-entry.png new file mode 100644 index 000000000..713fc239b Binary files /dev/null and b/docs/img/how-to/manual-network-entry.png differ diff --git a/docs/img/how-to/tx-success.png b/docs/img/how-to/tx-success.png new file mode 100644 index 000000000..470b97a00 Binary files /dev/null and b/docs/img/how-to/tx-success.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 801696a30..11d6eeec7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,19 +24,21 @@ theme: nav: - Overview: index.md - - Getting started: - - For technical users: - - Deploy the CDK stack: quickstart/deploy-stack.md - - Set up a permissionless node: quickstart/set-up-node.md - - Observability: quickstart/observability.md - - For developers: - - Breakdown the deployment: quickstart/breakdown-deployment.md - - zkEVM contracts caching: quickstart/zkevm-cache-contracts.md - - Connect to CDK testnets: quickstart/connect-testnet.md + - For technical users: + - Deploy the CDK stack: quickstart/deploy-stack.md + - Set up a permissionless node: quickstart/set-up-node.md + - Observability: quickstart/observability.md + - For developers: + - Breakdown the deployment: quickstart/breakdown-deployment.md + - zkEVM contracts caching: quickstart/zkevm-cache-contracts.md - How to: - #- Migrate: - # - Fork id 7 to 9: how-to/migrate/forkid-7-to-9.md + - Migrate: + - Fork id 7 to 9: how-to/migrate/forkid-7-to-9.md - Use a native token: how-to/use-native-token.md + - Integrate a DAC: how-to/integrate-da.md + - Manage allowlists with policies: how-to/manage-policies.md + - Quickly test a running stack: how-to/quick-test-stack.md + - Connect to CDK testnets: quickstart/connect-testnet.md