@bloxchain/contracts 1.0.0-alpha

package/contracts/core/security/SecureOwnable.sol

@@ -0,0 +1,419 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.33;
+
+// Contracts imports
+import "../base/BaseStateMachine.sol";
+import "./lib/definitions/SecureOwnableDefinitions.sol";
+import "../../interfaces/IDefinition.sol";
+import "../../utils/SharedValidation.sol";
+import "./interface/ISecureOwnable.sol";
+
+/**
+ * @title SecureOwnable
+ * @dev Security-focused contract extending BaseStateMachine with ownership management
+ *
+ * SecureOwnable provides security-specific functionality built on top of the base state machine:
+ * - Multi-role security model with Owner, Broadcaster, and Recovery roles
+ * - Secure ownership transfer with time-locked operations
+ * - Broadcaster and recovery address management
+ * - Time-lock period configuration
+ *
+ * The contract implements four primary secure operation types:
+ * 1. OWNERSHIP_TRANSFER - For securely transferring contract ownership
+ * 2. BROADCASTER_UPDATE - For changing the broadcaster address
+ * 3. RECOVERY_UPDATE - For updating the recovery address
+ * 4. TIMELOCK_UPDATE - For modifying the time lock period
+ *
+ * Each operation follows a request -> approval workflow with appropriate time locks
+ * and authorization checks. Operations can be cancelled within specific time windows.
+ *
+ * This contract focuses purely on security logic while leveraging the BaseStateMachine
+ * for transaction management, meta-transactions, and state machine operations.
+ */
+abstract contract SecureOwnable is BaseStateMachine, ISecureOwnable {
+    using SharedValidation for *;
+
+
+    // Request flags
+    bool private _hasOpenOwnershipRequest;
+    bool private _hasOpenBroadcasterRequest;
+
+    event OwnershipTransferRequest(address currentOwner, address newOwner);
+    event OwnershipTransferCancelled(uint256 txId);
+    event OwnershipTransferUpdated(address oldOwner, address newOwner);
+    event BroadcasterUpdateRequest(address currentBroadcaster, address newBroadcaster);
+    event BroadcasterUpdateCancelled(uint256 txId);
+    event BroadcasterUpdated(address oldBroadcaster, address newBroadcaster);
+    event RecoveryAddressUpdated(address oldRecovery, address newRecovery);
+    event TimeLockPeriodUpdated(uint256 oldPeriod, uint256 newPeriod);
+
+
+    /**
+     * @notice Initializer to initialize SecureOwnable state
+     * @param initialOwner The initial owner address
+     * @param broadcaster The broadcaster address
+     * @param recovery The recovery address
+     * @param timeLockPeriodSec The timelock period in seconds
+     * @param eventForwarder The event forwarder address 
+     */
+    function initialize(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,    
+        address eventForwarder
+    ) public virtual onlyInitializing {
+        // Initialize base state machine (only if not already initialized)
+        if (!_secureState.initialized) {
+            _initializeBaseStateMachine(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        }
+        
+        // Load SecureOwnable-specific definitions
+        IDefinition.RolePermission memory secureOwnablePermissions = SecureOwnableDefinitions.getRolePermissions();
+        _loadDefinitions(
+            SecureOwnableDefinitions.getFunctionSchemas(),
+            secureOwnablePermissions.roleHashes,
+            secureOwnablePermissions.functionPermissions
+        );
+    }
+
+    // ============ INTERFACE SUPPORT ============
+
+    /**
+     * @dev See {IERC165-supportsInterface}.
+     * @notice Adds ISecureOwnable interface ID for component detection
+     */
+    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+        return interfaceId == type(ISecureOwnable).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    // Ownership Management
+    /**
+     * @dev Requests a transfer of ownership
+     * @return The transaction record
+     */
+    function transferOwnershipRequest() public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateRecovery(getRecovery());
+        if (_hasOpenOwnershipRequest) revert SharedValidation.ResourceAlreadyExists(bytes32(uint256(0)));
+        
+        EngineBlox.TxRecord memory txRecord = _requestTransaction(
+            msg.sender,
+            address(this),
+            0, // value
+            0, // no gas limit
+            SecureOwnableDefinitions.OWNERSHIP_TRANSFER,
+            SecureOwnableDefinitions.TRANSFER_OWNERSHIP_SELECTOR,
+            abi.encode(getRecovery())
+        );
+
+        _hasOpenOwnershipRequest = true;
+        emit OwnershipTransferRequest(owner(), getRecovery());
+        return txRecord;
+    }
+
+    /**
+     * @dev Approves a pending ownership transfer transaction after the release time
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function transferOwnershipDelayedApproval(uint256 txId) public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateOwnerOrRecovery(owner(), getRecovery());
+        
+        EngineBlox.TxRecord memory updatedRecord = _approveTransaction(txId);
+        _hasOpenOwnershipRequest = false;
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Approves a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        EngineBlox.TxRecord memory updatedRecord = _approveTransactionWithMetaTx(metaTx);
+        _hasOpenOwnershipRequest = false;
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function transferOwnershipCancellation(uint256 txId) public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateRecovery(getRecovery());
+        EngineBlox.TxRecord memory updatedRecord = _cancelTransaction(txId);
+        _hasOpenOwnershipRequest = false;
+        emit OwnershipTransferCancelled(txId);
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        EngineBlox.TxRecord memory updatedRecord = _cancelTransactionWithMetaTx(metaTx);
+        _hasOpenOwnershipRequest = false;
+        emit OwnershipTransferCancelled(updatedRecord.txId);
+        return updatedRecord;
+    }
+
+    // Broadcaster Management
+    /**
+     * @dev Updates the broadcaster address
+     * @param newBroadcaster The new broadcaster address
+     * @return The execution options
+     */
+    function updateBroadcasterRequest(address newBroadcaster) public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateOwner(owner());
+        if (_hasOpenBroadcasterRequest) revert SharedValidation.ResourceAlreadyExists(bytes32(uint256(0)));
+        address[] memory broadcasters = getBroadcasters();
+        address currentBroadcaster = broadcasters.length > 0 ? broadcasters[0] : address(0);
+        SharedValidation.validateAddressUpdate(newBroadcaster, currentBroadcaster);
+        
+        EngineBlox.TxRecord memory txRecord = _requestTransaction(
+            msg.sender,
+            address(this),
+            0, // value
+            0, // gas limit
+            SecureOwnableDefinitions.BROADCASTER_UPDATE,
+            SecureOwnableDefinitions.UPDATE_BROADCASTER_SELECTOR,
+            abi.encode(newBroadcaster)
+        );
+
+        _hasOpenBroadcasterRequest = true;
+        emit BroadcasterUpdateRequest(currentBroadcaster, newBroadcaster);
+        return txRecord;
+    }
+
+    /**
+     * @dev Approves a pending broadcaster update transaction after the release time
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function updateBroadcasterDelayedApproval(uint256 txId) public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateOwner(owner());
+        EngineBlox.TxRecord memory updatedRecord = _approveTransaction(txId);
+        _hasOpenBroadcasterRequest = false;
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Approves a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        EngineBlox.TxRecord memory updatedRecord = _approveTransactionWithMetaTx(metaTx);
+        _hasOpenBroadcasterRequest = false;
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function updateBroadcasterCancellation(uint256 txId) public returns (EngineBlox.TxRecord memory) {
+        SharedValidation.validateOwner(owner());
+        EngineBlox.TxRecord memory updatedRecord = _cancelTransaction(txId);
+        _hasOpenBroadcasterRequest = false;
+        emit BroadcasterUpdateCancelled(txId);
+        return updatedRecord;
+    }
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        EngineBlox.TxRecord memory updatedRecord = _cancelTransactionWithMetaTx(metaTx);
+        _hasOpenBroadcasterRequest = false;
+        emit BroadcasterUpdateCancelled(updatedRecord.txId);
+        return updatedRecord;
+    }
+
+    // Recovery Management
+    /**
+     * @dev Creates execution params for updating the recovery address
+     * @param newRecoveryAddress The new recovery address
+     * @return The execution params
+     */
+    function updateRecoveryExecutionParams(
+        address newRecoveryAddress
+    ) public view returns (bytes memory) {
+        SharedValidation.validateAddressUpdate(newRecoveryAddress, getRecovery());
+        return abi.encode(newRecoveryAddress);
+    }
+
+    /**
+     * @dev Requests and approves a recovery address update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     */
+    function updateRecoveryRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        return _requestAndApproveTransaction(metaTx);
+    }
+
+    // TimeLock Management
+    /**
+     * @dev Creates execution params for updating the time lock period
+     * @param newTimeLockPeriodSec The new time lock period in seconds
+     * @return The execution params
+     */
+    function updateTimeLockExecutionParams(
+        uint256 newTimeLockPeriodSec
+    ) public view returns (bytes memory) {
+        SharedValidation.validateTimeLockUpdate(newTimeLockPeriodSec, getTimeLockPeriodSec());
+        return abi.encode(newTimeLockPeriodSec);
+    }
+
+    /**
+     * @dev Requests and approves a time lock period update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     */
+    function updateTimeLockRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) public returns (EngineBlox.TxRecord memory) {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+        
+        return _requestAndApproveTransaction(metaTx);
+    }
+
+    // Execution Functions
+    /**
+     * @dev External function that can only be called by the contract itself to execute ownership transfer
+     * @param newOwner The new owner address
+     */
+    function executeTransferOwnership(address newOwner) external {
+        SharedValidation.validateInternalCall(address(this));
+        _transferOwnership(newOwner);
+    }
+
+    /**
+     * @dev External function that can only be called by the contract itself to execute broadcaster update
+     * @param newBroadcaster The new broadcaster address
+     */
+    function executeBroadcasterUpdate(address newBroadcaster) external {
+        SharedValidation.validateInternalCall(address(this));
+        _updateBroadcaster(newBroadcaster, 0);
+    }
+
+    /**
+     * @dev External function that can only be called by the contract itself to execute recovery update
+     * @param newRecoveryAddress The new recovery address
+     */
+    function executeRecoveryUpdate(address newRecoveryAddress) external {
+        SharedValidation.validateInternalCall(address(this));
+        _updateRecoveryAddress(newRecoveryAddress);
+    }
+
+    /**
+     * @dev External function that can only be called by the contract itself to execute timelock update
+     * @param newTimeLockPeriodSec The new timelock period in seconds
+     */
+    function executeTimeLockUpdate(uint256 newTimeLockPeriodSec) external {
+        SharedValidation.validateInternalCall(address(this));
+        _updateTimeLockPeriod(newTimeLockPeriodSec);
+    }
+
+    // ============ INTERNAL FUNCTIONS ============
+
+    /**
+     * @dev Transfers ownership of the contract
+     * @param newOwner The new owner of the contract
+     */
+    function _transferOwnership(address newOwner) internal virtual {
+        address oldOwner = owner();
+        _updateAssignedWallet(EngineBlox.OWNER_ROLE, newOwner, oldOwner);
+        emit OwnershipTransferUpdated(oldOwner, newOwner);
+    }
+
+    /**
+     * @dev Updates the broadcaster role at a specific index (location)
+     * @param newBroadcaster The new broadcaster address (zero address to revoke)
+     * @param location The index in the broadcaster role's authorized wallets set
+     *
+     * Logic:
+     * - If a broadcaster exists at `location` and `newBroadcaster` is non-zero,
+     *   update that slot from old to new (role remains full).
+     * - If no broadcaster exists at `location` and `newBroadcaster` is non-zero,
+     *   assign `newBroadcaster` to the broadcaster role (respecting maxWallets).
+     * - If `newBroadcaster` is the zero address and a broadcaster exists at `location`,
+     *   revoke that broadcaster from the role.
+     */
+    function _updateBroadcaster(address newBroadcaster, uint256 location) internal virtual {
+        EngineBlox.Role storage role = _getSecureState().roles[EngineBlox.BROADCASTER_ROLE];
+
+        address oldBroadcaster;
+        uint256 length = role.walletCount;
+
+        if (location < length) {
+            oldBroadcaster = _getAuthorizedWalletAt(EngineBlox.BROADCASTER_ROLE, location);
+        } else {
+            oldBroadcaster = address(0);
+        }
+
+        // Case 1: Revoke existing broadcaster at location
+        if (newBroadcaster == address(0)) {
+            if (oldBroadcaster != address(0)) {
+                _revokeWallet(EngineBlox.BROADCASTER_ROLE, oldBroadcaster);
+                emit BroadcasterUpdated(oldBroadcaster, address(0));
+            }
+            return;
+        }
+
+        // Case 2: Update existing broadcaster at location
+        if (oldBroadcaster != address(0)) {
+            _updateAssignedWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster, oldBroadcaster);
+            emit BroadcasterUpdated(oldBroadcaster, newBroadcaster);
+            return;
+        }
+
+        // Case 3: No broadcaster at location, assign a new one (will respect maxWallets)
+        _assignWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster);
+        emit BroadcasterUpdated(address(0), newBroadcaster);
+    }
+
+    /**
+     * @dev Updates the recovery address
+     * @param newRecoveryAddress The new recovery address
+     */
+    function _updateRecoveryAddress(address newRecoveryAddress) internal virtual {
+        address oldRecovery = getRecovery();
+        _updateAssignedWallet(EngineBlox.RECOVERY_ROLE, newRecoveryAddress, oldRecovery);
+        emit RecoveryAddressUpdated(oldRecovery, newRecoveryAddress);
+    }
+
+    /**
+     * @dev Updates the time lock period
+     * @param newTimeLockPeriodSec The new time lock period in seconds
+     */
+    function _updateTimeLockPeriod(uint256 newTimeLockPeriodSec) internal virtual override {
+        uint256 oldPeriod = getTimeLockPeriodSec();
+        super._updateTimeLockPeriod(newTimeLockPeriodSec);
+        emit TimeLockPeriodUpdated(oldPeriod, newTimeLockPeriodSec);
+    }
+}

