@bloxchain/contracts 1.0.0-alpha → 1.0.0-alpha.10

package/abi/SimpleVaultDefinitions.abi.json

@@ -246,5 +246,24 @@
     ],
     "stateMutability": "pure",
     "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes4",
+        "name": "interfaceId",
+        "type": "bytes4"
+      }
+    ],
+    "name": "supportsInterface",
+    "outputs": [
+      {
+        "internalType": "bool",
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "stateMutability": "pure",
+    "type": "function"
   }
 ]

package/components/README.md

@@ -0,0 +1,8 @@
+# Bloxchain Components
+
+Official **components** built on top of `core/` that form a component library for building applications. These are maintained by the protocol team and sit outside the minimal engine.
+
+
+## Structure
+
+Subfolders will be added by domain as components are added.

package/core/access/RuntimeRBAC.sol

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.33;
+
+// Contract imports
+import "../base/BaseStateMachine.sol";
+import "../lib/EngineBlox.sol";
+import "../lib/utils/SharedValidation.sol";
+import "./lib/definitions/RuntimeRBACDefinitions.sol";
+import "../lib/interfaces/IDefinition.sol";
+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
+ */
+abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
+    using EngineBlox for EngineBlox.SecureOperationState;
+    using SharedValidation for *;
+
+    /**
+     * @notice Initializer to initialize RuntimeRBAC
+     * @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 RuntimeRBAC-specific definitions
+        IDefinition.RolePermission memory permissions = RuntimeRBACDefinitions.getRolePermissions();
+        _loadDefinitions(
+            RuntimeRBACDefinitions.getFunctionSchemas(),
+            permissions.roleHashes,
+            permissions.functionPermissions,
+            true // Allow protected schemas for factory settings
+        );
+    }
+
+    // ============ INTERFACE SUPPORT ============
+
+    /**
+     * @dev See {IERC165-supportsInterface}.
+     * @notice Adds IRuntimeRBAC interface ID for component detection
+     */
+    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+        return interfaceId == type(IRuntimeRBAC).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    // ============ ROLE CONFIGURATION BATCH INTERFACE ============
+
+    /**
+     * @dev Requests and approves a RBAC configuration batch using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     * @notice OWNER signs, BROADCASTER executes according to RuntimeRBACDefinitions
+     */
+    function roleConfigBatchRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) public returns (uint256) {
+        _validateBroadcaster(msg.sender);
+        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
+        return txRecord.txId;
+    }
+
+    /**
+     * @dev External function that can only be called by the contract itself to execute a RBAC configuration batch
+     * @param actions Encoded role configuration actions
+     */
+    function executeRoleConfigBatch(IRuntimeRBAC.RoleConfigAction[] calldata actions) external {
+        _validateExecuteBySelf();
+        _executeRoleConfigBatch(actions);
+    }
+
+    // ============ HELPER FUNCTIONS ============
+
+    /**
+     * @dev Reverts if the role is protected (prevents editing OWNER, BROADCASTER, RECOVERY via batch).
+     * @param roleHash The role hash to check
+     */
+    function _requireRoleNotProtected(bytes32 roleHash) internal view {
+        if (_getSecureState().roles[roleHash].isProtected) {
+            revert SharedValidation.CannotModifyProtected(roleHash);
+        }
+    }
+
+    /**
+     * @dev Internal helper to execute a RBAC configuration batch
+     * @param actions Encoded role configuration actions
+     */
+    function _executeRoleConfigBatch(IRuntimeRBAC.RoleConfigAction[] calldata actions) internal {
+        _validateBatchSize(actions.length);
+
+        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)));
+            } 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)));
+            } 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)));
+            } 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)));
+            } 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));
+            } 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));
+            } else {
+                revert SharedValidation.NotSupported();
+            }
+        }
+    }
+
+    /**
+     * @dev Encodes RBAC config event payload for ComponentEvent. Decode as (RoleConfigActionType, bytes32 roleHash, bytes4 functionSelector).
+     */
+    function _encodeRoleConfigEvent(IRuntimeRBAC.RoleConfigActionType action, bytes32 roleHash, bytes4 selector) internal pure returns (bytes memory) {
+        return abi.encode(action, roleHash, selector);
+    }
+}

