@bloxchain/contracts 1.0.0-alpha.6 → 1.0.0

package/core/access/RuntimeRBAC.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.35;
 
 // Contract imports
 import "../base/BaseStateMachine.sol";
@@ -12,18 +12,31 @@ import "./interface/IRuntimeRBAC.sol";
 /**
  * @title RuntimeRBAC
  * @dev Minimal Runtime Role-Based Access Control system based on EngineBlox
- * 
+ *
  * This contract provides essential runtime RBAC functionality:
  * - Creation of non-protected roles
  * - Basic wallet assignment to roles
  * - Function permission management per role
  * - Integration with EngineBlox for secure operations
- * 
+ *
  * Key Features:
  * - Only non-protected roles can be created dynamically
  * - Protected roles (OWNER, BROADCASTER, RECOVERY) are managed by SecureOwnable
  * - Minimal interface for core RBAC operations
  * - Essential role management functions only
+ *
+ * @custom:security PROTECTED-ROLE POLICY (defense in layers):
+ * - RuntimeRBAC is **unauthorized** to modify protected roles (wallet add/revoke/remove).
+ * - For ADD_WALLET and REVOKE_WALLET we call _requireRoleNotProtected so batch ops cannot
+ *   change who holds system roles. For REMOVE_ROLE we rely on EngineBlox.removeRole, which
+ *   enforces the same policy at the library layer (cannot remove protected roles).
+ * - Function-permission updates on protected roles are intentionally supported for flexibility.
+ *   EngineBlox.removeFunctionFromRole allows removing a grant whenever the schema's **`isGrantRevocable`**
+ *   is true (including from protected roles); **`GrantNotRevocable`** applies when it is false.
+ * - The **only** place to modify system wallets (protected roles) is the SecureOwnable
+ *   security component (e.g. transferOwnershipRequest, broadcaster/recovery changes).
+ * - This layering is intentional: RBAC cannot touch protected roles; SecureOwnable is the
+ *   single source of truth for system wallet changes.
  */
 abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     using EngineBlox for EngineBlox.SecureOperationState;
@@ -44,18 +57,15 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
         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);
-        }
-        
+        _initializeBaseStateMachine(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+
         // Load RuntimeRBAC-specific definitions
         IDefinition.RolePermission memory permissions = RuntimeRBACDefinitions.getRolePermissions();
         _loadDefinitions(
             RuntimeRBACDefinitions.getFunctionSchemas(),
             permissions.roleHashes,
             permissions.functionPermissions,
-            true // Allow protected schemas for factory settings
+            true // Enforce all function schemas are protected
         );
     }
 
@@ -74,13 +84,19 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     /**
      * @dev Requests and approves a RBAC configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
-     * @return The transaction record
+     * @return The transaction ID of the applied batch
      * @notice OWNER signs, BROADCASTER executes according to RuntimeRBACDefinitions
      */
     function roleConfigBatchRequestAndApprove(
         EngineBlox.MetaTransaction memory metaTx
     ) public returns (uint256) {
         _validateBroadcaster(msg.sender);
+        SharedValidation.validateEmptyPayment(
+            metaTx.txRecord.payment.recipient,
+            metaTx.txRecord.payment.nativeTokenAmount,
+            metaTx.txRecord.payment.erc20TokenAddress,
+            metaTx.txRecord.payment.erc20TokenAmount
+        );
         EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
         return txRecord.txId;
     }
