matter-labs / zksync-withdrawal-finalizer

zkSync 2.0 Withdrawal Finalizer

zksync-era-withdrawal-finalizer

A Withdrawal Finalizer in Rust.

Purpose

Withdrawal Finalizer is a component of zksync-era responsible for monitoring and finalizing L2->L1 withdrawals. It does so by continuously monitoring events happening on both L2 and L1, keeping some state in persistent storage (which is PostgreSQL) and sending withdrawal finalization transactions whenever necessary.

Building

Building the project is straightforward:

cargo build

Deploying

To deploy this service you will need the following prerequisites:

1. Websocket RPC endpoint on Ethereum.
2. Websocket RPC endpoint on zkSync Era.
3. An instance of PostgreSQL database.

Running DB migrations

Prior to deployment of the service the database migrations have to be run with sqlx-cli component of sqlx:

$ cd ./storage
$ env DATABASE_URL=postgres://mycreds@myhost/mydb sqlx database create
$ env DATABASE_URL=postgres://mycreds@myhost/mydb sqlx migrate run

Configuration

Configuration is done via environment variables that can also be read from .env file if it is present. Deployment is done by deploying a dockerized image of the service.

Variable	Description
ETH_CLIENT_WS_URL	The address of Ethereum WebSocket RPC endpoint
ETH_CLIENT_HTTP_URL	The address of Ethereum HTTP RPC endpoint
CONTRACTS_L1_ERC20_BRIDGE_PROXY_ADDR	Address of the L1 ERC20 bridge contract**
CONTRACTS_L2_ERC20_BRIDGE_ADDR	Address of the L2 ERC20 bridge contract**
CONTRACTS_DIAMOND_PROXY_ADDR	Address of the L1 diamond proxy contract**
CONTRACTS_WITHDRAWAL_FINALIZER_CONTRACT	Address of the Withdrawal Finalizer contract **
API_WEB3_JSON_RPC_WS_URL	Address of the zkSync Era WebSocket RPC endpoint
API_WEB3_JSON_RPC_HTTP_URL	Address of the zkSync Era HTTP RPC endpoint
DATABSE_URL	The url of PostgreSQL database the service stores its state into
GAS_LIMIT	The gas limit of a single withdrawal finalization within the batch of withdrawals finalized in a call to finalizeWithdrawals in WithdrawalFinalizerContract
BATCH_FINALIZATION_GAS_LIMIT	The gas limit of the finalization of the whole batch in a call to finalizeWithdrawals in Withdrawal Finalizer Contract
WITHDRAWAL_FINALIZER_ACCOUNT_PRIVATE_KEY	The private key of the account that is going to be submit finalization transactions
TX_RETRY_TIMEOUT_SECS	Number of seconds to wait for a potentially stuck finalization transaction before readjusting its fees
FINALIZE_ETH_TOKEN	(Optional) Configure, whether the Ethereum withdrawal events should be monitored. Useful to turn off for custom bridges that are only interested in a particular ERC20 token and have nothing to do with main Ethereum withdrawals
CUSTOM_TOKEN_DEPLOYER_ADDRESSES	(Optional) Normally ERC20 tokens are deployed by the bridge contract. However, in custom cases it may be necessary to override that behavior with a custom set of addresses that have deployed tokens
CUSTOM_TOKEN_ADDRESSES	(Optional) Adds a predefined list of tokens to finalize. May be useful in case of custom bridge setups when the regular technique of finding token deployments does not work.
ENABLE_WITHDRAWAL_METERING	(Optional, default: "true") By default Finalizer collects metrics about withdrawn token volumens. Users may optionally switch off this metering.
ETH_FINALIZATION_THRESHOLD	(Optional, default: "0") Finalizer will only finalize ETH withdrawals that are greater or equal to this value
ONLY_FINALIZE_THESE_TOKENS	(Optional, default: None) If specified, creates a whitelist of erc20 tokens that will be finalized.

The configuration structure describing the service config can be found in config.rs

** more about zkSync contracts can be found here

Deploying the finalizer smart contract

The finalizer smart contract needs to reference the addresses of the diamond proxy contract and l1 erc20 proxy contract. You also need to know the key of the account you want to use to deploy the finalizer contract.

When you know those to deploy the contract you need to run (assume you are running anvil in a separate terminal):

$ yarn
$ env CONTRACTS_DIAMOND_PROXY_ADDR="0x9A6DE0f62Aa270A8bCB1e2610078650D539B1Ef9" CONTRACTS_L1_ERC20_BRIDGE_PROXY_ADDR="0x2Ae09702F77a4940621572fBcDAe2382D44a2cbA" MNEMONIC="test test test test test test test test test test test junk" ETH_CLIENT_WEB3_URL="http://localhost:8545" npx hardhat run ./scripts/deploy.ts

If all goes well the the result would be

...
Compiled 18 Solidity files successfully (evm target: paris).
CONTRACTS_WITHDRAWAL_FINALIZER_ADDRESS=0x712516e61C8B383dF4A63CFe83d7701Bce54B03e

And so you know the address of the deployed contract.

License

zkSync Withdrawal Finalizer is distributed under the terms of either

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Official Links

• Website
• GitHub
• Twitter
• Twitter for Devs
• Discord

Disclaimer

zkSync Era has been through lots of testing and audits. Although it is live, it is still in alpha state and will go through more audits and bug bounties programs. We would love to hear our community's thoughts and suggestions about it! It is important to state that forking it now can potentially lead to missing important security updates, critical features, and performance improvements.

