diff --git a/docs/README.md b/docs/README.md index 7d5398e61..3c18c2f96 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,35 @@ # ZK Stack contracts specs -1. [Introduction](./introduction.md) -1. [Bridgehub](./bridgehub/README.md) -1. [ZKChain](./zk_chain/README.md) -1. [L1 Contracts](./l1_smart_contracts.md) +- [Glossary](./glossary.md) +- [Overview](./overview.md) +- [Bridging](./bridging/overview.md) + - [Bridgehub](./bridgehub/overview.md) + - [Chain registry](./bridgehub/chain_registry.md) + - [L1 ecosystem contracts](./bridgehub/bridgehub.md) + - [Asset Router](./asset_router/overview.md) +- [Chain Management](./chain_managment/overview.md) + - [Chain type manager](./chain_managment/chain_type_manager.md) + - [Admin roles](./chain_managment/admin_roles.md) + - [Chain genesis](./chain_managment/chain_genesis.md) + - [Upgrade process](./chain_managment/upgrade_process.md) +- [Settlement contracts](./settlement_contracts/overview.md) + - [L1 smart contracts](./settlement_contracts/l1_smart_contracts.md) + - [Data availability](./settlement_contracts/data_availability.md) + - [Custom DA](./settlement_contracts/data_availability/custom_da.md) + - [Rollup DA](./settlement_contracts/data_availability/rollup_da.md) + - [Standard pubdata format](./settlement_contracts/data_availability/standard_pubdata_format.md) + - [State diff compression v1 spec](./settlement_contracts/data_availability/state_diff_compression_v1_spec.md) + - [Priority Queue](./settlement_contracts/priority_queue.md) +- [L2 System Contracts](./l2_system_contracts.md) + - [Batches and blocks on ZKsync](./l2_system_contracts/batches_and_blocks_on_zksync.md) + - [Elliptic curve precompiles](./l2_system_contracts/elliptic_curve_precompiles.md) + - [L2 processing of L1->L2 transactions](./l2_system_contracts/l2_processing_of_l1->l2_txs.md) + - [System contracts bootloader description](./l2_system_contracts/system_contracts_bootloader_description.md) + - [ZKsync fee model](./l2_system_contracts/zksync_fee_model.md) +- [Gateway](./gateway/overview.md) + - [Chain migration](./gateway/chain_migration.md) + - [Gateway protocol upgrades](./gateway/gateway_protocol_upgrades.md) +- [Upgrade History](./upgrade_history.md) + - [Gateway upgrade](./upgrade_history/gateway_upgrade.md) ![Reading order](./img/reading_order.png) \ No newline at end of file diff --git a/docs/bridging/custom_asset_bridging/Overview.md b/docs/bridging/asset_router/Overview.md similarity index 100% rename from docs/bridging/custom_asset_bridging/Overview.md rename to docs/bridging/asset_router/Overview.md diff --git a/docs/bridging/custom_asset_bridging/contracts_review_cab.md b/docs/bridging/asset_router/asset_router.md similarity index 62% rename from docs/bridging/custom_asset_bridging/contracts_review_cab.md rename to docs/bridging/asset_router/asset_router.md index 3fa46229c..21c23bc8e 100644 --- a/docs/bridging/custom_asset_bridging/contracts_review_cab.md +++ b/docs/bridging/asset_router/asset_router.md @@ -32,47 +32,3 @@ The Native Token Vault is a special case of the Asset Handler, as we want it to ![Automatic Bridge](./automatic-bridging.png) -## Known Issues - -### storage layout - -L2SharedBridge will be a system contract, L2NativeTokenVault will replace it (the storage layout is still not yet backwards compatible) - -### bridgehubDeposit API change - -> /// @notice Allows bridgehub to acquire mintValue for L1->L2 transactions. - - /// @dev If the corresponding L2 transaction fails, refunds are issued to a refund recipient on L2. - function bridgehubDepositBaseToken( - uint256 _chainId, - bytes32 _assetId, - -Note, that the new SB is not compatible with both: - -- old Mailbox on Era -- old Bridgehub -- And vice versa. - -We need to either: - -- ensure that all 3 get upgraded at the same time. Upgrading BH and SB at the same time is feasible IMHO. But upgrading DP (Mailbox) in the same transaction may not be. -- have a concrete plan for such case. E.g. explicitly tell that the legacy deposits will stop working. In this case we need to check (at the very least visually) that the worst thing that can happen is just deposits not working and not some funds lost -- Add the corresponding legacy functions - -### Not allowing legacy withdrawals - -> require(!\_isEraLegacyEthWithdrawal(\_chainId, \_l2BatchNumber), "ShB: legacy eth withdrawal"); - -No method to finalize an old withdrawal. -We will manually finalize all legacy withdrawals before the upgrade, i.e. withdrawals that happened before the previous Bridgehub upgrade. - -### Custom Errors not implemented - -> require(expectedDepositAmount == \_depositAmount, "3T"); // The token has non-standard transfer logic - -Custom errors will be introduced for all contracts. - -## Migration plan - -- Bulkheads will need to be migrated (methods added) -- Tokens will have to be transferred (methods added) diff --git a/docs/bridging/custom_asset_bridging/img/asset-registration.png b/docs/bridging/asset_router/img/asset-registration.png similarity index 100% rename from docs/bridging/custom_asset_bridging/img/asset-registration.png rename to docs/bridging/asset_router/img/asset-registration.png diff --git a/docs/bridging/custom_asset_bridging/img/automatic-bridging.png b/docs/bridging/asset_router/img/automatic-bridging.png similarity index 100% rename from docs/bridging/custom_asset_bridging/img/automatic-bridging.png rename to docs/bridging/asset_router/img/automatic-bridging.png diff --git a/docs/bridging/bridgehub/l1_ecosystem_contracts.md b/docs/bridging/bridgehub/bridgehub.md similarity index 97% rename from docs/bridging/bridgehub/l1_ecosystem_contracts.md rename to docs/bridging/bridgehub/bridgehub.md index e7b547621..eff553033 100644 --- a/docs/bridging/bridgehub/l1_ecosystem_contracts.md +++ b/docs/bridging/bridgehub/bridgehub.md @@ -242,18 +242,8 @@ Note, however, that it is not the way to withdraw base token. To withdraw base t After the batch with the withdrawal request has been executed, the user can finalize the withdrawal on L1 by calling `L1AssetRouter.finalizeWithdrawal`, where the user provides the proof of the corresponding withdrawal message. -# Additional limitations for the current release +# Additional limitations for the current version -In the current release creating new chains will not be permissionless. That is needed to ensure that no malicious input can be provided there. +In the current version creating new chains will not be permissionless. That is needed to ensure that no malicious input can be provided there. Also, since in the current release, there will be little benefits from shared liquidity, i.e. the there will be no direct ST<>ST transfers supported, as a measure of additional security we’ll also keep track of balances for each individual ST and will not allow it to withdraw more than it has deposited into the system. - -# Other contracts - -## Governance - -The documentation about decentralized governance can be read here (FIXME: provide link). - -## ValidatorTimelock - -All the chains registered on the current CTM share the same timelock for batch execution. It is a security feature, you can read more about it [here](./L1%20smart%20contracts.md#validatortimelock). diff --git a/docs/bridging/bridgehub/chain_registry.md b/docs/bridging/bridgehub/chain_registry.md index e69de29bb..f35a2a93b 100644 --- a/docs/bridging/bridgehub/chain_registry.md +++ b/docs/bridging/bridgehub/chain_registry.md @@ -0,0 +1,2 @@ +# Chain registry +https://github.com/ethereum/ERCs/pull/669/files diff --git a/docs/chain_managment/chain_type_manager.md b/docs/chain_managment/chain_type_manager.md new file mode 100644 index 000000000..417fbfca8 --- /dev/null +++ b/docs/chain_managment/chain_type_manager.md @@ -0,0 +1,68 @@ +## Chain Type Manager (CTM) + +> If someone is already familiar with the [previous version](https://github.com/code-423n4/2024-03-zksync) of zkSync architecture, this contract was previously known as "State Transition Manager (CTM)". + +Currently bridging between different zk rollups requires the funds to pass through L1. This is slow & expensive. + +The vision of seamless internet of value requires transfers of value to be *both* seamless and trustless. This means that for instance different STs need to share the same L1 liquidity, i.e. a transfer of funds should never touch L1 in the process. However, it requires some sort of trust between two chains. If a malicious (or broken) rollup becomes a part of the shared liquidity pool it can steal all the funds. + +However, can two instances of the same zk rollup trust each other? The answer is yes, because no new additions of rollups introduce new trust assumptions. Assuming there are no bugs in circuits, the system will work as intended. + +How can two rollups know that they are two different instances of the same system? We can create a factory of such contracts (and so we would know that each new rollup created by this instance is correct one). But just creating correct contracts is not enough. Ethereum changes, new bugs may be found in the original system & so an instance that does not keep itself up-to-date with the upgrades may exploit some bug from the past and jeopardize the entire system. Just deploying is not enough. We need to constantly make sure that all STs are up to date and maintain whatever other invariants are needed for these STs to trust each other. + +Let’s define as *Chain Type Manager* (CTM) **as a contract that is responsible for the following: + +- It serves as a factory to deploy STs (new ZK chains) +- It is responsible for ensuring that all the STs deployed by it are up-to-date. + +Note, that this means that STs have a “weaker” governance. I.e. governance can only do very limited number of things, such as setting the validator. ST admin can not set its own upgrades and it can only “execute” the upgrade that has already been prepared by the CTM. + +In the long term vision STs deployment will be permissionless, however CTM will always remain the main point of trust and will have to be explicitly whitelisted by the decentralized governance of the entire ecosystem before its ST can get the access to the shared liquidity. + +## Configurability in the first release + +For now, only one CTM will be supported — the one that deploys instances of zkSync Era, possibly using other DA layers. To read more about different DA layers, check out this document (FIXME link). + +The exact process of deploying & registering a ST will be described in [sections below](#creating-new-chains-with-bridgehub). Overall, each ST in the first release will have the following parameters: + +| ST parameter | Updatability | Comment | +| --- | --- | --- | +| chainId | Permanent | Permanent identifier of the ST. Due to wallet support reasons, for now chainId has to be small (48 bits). This is one of the reasons why for now we’ll deploy STs manually, to prevent STs from having the same chainId as some another popular chain. In the future it will be trustlessly assigned as a random 32-byte value.| +| baseTokenAssetId | Permanent | Each ST can have their own custom base token (i.e. token used for paying the fees). It is set once during creation and can never be changed. Note, that we refer to and "asset id" here instead of an L1 address. To read more about what is assetId and how it works check out the document for custom asset bridging (FIXME: link) | +| chainTypeManager | Permanent | The CTM that deployed the ST. In principle, it could be possible to migrate between CTMs (assuming both CTMs support that). However, in practice it may be very hard and as of now such functionality is not supported. | +| admin | By admin of ST | The admin of the ST. It has some limited powers to govern the chain. To read more about which powers are available to a chain admin and which precautions should be taken, check out this document (FIXME: link to document about admin precauotions) | +| validatorTimelock | CTM | For now, we want all the chains to use the same 21h timelock period before their batches are finalized. Only CTM can update the address that can submit state transitions to the rollup (that is, the validatorTimelock). | +| validatorTimelock.validator | By admin of ST | The admin of ST can choose who can submit new batches to the ValidatorTimelock. | +| priorityTx FeeParams | By admin of ST | The admin of a ZK chain can amend the priority transaction fee params. | +| transactionFilterer | By admin of ST | A chain may put an additional filter to the incoming L1->L2 transactions. This may be needed by a permissioned chain (e.g. a Validium bank-lile corporate chain). | +| DA validation / permanent rollup status | By admin of ST | A chain can decide which DA layer to use. You check out more about safe DA management here (FIXME: link to admin doc) | +| executing upgrades | By admin of ST | While exclusively CTM governance can set the content of the upgrade, STs will typically be able to choose suitable time for them to actually execute it. In the first release, STs will have to follow our upgrades. | +| settlement layer | By admin of ST | The admin of the chain can enact migrations to other settlement layers. | + +> Note, that if we take a look at the access control for the corresponding functions inside the [AdminFacet](../../l1-contracts/contracts/state-transition/chain-deps/facets/Admin.sol), the may see that a lot of methods from above that are marked as "By admin of ST" could be in theory amended by the ChainTypeManager. However, this sort of action requires approval from decentralized governance. Also, in case of an urgent high risk situation, the decentralized governance might force upgrade the contract via CTM. + +## Upgradability in the current release + +In the first release, each chain will be an instance of zkSync Era and so the upgrade process of each individual ST will be similar to that of zkSync Era. + +1. Firstly, the governance of the CTM will publish the server (including sequencer, prover, etc) that support the new version . This is done offchain. Enough time should be given to various zkStack devs to update their version. +2. The governance of the CTM will publish the upgrade onchain by atomatically executing the following three transactions: + +- `setChainCreationParams` ⇒ to ensure that new chains will be created with the version +- `setValidatorTimelock` (if needed) ⇒ to ensure that the new chains will use the new validator timelock right-away +- `setNewVersionUpgrade` ⇒ to save the upgrade information that each ST will need to follow to conduct the upgrade on their side. + +3. After that, each ChainAdmin can upgrade to the new version in suitable time for them. + +> Note, that while the governance does try to give the maximal possible time for chains to upgrade, the governance will typically put restrictions (aka deadlines) on the time by which the chain has to be upgraded. If the deadline is passed, the chain can not commit new batches until the upgrade is executed. + +### Emergency upgrade + +In case of an emergency, the [security council](https://blog.zknation.io/introducing-zk-nation/) has the ability to freeze the ecosystem and conduct an emergency upgrade (FIXME: link to governance doc). + +In case we are aware that some of the committed batches on an ST are dangerous to be executed, the CTM can call `revertBatches` on that ST. For faster reaction, the admin of the ChainTypeManager has the ability to do so without waiting for govenrnace approval that may take a lot of time. This action does not lead to funds being lost, so it is considered suitable for the partially trusted role of the admin of the ChainTypeManager. + +### Issues & caveats + +- If an ZK chain skips an upgrade (i.e. it has version X, it did not upgrade to `X + 1` and now the latest protocol version is `X + 2` there is no built-in way to upgrade). This team will require manual intervention from us to upgrade. +- The approach of calling `revertBatches` for malicious STs is not scalable (O(N) of the number of chains). The situation is very rare, so it is fine in the short term, but not in the long run. diff --git a/docs/chain_managment/overview.md b/docs/chain_managment/overview.md index 417fbfca8..e69de29bb 100644 --- a/docs/chain_managment/overview.md +++ b/docs/chain_managment/overview.md @@ -1,68 +0,0 @@ -## Chain Type Manager (CTM) - -> If someone is already familiar with the [previous version](https://github.com/code-423n4/2024-03-zksync) of zkSync architecture, this contract was previously known as "State Transition Manager (CTM)". - -Currently bridging between different zk rollups requires the funds to pass through L1. This is slow & expensive. - -The vision of seamless internet of value requires transfers of value to be *both* seamless and trustless. This means that for instance different STs need to share the same L1 liquidity, i.e. a transfer of funds should never touch L1 in the process. However, it requires some sort of trust between two chains. If a malicious (or broken) rollup becomes a part of the shared liquidity pool it can steal all the funds. - -However, can two instances of the same zk rollup trust each other? The answer is yes, because no new additions of rollups introduce new trust assumptions. Assuming there are no bugs in circuits, the system will work as intended. - -How can two rollups know that they are two different instances of the same system? We can create a factory of such contracts (and so we would know that each new rollup created by this instance is correct one). But just creating correct contracts is not enough. Ethereum changes, new bugs may be found in the original system & so an instance that does not keep itself up-to-date with the upgrades may exploit some bug from the past and jeopardize the entire system. Just deploying is not enough. We need to constantly make sure that all STs are up to date and maintain whatever other invariants are needed for these STs to trust each other. - -Let’s define as *Chain Type Manager* (CTM) **as a contract that is responsible for the following: - -- It serves as a factory to deploy STs (new ZK chains) -- It is responsible for ensuring that all the STs deployed by it are up-to-date. - -Note, that this means that STs have a “weaker” governance. I.e. governance can only do very limited number of things, such as setting the validator. ST admin can not set its own upgrades and it can only “execute” the upgrade that has already been prepared by the CTM. - -In the long term vision STs deployment will be permissionless, however CTM will always remain the main point of trust and will have to be explicitly whitelisted by the decentralized governance of the entire ecosystem before its ST can get the access to the shared liquidity. - -## Configurability in the first release - -For now, only one CTM will be supported — the one that deploys instances of zkSync Era, possibly using other DA layers. To read more about different DA layers, check out this document (FIXME link). - -The exact process of deploying & registering a ST will be described in [sections below](#creating-new-chains-with-bridgehub). Overall, each ST in the first release will have the following parameters: - -| ST parameter | Updatability | Comment | -| --- | --- | --- | -| chainId | Permanent | Permanent identifier of the ST. Due to wallet support reasons, for now chainId has to be small (48 bits). This is one of the reasons why for now we’ll deploy STs manually, to prevent STs from having the same chainId as some another popular chain. In the future it will be trustlessly assigned as a random 32-byte value.| -| baseTokenAssetId | Permanent | Each ST can have their own custom base token (i.e. token used for paying the fees). It is set once during creation and can never be changed. Note, that we refer to and "asset id" here instead of an L1 address. To read more about what is assetId and how it works check out the document for custom asset bridging (FIXME: link) | -| chainTypeManager | Permanent | The CTM that deployed the ST. In principle, it could be possible to migrate between CTMs (assuming both CTMs support that). However, in practice it may be very hard and as of now such functionality is not supported. | -| admin | By admin of ST | The admin of the ST. It has some limited powers to govern the chain. To read more about which powers are available to a chain admin and which precautions should be taken, check out this document (FIXME: link to document about admin precauotions) | -| validatorTimelock | CTM | For now, we want all the chains to use the same 21h timelock period before their batches are finalized. Only CTM can update the address that can submit state transitions to the rollup (that is, the validatorTimelock). | -| validatorTimelock.validator | By admin of ST | The admin of ST can choose who can submit new batches to the ValidatorTimelock. | -| priorityTx FeeParams | By admin of ST | The admin of a ZK chain can amend the priority transaction fee params. | -| transactionFilterer | By admin of ST | A chain may put an additional filter to the incoming L1->L2 transactions. This may be needed by a permissioned chain (e.g. a Validium bank-lile corporate chain). | -| DA validation / permanent rollup status | By admin of ST | A chain can decide which DA layer to use. You check out more about safe DA management here (FIXME: link to admin doc) | -| executing upgrades | By admin of ST | While exclusively CTM governance can set the content of the upgrade, STs will typically be able to choose suitable time for them to actually execute it. In the first release, STs will have to follow our upgrades. | -| settlement layer | By admin of ST | The admin of the chain can enact migrations to other settlement layers. | - -> Note, that if we take a look at the access control for the corresponding functions inside the [AdminFacet](../../l1-contracts/contracts/state-transition/chain-deps/facets/Admin.sol), the may see that a lot of methods from above that are marked as "By admin of ST" could be in theory amended by the ChainTypeManager. However, this sort of action requires approval from decentralized governance. Also, in case of an urgent high risk situation, the decentralized governance might force upgrade the contract via CTM. - -## Upgradability in the current release - -In the first release, each chain will be an instance of zkSync Era and so the upgrade process of each individual ST will be similar to that of zkSync Era. - -1. Firstly, the governance of the CTM will publish the server (including sequencer, prover, etc) that support the new version . This is done offchain. Enough time should be given to various zkStack devs to update their version. -2. The governance of the CTM will publish the upgrade onchain by atomatically executing the following three transactions: - -- `setChainCreationParams` ⇒ to ensure that new chains will be created with the version -- `setValidatorTimelock` (if needed) ⇒ to ensure that the new chains will use the new validator timelock right-away -- `setNewVersionUpgrade` ⇒ to save the upgrade information that each ST will need to follow to conduct the upgrade on their side. - -3. After that, each ChainAdmin can upgrade to the new version in suitable time for them. - -> Note, that while the governance does try to give the maximal possible time for chains to upgrade, the governance will typically put restrictions (aka deadlines) on the time by which the chain has to be upgraded. If the deadline is passed, the chain can not commit new batches until the upgrade is executed. - -### Emergency upgrade - -In case of an emergency, the [security council](https://blog.zknation.io/introducing-zk-nation/) has the ability to freeze the ecosystem and conduct an emergency upgrade (FIXME: link to governance doc). - -In case we are aware that some of the committed batches on an ST are dangerous to be executed, the CTM can call `revertBatches` on that ST. For faster reaction, the admin of the ChainTypeManager has the ability to do so without waiting for govenrnace approval that may take a lot of time. This action does not lead to funds being lost, so it is considered suitable for the partially trusted role of the admin of the ChainTypeManager. - -### Issues & caveats - -- If an ZK chain skips an upgrade (i.e. it has version X, it did not upgrade to `X + 1` and now the latest protocol version is `X + 2` there is no built-in way to upgrade). This team will require manual intervention from us to upgrade. -- The approach of calling `revertBatches` for malicious STs is not scalable (O(N) of the number of chains). The situation is very rare, so it is fine in the short term, but not in the long run. diff --git a/docs/chain_managment/upgrade_process.md b/docs/chain_managment/upgrade_process.md new file mode 100644 index 000000000..edc45d56b --- /dev/null +++ b/docs/chain_managment/upgrade_process.md @@ -0,0 +1,67 @@ +# TODO a mess currently +# Upgrade process document + + +## Intro + +Upgrading the ecosystem of ZKChains is a complicated process. ZKSync is a complex ecosystem with many chains and contracts and each upgrade is unique, but there are some steps that repeat for most upgrades. These are mostly how we interact with the CTM, the diamond facets, the L1→L2 upgrade, how we update the verification keys. + +Where each upgrade consists of two parameters: + +- Facet cuts - change of the internal implementation of the diamond proxy +- Diamond Initialization - delegate call to the specified address with specified data + +The second parameter is very powerful and flexible enough to move majority of upgrade logic there. However, until this day we had no ready or semi-finished template for the diamond initialization and now we are did the template for the upgrades with the most common and more likely needs. + +There are two contracts for this, + +1. [BaseZkSyncUpgrade](https://github.com/matter-labs/zksync-2-contracts/blob/sb-new-upgrade-system/ethereum/contracts/upgrades/BaseZkSyncUpgrade.sol) - Generic template with function that can be useful for upgrades +2. [DefaultUpgrade](https://github.com/matter-labs/zksync-2-contracts/blob/sb-new-upgrade-system/ethereum/contracts/upgrades/DefaultUpgrade.sol) - Default implementation of the [BaseZkSyncUpgrade](https://github.com/matter-labs/zksync-2-contracts/blob/sb-new-upgrade-system/ethereum/contracts/upgrades/BaseZkSyncUpgrade.sol), contract that is most often planned to be used as diamond intialization when doing upgrades. + +While usually every upgrade is different, a common part can be distinguished, that’s their job. + +### Protocol version + +For tracking upgrade versions on different networks (private testnet, public testnet, mainnet) we use protocol version, which is basically just a number denoting the deployed version. The protocol version is different from Diamond Cut `proposalId`, since `protocolId` only shows how much upgrade proposal was proposed/executed, but nothing about the content of upgrades, while the protocol version is needed to understand what version is deployed. + +In the [BaseZkSyncUpgrade](https://github.com/matter-labs/zksync-2-contracts/blob/sb-new-upgrade-system/ethereum/contracts/upgrades/BaseZkSyncUpgrade.sol) & [DefaultUpgrade](https://github.com/matter-labs/zksync-2-contracts/blob/sb-new-upgrade-system/ethereum/contracts/upgrades/DefaultUpgrade.sol) we allow to arbitrarily increase the proposal version while upgrading a system, but only increase it. We are doing that since we can skip some protocol versions if for example found a bug there (but it was deployed on another network already). + + + +# + +This upgrade tx: + +- force deploys and updates base system contracts +- updates base system contracts, bootloader, default AA + + + +## STM interactions + +- Context: all upgrade txs are sent via the Governance contract via a scheduleTransparent and execute operations. This can call any of our contracts, the Governance is the owner of all of them. +- Previously we called the DiamondProxy directly with the diamond cut. After v0.24.1 we call the STM which records the diamondCut hash in a mapping(protocolVersion ⇒ upgradeCutHash) . After this the chainAdmin can call the Admin facet of their chain with the same diamondCut data, and this executes the diamondCut ( the provided diamondCut is checked against the upgradeCutHash in the STM) + +## Contracts involved in the L1→L2 tx: + +### L1 + +- The L1→L2 upgrade tx is set via the DiamondCut via the DefaultUpgrade / BaseZkSyncUpgrade. The server picks the diamondCut up similarly to how it pick up the PQ transaction, and executes it. The upgrade tx is special, it has its own tx type, an L2→L1 system log is sent with the upgrade tx hash, and this L2→L1 log is compared in the Executor facet with the currently recorded upgrade tx hash when the batch is executed. If the hash is incorrect the upgrade fails. + +### L2 + +- ComplexUpgrader.sol + - This is the general L2 System Contract that can execute any upgrade by delegateCalling an implementation upgrade contract. This implementation can change for each upgrade, it might inherit the ForceDeployUpgrader.sol +- ForceDeployUpgrader.sol + - Is a standard L2 implementation. It is used to call the ContractDeployer to force deploy contracts. In itself it is not really useful ( as the FORCE_DEPLOYER address can also do this), but if a custom upgrade implementation inherits it then it is useful. +- ContractDeployer.sol + - The contract that deploys all contracts. It also supports ForceDeployments when called from the ComplexUpgrader or the FORCE_DEPLOYER address ( which is not the address of the ForceDeployUpgrader) . +- GenesisUpgrade (WIP for Gateway). This will be the upgrade used in the genesis upgrade to deploy the Bridgehub. ( we need to use it as the BH has a constructor). We will also use this in the future to deploy the custom base token contract. \ No newline at end of file diff --git a/docs/l2_system_contracts/handling_l1->l2_ops_on_zksync.md b/docs/l2_system_contracts/l2_processing_of_l1->l2_txs.md similarity index 100% rename from docs/l2_system_contracts/handling_l1->l2_ops_on_zksync.md rename to docs/l2_system_contracts/l2_processing_of_l1->l2_txs.md diff --git a/docs/l2_system_contracts/zksync_fee_modal.md b/docs/l2_system_contracts/zksync_fee_model.md similarity index 100% rename from docs/l2_system_contracts/zksync_fee_modal.md rename to docs/l2_system_contracts/zksync_fee_model.md diff --git a/docs/settlement_contracts/data_availability/custom-da.md b/docs/settlement_contracts/data_availability/custom_da.md similarity index 100% rename from docs/settlement_contracts/data_availability/custom-da.md rename to docs/settlement_contracts/data_availability/custom_da.md diff --git a/docs/settlement_contracts/data_availability/custom_da_support.md b/docs/settlement_contracts/data_availability/custom_da_support.md deleted file mode 100644 index 9c02e23fa..000000000 --- a/docs/settlement_contracts/data_availability/custom_da_support.md +++ /dev/null @@ -1,49 +0,0 @@ -# Custom DA support - -# Custom DA support - -## Intro - -We introduced modularity into our contracts to support multiple DA layers, easier support for Validium and Rollup mode, and to settlement via the Gateway. - -![CustomDA.png](./Custom_DA.png) - -### Background - -**Pubdata** - information published by the ZK Chain that can be used to reconstruct its state, it consists of l2→l1 logs, l2→l1 messages, contract bytecodes, and compressed state diffs. - -```solidity -struct PubdataInput { - pub(crate) user_logs: Vec, - pub(crate) l2_to_l1_messages: Vec>, - pub(crate) published_bytecodes: Vec>, - pub(crate) state_diffs: Vec, -} - -``` - -The current version of ZK Chains supports the following DataAvailability(DA) modes: - -- `Calldata` - uses Ethereum tx calldata as pubdata storage -- `Blobs` - uses Ethereum blobs calldata as pubdata storage -- `No DA Validium` - posting pubdata is not enforced - -The goal is to create a general purpose solution, that would ensure DA consistency and verifiability, on top of which we would build what is requested by many partners and covers many use cases like on-chain games and DEXes: **Validium with Abstract DA.** - -This means that a separate solution like AvailDA, EigenDA, Celestia, etc. would be used to store the pubdata. The idea is that every solution like that (`DA layer`) provides a proof of inclusion of our pubdata to their storage, and this proof can later be verified on Ethereum. This results in an approach that has more security guarantees than `No DA Validium`, but lower fees than `Blobs`(assuming that Ethereum usage grows and blobs become more expensive). - -## Proposed solution - -The proposed solution is to introduce an abstract 3rd party DA layer, that the sequencer would publish the data to. When the batch is sealed, the hashes of the data related to that batch will be made available on L1. Then, after the DA layer has confirmed that its state is synchronized, the sequencer calls a `commitBatches` function with the proofs required to verify the DA inclusion on L1. - -### Challenges - -On the protocol level, the complexity is in introducing two new components: L1 and L2 DA verifiers. They are required to ensure the verifiable delivery of the DA inclusion proofs to L1 and consequent verification of these proofs. - -The L2 verifier would validate the pubdata correctness and compute a final commitment for DA called `outputHash`. It consists of hashes of `L2→L1 logs and messages`, `bytecodes`, and `compressed state diffs`(blob hashes in case of blobs). This contract has to be deployed by the chain operator and it has to be tied to the DA layer logic, e.g. DA layer accepts 256kb blobs → on the final hash computation stage, the pubdata has to be packed into the chunks of <256kb, and a either the hashes of all blobs, or a rolling hash has to be be part of the `outputHash` preimage. - -The `outputHash` will be sent to L1 as a L2→L1 log, so this process is a part of a bootloader execution and can be trusted. - -The hashes of data chunks alongside the inclusion proofs have to be provided in the calldata of the L1 diamond proxy’s `commitBatches` function. - -L1 contracts have to recalculate the `outputHash` and make sure it matches the one from the logs, after which the abstract DA verification contract is called. In general terms, it would accept the set of chunk’s hashes (by chunk here I mean DA blob, not to be confused with 4844 blob) and a set of inclusion proofs, that should be enough to verify that the preimage (chunk data) is included in the DA layer. This verification would be done by specific contract e.g. `Attestation Bridge`, which holds the state tree information and can perform verification against it. \ No newline at end of file diff --git a/docs/settlement_contracts/data_availability/Rollup DA.md b/docs/settlement_contracts/data_availability/rollup_da.md similarity index 100% rename from docs/settlement_contracts/data_availability/Rollup DA.md rename to docs/settlement_contracts/data_availability/rollup_da.md diff --git a/docs/settlement_contracts/data_availability/Standard pubdata format.md b/docs/settlement_contracts/data_availability/standard_pubdata_format.md similarity index 100% rename from docs/settlement_contracts/data_availability/Standard pubdata format.md rename to docs/settlement_contracts/data_availability/standard_pubdata_format.md diff --git a/docs/settlement_contracts/priority_queue/priority-merkle-tree.md b/docs/settlement_contracts/priority_queue/priority-queue.md similarity index 100% rename from docs/settlement_contracts/priority_queue/priority-merkle-tree.md rename to docs/settlement_contracts/priority_queue/priority-queue.md diff --git a/docs/upgrade-history/gateway_upgrade/cab_todo_merge.md b/docs/upgrade-history/gateway_upgrade/cab_todo_merge.md new file mode 100644 index 000000000..2afd93744 --- /dev/null +++ b/docs/upgrade-history/gateway_upgrade/cab_todo_merge.md @@ -0,0 +1,44 @@ +## Known Issues + +### storage layout + +L2SharedBridge will be a system contract, L2NativeTokenVault will replace it (the storage layout is still not yet backwards compatible) + +### bridgehubDeposit API change + +> /// @notice Allows bridgehub to acquire mintValue for L1->L2 transactions. + + /// @dev If the corresponding L2 transaction fails, refunds are issued to a refund recipient on L2. + function bridgehubDepositBaseToken( + uint256 _chainId, + bytes32 _assetId, + +Note, that the new SB is not compatible with both: + +- old Mailbox on Era +- old Bridgehub +- And vice versa. + +We need to either: + +- ensure that all 3 get upgraded at the same time. Upgrading BH and SB at the same time is feasible IMHO. But upgrading DP (Mailbox) in the same transaction may not be. +- have a concrete plan for such case. E.g. explicitly tell that the legacy deposits will stop working. In this case we need to check (at the very least visually) that the worst thing that can happen is just deposits not working and not some funds lost +- Add the corresponding legacy functions + +### Not allowing legacy withdrawals + +> require(!\_isEraLegacyEthWithdrawal(\_chainId, \_l2BatchNumber), "ShB: legacy eth withdrawal"); + +No method to finalize an old withdrawal. +We will manually finalize all legacy withdrawals before the upgrade, i.e. withdrawals that happened before the previous Bridgehub upgrade. + +### Custom Errors not implemented + +> require(expectedDepositAmount == \_depositAmount, "3T"); // The token has non-standard transfer logic + +Custom errors will be introduced for all contracts. + +## Migration plan + +- Bulkheads will need to be migrated (methods added) +- Tokens will have to be transferred (methods added) diff --git a/docs/gateway/contracts-review-gateway.md b/docs/upgrade-history/gateway_upgrade/contracts-review-gateway.md similarity index 100% rename from docs/gateway/contracts-review-gateway.md rename to docs/upgrade-history/gateway_upgrade/contracts-review-gateway.md