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

package/abi/BaseStateMachine.abi.json

@@ -1141,6 +1141,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/EngineBlox.abi.json

@@ -349,6 +349,28 @@
     "name": "MetaTxExpired",
     "type": "error"
   },
+  {
+    "inputs": [
+      {
+        "internalType": "uint256",
+        "name": "txId",
+        "type": "uint256"
+      }
+    ],
+    "name": "MetaTxPaymentMismatchStoredTx",
+    "type": "error"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "uint256",
+        "name": "txId",
+        "type": "uint256"
+      }
+    ],
+    "name": "MetaTxRecordMismatchStoredTx",
+    "type": "error"
+  },
   {
     "inputs": [
       {

package/abi/GuardController.abi.json

@@ -858,6 +858,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/GuardControllerDefinitions.abi.json

@@ -160,6 +160,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/IDefinition.abi.json

@@ -30,6 +30,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/RuntimeRBAC.abi.json

@@ -858,6 +858,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/RuntimeRBACDefinitions.abi.json

@@ -69,6 +69,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/SecureOwnable.abi.json

@@ -884,6 +884,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/abi/SecureOwnableDefinitions.abi.json

@@ -290,6 +290,11 @@
             "name": "supportedActionsBitmap",
             "type": "uint16"
           },
+          {
+            "internalType": "bool",
+            "name": "enforceHandlerRelations",
+            "type": "bool"
+          },
           {
             "internalType": "bool",
             "name": "isProtected",

package/core/access/RuntimeRBAC.sol

@@ -12,18 +12,28 @@ 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).
+ * - 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;
@@ -71,7 +81,7 @@ 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(
@@ -85,6 +95,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();
@@ -95,6 +112,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 {
@@ -106,6 +126,10 @@ 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);
@@ -142,7 +166,11 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     }
 
     /**
-     * @dev Executes REMOVE_ROLE: removes a role by hash
+     * @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 {
@@ -174,8 +202,11 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     }
 
     /**
-     * @dev Executes ADD_FUNCTION_TO_ROLE: adds a function permission to a role
+     * @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 {
         (
@@ -187,8 +218,11 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     }
 
     /**
-     * @dev Executes REMOVE_FUNCTION_FROM_ROLE: removes a function permission from a role
+     * @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)
+     *                 to retain flexibility to adjust which functions system roles can call; only wallet add/revoke
+     *                 are restricted on protected roles.
      */
     function _executeRemoveFunctionFromRole(bytes calldata data) internal {
         (bytes32 roleHash, bytes4 functionSelector) = abi.decode(data, (bytes32, bytes4));

package/core/access/interface/IRuntimeRBAC.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