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

package/{contracts/core → core}/base/BaseStateMachine.sol

@@ -8,7 +8,7 @@ import "@openzeppelin/contracts-upgradeable/utils/ReentrancyGuardUpgradeable.sol
 
 // Contracts imports
 import "../lib/EngineBlox.sol";
-import "../../utils/SharedValidation.sol";
+import "../lib/utils/SharedValidation.sol";
 import "./interface/IBaseStateMachine.sol";
 
 /**
@@ -42,31 +42,13 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
 
     EngineBlox.SecureOperationState internal _secureState;
 
-    // Events for core state machine operations
-    event TransactionRequested(
-        uint256 indexed txId,
-        address indexed requester,
-        bytes32 indexed operationType,
-        uint256 releaseTime
-    );
-    
-    event TransactionApproved(
-        uint256 indexed txId,
-        bytes32 indexed operationType,
-        address indexed approver
-    );
-    
-    event TransactionCancelled(
-        uint256 indexed txId,
-        bytes32 indexed operationType,
-        address indexed canceller
-    );
-    
-    event TransactionExecuted(
-        uint256 indexed txId,
-        bytes32 indexed operationType,
-        bool success
-    );
+    /**
+     * @dev Unified component event for SecureOwnable, GuardController, RuntimeRBAC.
+     * Indexers filter by functionSelector (msg.sig at emit site) and decode data (abi-encoded payload).
+     * @param functionSelector The function selector (msg.sig) at the emit site; used by indexers to filter
+     * @param data ABI-encoded payload associated with the event
+     */
+    event ComponentEvent(bytes4 indexed functionSelector, bytes data);
 
     /**
      * @notice Initializes the base state machine core
@@ -157,7 +139,7 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
         bytes4 functionSelector,
         bytes memory params
     ) internal virtual returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.txRequest(
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txRequest(
             _getSecureState(),
             requester,
             target,
@@ -168,6 +150,48 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
             functionSelector,
             params
         );
+        _postActionHook(txRecord);
+        return txRecord;
+    }
+
+    /**
+     * @dev Centralized function to request a transaction with payment details attached from the start
+     * @param requester The address requesting the transaction
+     * @param target The target contract address
+     * @param value The ETH value to send (0 for standard function calls)
+     * @param gasLimit The gas limit for execution
+     * @param operationType The type of operation
+     * @param functionSelector The function selector for execution (NATIVE_TRANSFER_SELECTOR for simple native token transfers)
+     * @param params The encoded parameters for the function (empty for simple native token transfers)
+     * @param paymentDetails The payment details to attach to the transaction
+     * @return The created transaction record with payment set
+     * @notice Validates request permissions (same as request without payment)
+     * @notice This function is virtual to allow extensions to add hook functionality
+     */
+    function _requestTransactionWithPayment(
+        address requester,
+        address target,
+        uint256 value,
+        uint256 gasLimit,
+        bytes32 operationType,
+        bytes4 functionSelector,
+        bytes memory params,
+        EngineBlox.PaymentDetails memory paymentDetails
+    ) internal virtual returns (EngineBlox.TxRecord memory) {
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txRequestWithPayment(
+            _getSecureState(),
+            requester,
+            target,
+            value,
+            gasLimit,
+            operationType,
+            bytes4(msg.sig),
+            functionSelector,
+            params,
+            paymentDetails
+        );
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
@@ -182,7 +206,9 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     function _approveTransaction(
         uint256 txId
     ) internal virtual nonReentrant returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.txDelayedApproval(_getSecureState(), txId, bytes4(msg.sig));
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txDelayedApproval(_getSecureState(), txId, bytes4(msg.sig));
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
@@ -197,7 +223,9 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     function _approveTransactionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx
     ) internal virtual nonReentrant returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.txApprovalWithMetaTx(_getSecureState(), metaTx);
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txApprovalWithMetaTx(_getSecureState(), metaTx);
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
@@ -211,7 +239,9 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     function _cancelTransaction(
         uint256 txId
     ) internal virtual returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.txCancellation(_getSecureState(), txId, bytes4(msg.sig));
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txCancellation(_getSecureState(), txId, bytes4(msg.sig));
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
@@ -225,7 +255,9 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     function _cancelTransactionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx
     ) internal virtual returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.txCancellationWithMetaTx(_getSecureState(), metaTx);
+        EngineBlox.TxRecord memory txRecord = EngineBlox.txCancellationWithMetaTx(_getSecureState(), metaTx);
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
@@ -240,21 +272,51 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     function _requestAndApproveTransaction(
         EngineBlox.MetaTransaction memory metaTx
     ) internal virtual nonReentrant returns (EngineBlox.TxRecord memory) {
-        return EngineBlox.requestAndApprove(_getSecureState(), metaTx);
+        EngineBlox.TxRecord memory txRecord = EngineBlox.requestAndApprove(_getSecureState(), metaTx);
+        _postActionHook(txRecord);
+        return txRecord;
     }
 
     /**
-     * @dev Centralized function to update payment details for a pending transaction
-     * @param txId The transaction ID to update payment for
-     * @param paymentDetails The new payment details
-     * @notice This function is virtual to allow extensions to add hook functionality
+     * @dev Post-action hook invoked after any transaction operation that produces a TxRecord.
+     *      Override in derived contracts to add centralized post-tx logic (e.g. notifications, side effects).
+     * @param txRecord The transaction record produced by the operation
      */
