update design docs & add Timelock contract

Author: bergjefferson

DeGate Protocol Specification Document.md

@@ -39,9 +39,8 @@ For more details, refer to [Circuit Design Document - Entire Merkle Tree](./Circ
 ## No Limitation On Deposit/Withdrawal
 All funds deposited by users are stored in the smart contract of Layer 1, which can neither be transferred by any account in DeGate nor locked by the smart contract itself. Users can request to withdraw their funds at any time and complete their withdrawal within a set period of time.
 
-## Certainty of Smart Contracts & Circuits 
-DeGate smart contracts and circuits do not include any code upgrade logic. Once Smart Contracts & Circuits are deployed, no one can update them.
-
+## Delayed Upgradable of Smart Contracts 
+In order to enhance product functionality and safety, products can evolve and improve sustainably, DeGate smart contracts deployment adopts a delayed upgradable scheme. In the scheme, the admin rights to upgrade the contract are jointly managed by the Timelock contract and HomeDAO multi-signature account. When an upgrade occurs, DeGate users have at least 45 days to review the upcoming transaction and take action to decide whether to continue using DeGate, thus ensuring the highest level of trustless.
 
 ## Asset Independence
 Users can withdraw their assets from Layer 1 through Exodus Mode in the event that DeGate stops operation for any reason or accident.

Smart Contract Design.md

@@ -70,7 +70,7 @@ The validaty of conditional transactions is enforced by both zk-SNARKs and the s
 
 A zk-SNARKs key pair is composed of a proving key and a verifying key. The proving key is used to generate proofs, while the verifying key is used for verifying proofs. Refer to "trusted setup" for more details about how these keys are generated.
 
-On the off-chain side, the operators generate the proof through the circuit and proving key; On the on-chain side, the smart contract selects the corresponding verifying key by zkBlock size to verify proof. Different zkBlock sizes correspond to different verifying keys, and the keys are hardcoded into the smart contracts, so once deployed they cannot be changed. One zk-SNARKs key pair is unique to one circuit, meaning that changing keys will result in changing circuits. To make DeGate fully trustless, no verifying keys are allowed to be updated.
+On the off-chain side, the operators generate the proof through the circuit and proving key; On the on-chain side, the smart contract selects the corresponding verifying key by zkBlock size to verify proof. Different zkBlock sizes correspond to different verifying keys, and the keys are hardcoded into the smart contracts. One zk-SNARKs key pair is unique to one circuit, meaning that changing keys will result in changing circuits. 
 
 
 Zk proofs are generated by operators, embedded inside zkBlock, then verified by smart contract using a hardcoded verifying key. To generate zero-knowledge proofs, DeGate takes Groth16 for zk-SNARKs, which is based on the ALT_BN128 curve.  There are several precompiled opcodes ( ecAdd/ecMul/ecPairing, added in EIP-196 and EIP-197) for this curve that make verification efficient.
@@ -156,6 +156,8 @@ When using DeGate, users may need to pay different fees depending on the operati
 
 For scenarios and fees，please refer to DeGate product documentation for details https://docs.degate.com/v/product_en/concepts/protocol-fees
 
+## Delayed Upgradable of Smart Contracts 
+In order to enhance product functionality and safety, products can evolve and improve sustainably, DeGate smart contracts deployment adopts a delayed upgradable scheme. In the scheme, the admin rights to upgrade the contract are jointly managed by the Timelock contract and HomeDAO multi-signature account. When an upgrade occurs, DeGate users have at least 45 days to review the upcoming transaction and take action to decide whether to continue using DeGate, thus ensuring the highest level of trustless.
 
 # Contract Implementation
 ## Overview
@@ -742,8 +744,7 @@ About gas cost for verification :
 ## About Trustless
 User doesn't have to make any trust assumptions when using the DeGate contract, as "trustless" is guaranteed by the following factors:
 
-- Contracts are immutable: DeGate does not use proxy mode, hence no change can be made after deployment.
-- Circuits are immutable: BlockVerifier contract does not allow verifying keys to be changed.
+- Contracts and circuits are upgradable with a delay. DeGate users have at least 45 days to review upcoming transactions and take action in advance. 
 - Forced withdrawal can be made by users to force the operator to process the withdrawal request, otherwise, the exchange will shift into Exodus Mode.
 - Users can rebuild the whole Asset Merkle Tree by crawling Calldata in blocks.
 - In Exodus Mode, users can submit merkle proof of Asset Merkle Tree to withdraw funds from Layer 1 directly.

packages/loopring_v3/contracts/thirdparty/timelock/SafeMath.sol

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity ^0.8.10;
+
+// From https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/math/Math.sol
+// Subject to the MIT license.
+
+/**
+ * @dev Wrappers over Solidity's arithmetic operations with added overflow
+ * checks.
+ *
+ * Arithmetic operations in Solidity wrap on overflow. This can easily result
+ * in bugs, because programmers usually assume that an overflow raises an
+ * error, which is the standard behavior in high level programming languages.
+ * `SafeMath` restores this intuition by reverting the transaction when an
+ * operation overflows.
+ *
+ * Using this library instead of the unchecked operations eliminates an entire
+ * class of bugs, so it's recommended to use it always.
+ */
+library SafeMath {
+    /**
+     * @dev Returns the addition of two unsigned integers, reverting on overflow.
+     *
+     * Counterpart to Solidity's `+` operator.
+     *
+     * Requirements:
+     * - Addition cannot overflow.
+     */
+    function add(uint256 a, uint256 b) internal pure returns (uint256) {
+        uint256 c;
+        unchecked { c = a + b; }
+        require(c >= a, "SafeMath: addition overflow");
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the addition of two unsigned integers, reverting with custom message on overflow.
+     *
+     * Counterpart to Solidity's `+` operator.
+     *
+     * Requirements:
+     * - Addition cannot overflow.
+     */
+    function add(uint256 a, uint256 b, string memory errorMessage) internal pure returns (uint256) {
+        uint256 c;
+        unchecked { c = a + b; }
+        require(c >= a, errorMessage);
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the subtraction of two unsigned integers, reverting on underflow (when the result is negative).
+     *
+     * Counterpart to Solidity's `-` operator.
+     *
+     * Requirements:
+     * - Subtraction cannot underflow.
+     */
+    function sub(uint256 a, uint256 b) internal pure returns (uint256) {
+        return sub(a, b, "SafeMath: subtraction underflow");
+    }
+
+    /**
+     * @dev Returns the subtraction of two unsigned integers, reverting with custom message on underflow (when the result is negative).
+     *
+     * Counterpart to Solidity's `-` operator.
+     *
+     * Requirements:
+     * - Subtraction cannot underflow.
+     */
+    function sub(uint256 a, uint256 b, string memory errorMessage) internal pure returns (uint256) {
+        require(b <= a, errorMessage);
+        uint256 c = a - b;
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the multiplication of two unsigned integers, reverting on overflow.
+     *
+     * Counterpart to Solidity's `*` operator.
+     *
+     * Requirements:
+     * - Multiplication cannot overflow.
+     */
+    function mul(uint256 a, uint256 b) internal pure returns (uint256) {
+        // Gas optimization: this is cheaper than requiring 'a' not being zero, but the
+        // benefit is lost if 'b' is also tested.
+        // See: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/522
+        if (a == 0) {
+            return 0;
+        }
+
+        uint256 c;
+        unchecked { c = a * b; }
+        require(c / a == b, "SafeMath: multiplication overflow");
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the multiplication of two unsigned integers, reverting on overflow.
+     *
+     * Counterpart to Solidity's `*` operator.
+     *
+     * Requirements:
+     * - Multiplication cannot overflow.
+     */
+    function mul(uint256 a, uint256 b, string memory errorMessage) internal pure returns (uint256) {
+        // Gas optimization: this is cheaper than requiring 'a' not being zero, but the
+        // benefit is lost if 'b' is also tested.
+        // See: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/522
+        if (a == 0) {
+            return 0;
+        }
+
+        uint256 c;
+        unchecked { c = a * b; }
+        require(c / a == b, errorMessage);
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the integer division of two unsigned integers.
+     * Reverts on division by zero. The result is rounded towards zero.
+     *
+     * Counterpart to Solidity's `/` operator. Note: this function uses a
+     * `revert` opcode (which leaves remaining gas untouched) while Solidity
+     * uses an invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
+     */
+    function div(uint256 a, uint256 b) internal pure returns (uint256) {
+        return div(a, b, "SafeMath: division by zero");
+    }
+
+    /**
+     * @dev Returns the integer division of two unsigned integers.
+     * Reverts with custom message on division by zero. The result is rounded towards zero.
+     *
+     * Counterpart to Solidity's `/` operator. Note: this function uses a
+     * `revert` opcode (which leaves remaining gas untouched) while Solidity
+     * uses an invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
+     */
+    function div(uint256 a, uint256 b, string memory errorMessage) internal pure returns (uint256) {
+        // Solidity only automatically asserts when dividing by 0
+        require(b > 0, errorMessage);
+        uint256 c = a / b;
+        // assert(a == b * c + a % b); // There is no case in which this doesn't hold
+
+        return c;
+    }
+
+    /**
+     * @dev Returns the remainder of dividing two unsigned integers. (unsigned integer modulo),
+     * Reverts when dividing by zero.
+     *
+     * Counterpart to Solidity's `%` operator. This function uses a `revert`
+     * opcode (which leaves remaining gas untouched) while Solidity uses an
+     * invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
+     */
+    function mod(uint256 a, uint256 b) internal pure returns (uint256) {
+        return mod(a, b, "SafeMath: modulo by zero");
+    }
+
+    /**
+     * @dev Returns the remainder of dividing two unsigned integers. (unsigned integer modulo),
+     * Reverts with custom message when dividing by zero.
+     *
+     * Counterpart to Solidity's `%` operator. This function uses a `revert`
+     * opcode (which leaves remaining gas untouched) while Solidity uses an
+     * invalid opcode to revert (consuming all remaining gas).
+     *
+     * Requirements:
+     * - The divisor cannot be zero.
+     */
+    function mod(uint256 a, uint256 b, string memory errorMessage) internal pure returns (uint256) {
+        require(b != 0, errorMessage);
+        return a % b;
+    }
+}

packages/loopring_v3/contracts/thirdparty/timelock/Timelock.sol

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// This code is taken from https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol
+
+pragma solidity ^0.8.10;
+
+import "./SafeMath.sol";
+
+contract Timelock {
+    using SafeMath for uint;
+
+    event NewAdmin(address indexed newAdmin);
+    event NewPendingAdmin(address indexed newPendingAdmin);
+    event NewDelay(uint indexed newDelay);
+    event CancelTransaction(bytes32 indexed txHash, address indexed target, uint value, string signature,  bytes data, uint eta);
+    event ExecuteTransaction(bytes32 indexed txHash, address indexed target, uint value, string signature,  bytes data, uint eta);
+    event QueueTransaction(bytes32 indexed txHash, address indexed target, uint value, string signature, bytes data, uint eta);
+
+    uint public constant GRACE_PERIOD = 7 days;
+    uint public constant MINIMUM_DELAY = 45 days;
+    uint public constant MAXIMUM_DELAY = 365 days;
+
+    address public admin;
+    address public pendingAdmin;
+    uint public delay;
+
+    mapping (bytes32 => bool) public queuedTransactions;
+
+
+    constructor(address admin_, uint delay_) public {
+        require(delay_ >= MINIMUM_DELAY, "Timelock::constructor: Delay must exceed minimum delay.");
+        require(delay_ <= MAXIMUM_DELAY, "Timelock::setDelay: Delay must not exceed maximum delay.");
+
+        admin = admin_;
+        delay = delay_;
+    }
+
+    fallback() external payable { }
+
+    function setDelay(uint delay_) public {
+        require(msg.sender == address(this), "Timelock::setDelay: Call must come from Timelock.");
+        require(delay_ >= MINIMUM_DELAY, "Timelock::setDelay: Delay must exceed minimum delay.");
+        require(delay_ <= MAXIMUM_DELAY, "Timelock::setDelay: Delay must not exceed maximum delay.");
+        delay = delay_;
+
+        emit NewDelay(delay);
+    }
+
+    function acceptAdmin() public {
+        require(msg.sender == pendingAdmin, "Timelock::acceptAdmin: Call must come from pendingAdmin.");
+        admin = msg.sender;
+        pendingAdmin = address(0);
+
+        emit NewAdmin(admin);
+    }
+
+    function setPendingAdmin(address pendingAdmin_) public {
+        require(msg.sender == address(this), "Timelock::setPendingAdmin: Call must come from Timelock.");
+        pendingAdmin = pendingAdmin_;
+
+        emit NewPendingAdmin(pendingAdmin);
+    }
+
+    function queueTransaction(address target, uint value, string memory signature, bytes memory data, uint eta) public returns (bytes32) {
+        require(msg.sender == admin, "Timelock::queueTransaction: Call must come from admin.");
+        require(eta >= getBlockTimestamp().add(delay), "Timelock::queueTransaction: Estimated execution block must satisfy delay.");
+
+        bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta));
+        queuedTransactions[txHash] = true;
+
+        emit QueueTransaction(txHash, target, value, signature, data, eta);
+        return txHash;
+    }
+
+    function cancelTransaction(address target, uint value, string memory signature, bytes memory data, uint eta) public {
+        require(msg.sender == admin, "Timelock::cancelTransaction: Call must come from admin.");
+
+        bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta));
+        queuedTransactions[txHash] = false;
+
+        emit CancelTransaction(txHash, target, value, signature, data, eta);
+    }
+
+    function executeTransaction(address target, uint value, string memory signature, bytes memory data, uint eta) public payable returns (bytes memory) {
+        require(msg.sender == admin, "Timelock::executeTransaction: Call must come from admin.");
+
+        bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta));
+        require(queuedTransactions[txHash], "Timelock::executeTransaction: Transaction hasn't been queued.");
+        require(getBlockTimestamp() >= eta, "Timelock::executeTransaction: Transaction hasn't surpassed time lock.");
+        require(getBlockTimestamp() <= eta.add(GRACE_PERIOD), "Timelock::executeTransaction: Transaction is stale.");
+
+        queuedTransactions[txHash] = false;
+
+        bytes memory callData;
+
+        if (bytes(signature).length == 0) {
+            callData = data;
+        } else {
+            callData = abi.encodePacked(bytes4(keccak256(bytes(signature))), data);
+        }
+
+        // solium-disable-next-line security/no-call-value
+        (bool success, bytes memory returnData) = target.call{value: value}(callData);
+        require(success, "Timelock::executeTransaction: Transaction execution reverted.");
+
+        emit ExecuteTransaction(txHash, target, value, signature, data, eta);
+
+        return returnData;
+    }
+
+    function getBlockTimestamp() internal view returns (uint) {
+        // solium-disable-next-line security/no-block-members
+        return block.timestamp;
+    }
+}