@@ -88,6 +104,13 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     /**
      * @dev External function that can only be called by the contract itself to execute a RBAC configuration batch
      * @param actions Encoded role configuration actions
+     *
+     * ## Role config batch ordering (required to avoid revert and gas waste)
+     *
+     * Actions must be ordered so that dependencies are satisfied:
+     * - **CREATE_ROLE** must appear before **ADD_WALLET** or **ADD_FUNCTION_TO_ROLE** for the same role; otherwise the role does not exist and the add will revert.
+     * - **REMOVE_ROLE** should be used only for an existing role; use **REVOKE_WALLET** first if the role has assigned wallets (optional but recommended for clarity).
+     * - For a given role, typical order: CREATE_ROLE → ADD_WALLET / ADD_FUNCTION_TO_ROLE as needed; to remove: REVOKE_WALLET (and REMOVE_FUNCTION_FROM_ROLE) as needed → REMOVE_ROLE.
      */
     function executeRoleConfigBatch(IRuntimeRBAC.RoleConfigAction[] calldata actions) external {
         _validateExecuteBySelf();
@@ -98,6 +121,9 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
 
     /**
      * @dev Reverts if the role is protected (prevents editing OWNER, BROADCASTER, RECOVERY via batch).
+     *      Used for ADD_WALLET and REVOKE_WALLET so RuntimeRBAC cannot change who holds system roles.
+     *      REMOVE_ROLE is not checked here; EngineBlox.removeRole enforces protected-role policy at
+     *      the library layer. See contract-level @custom:security PROTECTED-ROLE POLICY.
      * @param roleHash The role hash to check
      */
     function _requireRoleNotProtected(bytes32 roleHash) internal view {
@@ -109,66 +135,29 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     /**
      * @dev Internal helper to execute a RBAC configuration batch
      * @param actions Encoded role configuration actions
+     *
+     * @custom:order Required ordering to avoid revert and gas waste:
+     *   1. CREATE_ROLE before any ADD_WALLET or ADD_FUNCTION_TO_ROLE for that role.
+     *   2. REMOVE_ROLE only for a role that exists; prefer REVOKE_WALLET (and REMOVE_FUNCTION_FROM_ROLE) before REMOVE_ROLE when the role has members.
      */
     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) {
-                // Decode CREATE_ROLE action data
-                // Format: (string roleName, uint256 maxWallets)
-                (
-                    string memory roleName,
-                    uint256 maxWallets
-                ) = abi.decode(action.data, (string, uint256));
-
-                // Create the role in the secure state with isProtected = false
-                bytes32 roleHash = _createRole(roleName, maxWallets, false);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.CREATE_ROLE, roleHash, bytes4(0)));
+                _executeCreateRole(action.data);
             } else if (action.actionType == IRuntimeRBAC.RoleConfigActionType.REMOVE_ROLE) {
-                // Decode REMOVE_ROLE action data
-                // Format: (bytes32 roleHash)
-                (bytes32 roleHash) = abi.decode(action.data, (bytes32));
-                _removeRole(roleHash);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REMOVE_ROLE, roleHash, bytes4(0)));
+                _executeRemoveRole(action.data);
             } else if (action.actionType == IRuntimeRBAC.RoleConfigActionType.ADD_WALLET) {
-                // Decode ADD_WALLET action data
-                // Format: (bytes32 roleHash, address wallet)
-                (bytes32 roleHash, address wallet) = abi.decode(action.data, (bytes32, address));
-                _requireRoleNotProtected(roleHash);
-                _assignWallet(roleHash, wallet);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.ADD_WALLET, roleHash, bytes4(0)));
+                _executeAddWallet(action.data);
             } else if (action.actionType == IRuntimeRBAC.RoleConfigActionType.REVOKE_WALLET) {
-                // Decode REVOKE_WALLET action data
-                // Format: (bytes32 roleHash, address wallet)
-                (bytes32 roleHash, address wallet) = abi.decode(action.data, (bytes32, address));
-                _requireRoleNotProtected(roleHash);
-                _revokeWallet(roleHash, wallet);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REVOKE_WALLET, roleHash, bytes4(0)));
+                _executeRevokeWallet(action.data);
             } else if (action.actionType == IRuntimeRBAC.RoleConfigActionType.ADD_FUNCTION_TO_ROLE) {
-                // Decode ADD_FUNCTION_TO_ROLE action data
-                // Format: (bytes32 roleHash, FunctionPermission functionPermission)
-                (
-                    bytes32 roleHash,
-                    EngineBlox.FunctionPermission memory functionPermission
-                ) = abi.decode(action.data, (bytes32, EngineBlox.FunctionPermission));
-
-                _addFunctionToRole(roleHash, functionPermission);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.ADD_FUNCTION_TO_ROLE, roleHash, functionPermission.functionSelector));
+                _executeAddFunctionToRole(action.data);
             } else if (action.actionType == IRuntimeRBAC.RoleConfigActionType.REMOVE_FUNCTION_FROM_ROLE) {
-                // Decode REMOVE_FUNCTION_FROM_ROLE action data
-                // Format: (bytes32 roleHash, bytes4 functionSelector)
-                (bytes32 roleHash, bytes4 functionSelector) = abi.decode(action.data, (bytes32, bytes4));
-                _removeFunctionFromRole(roleHash, functionSelector);
-
-                _logComponentEvent(_encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REMOVE_FUNCTION_FROM_ROLE, roleHash, functionSelector));
+                _executeRemoveFunctionFromRole(action.data);
             } else {
                 revert SharedValidation.NotSupported();
             }