package/core/access/interface/IRuntimeRBAC.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.33;
+
+import "../../lib/EngineBlox.sol";
+
+/**
+ * @title IRuntimeRBAC
+ * @dev Interface for Runtime Role-Based Access Control system
+ * 
+ * This interface defines the functions for managing runtime roles through batch operations.
+ * All role management operations are performed via the batch interface for atomic execution.
+ * 
+ * Key Features:
+ * - Batch-based role configuration (atomic operations)
+ * - Runtime function schema registration
+ * - Integration with EngineBlox for secure operations
+ * - Query functions for role and permission inspection
+ * 
+ * Note: This contract inherits from BaseStateMachine which provides additional query functions
+ * such as getRole(), hasRole(), getActiveRolePermissions(), getSupportedRoles(), etc.
+ */
+interface IRuntimeRBAC {
+    /**
+     * @dev Action types for batched RBAC configuration
+     */
+    enum RoleConfigActionType {
+        CREATE_ROLE,
+        REMOVE_ROLE,
+        ADD_WALLET,
+        REVOKE_WALLET,
+        ADD_FUNCTION_TO_ROLE,
+        REMOVE_FUNCTION_FROM_ROLE
+    }
+
+    /**
+     * @dev Encodes a single RBAC configuration action in a batch
+     */
+    struct RoleConfigAction {
+        RoleConfigActionType actionType;
+        bytes data;
+    }
+
+    /// @dev RBAC config changes are emitted via BaseStateMachine.ComponentEvent with functionSelector = msg.sig (executeRoleConfigBatch). Decode data as (RoleConfigActionType, bytes32 roleHash, bytes4 functionSelector).
+
+    // ============ ROLE CONFIGURATION BATCH INTERFACE ============
+
+    /**
+     * @dev Requests and approves a RBAC configuration batch using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction record
+     */
+    function roleConfigBatchRequestAndApprove(
+        EngineBlox.MetaTransaction memory metaTx
+    ) external returns (uint256);
+}

package/{contracts/core → core}/access/lib/definitions/RuntimeRBACDefinitions.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MPL-2.0
 pragma solidity 0.8.33;
 
+import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import "../../../lib/EngineBlox.sol";
-import "../../../../interfaces/IDefinition.sol";
+import "../../../lib/interfaces/IDefinition.sol";
+import "../../../access/interface/IRuntimeRBAC.sol";
 
 /**
  * @title RuntimeRBACDefinitions
@@ -165,4 +167,122 @@ library RuntimeRBACDefinitions {
             functionPermissions: functionPermissions
         });
     }
+
+    /**
+     * @dev Returns all available RoleConfig action types and their decode formats for discovery.
+     * @return actionNames Human-readable action names (same order as RoleConfigActionType enum)
+     * @return formats ABI decode format for each action's data, e.g. "(string roleName, uint256 maxWallets)"
+     * @notice Use with RoleConfigActionType enum: actionNames[i] and formats[i] describe enum value i
+     */
+    function getRoleConfigActionSpecs() public pure returns (string[] memory actionNames, string[] memory formats) {
+        actionNames = new string[](6);
+        formats = new string[](6);
+
+        actionNames[0] = "CREATE_ROLE";
+        formats[0] = "(string roleName, uint256 maxWallets)";
+
+        actionNames[1] = "REMOVE_ROLE";
+        formats[1] = "(bytes32 roleHash)";
+
+        actionNames[2] = "ADD_WALLET";
+        formats[2] = "(bytes32 roleHash, address wallet)";
+
+        actionNames[3] = "REVOKE_WALLET";
+        formats[3] = "(bytes32 roleHash, address wallet)";
+
+        actionNames[4] = "ADD_FUNCTION_TO_ROLE";
+        formats[4] = "(bytes32 roleHash, FunctionPermission functionPermission)";
+
+        actionNames[5] = "REMOVE_FUNCTION_FROM_ROLE";
+        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)
+     * @return The execution params for EngineBlox
+     */
+    function roleConfigBatchExecutionParams(
+        IRuntimeRBAC.RoleConfigAction[] memory actions
+    ) public pure returns (bytes memory) {
+        return abi.encode(actions);
+    }
+
+    /**
+     * @dev Creates execution params from pre-encoded actions (e.g. abi.encode(RuntimeRBAC.RoleConfigAction[])).
+     * Use when callers have RuntimeRBAC.RoleConfigAction[] and same encoding applies.
+     * @param preEncoded ABI-encoded role config actions array
+     * @return The execution params for EngineBlox
+     */
+    function roleConfigBatchExecutionParams(bytes memory preEncoded) public pure returns (bytes memory) {
+        return preEncoded;
+    }
+
+    /**
+     * @dev ERC165: report support for IDefinition and IERC165 when this library is used at an address.
+     * IDefinition extends IERC165; both interface IDs must be reported for ERC165 compliance.
+     */
+    function supportsInterface(bytes4 interfaceId) external pure returns (bool) {
+        return interfaceId == type(IERC165).interfaceId || interfaceId == type(IDefinition).interfaceId;
+    }
 }