zksync-withdrawal-finalizer's Issues

Current status of the project (April 2024)

Hello, first of all thanks for all the open-source work concerning the zk stack. Very useful and well documented.

To my question: is this project still working as expected after the Discord announcement on March 27? It would be super useful to have that confirmed as we're attempting to get automatic finalization of withdrawals on a pre-eip-4844 hyperchain.

cc @montekki, zkSync-Community-Hub/zksync-developers#457

[EIP-4844] Protocol upgrade implications on the project

Hello,

For someone lacking full context and understanding of the ZK stack, what was the rationale for #398 and why is it no longer needed to listen for L2->L1 events? I suspect this has to do with EIP-4844 but I cannot deduce anything with confidence after looking at the source code around the watcher and finalizer module, and how it affects the condition(s) in which the service triggers the onchain tx.

Any response or pointers would be much appreciated, thanks in advance 🙏

(edit: did not intend to add the bug label and I cannot remove it.)

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update actions/checkout digest to a5ac7e5
• chore(deps): update trufflesecurity/trufflehog digest to 0024b6c
• chore(deps): update rust crate itertools to 0.13.0
• fix(deps): update dependency @sentry/node to v8
• Click on this checkbox to rebase all open PRs at once

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• chore(deps): update dependency @types/node to v20
• chore(deps): update dependency chai to v5
• chore(deps): update dependency mocha to v10 (mocha, @types/mocha)
• chore(deps): update dependency prettier to v3
• chore(deps): update dependency typechain to v8
• fix(deps): update dependency @openzeppelin/contracts to v5
• fix(deps): update dependency node-fetch to v3
• fix(deps): update dependency prom-client to v15

Detected dependencies

cargo

Cargo.toml

• auto_impl 1.2.0
• async-trait 0.1.80
• ethers 2.0.14
• tokio 1.37.0
• clap 4.5.4
• tracing 0.1.40
• tracing-subscriber 0.3.18
• sentry 0.33.0
• lazy_static 1.4.0
• itertools 0.12.1
• serde 1.0.200
• thiserror 1.0.59
• serde_json 1.0.116
• color-eyre 0.6.3
• eyre 0.6.12
• dotenvy 0.15.7
• envconfig 0.10.0
• proc-macro2 1.0.81
• bincode 1.3.3
• futures 0.3.30
• quote 1.0.36
• num 0.4.2
• syn 2.0.60
• hex 0.4.3
• pretty_assertions 1.4.0
• sqlx 0.7.4
• chrono 0.4.38
• tokio-stream 0.1.15
• tokio-util 0.7.10
• url 2.5.0

bin/delete-db-content-migration/Cargo.toml

bin/delete-finalization-data-migration/Cargo.toml

bin/prepare-calldata-for-withdrawal/Cargo.toml

bin/withdrawal-finalizer/Cargo.toml

chain-events/Cargo.toml

client/Cargo.toml

ethers-log-decode/Cargo.toml

finalizer/Cargo.toml

storage/Cargo.toml

tx-sender/Cargo.toml

vlog/Cargo.toml

watcher/Cargo.toml

withdrawals-meterer/Cargo.toml

dockerfile

Dockerfile

• rust 1.78

github-actions

.github/workflows/build_and_publish.yml

• actions/checkout v4@3df4ab11eba7bda6032a0b82a6bb43b11571feac
• docker/setup-buildx-action v3
• docker/login-action v3
• docker/build-push-action v5.3.0

.github/workflows/cargo-deny.yml

• actions/checkout v4@3df4ab11eba7bda6032a0b82a6bb43b11571feac
• EmbarkStudios/cargo-deny-action v1

.github/workflows/check-pr-title.yml

• aslafy-z/conventional-pr-title-action v3

.github/workflows/check-spelling.yml

• taiki-e/install-action v2
• actions/checkout v4@3df4ab11eba7bda6032a0b82a6bb43b11571feac

.github/workflows/ci.yml

• actions/checkout v4@3df4ab11eba7bda6032a0b82a6bb43b11571feac
• actions-rs/toolchain v1
• Swatinem/rust-cache v2
• foundry-rs/foundry-toolchain v1

.github/workflows/secrets_scanner.yaml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• trufflesecurity/trufflehog 80e8a67c2d863ee8f6563b4e2806c93b8bfd96ea

npm

package.json

• @matterlabs/zksync-contracts ^0.6.0
• @openzeppelin/contracts ^4.8.1
• @sentry/node ^7.2.0
• @sentry/tracing ^7.2.0
• ethers ^6.0.0
• node-fetch ^2.6.1
• prom-client ^14.2.0
• zksync-web3 ^0.17.0
• @nomiclabs/hardhat-ethers ^2.0.5
• @nomiclabs/hardhat-etherscan ^3.0.3
• @nomiclabs/hardhat-solpp ^2.0.1
• @typechain/ethers-v5 ^11.0.0
• @typechain/hardhat ^9.0.0
• @types/chai ^4.2.0
• @types/mocha ^9.1.0
• @types/node ^14.14.5
• chai ^4.3.6
• hardhat ^2.12.7
• mocha ^9.2.1
• prettier ^2.5.1
• prettier-plugin-solidity ^1.1.2
• ts-generator ^0.1.1
• ts-node ^10.8.1
• typechain ^7.0.0
• typescript ^5.0.0

---

• Check this box to trigger a request for Renovate to run again on this repository