docs: migrate docs from era-contracts #4579

0xValera · 2025-11-27T01:36:36Z

What ❔

There was still some documentation present in era-contracts repository.

We want to contain all of the documentation in zksync-era repository, so in this PR the missing pieces that were present there but not here are being moved, and some small refactoring/fixes are being applied.

The respective PR in era-contracts is here.

Why ❔

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.

zkzoomer

Looks good overall, just some suggestions. The dead links CI from era-contracts should also be added in as a new workflow.

zkzoomer · 2025-11-28T12:34:29Z

docs/src/specs/contracts/README.md

-  - [Precompiles](../contracts/zkevm/precompiles.md)
  - [Account abstraction](../contracts/zkevm/account_abstraction.md)
  - [Fee model](../contracts/zkevm/zksync_fee_model.md)
+- [EVM Emulation](../contracts/evm_emulation/technical_overview.md)


This file mentions "L3" which I was told was a big no-no. Not sure if it should be changed

zkzoomer · 2025-11-28T12:35:57Z

docs/src/specs/contracts/evm_emulation/evm_predeploys_list.md

@@ -0,0 +1,18 @@
+# EVM predeploys
+
+Some important EVM contracts can be deployed to predefined addresses if EVM emulation is enabled on the chain. It can be done using [DeployEvmPredeploys.s.sol](https://github.com/matter-labs/era-contracts/blob/8222265420f362c853da7160769620d9fed7f834/l1-contracts/deploy-scripts/evm-predeploys/DeployEvmPredeploys.s.sol) script.


We might want to point to the main branch which contains the most up to date changes in the (unlikely) case the script is modified. If the link breaks because the script is moved elsewhere, the dead links CI should catch it.

Suggested change

Some important EVM contracts can be deployed to predefined addresses if EVM emulation is enabled on the chain. It can be done using [DeployEvmPredeploys.s.sol](https://github.com/matter-labs/era-contracts/blob/8222265420f362c853da7160769620d9fed7f834/l1-contracts/deploy-scripts/evm-predeploys/DeployEvmPredeploys.s.sol) script.

Some important EVM contracts can be deployed to predefined addresses if EVM emulation is enabled on the chain. It can be done using [DeployEvmPredeploys.s.sol](https://github.com/matter-labs/era-contracts/tree/main/l1-contracts/deploy-scripts/evm-predeploys/DeployEvmPredeploys.s.sol) script.

zkzoomer · 2025-11-28T12:36:27Z

docs/src/specs/contracts/gateway/l2_gw_l1_messaging.md

-This document assumes that the reader is already aware of how [L2→L1 logs](../settlement_contracts/priority_queue/l1_l2_communication/l2_to_l1.md) are aggregated into the [MessageRoot](../interop/message_root.md) and what the [Gateway](../gateway/overview.md) is. To reduce interactions with L1, the Gateway gathers all the `ChainBatchRoot`s from all the chains into the tree with following structure:
+This document assumes that the reader is already aware of what SyncLayer (or how it is now called Gateway) is. To reduce the interactions with L1, on SyncLayer we will gather all the batch roots from all the chains into the tree with following structure:

 ![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging.png)


This file is missing:

Suggested change

![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging.png)

![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging.png)

![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging_2.png)

zkzoomer · 2025-11-28T12:36:55Z

docs/src/specs/contracts/settlement_contracts/zkchain_basics.md

-The execution delay is dynamically read from the contract's `executionDelay()` function by the node, eliminating the need for manual configuration management.
-
-The owner of the ValidatorTimelock contract is the decentralized governance. Note, that all the chains share the same ValidatorTimelock for simplicity.
+# Settlement Contracts


I think this file is missing

zkzoomer · 2025-11-28T12:37:18Z

docs/src/specs/upgrade_history/v27_evm_emulation/v27_evm_emulation.md

+The V27 upgrade happened after the gateway preparation upgrade, but before the gateway was deployed. As such the upgrade
+process did not involve the Gateway parts (upgrading the CTM on GW, etc), it was an L1-only upgrade.


Suggested change

The V27 upgrade happened after the gateway preparation upgrade, but before the gateway was deployed. As such the upgrade

process did not involve the Gateway parts (upgrading the CTM on GW, etc), it was an L1-only upgrade.

The V27 upgrade happened after the gateway preparation upgrade, but before the gateway was deployed. As such the upgrade process did not involve the Gateway parts (upgrading the CTM on GW, etc), it was an L1-only upgrade.

zkzoomer · 2025-11-28T12:38:25Z

docs/src/specs/upgrade_history/v27_evm_emulation/v27_evm_emulation.md

+Additionally this was not a bridge upgrade, as the bridge and ecosystem contracts didn't have new features, so L1<>L2
+bridging was not affected. This meant that only the system components, the Verifiers, Facets and L2 contracts needed to
+be upgraded.


Suggested change

Additionally this was not a bridge upgrade, as the bridge and ecosystem contracts didn't have new features, so L1<>L2

bridging was not affected. This meant that only the system components, the Verifiers, Facets and L2 contracts needed to

be upgraded.

Additionally this was not a bridge upgrade, as the bridge and ecosystem contracts didn't have new features, so L1<>L2 bridging was not affected. This meant that only the system components, the Verifiers, Facets and L2 contracts needed to be upgraded.

zkzoomer · 2025-11-28T12:45:15Z

docs/src/specs/contracts/settlement_contracts/data_availability/rollup_da.md

 ## Structure of the pubdata

-Rollups maintain the same structure of pubdata and apply the same rules for compression as those that were used in the previous versions of the system. These can be read [here](./state_diff_compression_v1_spec.md).
+Rollups maintain the same structure of pubdata and apply the same rules for compression as those that were used in the previous versions of the system. These can be read [here](./compression.md).


This file differs a lot from the analogous one that was removed in the contracts PR

zkzoomer · 2025-11-28T12:57:51Z

docs/src/specs/contracts/consensus/README.md

@@ -1,3 +0,0 @@
-# Consensus


I'm guessing these docs were removed as consensus was deprioritized, but not sure if we want to get rid of them completely?

migrate docs from era-contracts, small fixes

ecd4e20

0xValera mentioned this pull request Nov 27, 2025

docs: remove docs completely, migrate them to zksync-era matter-labs/era-contracts#1845

Open

3 tasks

0xValera added 2 commits November 26, 2025 22:44

lint

3c037e3

delete precompiles file (very outdated)

3dc3fe5

zkzoomer reviewed Nov 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: migrate docs from era-contracts #4579

docs: migrate docs from era-contracts #4579

0xValera commented Nov 27, 2025 •

edited

Loading

Uh oh!

zkzoomer left a comment

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

zkzoomer Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,18 @@
		# EVM predeploys

		Some important EVM contracts can be deployed to predefined addresses if EVM emulation is enabled on the chain. It can be done using [DeployEvmPredeploys.s.sol](https://github.com/matter-labs/era-contracts/blob/8222265420f362c853da7160769620d9fed7f834/l1-contracts/deploy-scripts/evm-predeploys/DeployEvmPredeploys.s.sol) script.

	![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging.png)
	![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging.png)
	![NestedL2GWL1Messaging.png](./img/nested_l2_gw_l1_messaging_2.png)

		The V27 upgrade happened after the gateway preparation upgrade, but before the gateway was deployed. As such the upgrade
		process did not involve the Gateway parts (upgrading the CTM on GW, etc), it was an L1-only upgrade.

docs: migrate docs from era-contracts #4579

Are you sure you want to change the base?

docs: migrate docs from era-contracts #4579

Conversation

0xValera commented Nov 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!

zkzoomer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

0xValera commented Nov 27, 2025 •

edited

Loading