feat(gateway): Migration to Gateway #3654

Deniallugo · 2025-02-27T12:00:29Z

What ❔

Support migration to Gateway. That will be done through restart.

There are few major changes in server

Contracats config now splitted to 3 configs:
a. L1SpecificConfig - Stuff that exists only on l1 and will never be migrated to gateway
b. L2Contracts - Contracts that were deployed on l2
c. ChainSpecificContracts - Contracts that deployed on l1 and on gateway
L1 specific contracts and L2 contracts, for now, should be specified in contracts config, manually. In a future we will be able to load them as well
ChainSpecificContracts, are loading from the Settlement Layer, no need to specify
There are no configuration for settlement layer. The settlement layer known during the start of the node and the source of truth is contracts both on l1 and settlement layer.
Server constantly checks that settlement layer has not changed. If it chaged, server will wait until all processed transaction are sent and confirmed and the necessary contracts are deployed to l1. After that server will be killed. We assume that kubernetes will restart the server
During the start server checks the settlement layer and download the necessary contracts config, later on almost all components of the system are manipulating only with settlement layer client and config. Only eth watcher knows about both layers.

External Node:

During the sync with the server External node verifies the transaction on l1 for consistency. Once consistency checker is panicking, external node crashes
During the start External node checks the latest eth txs in db and depends on it setup the system to work either on Gateway or on L1

Migration process

Operator call the server notifier contract and this contract will send the message to server, that all commit operations, should be stopped
Server stops the commit operations, but continue to work in all other parts
Operator call the migrate to gateway function on contracts
Once the migration is executed both on l1 and gateway, server will crash
During the next start server will load all necessary contracts and continue to work

Why ❔

The migration to settlement layer should be smooth. Without necessary of manual restarts and setting the contracts, it will drastically increase the mistakes, especially with multiple chains in operation.

Is this a breaking change?

Yes
No

Operational changes

Checklist

PR title corresponds to the body of PR (we generate changelog entries from PRs).
Tests for the changes have been added / updated.
Documentation comments have been added / updated.
Code has been formatted via zkstack dev fmt and zkstack dev lint.

Signed-off-by: Danil <deniallugo@gmail.com>

core/node/node_framework/src/implementations/layers/gateway_migrator_layer.rs

Signed-off-by: Danil <deniallugo@gmail.com>

RomanBrodetski · 2025-03-03T12:19:01Z

Please add the PR description (what/why)

## What ❔ Refactor contracts config and moving it to framework. Also it support both layers Gateway and L1, allowing to automatically decide what layer supposed to be used now. ## Why ❔ In the future the contracts config will be loaded from Settlement Layer. It's the preparation, where no components depends on the contracts config directly. ## Is this a breaking change? - [ ] Yes - [x] No ## Operational changes   ## Checklist   - [ ] PR title corresponds to the body of PR (we generate changelog entries from PRs). - [ ] Tests for the changes have been added / updated. - [ ] Documentation comments have been added / updated. - [ ] Code has been formatted via `zkstack dev fmt` and `zkstack dev lint`. --------- Signed-off-by: Danil <deniallugo@gmail.com>

Signed-off-by: Danil <deniallugo@gmail.com>

RomanBrodetski

Thanks for taking care of my comments. I don't have any more at the moment.

I cannot say I'm happy with the current state, as already convoluted config system became more complex, but I don't have concrete guidelines on how to improve. Perhaps we cannot do much better because of the protocol requirements.

Please wait for @slowli 's approval as well.

slowli

I feel I'm still nowhere close to covering the entire PR changeset, so here's partial feedback.

zkstack_cli/crates/zkstack/src/commands/dev/commands/test/args/gateway_migration.rs

core/node/node_framework/src/implementations/layers/settlement_layer_data.rs

core/bin/external_node/src/config/mod.rs

core/node/consistency_checker/src/lib.rs

core/node/eth_watch/src/event_processors/gateway_migration.rs

Signed-off-by: Danil <deniallugo@gmail.com>

slowli

Haven't found anything major, but I still feel that I haven't covered the entire changeset.

core/lib/dal/src/server_notifications.rs

core/lib/eth_client/src/contracts_loader.rs

core/node/gateway_migrator/src/lib.rs

core/bin/zksync_server/src/main.rs

core/bin/zksync_server/src/node_builder.rs

core/lib/web3_decl/src/namespaces/zks.rs

core/node/genesis/src/lib.rs

core/node/node_framework/src/implementations/layers/base_token/base_token_ratio_persister.rs

Signed-off-by: Danil <deniallugo@gmail.com>