@@ -176,9 +165,89 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     }
 
     /**
-     * @dev Encodes RBAC config event payload for ComponentEvent. Decode as (RoleConfigActionType, bytes32 roleHash, bytes4 functionSelector).
+     * @dev Executes CREATE_ROLE: creates a new non-protected role
+     * @param data ABI-encoded (string roleName, uint256 maxWallets)
+     */
+    function _executeCreateRole(bytes calldata data) internal {
+        (string memory roleName, uint256 maxWallets) = abi.decode(data, (string, uint256));
+        bytes32 roleHash = _createRole(roleName, maxWallets, false);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.CREATE_ROLE, roleHash, bytes4(0), address(0));
+    }
+
+    /**
+     * @dev Executes REMOVE_ROLE: removes a role by hash.
+     *      Protected-role check is enforced in EngineBlox.removeRole (library layer); RuntimeRBAC
+     *      does not duplicate it here. SecureOwnable is the only component authorized to change
+     *      system wallets; RBAC is unauthorized to modify protected roles. See @custom:security
+     *      PROTECTED-ROLE POLICY on the contract.
+     * @param data ABI-encoded (bytes32 roleHash)
+     */
+    function _executeRemoveRole(bytes calldata data) internal {
+        (bytes32 roleHash) = abi.decode(data, (bytes32));
+        _removeRole(roleHash);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REMOVE_ROLE, roleHash, bytes4(0), address(0));
+    }
+
+    /**
+     * @dev Executes ADD_WALLET: assigns a wallet to a role (role must not be protected)
+     * @param data ABI-encoded (bytes32 roleHash, address wallet)
+     */
+    function _executeAddWallet(bytes calldata data) internal {
+        (bytes32 roleHash, address wallet) = abi.decode(data, (bytes32, address));
+        _requireRoleNotProtected(roleHash);
+        _assignWallet(roleHash, wallet);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.ADD_WALLET, roleHash, bytes4(0), wallet);
+    }
+
+    /**
+     * @dev Executes REVOKE_WALLET: revokes a wallet from a role (role must not be protected)
+     * @param data ABI-encoded (bytes32 roleHash, address wallet)
+     */
+    function _executeRevokeWallet(bytes calldata data) internal {
+        (bytes32 roleHash, address wallet) = abi.decode(data, (bytes32, address));
+        _requireRoleNotProtected(roleHash);
+        _revokeWallet(roleHash, wallet);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REVOKE_WALLET, roleHash, bytes4(0), wallet);
+    }
+
+    /**
+     * @dev Executes ADD_FUNCTION_TO_ROLE: adds a function permission to a role.
+     * @param data ABI-encoded (bytes32 roleHash, FunctionPermission functionPermission)
+     * @custom:security By design we allow adding function permissions to protected roles (OWNER, BROADCASTER, RECOVERY)
+     *                 to retain flexibility to grant new function permissions to system roles; only wallet add/revoke
+     *                 are restricted on protected roles.
+     */
+    function _executeAddFunctionToRole(bytes calldata data) internal {
+        (
+            bytes32 roleHash,
+            EngineBlox.FunctionPermission memory functionPermission
+        ) = abi.decode(data, (bytes32, EngineBlox.FunctionPermission));
+        _addFunctionToRole(roleHash, functionPermission);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.ADD_FUNCTION_TO_ROLE, roleHash, functionPermission.functionSelector, address(0));
+    }
+
+    /**
+     * @dev Executes REMOVE_FUNCTION_FROM_ROLE: removes a function permission from a role.
+     * @param data ABI-encoded (bytes32 roleHash, bytes4 functionSelector)
+     * @custom:security By design we allow removing function permissions from protected roles (OWNER, BROADCASTER, RECOVERY)
+     *                 for flexibility; only wallet add/revoke are restricted on protected roles. EngineBlox.removeFunctionFromRole
+     *                 enforces **`GrantNotRevocable`** when the schema's **`isGrantRevocable`** is false; when true,
+     *                 grants may be removed from protected roles as well as custom roles.
+     */
+    function _executeRemoveFunctionFromRole(bytes calldata data) internal {
+        (bytes32 roleHash, bytes4 functionSelector) = abi.decode(data, (bytes32, bytes4));
+        _removeFunctionFromRole(roleHash, functionSelector);
+        _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType.REMOVE_FUNCTION_FROM_ROLE, roleHash, functionSelector, address(0));
+    }
+
+    /**
+     * @dev Encodes and logs a role config event via ComponentEvent. Payload decodes as (RoleConfigActionType, bytes32 roleHash, bytes4 functionSelector, address wallet).
+     * @param action The role config action type
+     * @param roleHash The role hash
+     * @param selector The function selector (or zero for N/A)
+     * @param wallet The wallet address (or zero for actions that do not apply to a wallet)
      */
