Implement governance mechanism with timelock and security council

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,41 +56,33 @@ 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 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.
+
+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.
 
-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
 
@@ -238,6 +230,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 `commitBatches`, `proveBatches`, `executeBatches`, and `revertBatches`, that
+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 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.
+
 #### Allowlist
 
 The auxiliary contract controls the permission access list. It is used in bridges and diamond proxies to control which

ethereum/contracts/dev-contracts/test/GovernanceFacetTest.sol → ethereum/contracts/dev-contracts/test/AdminFacetTest.sol

@@ -2,9 +2,9 @@
 
 pragma solidity ^0.8.13;
 
-import "../../zksync/facets/Governance.sol";
+import "../../zksync/facets/Admin.sol";
 
-contract GovernanceFacetTest is GovernanceFacet {
+contract AdminFacetTest is AdminFacet {
     constructor() {
         s.governor = msg.sender;
     }

ethereum/contracts/governance/Governance.sol

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.13;
+
+import {Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+import {Address} from "@openzeppelin/contracts/utils/Address.sol";
+import {IGovernance} from "./IGovernance.sol";
+
+/// @author Matter Labs
+/// @custom:security-contact [email protected]
+/// @dev Contract design is inspired by OpenZeppelin TimelockController and in-house Diamond Proxy upgrade mechanism.
+/// @notice 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.
+contract Governance is IGovernance, Ownable2Step {
+    /// @notice A constant representing the timestamp for completed operations.
+    uint256 internal constant EXECUTED_PROPOSAL_TIMESTAMP = uint256(1);
+
+    /// @notice The address of the security council.
+    /// @dev It is supposed to be multisig contract.
+    address public securityCouncil;
+
+    /// @notice A mapping to store timestamps where each operation will be ready for execution.
+    /// @dev - 0 means the operation is not created.
+    /// @dev - 1 (EXECUTED_PROPOSAL_TIMESTAMP) means the operation is already executed.
+    /// @dev - any other value means timestamp in seconds when the operation will be ready for execution.
+    mapping(bytes32 => uint256) public timestamps;
+
+    /// @notice The minimum delay in seconds for operations to be ready for execution.
+    uint256 public minDelay;
+
+    /// @notice Initializes the contract with the admin address, security council address, and minimum delay.
+    /// @param _admin The address to be assigned as the admin of the contract.
+    /// @param _securityCouncil The address to be assigned as the security council of the contract.
+    /// @param _minDelay The initial minimum delay (in seconds) to be set for operations.
+    constructor(address _admin, address _securityCouncil, uint256 _minDelay) {
+        require(_admin != address(0), "Admin should be non zero address");
+
+        _transferOwnership(_admin);
+
+        securityCouncil = _securityCouncil;
+        emit ChangeSecurityCouncil(address(0), _securityCouncil);
+
+        minDelay = _minDelay;
+        emit ChangeMinDelay(0, _minDelay);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            MODIFIERS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Checks that the message sender is contract itself.
+    modifier onlySelf() {
+        require(msg.sender == address(this), "Only governance contract itself allowed to call this function");
+        _;
+    }
+
+    /// @notice Checks that the message sender is an active security council.
+    modifier onlySecurityCouncil() {
+        require(msg.sender == securityCouncil, "Only security council allowed to call this function");
+        _;
+    }
+
+    /// @notice Checks that the message sender is an active owner or an active security council.
+    modifier onlyOwnerOrSecurityCouncil() {
+        require(
+            msg.sender == owner() || msg.sender == securityCouncil,
+            "Only the owner and security council are allowed to call this function"
+        );
+        _;
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            OPERATION GETTERS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Returns whether an id corresponds to a registered operation. This
+    /// includes both Waiting, Ready, and Done operations.
+    function isOperation(bytes32 _id) public view returns (bool) {
+        return getOperationState(_id) != OperationState.Unset;
+    }
+
+    /// @dev Returns whether an operation is pending or not. Note that a "pending" operation may also be "ready".
+    function isOperationPending(bytes32 _id) public view returns (bool) {
+        OperationState state = getOperationState(_id);
+        return state == OperationState.Waiting || state == OperationState.Ready;
+    }
+
+    /// @dev Returns whether an operation is ready for execution. Note that a "ready" operation is also "pending".
+    function isOperationReady(bytes32 _id) public view returns (bool) {
+        return getOperationState(_id) == OperationState.Ready;
+    }
+
+    /// @dev Returns whether an operation is done or not.
+    function isOperationDone(bytes32 _id) public view returns (bool) {
+        return getOperationState(_id) == OperationState.Done;
+    }
+
+    /// @dev Returns operation state.
+    function getOperationState(bytes32 _id) public view returns (OperationState) {
+        uint256 timestamp = timestamps[_id];
+        if (timestamp == 0) {
+            return OperationState.Unset;
+        } else if (timestamp == EXECUTED_PROPOSAL_TIMESTAMP) {
+            return OperationState.Done;
+        } else if (timestamp > block.timestamp) {
+            return OperationState.Waiting;
+        } else {
+            return OperationState.Ready;
+        }
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            SCHEDULING CALLS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Propose a fully transparent upgrade, providing upgrade data on-chain.
+    /// @notice The owner will be able to execute the proposal either:
+    /// - With a `delay` timelock on its own.
+    /// - With security council instantly.
+    /// @dev Only the current owner can propose an upgrade.
+    /// @param _operation The operation parameters will be executed with the upgrade.
+    /// @param _delay The delay time (in seconds) after which the proposed upgrade can be executed by the owner.
+    function scheduleTransparent(Operation calldata _operation, uint256 _delay) external onlyOwner {
+        bytes32 id = hashOperation(_operation);
+        _schedule(id, _delay);
+        emit TransparentOperationScheduled(id, _delay, _operation);
+    }
+
+    /// @notice Propose "shadow" upgrade, upgrade data is not publishing on-chain.
+    /// @notice The owner will be able to execute the proposal either:
+    /// - With a `delay` timelock on its own.
+    /// - With security council instantly.
+    /// @dev Only the current owner can propose an upgrade.
+    /// @param _id The operation hash (see `hashOperation` function)
+    /// @param _delay The delay time (in seconds) after which the proposed upgrade may be executed by the owner.
+    function scheduleShadow(bytes32 _id, uint256 _delay) external onlyOwner {
+        _schedule(_id, _delay);
+        emit ShadowOperationScheduled(_id, _delay);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            CANCELING CALLS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Cancel the scheduled operation.
+    /// @dev Both the owner and security council may cancel an operation.
+    /// @param _id Proposal id value (see `hashOperation`)
+    function cancel(bytes32 _id) external onlyOwnerOrSecurityCouncil {
+        require(isOperationPending(_id));
+        delete timestamps[_id];
+        emit OperationCancelled(_id);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            EXECUTING CALLS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Executes the scheduled operation after the delay passed.
+    /// @dev Both the owner and security council may execute delayed operations.
+    /// @param _operation The operation parameters will be executed with the upgrade.
+    function execute(Operation calldata _operation) external onlyOwnerOrSecurityCouncil {
+        bytes32 id = hashOperation(_operation);
+        // Check if the predecessor operation is completed.
+        _checkPredecessorDone(_operation.predecessor);
+        // Ensure that the operation is ready to proceed.
+        require(isOperationReady(id), "Operation must be ready before execution");
+        // Execute operation.
+        _execute(_operation.calls);
+        // Reconfirming that the operation is still ready after execution.
+        // This is needed to avoid unexpected reentrancy attacks of re-executing the same operation.
+        require(isOperationReady(id), "Operation must be ready after execution");
+        // Set operation to be done
+        timestamps[id] = EXECUTED_PROPOSAL_TIMESTAMP;
+        emit OperationExecuted(id);
+    }
+
+    /// @notice Executes the scheduled operation with the security council instantly.
+    /// @dev Only the security council may execute an operation instantly.
+    /// @param _operation The operation parameters will be executed with the upgrade.
+    function executeInstant(Operation calldata _operation) external onlySecurityCouncil {
+        bytes32 id = hashOperation(_operation);
+        // Check if the predecessor operation is completed.
+        _checkPredecessorDone(_operation.predecessor);
+        // Ensure that the operation is in a pending state before proceeding.
+        require(isOperationPending(id), "Operation must be pending before execution");
+        // Execute operation.
+        _execute(_operation.calls);
+        // Reconfirming that the operation is still pending before execution.
+        // This is needed to avoid unexpected reentrancy attacks of re-executing the same operation.
+        require(isOperationPending(id), "Operation must be pending after execution");
+        // Set operation to be done
+        timestamps[id] = EXECUTED_PROPOSAL_TIMESTAMP;
+        emit OperationExecuted(id);
+    }
+
+    /// @dev Returns the identifier of an operation.
+    /// @param _operation The operation object to compute the identifier for.
+    function hashOperation(Operation calldata _operation) public pure returns (bytes32) {
+        return keccak256(abi.encode(_operation));
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            HELPERS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Schedule an operation that is to become valid after a given delay.
+    /// @param _id The operation hash (see `hashOperation` function)
+    /// @param _delay The delay time (in seconds) after which the proposed upgrade can be executed by the owner.
+    function _schedule(bytes32 _id, uint256 _delay) internal {
+        require(!isOperation(_id), "Operation with this proposal id already exists");
+        require(_delay >= minDelay, "Proposed delay is less than minimum delay");
+
+        timestamps[_id] = block.timestamp + _delay;
+    }
+
+    /// @dev Execute an operation's calls.
+    /// @param _calls The array of calls to be executed.
+    function _execute(Call[] calldata _calls) internal {
+        for (uint256 i = 0; i < _calls.length; ++i) {
+            (bool success, bytes memory returnData) = _calls[i].target.call{value: _calls[i].value}(_calls[i].data);
+            if (!success) {
+                // Propage an error if the call fails.
+                assembly {
+                    revert(add(returnData, 0x20), mload(returnData))
+                }
+            }
+        }
+    }
+
+    /// @notice Verifies if the predecessor operation is completed.
+    /// @param _predecessorId The hash of the operation that should be completed.
+    /// @dev Doesn't check the operation to be complete if the input is zero.
+    function _checkPredecessorDone(bytes32 _predecessorId) internal view {
+        require(_predecessorId == bytes32(0) || isOperationDone(_predecessorId), "Predecessor operation not completed");
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            SELF UPGRADES
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Changes the minimum timelock duration for future operations.
+    /// @param _newDelay The new minimum delay time (in seconds) for future operations.
+    function updateDelay(uint256 _newDelay) external onlySelf {
+        emit ChangeMinDelay(minDelay, _newDelay);
+        minDelay = _newDelay;
+    }
+
+    /// @dev Updates the address of the security council.
+    /// @param _newSecurityCouncil The address of the new security council.
+    function updateSecurityCouncil(address _newSecurityCouncil) external onlySelf {
+        emit ChangeSecurityCouncil(securityCouncil, _newSecurityCouncil);
+        securityCouncil = _newSecurityCouncil;
+    }
+
+    /// @dev Contract might receive/hold ETH as part of the maintenance process.
+    receive() external payable {}
+}