package/contracts/core/security/interface/ISecureOwnable.sol

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.33;
+
+// Contracts imports
+import "../../lib/EngineBlox.sol";
+
+/**
+ * @title ISecureOwnable
+ * @dev Interface for SecureOwnable functionality
+ * @notice This interface defines SecureOwnable-specific operations
+ * @notice Note: owner(), getBroadcasters(), and getRecovery() are available through BaseStateMachine
+ */
+interface ISecureOwnable {
+    // ============ OWNERSHIP MANAGEMENT ============
+
+    /**
+     * @dev Requests a transfer of ownership
+     * @return The transaction record
+     */
+    function transferOwnershipRequest() external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Approves a pending ownership transfer transaction after the release time
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function transferOwnershipDelayedApproval(uint256 txId) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Approves a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function transferOwnershipCancellation(uint256 txId) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+
+    // ============ BROADCASTER MANAGEMENT ============
+
+    /**
+     * @dev Updates the broadcaster address
+     * @param newBroadcaster The new broadcaster address
+     * @return The transaction record
+     */
+    function updateBroadcasterRequest(address newBroadcaster) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Approves a pending broadcaster update transaction after the release time
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function updateBroadcasterDelayedApproval(uint256 txId) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Approves a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction
+     * @param txId The transaction ID
+     * @return The updated transaction record
+     */
+    function updateBroadcasterCancellation(uint256 txId) external returns (EngineBlox.TxRecord memory);
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The updated transaction record
+     */
+    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+
+    // ============ RECOVERY MANAGEMENT ============
+
+    /**
+     * @dev Creates execution params for updating the recovery address
+     * @param newRecoveryAddress The new recovery address
+     * @return The execution params
+     */
+    function updateRecoveryExecutionParams(address newRecoveryAddress) external view returns (bytes memory);
+
+    /**
+     * @dev Requests and approves a recovery address update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     */
+    function updateRecoveryRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+
+    // ============ TIMELOCK MANAGEMENT ============
+
+    /**
+     * @dev Creates execution params for updating the time lock period
+     * @param newTimeLockPeriodSec The new time lock period in seconds
+     * @return The execution params
+     */
+    function updateTimeLockExecutionParams(uint256 newTimeLockPeriodSec) external view returns (bytes memory);
+
+    /**
+     * @dev Requests and approves a time lock period update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     */
+    function updateTimeLockRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
+}