-    function _encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType action, bytes32 roleHash, bytes4 selector) internal pure returns (bytes memory) {
-        return abi.encode(action, roleHash, selector);
+    function _logRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType action, bytes32 roleHash, bytes4 selector, address wallet) internal {
+        _logComponentEvent(abi.encode(action, roleHash, selector, wallet));
     }
 }

package/core/access/interface/IRuntimeRBAC.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.35;
 
 import "../../lib/EngineBlox.sol";
 
@@ -12,7 +12,7 @@ import "../../lib/EngineBlox.sol";
  * 
  * Key Features:
  * - Batch-based role configuration (atomic operations)
- * - Runtime function schema registration
+ * - Role and permission management (function schema registration is handled by GuardController)
  * - Integration with EngineBlox for secure operations
  * - Query functions for role and permission inspection
  * 
@@ -47,7 +47,7 @@ interface IRuntimeRBAC {
     /**
      * @dev Requests and approves a RBAC configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
-     * @return The transaction record
+     * @return The transaction ID of the applied batch
      */
     function roleConfigBatchRequestAndApprove(
         EngineBlox.MetaTransaction memory metaTx

package/core/access/lib/definitions/RuntimeRBACDefinitions.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.35;
 
 import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import "../../../lib/EngineBlox.sol";
@@ -30,7 +30,7 @@ library RuntimeRBACDefinitions {
     bytes4 public constant ROLE_CONFIG_BATCH_META_SELECTOR =
         bytes4(
             keccak256(
-                "roleConfigBatchRequestAndApprove(((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))"
+                "roleConfigBatchRequestAndApprove(((uint256,uint256,uint8,(address,address,uint256,uint256,bytes32,bytes4,bytes),bytes32,bytes32,(address,uint256,address,uint256)),(uint256,uint256,address,bytes4,uint8,uint256,uint256,address),bytes32,bytes,bytes))"
             )
         );
     
@@ -57,12 +57,14 @@ library RuntimeRBACDefinitions {
         handlerForSelectors[0] = ROLE_CONFIG_BATCH_EXECUTE_SELECTOR;
         
         schemas[0] = EngineBlox.FunctionSchema({
-            functionSignature: "roleConfigBatchRequestAndApprove(((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))",
+            functionSignature: "roleConfigBatchRequestAndApprove(((uint256,uint256,uint8,(address,address,uint256,uint256,bytes32,bytes4,bytes),bytes32,bytes32,(address,uint256,address,uint256)),(uint256,uint256,address,bytes4,uint8,uint256,uint256,address),bytes32,bytes,bytes))",
             functionSelector: ROLE_CONFIG_BATCH_META_SELECTOR,
             operationType: ROLE_CONFIG_BATCH,
             operationName: "ROLE_CONFIG_BATCH",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaRequestApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
+            isGrantRevocable: false,
             handlerForSelectors: handlerForSelectors
         });
         
@@ -83,7 +85,9 @@ library RuntimeRBACDefinitions {
             operationType: ROLE_CONFIG_BATCH,
             operationName: "ROLE_CONFIG_BATCH",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(executionActions),
+            enforceHandlerRelations: false,
             isProtected: true,
+            isGrantRevocable: false,
             handlerForSelectors: executionHandlerForSelectors
         });
         
@@ -197,6 +201,66 @@ library RuntimeRBACDefinitions {
         formats[5] = "(bytes32 roleHash, bytes4 functionSelector)";
     }
 
+    // ============ ROLE CONFIG ACTION DATA ENCODERS ============
+    // Use these helpers to build action.data for each RoleConfigActionType without reading the contract.
+    // Each encoder returns bytes suitable for RoleConfigAction(actionType, data).
+
+    /**
+     * @dev Encodes data for CREATE_ROLE. Use with RoleConfigActionType.CREATE_ROLE.
+     * @param roleName Name of the role to create
+     * @param maxWallets Maximum number of wallets that can be assigned to this role
+     */
+    function encodeCreateRole(string memory roleName, uint256 maxWallets) public pure returns (bytes memory) {
+        return abi.encode(roleName, maxWallets);
+    }
+
+    /**
+     * @dev Encodes data for REMOVE_ROLE. Use with RoleConfigActionType.REMOVE_ROLE.
+     * @param roleHash keccak256 hash of the role name
+     */
+    function encodeRemoveRole(bytes32 roleHash) public pure returns (bytes memory) {
+        return abi.encode(roleHash);
+    }
+
+    /**
+     * @dev Encodes data for ADD_WALLET. Use with RoleConfigActionType.ADD_WALLET.
+     * @param roleHash Role to add the wallet to
+     * @param wallet Address to assign to the role
+     */
+    function encodeAddWallet(bytes32 roleHash, address wallet) public pure returns (bytes memory) {
+        return abi.encode(roleHash, wallet);
+    }
+
+    /**
+     * @dev Encodes data for REVOKE_WALLET. Use with RoleConfigActionType.REVOKE_WALLET.
+     * @param roleHash Role to revoke the wallet from
+     * @param wallet Address to revoke
+     */
+    function encodeRevokeWallet(bytes32 roleHash, address wallet) public pure returns (bytes memory) {
+        return abi.encode(roleHash, wallet);
+    }
+
+    /**
+     * @dev Encodes data for ADD_FUNCTION_TO_ROLE. Use with RoleConfigActionType.ADD_FUNCTION_TO_ROLE.
+     * @param roleHash Role to grant the function permission to
+     * @param functionPermission FunctionPermission (functionSelector, grantedActionsBitmap, handlerForSelectors)
+     */
+    function encodeAddFunctionToRole(
+        bytes32 roleHash,
+        EngineBlox.FunctionPermission memory functionPermission
+    ) public pure returns (bytes memory) {
+        return abi.encode(roleHash, functionPermission);
+    }
+
+    /**
+     * @dev Encodes data for REMOVE_FUNCTION_FROM_ROLE. Use with RoleConfigActionType.REMOVE_FUNCTION_FROM_ROLE.
+     * @param roleHash Role to remove the function from
+     * @param functionSelector Selector of the function to remove
+     */
+    function encodeRemoveFunctionFromRole(bytes32 roleHash, bytes4 functionSelector) public pure returns (bytes memory) {
+        return abi.encode(roleHash, functionSelector);
+    }
+
     /**
      * @dev Creates execution params for a RBAC configuration batch (pure helper for EngineBlox).
      * @param actions Encoded role configuration actions (IRuntimeRBAC.RoleConfigAction[] layout)