🤖 I have created a release *beep* *boop* --- ## [20.0.0](prover-v19.0.0...prover-v20.0.0) (2025-04-01) ### ⚠ BREAKING CHANGES * Remove old prover stack ([#3729](#3729)) * V27 update ([#3580](#3580)) ### Features * Add S3 implementation for object_store ([#3664](#3664)) ([a848927](a848927)) * **consensus:** Add consensus protocol versioning ([#3720](#3720)) ([d1b4308](d1b4308)) * **gateway:** Migration to Gateway ([#3654](#3654)) ([2858ba0](2858ba0)) * Remove old prover stack ([#3729](#3729)) ([fbbdc76](fbbdc76)) * Use JSON-RPC for core <> prover interaction ([#3626](#3626)) ([4e74730](4e74730)) * V27 update ([#3580](#3580)) ([9e18550](9e18550)) ### Bug Fixes * API URL for prover gateway ([#3716](#3716)) ([ca2c4a4](ca2c4a4)) * make proof data handler backwards compatible ([#3767](#3767)) ([bdbbaaa](bdbbaaa)) * Prover job ordering ([#3738](#3738)) ([8f7f831](8f7f831)) * **prover:** Fixing shutdown time for circuit-prover ([#3768](#3768)) ([6c9de26](6c9de26)) * **prover:** Reevaluation of 'heavy' jobs for WVG ([#3754](#3754)) ([2a8d33b](2a8d33b)) * **prover:** Remove deleted pods from autoscaler-agent cluster cache ([#3739](#3739)) ([e94985f](e94985f)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: zksync-era-bot <147085853+zksync-era-bot@users.noreply.github.com> Co-authored-by: zksync-era-bot <zksync-era-bot@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- ## [27.2.0](core-v27.1.0...core-v27.2.0) (2025-04-03) ### Features * **api:** Allow EVM bytecode overrides ([#3761](#3761)) ([8aee9f8](8aee9f8)) * **en:** Allow tree / state keeper cache recovery for genesis ([#3781](#3781)) ([dd18c48](dd18c48)) * **eth_signer:** Support eip712 txs ([#3752](#3752)) ([e278ab5](e278ab5)) * **gateway:** Handle server shutting down error ([#3777](#3777)) ([8e11adc](8e11adc)) * **gateway:** Migration to Gateway ([#3654](#3654)) ([2858ba0](2858ba0)) * **main:** Eigenda add custom quorum params ([#3719](#3719)) ([dac58ad](dac58ad)) * Update zksync-protocol deps to 0.151.5 ([#3790](#3790)) ([92beffe](92beffe)) * **zkos:** remove prev index pointer from leaves ([#3771](#3771)) ([5b8fd29](5b8fd29)) ### Bug Fixes * insert tokens without PG copy ([#3778](#3778)) ([b7a8152](b7a8152)) * **prover:** Force set all the `prover_job` labels to 0 ([#3787](#3787)) ([3ecc8db](3ecc8db)) * **prover:** Reevaluation of 'heavy' jobs for WVG ([#3754](#3754)) ([2a8d33b](2a8d33b)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: zksync-era-bot <zksync-era-bot@users.noreply.github.com>

## What ❔ Support migration to Gateway. That will be done through restart. There are few major changes in server 1. Contracats config now splitted to 3 configs: a. L1SpecificConfig - Stuff that exists only on l1 and will never be migrated to gateway b. L2Contracts - Contracts that were deployed on l2 c. ChainSpecificContracts - Contracts that deployed on l1 and on gateway 2. L1 specific contracts and L2 contracts, for now, should be specified in contracts config, manually. In a future we will be able to load them as well 3. ChainSpecificContracts, are loading from the Settlement Layer, no need to specify 4. There are no configuration for settlement layer. The settlement layer known during the start of the node and the source of truth is contracts both on l1 and settlement layer. 5. Server constantly checks that settlement layer has not changed. If it chaged, server will wait until all processed transaction are sent and confirmed and the necessary contracts are deployed to l1. After that server will be killed. We assume that kubernetes will restart the server 6. During the start server checks the settlement layer and download the necessary contracts config, later on almost all components of the system are manipulating only with settlement layer client and config. Only eth watcher knows about both layers. External Node: 1. During the sync with the server External node verifies the transaction on l1 for consistency. Once consistency checker is panicking, external node crashes 2. During the start External node checks the latest eth txs in db and depends on it setup the system to work either on Gateway or on L1 Migration process 1. Operator call the server notifier contract and this contract will send the message to server, that all commit operations, should be stopped 2. Server stops the commit operations, but continue to work in all other parts 3. Operator call the migrate to gateway function on contracts 4. Once the migration is executed both on l1 and gateway, server will crash 5. During the next start server will load all necessary contracts and continue to work ## Why ❔ The migration to settlement layer should be smooth. Without necessary of manual restarts and setting the contracts, it will drastically increase the mistakes, especially with multiple chains in operation. ## Is this a breaking change? - [ ] Yes - [x] No ## Operational changes   ## Checklist   - [x] PR title corresponds to the body of PR (we generate changelog entries from PRs). - [x] Tests for the changes have been added / updated. - [x] Documentation comments have been added / updated. - [x] Code has been formatted via `zkstack dev fmt` and `zkstack dev lint`. --------- Signed-off-by: Danil <deniallugo@gmail.com>