-    function _updatePaymentForTransaction(
-        uint256 txId,
-        EngineBlox.PaymentDetails memory paymentDetails
-    ) internal virtual returns (EngineBlox.TxRecord memory) {
-        EngineBlox.updatePaymentForTransaction(_getSecureState(), txId, paymentDetails);
-        return _secureState.getTxRecord(txId);
+    function _postActionHook(EngineBlox.TxRecord memory txRecord) internal virtual {}
+
+    // ============ HOOK MANAGEMENT ============
+
+    /**
+     * @dev Sets the hook contract for a function selector (internal; no access control).
+     *      Extensions (e.g. HookManager) may expose an external setHook with owner check.
+     * @param functionSelector The function selector
+     * @param hook The hook contract address (must not be zero)
+     */
+    function _setHook(bytes4 functionSelector, address hook) internal {
+        EngineBlox.addTargetToFunctionHooks(_getSecureState(), functionSelector, hook);
+        _logComponentEvent(abi.encode(functionSelector, hook));
+    }
+
+    /**
+     * @dev Clears the hook contract for a function selector (internal; no access control).
+     *      Extensions may expose an external clearHook with owner check.
+     * @param functionSelector The function selector
+     * @param hook The hook contract address to remove (must not be zero)
+     */
+    function _clearHook(bytes4 functionSelector, address hook) internal {
+        EngineBlox.removeTargetFromFunctionHooks(_getSecureState(), functionSelector, hook);
+        _logComponentEvent(abi.encode(functionSelector, hook));
+    }
+
+    /**
+     * @dev Returns all configured hooks for a function selector
+     * @param functionSelector The function selector
+     * @return hooks Array of hook contract addresses
+     * @notice Requires caller to have any role (via _validateAnyRole) to limit information visibility
+     */
+    function getHooks(bytes4 functionSelector) public view returns (address[] memory hooks) {
+        _validateAnyRole();
+        return EngineBlox.getFunctionHookTargets(_getSecureState(), functionSelector);
     }
 
     // ============ META-TRANSACTION UTILITIES ============
@@ -441,6 +503,18 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
         return EngineBlox.getWalletRoles(_getSecureState(), wallet);
     }
 
+    /**
+     * @dev Gets all authorized wallets for a role
+     * @param roleHash The role hash to get wallets for
+     * @return Array of authorized wallet addresses
+     * @notice Requires caller to have any role (via _validateAnyRole) to limit information visibility
+     */
+    function getWalletsInRole(bytes32 roleHash) public view returns (address[] memory) {
+        _validateAnyRole();
+        _validateRoleExists(roleHash);
+        return _getAuthorizedWallets(roleHash);
+    }
+
     /**
      * @dev Checks if a function schema exists
      * @param functionSelector The function selector to check
@@ -460,6 +534,16 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
         return _secureState.isActionSupportedByFunction(functionSelector, action);
     }
 
+    /**
+     * @dev Gets function schema information
+     * @param functionSelector The function selector to get information for
+     * @return The full FunctionSchema struct (functionSignature, functionSelector, operationType, operationName, supportedActionsBitmap, isProtected, handlerForSelectors)
+     */
+    function getFunctionSchema(bytes4 functionSelector) external view returns (EngineBlox.FunctionSchema memory) {
+        _validateAnyRole();
+        return _secureState.getFunctionSchema(functionSelector);
+    }
+
     /**
      * @dev Gets the function permissions for a specific role
      * @param roleHash The hash of the role to get permissions for
@@ -548,15 +632,7 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
      * @return Array of authorized wallet addresses
      */
     function _getAuthorizedWallets(bytes32 roleHash) internal view returns (address[] memory) {
-        EngineBlox.Role storage role = _secureState.roles[roleHash];
-        uint256 walletCount = role.walletCount;
-
-        address[] memory wallets = new address[](walletCount);
-        for (uint256 i = 0; i < walletCount; i++) {
-            wallets[i] = _getAuthorizedWalletAt(roleHash, i);
-        }
-
-        return wallets;
+        return EngineBlox._getAuthorizedWallets(_getSecureState(), roleHash);
     }
 
     /**
@@ -623,7 +699,9 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
      * @notice This function is virtual to allow extensions to add hook functionality
      */
     function _updateTimeLockPeriod(uint256 newTimeLockPeriodSec) internal virtual {
+        uint256 oldPeriod = getTimeLockPeriodSec();
         EngineBlox.updateTimeLockPeriod(_getSecureState(), newTimeLockPeriodSec);
+        _logComponentEvent(abi.encode(oldPeriod, newTimeLockPeriodSec));
     }
 
     // ============ FUNCTION SCHEMA MANAGEMENT ============
