@bloxchain/contracts 1.0.0-alpha.17 → 1.0.0-alpha.19

package/abi/EngineBlox.abi.json

@@ -689,38 +689,12 @@
   },
   {
     "inputs": [],
-    "name": "VERSION_MAJOR",
+    "name": "VERSION",
     "outputs": [
       {
-        "internalType": "uint8",
-        "name": "",
-        "type": "uint8"
-      }
-    ],
-    "stateMutability": "view",
-    "type": "function"
-  },
-  {
-    "inputs": [],
-    "name": "VERSION_MINOR",
-    "outputs": [
-      {
-        "internalType": "uint8",
+        "internalType": "string",
         "name": "",
-        "type": "uint8"
-      }
-    ],
-    "stateMutability": "view",
-    "type": "function"
-  },
-  {
-    "inputs": [],
-    "name": "VERSION_PATCH",
-    "outputs": [
-      {
-        "internalType": "uint8",
-        "name": "",
-        "type": "uint8"
+        "type": "string"
       }
     ],
     "stateMutability": "view",

package/abi/GuardControllerDefinitions.abi.json

@@ -51,6 +51,19 @@
     "stateMutability": "view",
     "type": "function"
   },
+  {
+    "inputs": [],
+    "name": "CONTROLLER_CONFIG_OPERATION",
+    "outputs": [
+      {
+        "internalType": "bytes32",
+        "name": "",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
   {
     "inputs": [],
     "name": "CONTROLLER_OPERATION",

package/core/access/RuntimeRBAC.sol

@@ -134,7 +134,7 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     function _executeRoleConfigBatch(IRuntimeRBAC.RoleConfigAction[] calldata actions) internal {
         _validateBatchSize(actions.length);
 
-        for (uint256 i = 0; i < actions.length; i++) {
+        for (uint256 i = 0; i < actions.length; ++i) {
             IRuntimeRBAC.RoleConfigAction calldata action = actions[i];
 
             if (action.actionType == IRuntimeRBAC.RoleConfigActionType.CREATE_ROLE) {

package/core/execution/lib/definitions/GuardControllerDefinitions.sol

@@ -16,7 +16,7 @@ import "../../interface/IGuardController.sol";
  * and role permissions for GuardController's public execution functions.
  * 
  * Key Features:
- * - Registers all 6 GuardController public execution functions
+ * - Registers all 9 GuardController public execution functions
  * - Defines role permissions for OWNER_ROLE and BROADCASTER_ROLE
  * - Supports time-delay and meta-transaction workflows
  * - Matches EngineBloxDefinitions pattern for consistency
@@ -33,6 +33,8 @@ library GuardControllerDefinitions {
     
     // Operation Type Constants
     bytes32 public constant CONTROLLER_OPERATION = keccak256("CONTROLLER_OPERATION");
+    // Guard config batch only (whitelist / register-unregister function); distinct execution operation type bitmap.
+    bytes32 public constant CONTROLLER_CONFIG_OPERATION = keccak256("CONTROLLER_CONFIG_OPERATION");
     
     // Function Selector Constants
     // GuardController: executeWithTimeLock(address,uint256,bytes4,bytes,uint256,bytes32)
@@ -86,7 +88,7 @@ library GuardControllerDefinitions {
      * 
      * Function schemas define:
      * - GuardController public execution functions
-     * - What operation types they belong to (CONTROLLER_OPERATION)
+     * - What operation types they belong to (CONTROLLER_OPERATION vs CONTROLLER_CONFIG_OPERATION)
      * - What actions are supported (time-delay request/approve/cancel, meta-tx approve/cancel/request-and-approve)
      * - Whether they are protected
      * 
@@ -96,7 +98,7 @@ library GuardControllerDefinitions {
      * - Role permissions are defined in getRolePermissions() matching EngineBloxDefinitions pattern
      */
     function getFunctionSchemas() public pure returns (EngineBlox.FunctionSchema[] memory) {
-        EngineBlox.FunctionSchema[] memory schemas = new EngineBlox.FunctionSchema[](8);
+        EngineBlox.FunctionSchema[] memory schemas = new EngineBlox.FunctionSchema[](9);
         
         // ============ TIME-DELAY WORKFLOW ACTIONS ============
         // Request action for executeWithTimeLock
@@ -144,6 +146,9 @@ library GuardControllerDefinitions {
         requestAndApproveExecutionHandlerForSelectors[0] = REQUEST_AND_APPROVE_EXECUTION_SELECTOR;
         bytes4[] memory guardConfigBatchExecuteHandlerForSelectors = new bytes4[](1);
         guardConfigBatchExecuteHandlerForSelectors[0] = GUARD_CONFIG_BATCH_EXECUTE_SELECTOR;
+
+        bytes4[] memory executeWithPaymentHandlerForSelectors = new bytes4[](1);
+        executeWithPaymentHandlerForSelectors[0] = EXECUTE_WITH_PAYMENT_SELECTOR;
         
         // Handler selectors point to execution selectors
         bytes4[] memory guardConfigHandlerForSelectors = new bytes4[](1);
@@ -225,8 +230,8 @@ library GuardControllerDefinitions {
         schemas[6] = EngineBlox.FunctionSchema({
             functionSignature: "guardConfigBatchRequestAndApprove(((uint256,uint256,uint8,(address,address,uint256,uint256,bytes32,bytes4,bytes),bytes32,bytes,(address,uint256,address,uint256)),(uint256,uint256,address,bytes4,uint8,uint256,uint256,address),bytes32,bytes,bytes))",
             functionSelector: GUARD_CONFIG_BATCH_META_SELECTOR,
-            operationType: CONTROLLER_OPERATION,
-            operationName: "CONTROLLER_OPERATION",
+            operationType: CONTROLLER_CONFIG_OPERATION,
+            operationName: "CONTROLLER_CONFIG_OPERATION",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaTxRequestApproveActions),
             enforceHandlerRelations: true,
             isProtected: true,
@@ -241,14 +246,27 @@ library GuardControllerDefinitions {
         schemas[7] = EngineBlox.FunctionSchema({
             functionSignature: "executeGuardConfigBatch((uint8,bytes)[])",
             functionSelector: GUARD_CONFIG_BATCH_EXECUTE_SELECTOR,
-            operationType: CONTROLLER_OPERATION,
-            operationName: "CONTROLLER_OPERATION",
+            operationType: CONTROLLER_CONFIG_OPERATION,
+            operationName: "CONTROLLER_CONFIG_OPERATION",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(guardConfigExecutionActions),
             enforceHandlerRelations: false,
             isProtected: true,
             handlerForSelectors: guardConfigBatchExecuteHandlerForSelectors
         });
 
+        // Schema 8: GuardController.executeWithPayment (same time-delay request action as executeWithTimeLock;
+        // OWNER_ROLE grant for this selector may be added manually if the flow is enabled)
+        schemas[8] = EngineBlox.FunctionSchema({
+            functionSignature: "executeWithPayment(address,uint256,bytes4,bytes,uint256,bytes32,(address,uint256,address,uint256))",
+            functionSelector: EXECUTE_WITH_PAYMENT_SELECTOR,
+            operationType: CONTROLLER_OPERATION,
+            operationName: "CONTROLLER_OPERATION",
+            supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            enforceHandlerRelations: false,
+            isProtected: true,
+            handlerForSelectors: executeWithPaymentHandlerForSelectors
+        });
+
         return schemas;
     }
     

package/core/lib/EngineBlox.sol

@@ -32,9 +32,7 @@ import "./interfaces/IEventForwarder.sol";
 library EngineBlox {
     // ============ VERSION INFORMATION ============
     bytes32 public constant PROTOCOL_NAME_HASH = keccak256("Bloxchain");
-    uint8 public constant VERSION_MAJOR = 1;
-    uint8 public constant VERSION_MINOR = 0;
-    uint8 public constant VERSION_PATCH = 0;
+    string public constant VERSION = "1.0.0";
     
     // ============ SYSTEM SAFETY LIMITS ============
     // These constants define the safety range limits for system operations
@@ -206,8 +204,25 @@ library EngineBlox {
     bytes32 public constant NATIVE_TRANSFER_OPERATION = keccak256("NATIVE_TRANSFER");
     
     // EIP-712 Type Hashes (selective meta-tx payload: MetaTxRecord = txId + params + payment only)
-    bytes32 private constant META_TX_TYPE_HASH = keccak256("MetaTransaction(MetaTxRecord txRecord,MetaTxParams params,bytes data)MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)");
-    bytes32 private constant META_TX_RECORD_TYPE_HASH = keccak256("MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)");
+    // These follow the canonical EIP-712 convention so that eth_signTypedData_v4 and equivalent
+    // wallet typed-data signers can reproduce the same hashes when given matching type definitions.
+    //
+    // Canonical primary type string for MetaTransaction (primary type + all referenced types,
+    // appended in alphabetical order by type name
+    bytes32 private constant META_TX_TYPE_HASH = keccak256(
+        "MetaTransaction(MetaTxRecord txRecord,MetaTxParams params,bytes data)"
+        "MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)"
+        "MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)"
+        "PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)"
+        "TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)"
+    );
+
+    // Canonical primary type string for MetaTxRecord (primary type + its referenced types).
+    bytes32 private constant META_TX_RECORD_TYPE_HASH = keccak256(
+        "MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)"
+        "PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)"
+        "TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)"
+    );
     bytes32 private constant TX_PARAMS_TYPE_HASH = keccak256("TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)");
     bytes32 private constant META_TX_PARAMS_TYPE_HASH = keccak256("MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)");
     bytes32 private constant PAYMENT_DETAILS_TYPE_HASH = keccak256("PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)");
@@ -361,6 +376,16 @@ library EngineBlox {
         // Validate both execution and handler selector permissions (same as txRequest)
         _validateExecutionAndHandlerPermissions(self, msg.sender, executionSelector, handlerSelector, TxAction.EXECUTE_TIME_DELAY_REQUEST);
 
+        // Request-time validation for attached payment details.
+        // This prevents creating persistent PENDING records that later fail during
+        // `executeAttachedPayment` due to missing/zero payment fields.
+        if (paymentDetails.nativeTokenAmount > 0 || paymentDetails.erc20TokenAmount > 0) {
+            SharedValidation.validateNotZeroAddress(paymentDetails.recipient);
+        }
+        if (paymentDetails.erc20TokenAmount > 0) {
+            SharedValidation.validateNotZeroAddress(paymentDetails.erc20TokenAddress);
+        }
+
         return _txRequest(
             self,
             requester,
@@ -559,6 +584,16 @@ library EngineBlox {
         // Validate both execution and handler selector permissions
         _validateExecutionAndHandlerPermissions(self, msg.sender, metaTx.txRecord.params.executionSelector, metaTx.params.handlerSelector, TxAction.EXECUTE_META_REQUEST_AND_APPROVE);
         
+        // Request-time validation for attached payment details.
+        // `requestAndApprove` creates the request and executes via the same meta-tx flow,
+        // so we validate here to avoid persisting bad PENDING records.
+        if (metaTx.txRecord.payment.nativeTokenAmount > 0 || metaTx.txRecord.payment.erc20TokenAmount > 0) {
+            SharedValidation.validateNotZeroAddress(metaTx.txRecord.payment.recipient);
+        }
+        if (metaTx.txRecord.payment.erc20TokenAmount > 0) {
+            SharedValidation.validateNotZeroAddress(metaTx.txRecord.payment.erc20TokenAddress);
+        }
+
         TxRecord memory txRecord = _txRequest(
             self,
             metaTx.txRecord.params.requester,
@@ -1690,27 +1725,36 @@ library EngineBlox {
 
     /**
      * @dev Generates the EIP-712 message hash for the meta-transaction.
-     *      Uses selective MetaTxRecord (txId, params, payment only).
-     *      Integrators must sign this digest as a raw hash with no EIP-191 or personal_sign prefix—
-     *      e.g. account.sign({ hash: contractDigest }) or equivalent raw-hash signing API—so that
-     *      signatures match the raw ecrecover(messageHash, v, r, s) verification in recoverSigner.
-     *      Do NOT use personal_sign or generic eth_signTypedData_v4; the contract uses
-     *      abi.encodePacked for the version string and a custom META_TX_TYPE_HASH, so those produce
-     *      incompatible hashes.
-     *      The resulting digest is also written into the `message` field of the helper-built
-     *      `MetaTransaction` structs (see `createMetaTransactionForSigning`) so integrators can use
-     *      it directly without recomputing the hash client-side.
+     *      Uses selective MetaTxRecord (txId, params, payment only) with standard EIP-712 type hashes
+     *      so that eth_signTypedData_v4 (and equivalent) can reproduce the same digest when given
+     *      matching domain + types:
+     *
+     *      - primaryType: MetaTransaction
+     *      - domain: { name: "Bloxchain", version: "1.0.0", chainId, verifyingContract }
+     *      - types: MetaTransaction, MetaTxRecord, TxParams, MetaTxParams, PaymentDetails
+     *
+     *      Integrators MAY:
+     *      - use typed-data signing (eth_signTypedData_v4 / signTypedData) with the above domain/types, or
+     *      - sign the resulting digest as a raw hash (e.g. account.sign({ hash: contractDigest })).
+     *
+     *      In all cases, on-chain verification uses recoverSigner(messageHash, signature) which applies
+     *      ecrecover(messageHash, v, r, s) with no personal_sign / EIP-191 prefix.
+     *
+     *      The resulting digest is also written into the `message` field of helper-built `MetaTransaction`
+     *      structs so integrators can use it directly without recomputing the hash client-side.
      * @param metaTx The meta-transaction to generate the hash for
      * @return The EIP-712 digest (no prefix; use standard recovery)
      */
     function generateMessageHash(MetaTransaction memory metaTx) private view returns (bytes32) {
-        bytes32 domainSeparator = keccak256(abi.encode(
-            DOMAIN_SEPARATOR_TYPE_HASH,
-            PROTOCOL_NAME_HASH,
-            keccak256(abi.encodePacked(VERSION_MAJOR, ".", VERSION_MINOR, ".", VERSION_PATCH)),
-            block.chainid,
-            address(this)
-        ));
+        bytes32 domainSeparator = keccak256(
+            abi.encode(
+                DOMAIN_SEPARATOR_TYPE_HASH,
+                PROTOCOL_NAME_HASH,
+                keccak256(bytes(VERSION)),
+                block.chainid,
+                address(this)
+            )
+        );
 
         TxParams memory tp = metaTx.txRecord.params;
         bytes32 txParamsStructHash = keccak256(abi.encode(
@@ -1769,11 +1813,20 @@ library EngineBlox {
 
     /**
      * @dev Recovers the signer from the EIP-712 digest and signature. Uses standard EIP-712 recovery (no message prefix).
-     *      Integrators must sign the digest returned by generateMessageHash as a raw hash—e.g.
-     *      account.sign({ hash: contractDigest }) or equivalent raw-hash signing API—with no
-     *      EIP-191/personal prefix, so signatures match this ecrecover(messageHash, v, r, s) verification.
-     *      Do NOT use personal_sign or generic eth_signTypedData_v4; the contract uses abi.encodePacked
-     *      for the domain version and a custom META_TX_TYPE_HASH, so those produce incompatible hashes.
+     *
+     *      Integrators have two equivalent options:
+     *      - Use typed-data signing (eth_signTypedData_v4 / signTypedData) with:
+     *          - primaryType: MetaTransaction
+     *          - domain: { name: "Bloxchain", version: "1.0.0", chainId, verifyingContract }
+     *          - types: MetaTransaction, MetaTxRecord, TxParams, MetaTxParams, PaymentDetails
+     *        In this case the wallet computes the same digest as generateMessageHash and signs it.
+     *      - Sign the digest returned by generateMessageHash as a raw hash—e.g.
+     *        account.sign({ hash: contractDigest }) or equivalent raw-hash signing API—with no
+     *        EIP-191/personal prefix.
+     *
+     *      In all cases, this function applies ecrecover(messageHash, v, r, s) over the raw EIP-712 digest.
+     *      personal_sign / EIP-191-prefixed signatures remain incompatible.
+     *
      * @param messageHash The EIP-712 digest (keccak256("\x19\x01" || domainSeparator || structHash))
      * @param signature The signature (r, s, v)
      * @return The address of the signer

package/core/pattern/Account.sol

@@ -2,8 +2,11 @@
 pragma solidity 0.8.34;
 
 import "../execution/GuardController.sol";
+import "../execution/interface/IGuardController.sol";
 import "../access/RuntimeRBAC.sol";
+import "../access/interface/IRuntimeRBAC.sol";
 import "../security/SecureOwnable.sol";
+import "../security/interface/ISecureOwnable.sol";
 import "../lib/utils/SharedValidation.sol";
 
 /**
@@ -51,9 +54,15 @@ abstract contract Account is GuardController, RuntimeRBAC, SecureOwnable {
 
     /**
      * @dev See {IERC165-supportsInterface}.
+     * @notice GuardController, RuntimeRBAC, and SecureOwnable each extend BaseStateMachine directly; a single
+     *         `super` chain only walks one branch. We OR the three component interface IDs here, then delegate
+     *         once to `super` for IBaseStateMachine / ERC165 — avoids tripling BaseStateMachine+ERC165 work.
      */
     function supportsInterface(bytes4 interfaceId) public view virtual override(GuardController, RuntimeRBAC, SecureOwnable) returns (bool) {
-        return GuardController.supportsInterface(interfaceId) || RuntimeRBAC.supportsInterface(interfaceId) || SecureOwnable.supportsInterface(interfaceId);
+        return interfaceId == type(IGuardController).interfaceId
+            || interfaceId == type(IRuntimeRBAC).interfaceId
+            || interfaceId == type(ISecureOwnable).interfaceId
+            || super.supportsInterface(interfaceId);
     }
 
     /**

package/core/security/SecureOwnable.sol

@@ -1,394 +1,424 @@
-// SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.34;
-
-// Contracts imports
-import "../base/BaseStateMachine.sol";
-import "./lib/definitions/SecureOwnableDefinitions.sol";
-import "../lib/interfaces/IDefinition.sol";
-import "../lib/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.
- *
- * At most one ownership-transfer or broadcaster-update request may be pending at a time:
- * a pending request of either type blocks new requests until it is approved or cancelled.
- *
- * 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 *;
-
-    /// @dev True while any pending ownership transfer or broadcaster update request exists; blocks new requests until handled.
-    bool private _hasOpenRequest;
-
-    /**
-     * @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 {
-        _initializeBaseStateMachine(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
-
-        // Load SecureOwnable-specific definitions
-        IDefinition.RolePermission memory secureOwnablePermissions = SecureOwnableDefinitions.getRolePermissions();
-        _loadDefinitions(
-            SecureOwnableDefinitions.getFunctionSchemas(),
-            secureOwnablePermissions.roleHashes,
-            secureOwnablePermissions.functionPermissions,
-            true // Enforce all function schemas are protected
-        );
-    }
-
-    // ============ 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 txId The transaction ID (use getTransaction(txId) for full record)
-     */
-    function transferOwnershipRequest() public returns (uint256 txId) {
-        SharedValidation.validateRecovery(getRecovery());
-        _requireNoPendingRequest();
-
-        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())
-        );
-
-        _hasOpenRequest = true;
-        _logAddressPairEvent(owner(), getRecovery());
-        return txRecord.txId;
-    }
-
-    /**
-     * @dev Approves a pending ownership transfer transaction after the release time
-     * @param txId The transaction ID
-     * @return The transaction ID
-     */
-    function transferOwnershipDelayedApproval(uint256 txId) public returns (uint256) {
-        SharedValidation.validateOwnerOrRecovery(owner(), getRecovery());
-        return _completeApprove(_approveTransaction(txId));
-    }
-
-    /**
-     * @dev Approves a pending ownership transfer transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        return _completeApprove(_approveTransactionWithMetaTx(metaTx));
-    }
-
-    /**
-     * @dev Cancels a pending ownership transfer transaction
-     * @param txId The transaction ID
-     * @return The transaction ID
-     */
-    function transferOwnershipCancellation(uint256 txId) public returns (uint256) {
-        SharedValidation.validateRecovery(getRecovery());
-        return _completeCancel(_cancelTransaction(txId));
-    }
-
-    /**
-     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        return _completeCancel(_cancelTransactionWithMetaTx(metaTx));
-    }
-
-    // Broadcaster Management
-    /**
-     * @dev Requests an update to the broadcaster at a specific location (index).
-     * @param newBroadcaster The new broadcaster address (zero address to revoke at location)
-     * @param location The index in the broadcaster role's authorized wallets set
-     * @return txId The transaction ID for the pending request (use getTransaction(txId) for full record)
-     */
-    function updateBroadcasterRequest(address newBroadcaster, uint256 location) public returns (uint256 txId) {
-        SharedValidation.validateOwner(owner());
-        _requireNoPendingRequest();
-
-        // Get the current broadcaster at the specified location. zero address if no broadcaster at location.
-        address currentBroadcaster = location < _getSecureState().roles[EngineBlox.BROADCASTER_ROLE].walletCount
-            ? _getAuthorizedWalletAt(EngineBlox.BROADCASTER_ROLE, location)
-            : address(0);
-
-        EngineBlox.TxRecord memory txRecord = _requestTransaction(
-            msg.sender,
-            address(this),
-            0, // value
-            0, // gas limit
-            SecureOwnableDefinitions.BROADCASTER_UPDATE,
-            SecureOwnableDefinitions.UPDATE_BROADCASTER_SELECTOR,
-            abi.encode(newBroadcaster, location)
-        );
-
-        _hasOpenRequest = true;
-        _logAddressPairEvent(currentBroadcaster, newBroadcaster);
-        return txRecord.txId;
-    }
-
-    /**
-     * @dev Approves a pending broadcaster update transaction after the release time
-     * @param txId The transaction ID
-     * @return The transaction ID
-     */
-    function updateBroadcasterDelayedApproval(uint256 txId) public returns (uint256) {
-        SharedValidation.validateOwner(owner());
-        return _completeApprove(_approveTransaction(txId));
-    }
-
-    /**
-     * @dev Approves a pending broadcaster update transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        return _completeApprove(_approveTransactionWithMetaTx(metaTx));
-    }
-
-    /**
-     * @dev Cancels a pending broadcaster update transaction
-     * @param txId The transaction ID
-     * @return The transaction ID
-     */
-    function updateBroadcasterCancellation(uint256 txId) public returns (uint256) {
-        SharedValidation.validateOwner(owner());
-        return _completeCancel(_cancelTransaction(txId));
-    }
-
-    /**
-     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        return _completeCancel(_cancelTransactionWithMetaTx(metaTx));
-    }
-
-    // Recovery Management
-
-    /**
-     * @dev Requests and approves a recovery address update using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function updateRecoveryRequestAndApprove(
-        EngineBlox.MetaTransaction memory metaTx
-    ) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
-        return txRecord.txId;
-    }
-
-    // TimeLock Management
-
-    /**
-     * @dev Requests and approves a time lock period update using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction ID
-     */
-    function updateTimeLockRequestAndApprove(
-        EngineBlox.MetaTransaction memory metaTx
-    ) public returns (uint256) {
-        _validateBroadcasterAndOwnerSigner(metaTx);
-        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
-        return txRecord.txId;
-    }
-
-    // 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 {
-        _validateExecuteBySelf();
-        _transferOwnership(newOwner);
-    }
-
-    /**
-     * @dev External function that can only be called by the contract itself to execute broadcaster update
-     * @param newBroadcaster The new broadcaster address (zero address to revoke at location)
-     * @param location The index in the broadcaster role's authorized wallets set
-     */
-    function executeBroadcasterUpdate(address newBroadcaster, uint256 location) external {
-        _validateExecuteBySelf();
-        _updateBroadcaster(newBroadcaster, location);
-    }
-
-    /**
-     * @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 {
-        _validateExecuteBySelf();
-        _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 {
-        _validateExecuteBySelf();
-        _updateTimeLockPeriod(newTimeLockPeriodSec);
-    }
-
-    // ============ INTERNAL FUNCTIONS ============
-
-    /**
-     * @dev Reverts if an ownership-transfer or broadcaster-update request is already pending.
-     */
-    function _requireNoPendingRequest() internal view {
-        if (_hasOpenRequest) revert SharedValidation.PendingSecureRequest();
-    }
-
-    /**
-     * @dev Validates that the caller is the broadcaster and that the meta-tx signer is the owner.
-     * @param metaTx The meta-transaction to validate
-     */
-    function _validateBroadcasterAndOwnerSigner(EngineBlox.MetaTransaction memory metaTx) internal view {
-        _validateBroadcaster(msg.sender);
-        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
-    }
-
-    /**
-     * @dev Completes ownership/broadcaster flow after approval: resets flag and returns txId.
-     * @param updatedRecord The updated transaction record from approval
-     * @return txId The transaction ID
-     */
-    function _completeApprove(EngineBlox.TxRecord memory updatedRecord) internal returns (uint256 txId) {
-        _hasOpenRequest = false;
-        return updatedRecord.txId;
-    }
-
-    /**
-     * @dev Completes ownership/broadcaster flow after cancellation: resets flag, logs txId, returns txId.
-     * @param updatedRecord The updated transaction record from cancellation
-     * @return txId The transaction ID
-     */
-    function _completeCancel(EngineBlox.TxRecord memory updatedRecord) internal returns (uint256 txId) {
-        _hasOpenRequest = false;
-        return updatedRecord.txId;
-    }
-
-    /**
-     * @dev Transfers ownership of the contract
-     * @param newOwner The new owner of the contract
-     */
-    function _transferOwnership(address newOwner) internal virtual {
-        address oldOwner = owner();
-        _updateWallet(EngineBlox.OWNER_ROLE, newOwner, oldOwner);
-        _logAddressPairEvent(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);
-                _logAddressPairEvent(oldBroadcaster, address(0));
-            }
-            return;
-        }
-
-        // Case 2: Update existing broadcaster at location
-        if (oldBroadcaster != address(0)) {
-            _updateWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster, oldBroadcaster);
-            _logAddressPairEvent(oldBroadcaster, newBroadcaster);
-            return;
-        }
-
-        // Case 3: No broadcaster at location, assign a new one (will respect maxWallets)
-        _assignWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster);
-        _logAddressPairEvent(address(0), newBroadcaster);
-    }
-
-    /**
-     * @dev Updates the recovery address
-     * @param newRecoveryAddress The new recovery address
-     */
-    function _updateRecoveryAddress(address newRecoveryAddress) internal virtual {
-        address oldRecovery = getRecovery();
-        _updateWallet(EngineBlox.RECOVERY_ROLE, newRecoveryAddress, oldRecovery);
-        _logAddressPairEvent(oldRecovery, newRecoveryAddress);
-    }
-
-    /**
-     * @dev Emits ComponentEvent with ABI-encoded (address, address) payload. Reused to reduce contract size.
-     * @param a First address
-     * @param b Second address
-     */
-    function _logAddressPairEvent(address a, address b) internal {
-        _logComponentEvent(abi.encode(a, b));
-    }
-}
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+// Contracts imports
+import "../base/BaseStateMachine.sol";
+import "./lib/definitions/SecureOwnableDefinitions.sol";
+import "../lib/interfaces/IDefinition.sol";
+import "../lib/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.
+ *
+ * Pending secure requests use separate flags for ownership transfer and broadcaster update.
+ * A new ownership-transfer request is allowed if no ownership transfer is already pending
+ * (a broadcaster update may still be pending). A new broadcaster-update request is allowed only
+ * when neither type has a pending request.
+ *
+ * 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 *;
+
+    /// @dev Tracks pending secure txs by type. Upgrading from legacy `_hasOpenRequest` / `_pendingBits` requires no pending requests.
+    bool private _hasOpenOwnershipRequest;
+    bool private _hasOpenBroadcasterRequest;
+
+    /**
+     * @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 {
+        _initializeBaseStateMachine(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+
+        // Load SecureOwnable-specific definitions
+        IDefinition.RolePermission memory secureOwnablePermissions = SecureOwnableDefinitions.getRolePermissions();
+        _loadDefinitions(
+            SecureOwnableDefinitions.getFunctionSchemas(),
+            secureOwnablePermissions.roleHashes,
+            secureOwnablePermissions.functionPermissions,
+            true // Enforce all function schemas are protected
+        );
+    }
+
+    // ============ 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 txId The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipRequest() public returns (uint256 txId) {
+        SharedValidation.validateRecovery(getRecovery());
+        _requireNoPendingRequest(SecureOwnableDefinitions.OWNERSHIP_TRANSFER);
+
+        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;
+        _logAddressPairEvent(owner(), getRecovery());
+        return txRecord.txId;
+    }
+
+    /**
+     * @dev Approves a pending ownership transfer transaction after the release time
+     * @param txId The transaction ID
+     * @return The transaction ID
+     */
+    function transferOwnershipDelayedApproval(uint256 txId) public returns (uint256) {
+        SharedValidation.validateOwnerOrRecovery(owner(), getRecovery());
+        return _completeApprove(_approveTransaction(txId));
+    }
+
+    /**
+     * @dev Approves a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        return _completeApprove(_approveTransactionWithMetaTx(metaTx));
+    }
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction
+     * @param txId The transaction ID
+     * @return The transaction ID
+     */
+    function transferOwnershipCancellation(uint256 txId) public returns (uint256) {
+        SharedValidation.validateRecovery(getRecovery());
+        return _completeCancel(_cancelTransaction(txId));
+    }
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        return _completeCancel(_cancelTransactionWithMetaTx(metaTx));
+    }
+
+    // Broadcaster Management
+    /**
+     * @dev Requests an update to the broadcaster at a specific location (index).
+     * @notice Requires no pending broadcaster-update and no pending ownership-transfer request.
+     * @param newBroadcaster The new broadcaster address (zero address to revoke at location)
+     * @param location The index in the broadcaster role's authorized wallets set
+     * @return txId The transaction ID for the pending request (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterRequest(address newBroadcaster, uint256 location) public returns (uint256 txId) {
+        SharedValidation.validateOwner(owner());
+        _requireNoPendingRequest(SecureOwnableDefinitions.BROADCASTER_UPDATE);
+        _requireNoPendingRequest(SecureOwnableDefinitions.OWNERSHIP_TRANSFER);
+
+        // Get the current broadcaster at the specified location. zero address if no broadcaster at location.
+        address currentBroadcaster = location < _getSecureState().roles[EngineBlox.BROADCASTER_ROLE].walletCount
+            ? _getAuthorizedWalletAt(EngineBlox.BROADCASTER_ROLE, location)
+            : address(0);
+
+        EngineBlox.TxRecord memory txRecord = _requestTransaction(
+            msg.sender,
+            address(this),
+            0, // value
+            0, // gas limit
+            SecureOwnableDefinitions.BROADCASTER_UPDATE,
+            SecureOwnableDefinitions.UPDATE_BROADCASTER_SELECTOR,
+            abi.encode(newBroadcaster, location)
+        );
+
+        _hasOpenBroadcasterRequest = true;
+        _logAddressPairEvent(currentBroadcaster, newBroadcaster);
+        return txRecord.txId;
+    }
+
+    /**
+     * @dev Approves a pending broadcaster update transaction after the release time
+     * @param txId The transaction ID
+     * @return The transaction ID
+     */
+    function updateBroadcasterDelayedApproval(uint256 txId) public returns (uint256) {
+        SharedValidation.validateOwner(owner());
+        return _completeApprove(_approveTransaction(txId));
+    }
+
+    /**
+     * @dev Approves a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        return _completeApprove(_approveTransactionWithMetaTx(metaTx));
+    }
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction
+     * @param txId The transaction ID
+     * @return The transaction ID
+     */
+    function updateBroadcasterCancellation(uint256 txId) public returns (uint256) {
+        SharedValidation.validateOwner(owner());
+        return _completeCancel(_cancelTransaction(txId));
+    }
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        return _completeCancel(_cancelTransactionWithMetaTx(metaTx));
+    }
+
+    // Recovery Management
+
+    /**
+     * @dev Requests and approves a recovery address update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function updateRecoveryRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
+        return txRecord.txId;
+    }
+
+    // TimeLock Management
+
+    /**
+     * @dev Requests and approves a time lock period update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID
+     */
+    function updateTimeLockRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) public returns (uint256) {
+        _validateBroadcasterAndOwnerSigner(metaTx);
+        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
+        return txRecord.txId;
+    }
+
+    // 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 {
+        _validateExecuteBySelf();
+        _transferOwnership(newOwner);
+    }
+
+    /**
+     * @dev External function that can only be called by the contract itself to execute broadcaster update
+     * @param newBroadcaster The new broadcaster address (zero address to revoke at location)
+     * @param location The index in the broadcaster role's authorized wallets set
+     */
+    function executeBroadcasterUpdate(address newBroadcaster, uint256 location) external {
+        _validateExecuteBySelf();
+        _updateBroadcaster(newBroadcaster, location);
+    }
+
+    /**
+     * @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 {
+        _validateExecuteBySelf();
+        _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 {
+        _validateExecuteBySelf();
+        _updateTimeLockPeriod(newTimeLockPeriodSec);
+    }
+
+    // ============ INTERNAL FUNCTIONS ============
+
+
+    /**
+     * @dev Validates that the caller is the broadcaster and that the meta-tx signer is the owner.
+     * @param metaTx The meta-transaction to validate
+     */
+    function _validateBroadcasterAndOwnerSigner(EngineBlox.MetaTransaction memory metaTx) internal view {
+        _validateBroadcaster(msg.sender);
+        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
+    }
+
+    /**
+     * @dev Completes ownership/broadcaster flow after approval: clears the matching pending flag and returns txId.
+     * @param updatedRecord The updated transaction record from approval
+     * @return txId The transaction ID
+     */
+    function _completeApprove(EngineBlox.TxRecord memory updatedRecord) internal returns (uint256 txId) {
+        _clearPendingFlagForOperation(updatedRecord.params.operationType);
+        return updatedRecord.txId;
+    }
+
+    /**
+     * @dev Completes ownership/broadcaster flow after cancellation: clears the matching pending flag and returns txId.
+     * @param updatedRecord The updated transaction record from cancellation
+     * @return txId The transaction ID
+     */
+    function _completeCancel(EngineBlox.TxRecord memory updatedRecord) internal returns (uint256 txId) {
+        _clearPendingFlagForOperation(updatedRecord.params.operationType);
+        return updatedRecord.txId;
+    }
+
+    /**
+     * @dev Reverts if the pending flag for `requestOperationType` is already set (one lane per call).
+     *      `OWNERSHIP_TRANSFER` checks only `_hasOpenOwnershipRequest` (a broadcaster update may still be pending).
+     *      `BROADCASTER_UPDATE` checks only `_hasOpenBroadcasterRequest`. Callers that need both lanes idle
+     *      (e.g. `updateBroadcasterRequest`) invoke this once per operation type.
+     * @param requestOperationType Lane to validate (`OWNERSHIP_TRANSFER` or `BROADCASTER_UPDATE`).
+     */
+    function _requireNoPendingRequest(bytes32 requestOperationType) internal view {
+        if (requestOperationType == SecureOwnableDefinitions.OWNERSHIP_TRANSFER) {
+            if (_hasOpenOwnershipRequest) revert SharedValidation.PendingSecureRequest();
+        } else if (requestOperationType == SecureOwnableDefinitions.BROADCASTER_UPDATE) {
+            if (_hasOpenBroadcasterRequest) revert SharedValidation.PendingSecureRequest();
+        } else {
+            revert();
+        }
+    }
+
+    /**
+     * @dev Clears the pending flag for a completed or cancelled secure op (approve/cancel paths).
+     * @param operationType The tx record's `operationType` (`OWNERSHIP_TRANSFER` or `BROADCASTER_UPDATE`).
+     */
+    function _clearPendingFlagForOperation(bytes32 operationType) private {
+        if (operationType == SecureOwnableDefinitions.OWNERSHIP_TRANSFER) {
+            _hasOpenOwnershipRequest = false;
+        } else if (operationType == SecureOwnableDefinitions.BROADCASTER_UPDATE) {
+            _hasOpenBroadcasterRequest = false;
+        } else {
+            revert();
+        }
+    }
+
+    /**
+     * @dev Transfers ownership of the contract
+     * @param newOwner The new owner of the contract
+     */
+    function _transferOwnership(address newOwner) internal virtual {
+        address oldOwner = owner();
+        _updateWallet(EngineBlox.OWNER_ROLE, newOwner, oldOwner);
+        _logAddressPairEvent(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);
+                _logAddressPairEvent(oldBroadcaster, address(0));
+            }
+            return;
+        }
+
+        // Case 2: Update existing broadcaster at location
+        if (oldBroadcaster != address(0)) {
+            _updateWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster, oldBroadcaster);
+            _logAddressPairEvent(oldBroadcaster, newBroadcaster);
+            return;
+        }
+
+        // Case 3: No broadcaster at location, assign a new one (will respect maxWallets)
+        _assignWallet(EngineBlox.BROADCASTER_ROLE, newBroadcaster);
+        _logAddressPairEvent(address(0), newBroadcaster);
+    }
+
+    /**
+     * @dev Updates the recovery address
+     * @param newRecoveryAddress The new recovery address
+     */
+    function _updateRecoveryAddress(address newRecoveryAddress) internal virtual {
+        address oldRecovery = getRecovery();
+        _updateWallet(EngineBlox.RECOVERY_ROLE, newRecoveryAddress, oldRecovery);
+        _logAddressPairEvent(oldRecovery, newRecoveryAddress);
+    }
+
+    /**
+     * @dev Emits ComponentEvent with ABI-encoded (address, address) payload. Reused to reduce contract size.
+     * @param a First address
+     * @param b Second address
+     */
+    function _logAddressPairEvent(address a, address b) internal {
+        _logComponentEvent(abi.encode(a, b));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloxchain/contracts",
-  "version": "1.0.0-alpha.17",
+  "version": "1.0.0-alpha.19",
   "description": "Library engine for building enterprise grade decentralized permissioned applications",
   "files": [
     "core",