🤖 I have created a release *beep* *boop* --- ## [27.2.0](core-v27.1.0...core-v27.2.0) (2025-04-03) ### Features * **api:** Allow EVM bytecode overrides ([#3761](#3761)) ([8aee9f8](8aee9f8)) * **en:** Allow tree / state keeper cache recovery for genesis ([#3781](#3781)) ([dd18c48](dd18c48)) * **eth_signer:** Support eip712 txs ([#3752](#3752)) ([e278ab5](e278ab5)) * **gateway:** Handle server shutting down error ([#3777](#3777)) ([8e11adc](8e11adc)) * **gateway:** Migration to Gateway ([#3654](#3654)) ([c861ce1](c861ce1)) * **main:** Eigenda add custom quorum params ([#3719](#3719)) ([dac58ad](dac58ad)) * Update zksync-protocol deps to 0.151.5 ([#3790](#3790)) ([92beffe](92beffe)) * **zkos:** remove prev index pointer from leaves ([#3771](#3771)) ([5b8fd29](5b8fd29)) ### Bug Fixes * insert tokens without PG copy ([#3778](#3778)) ([b7a8152](b7a8152)) * **prover:** Force set all the `prover_job` labels to 0 ([#3787](#3787)) ([3ecc8db](3ecc8db)) * **prover:** Reevaluation of 'heavy' jobs for WVG ([#3754](#3754)) ([2a8d33b](2a8d33b)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: zksync-era-bot <zksync-era-bot@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- ## [27.2.0](matter-labs/zksync-era@core-v27.1.0...core-v27.2.0) (2025-04-03) ### Features * **api:** Allow EVM bytecode overrides ([#3761](matter-labs/zksync-era#3761)) ([8aee9f8](matter-labs/zksync-era@8aee9f8)) * **en:** Allow tree / state keeper cache recovery for genesis ([#3781](matter-labs/zksync-era#3781)) ([dd18c48](matter-labs/zksync-era@dd18c48)) * **eth_signer:** Support eip712 txs ([#3752](matter-labs/zksync-era#3752)) ([e278ab5](matter-labs/zksync-era@e278ab5)) * **gateway:** Handle server shutting down error ([#3777](matter-labs/zksync-era#3777)) ([8e11adc](matter-labs/zksync-era@8e11adc)) * **gateway:** Migration to Gateway ([#3654](matter-labs/zksync-era#3654)) ([3c5e3c1](matter-labs/zksync-era@3c5e3c1)) * **main:** Eigenda add custom quorum params ([#3719](matter-labs/zksync-era#3719)) ([dac58ad](matter-labs/zksync-era@dac58ad)) * Update zksync-protocol deps to 0.151.5 ([#3790](matter-labs/zksync-era#3790)) ([92beffe](matter-labs/zksync-era@92beffe)) * **zkos:** remove prev index pointer from leaves ([#3771](matter-labs/zksync-era#3771)) ([5b8fd29](matter-labs/zksync-era@5b8fd29)) ### Bug Fixes * insert tokens without PG copy ([#3778](matter-labs/zksync-era#3778)) ([b7a8152](matter-labs/zksync-era@b7a8152)) * **prover:** Force set all the `prover_job` labels to 0 ([#3787](matter-labs/zksync-era#3787)) ([3ecc8db](matter-labs/zksync-era@3ecc8db)) * **prover:** Reevaluation of 'heavy' jobs for WVG ([#3754](matter-labs/zksync-era#3754)) ([2a8d33b](matter-labs/zksync-era@2a8d33b)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: zksync-era-bot <zksync-era-bot@users.noreply.github.com>

Deniallugo added 14 commits February 25, 2025 16:30

Add multilayer client

3d85dcf

Signed-off-by: Danil <deniallugo@gmail.com>

Remove sl_client denendency from aggregator

7562ffe

Signed-off-by: Danil <deniallugo@gmail.com>

Migrator checker as a task

f3c988d

Signed-off-by: Danil <deniallugo@gmail.com>

Just die when the settlement layer is set

41bed8b

Signed-off-by: Danil <deniallugo@gmail.com>

Fix print to logger

124a5bb

Signed-off-by: Danil <deniallugo@gmail.com>

Add new contract to config

5c65fb8

Signed-off-by: Danil <deniallugo@gmail.com>

Save notification to the database

f23bae2