@@ -707,6 +785,40 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
         EngineBlox._validateRoleExists(_getSecureState(), roleHash);
     }
 
+    /**
+     * @dev Centralized function to validate that the caller is the contract itself (for execution-only entry points).
+     */
+    function _validateExecuteBySelf() internal view {
+        SharedValidation.validateInternalCall(address(this));
+    }
+
+    /**
+     * @dev Centralized function to validate batch size against EngineBlox.MAX_BATCH_SIZE.
+     * @param length The batch length to validate
+     */
+    function _validateBatchSize(uint256 length) internal pure {
+        SharedValidation.validateBatchSize(length, EngineBlox.MAX_BATCH_SIZE);
+    }
+
+    // ============ MACRO SELECTORS ============
+
+    /**
+     * @dev Adds a function selector to the system macro selectors set.
+     *      Macro selectors are allowed to target address(this) for system-level operations.
+     * @param functionSelector The function selector to add (e.g. NATIVE_TRANSFER_SELECTOR).
+     */
+    function _addMacroSelector(bytes4 functionSelector) internal {
+        EngineBlox.addMacroSelector(_getSecureState(), functionSelector);
+    }
+
+    /**
+     * @dev Returns true if the given function selector is in the system macro selectors set.
+     * @param functionSelector The function selector to check.
+     */
+    function _isMacroSelector(bytes4 functionSelector) internal view returns (bool) {
+        return EngineBlox.isMacroSelector(_getSecureState(), functionSelector);
+    }
+
     // ============ UTILITY FUNCTIONS ============
 
     /**
@@ -750,11 +862,13 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
     }
 
     /**
-     * @dev Centralized function to get all whitelisted targets for a function selector
+     * @dev Gets all whitelisted targets for a function selector
      * @param functionSelector The function selector
      * @return Array of whitelisted target addresses
+     * @notice Requires caller to have any role (via _validateAnyRole) to limit information visibility
      */
-    function _getFunctionWhitelistTargets(bytes4 functionSelector) internal view returns (address[] memory) {
+    function getFunctionWhitelistTargets(bytes4 functionSelector) public view returns (address[] memory) {
+        _validateAnyRole();
         return _getSecureState().getFunctionWhitelistTargets(functionSelector);
     }
 
@@ -766,14 +880,24 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
      * @param functionSchemas Array of function schema definitions  
      * @param roleHashes Array of role hashes
      * @param functionPermissions Array of function permissions (parallel to roleHashes)
+     * @param allowProtectedSchemas Whether to allow protected function schemas (default: true for factory settings)
+     * @notice When allowProtectedSchemas is false, reverts if any function schema is protected
+     * @notice This allows custom definitions to be restricted from creating protected schemas
      */
     function _loadDefinitions(
         EngineBlox.FunctionSchema[] memory functionSchemas,
         bytes32[] memory roleHashes,
-        EngineBlox.FunctionPermission[] memory functionPermissions
+        EngineBlox.FunctionPermission[] memory functionPermissions,
+        bool allowProtectedSchemas
     ) internal {
         // Load function schemas
         for (uint256 i = 0; i < functionSchemas.length; i++) {
+            // Validate protected schemas if not allowed (for custom definitions)
+            if (!allowProtectedSchemas && functionSchemas[i].isProtected) {
+                revert SharedValidation.CannotModifyProtected(
+                    bytes32(functionSchemas[i].functionSelector)
+                );
+            }
             EngineBlox.createFunctionSchema(
                 _getSecureState(),
                 functionSchemas[i].functionSignature,
@@ -831,4 +955,13 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
         }
     }
 
+    /**
+     * @dev Centralized component event logging for SecureOwnable, GuardController, RuntimeRBAC.
+     * Uses msg.sig as the event index so callers only pass encoded data.
+     * @param data abi.encode of event parameters
+     */
+    function _logComponentEvent(bytes memory data) internal {
+        emit ComponentEvent(msg.sig, data);
+    }
+
 }

package/{contracts/core → core}/base/interface/IBaseStateMachine.sol

@@ -105,6 +105,13 @@ interface IBaseStateMachine {
      */
     function isActionSupportedByFunction(bytes4 functionSelector, EngineBlox.TxAction action) external view returns (bool);
 
+    /**
+     * @dev Gets function schema information
+     * @param functionSelector The function selector to get information for
+     * @return The full FunctionSchema struct
+     */
+    function getFunctionSchema(bytes4 functionSelector) external view returns (EngineBlox.FunctionSchema memory);
+
     /**
      * @dev Gets the function permissions for a specific role
      * @param roleHash The hash of the role to get permissions for