From 10ef4f91dbc65efa031cf2bb782dbe9b7892380c Mon Sep 17 00:00:00 2001 From: miladpiri <67259426+miladpiri@users.noreply.github.com> Date: Thu, 28 Sep 2023 17:12:27 +0200 Subject: [PATCH 1/3] Update Overview.md --- docs/Overview.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/Overview.md b/docs/Overview.md index b5c0afeb3..d8dc50798 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -82,6 +82,7 @@ The upgrade itself characterizes by three variables: Separate facet, whose only function is providing `view` and `pure` methods. It also implements [diamond loupe](https://eips.ethereum.org/EIPS/eip-2535#diamond-loupe) which makes managing facets easier. +This contract, similar to `DiamondCutFaucet` must never be frozen. #### GovernanceFacet @@ -238,6 +239,16 @@ investigation and mitigation before resuming normal operations. It is a temporary solution to prevent any significant impact of the validator hot key leakage, while the network is in the Alpha stage. +This contract consists of four main functions `commitBlocks`, `proveBlocks`, `executeBlocks`, and `revertBlocks`, that +can be called only by the validator. + +When the validator calls `commitBlocks`, the same calldata will be propogated to the zkSync contract (`DiamondProxy` through +`call` where it invokes the `ExecutorFacet` through `delegatecall`), and also a timestamp is assigned to these blocks to track +the time these blocks are commited by the validator to enforce a delay between committing and execution of blocks. Then, the +validator can prove the already commited blocks regardless of the mentioned timestamp, and again the same calldata (related +to the `proveBlocks` function) will be propogated to the zkSync contract. After, the `executionDelay` is elapsed, the validator +is allowed to call `executeBlocks` to propogate the same calldata to zkSync contract. + #### Allowlist The auxiliary contract controls the permission access list. It is used in bridges and diamond proxies to control which From 01c7016766db06b28305988d16a16fc353522e51 Mon Sep 17 00:00:00 2001 From: miladpiri <67259426+miladpiri@users.noreply.github.com> Date: Thu, 28 Sep 2023 18:10:51 +0200 Subject: [PATCH 2/3] Update Overview.md --- docs/Overview.md | 56 ++++++++++++++++++------------------------------ 1 file changed, 21 insertions(+), 35 deletions(-) diff --git a/docs/Overview.md b/docs/Overview.md index d8dc50798..f2f62e26e 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -44,9 +44,9 @@ even an upgrade system is a separate facet that can be replaced. One of the differences from the reference implementation is access freezability. Each of the facets has an associated parameter that indicates if it is possible to freeze access to the facet. Privileged actors can freeze the **diamond** -(not a specific facet!) and all facets with the marker `isFreezable` should be inaccessible until the governor unfreezes -the diamond. Note that it is a very dangerous thing since the diamond proxy can freeze the upgrade system and then the -diamond will be frozen forever. +(not a specific facet!) and all facets with the marker `isFreezable` should be inaccessible until the governor or its owner +unfreezes the diamond. Note that it is a very dangerous thing since the diamond proxy can freeze the upgrade system and then +the diamond will be frozen forever. #### DiamondInit @@ -56,42 +56,28 @@ diamond constructor and is not saved in the diamond as a facet. Implementation detail - function returns a magic value just like it is designed in [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271), but the magic value is 32 bytes in size. -#### DiamondCutFacet - -These smart contracts manage the freezing/unfreezing and upgrades of the diamond proxy. That being said, the contract -must never be frozen. - -Currently, freezing and unfreezing are implemented as access control functions. It is fully controlled by the governor -but can be changed later. The governor can call `freezeDiamond` to freeze the diamond and `unfreezeDiamond` to restore -it. - -Another purpose of `DiamondCutFacet` is to upgrade the facets. The upgrading is split into 2-3 phases: - -- `proposeTransparentUpgrade`/`proposeShadowUpgrade` - propose an upgrade with visible/hidden parameters. -- `cancelUpgradeProposal` - cancel the upgrade proposal. -- `securityCouncilUpgradeApprove` - approve the upgrade by the security council. -- `executeUpgrade` - finalize the upgrade. - -The upgrade itself characterizes by three variables: - -- `facetCuts` - a set of changes to the facets (adding new facets, removing facets, and replacing them). -- pair `(address _initAddress, bytes _calldata)` for initializing the upgrade by making a delegate call to - `_initAddress` with `_calldata` inputs. - #### GettersFacet Separate facet, whose only function is providing `view` and `pure` methods. It also implements [diamond loupe](https://eips.ethereum.org/EIPS/eip-2535#diamond-loupe) which makes managing facets easier. -This contract, similar to `DiamondCutFaucet` must never be frozen. +This contract must never be frozen. -#### GovernanceFacet +#### AdminFacet Controls changing the privileged addresses such as governor and validators or one of the system parameters (L2 -bootloader bytecode hash, verifier address, verifier parameters, etc). +bootloader bytecode hash, verifier address, verifier parameters, etc), and it also manages the freezing/unfreezing and execution of +upgrades in the diamond proxy. + +#### Governance + +This contract manages operations (calls with preconditions) for governance tasks. The contract allows for operations to be scheduled, +executed, and canceled with appropriate permissions and delays. It is used for managing and coordinating upgrades and changes in all +zkSync Era governed contracts. + +Operations can be proposed as either fully transparent upgrades with on-chain data, or "shadow" upgrades where upgrade data is not +published on-chain before execution. Proposed operations are subject to a delay before they can be executed, but they can be executed +instantly with the security council’s permission. -At the current stage, the governor has permission to instantly change the key system parameters with `GovernanceFacet`. -Later such functionality will be removed and changing system parameters will be possible only via Diamond upgrade (see -_DiamondCutFacet_). #### MailboxFacet @@ -239,15 +225,15 @@ investigation and mitigation before resuming normal operations. It is a temporary solution to prevent any significant impact of the validator hot key leakage, while the network is in the Alpha stage. -This contract consists of four main functions `commitBlocks`, `proveBlocks`, `executeBlocks`, and `revertBlocks`, that +This contract consists of four main functions `commitBatches`, `proveBatches`, `executeBatches`, and `revertBatches`, that can be called only by the validator. -When the validator calls `commitBlocks`, the same calldata will be propogated to the zkSync contract (`DiamondProxy` through +When the validator calls `commitBatches`, the same calldata will be propogated to the zkSync contract (`DiamondProxy` through `call` where it invokes the `ExecutorFacet` through `delegatecall`), and also a timestamp is assigned to these blocks to track the time these blocks are commited by the validator to enforce a delay between committing and execution of blocks. Then, the validator can prove the already commited blocks regardless of the mentioned timestamp, and again the same calldata (related -to the `proveBlocks` function) will be propogated to the zkSync contract. After, the `executionDelay` is elapsed, the validator -is allowed to call `executeBlocks` to propogate the same calldata to zkSync contract. +to the `proveBatches` function) will be propogated to the zkSync contract. After, the `delay` is elapsed, the validator +is allowed to call `executeBatches` to propogate the same calldata to zkSync contract. #### Allowlist From b93adb28db4d6a88f9179506236d339e16282791 Mon Sep 17 00:00:00 2001 From: miladpiri <67259426+miladpiri@users.noreply.github.com> Date: Thu, 28 Sep 2023 18:30:07 +0200 Subject: [PATCH 3/3] Update Overview.md --- docs/Overview.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/Overview.md b/docs/Overview.md index f2f62e26e..a294b47a2 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -74,9 +74,14 @@ This contract manages operations (calls with preconditions) for governance tasks executed, and canceled with appropriate permissions and delays. It is used for managing and coordinating upgrades and changes in all zkSync Era governed contracts. -Operations can be proposed as either fully transparent upgrades with on-chain data, or "shadow" upgrades where upgrade data is not -published on-chain before execution. Proposed operations are subject to a delay before they can be executed, but they can be executed -instantly with the security council’s permission. +Each upgrade consists of two steps: + +- Upgrade Proposal - The governor can schedule upgrades in two different manners: + - Fully transparent data. All implementation contracts and migration contracts are known to the community. The governor must wait +for the timelock to execute the upgrade. + - Shadow upgrade. The governor only shows the commitment for the upgrade. The upgrade can be executed only with security council +approval without timelock. +- Upgrade execution - perform the upgrade that was proposed. #### MailboxFacet @@ -229,9 +234,9 @@ This contract consists of four main functions `commitBatches`, `proveBatches`, ` can be called only by the validator. When the validator calls `commitBatches`, the same calldata will be propogated to the zkSync contract (`DiamondProxy` through -`call` where it invokes the `ExecutorFacet` through `delegatecall`), and also a timestamp is assigned to these blocks to track -the time these blocks are commited by the validator to enforce a delay between committing and execution of blocks. Then, the -validator can prove the already commited blocks regardless of the mentioned timestamp, and again the same calldata (related +`call` where it invokes the `ExecutorFacet` through `delegatecall`), and also a timestamp is assigned to these batches to track +the time these batches are commited by the validator to enforce a delay between committing and execution of batches. Then, the +validator can prove the already commited batches regardless of the mentioned timestamp, and again the same calldata (related to the `proveBatches` function) will be propogated to the zkSync contract. After, the `delay` is elapsed, the validator is allowed to call `executeBatches` to propogate the same calldata to zkSync contract.