Signed-off-by: Danil <deniallugo@gmail.com>

Change the behavior eth tx aggregator

cef2873

Signed-off-by: Danil <deniallugo@gmail.com>

Initialize server-notifier

bd5e421

Signed-off-by: Danil <deniallugo@gmail.com>

Aggregate all functionality convert to migration

93a20bf

Signed-off-by: Danil <deniallugo@gmail.com>

Use universal trait for L1 eth client

1ed3f17

Signed-off-by: Danil <deniallugo@gmail.com>

Remove unnecessary contracts abi dependencies

e525889

Signed-off-by: Danil <deniallugo@gmail.com>

Migration changes

ea7f914

Signed-off-by: Danil <deniallugo@gmail.com>

Support from and to gateway in server

a7d8222

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo force-pushed the deniallugo-multilayer-client branch from bbd3f72 to a7d8222 Compare February 27, 2025 13:34

popzxc reviewed Feb 27, 2025

View reviewed changes

core/node/node_framework/src/implementations/layers/gateway_migrator_layer.rs Outdated Show resolved Hide resolved

Replace governance with chain admin

dbd0b42

Signed-off-by: Danil <deniallugo@gmail.com>

Merge branch 'main' into deniallugo-multilayer-client

bdd72ea

Deniallugo force-pushed the deniallugo-multilayer-client branch from 75b96ef to bdd72ea Compare March 4, 2025 10:54

Deniallugo added 3 commits March 11, 2025 16:15

Merge branch 'main' into deniallugo-multilayer-client

8abb6c6

Fix autocomplete

aecdeaf

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo requested review from popzxc, StanislavBreadless, perekopskiy and kelemeno March 11, 2025 16:03

Switch to v27

1c8f21f

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo force-pushed the deniallugo-multilayer-client branch from fe2cce5 to 08a3901 Compare March 11, 2025 19:20

Update genesis file

2b6a6f1

Signed-off-by: Danil <deniallugo@gmail.com>

RomanBrodetski previously approved these changes Mar 26, 2025

View reviewed changes

slowli reviewed Mar 26, 2025

View reviewed changes

Fix review

2df4b2a

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo dismissed RomanBrodetski’s stale review via 2df4b2a March 26, 2025 17:04

Deniallugo force-pushed the deniallugo-multilayer-client branch from 5919d2d to 2df4b2a Compare March 26, 2025 17:04

Refactor api builder

69b6015

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo force-pushed the deniallugo-multilayer-client branch from 106b4bf to 69b6015 Compare March 26, 2025 19:33

Deniallugo requested a review from slowli March 26, 2025 20:32

Update params for gateway migration

307a409

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo force-pushed the deniallugo-multilayer-client branch from c0fe06c to 307a409 Compare March 26, 2025 21:42

Deniallugo added 2 commits March 27, 2025 11:36

Remove an option to log consistency checker error

2227bf3

Signed-off-by: Danil <deniallugo@gmail.com>

Merge branch 'main' into deniallugo-multilayer-client

6a42e01

slowli previously approved these changes Mar 27, 2025

View reviewed changes

Final review suggestions

381c609

Signed-off-by: Danil <deniallugo@gmail.com>

Deniallugo dismissed slowli’s stale review via 381c609 March 27, 2025 16:57

otani88 approved these changes Mar 27, 2025

View reviewed changes

Deniallugo enabled auto-merge March 27, 2025 17:34

slowli approved these changes Mar 27, 2025

View reviewed changes

Deniallugo added this pull request to the merge queue Mar 27, 2025

Merged via the queue into main with commit 2858ba0 Mar 27, 2025
46 checks passed

Deniallugo deleted the deniallugo-multilayer-client branch March 27, 2025 18:50

This was referenced Mar 27, 2025

chore(main): release prover 20.0.0 #3672

Merged

chore(main): release zkstack_cli 0.2.0 #3086

Open

chore(main): release core 27.2.0 #3776

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(gateway): Migration to Gateway #3654

feat(gateway): Migration to Gateway #3654

Uh oh!

Deniallugo commented Feb 27, 2025 •

edited

Loading

Uh oh!

Uh oh!

RomanBrodetski commented Mar 3, 2025

Uh oh!

RomanBrodetski left a comment

Uh oh!

slowli left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

slowli left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat(gateway): Migration to Gateway #3654

feat(gateway): Migration to Gateway #3654

Uh oh!

Conversation

Deniallugo commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What ❔

Why ❔

Is this a breaking change?

Operational changes

Checklist

Uh oh!

Uh oh!

RomanBrodetski commented Mar 3, 2025

Uh oh!

RomanBrodetski left a comment

Choose a reason for hiding this comment

Uh oh!

slowli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

slowli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Deniallugo commented Feb 27, 2025 •

edited

Loading