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

package/{contracts/core → core}/execution/GuardController.sol

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: MPL-2.0
 pragma solidity 0.8.33;
 
-import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 import "../base/BaseStateMachine.sol";
-import "../../utils/SharedValidation.sol";
+import "../lib/utils/SharedValidation.sol";
 import "./lib/definitions/GuardControllerDefinitions.sol";
-import "../../interfaces/IDefinition.sol";
+import "../lib/interfaces/IDefinition.sol";
 import "./interface/IGuardController.sol";
 
 /**
@@ -58,41 +57,6 @@ import "./interface/IGuardController.sol";
 abstract contract GuardController is BaseStateMachine {
     using EngineBlox for EngineBlox.SecureOperationState;
 
-    /**
-     * @dev Action types for batched Guard configuration
-     */
-    enum GuardConfigActionType {
-        ADD_TARGET_TO_WHITELIST,
-        REMOVE_TARGET_FROM_WHITELIST,
-        REGISTER_FUNCTION,
-        UNREGISTER_FUNCTION
-    }
-
-    /**
-     * @dev Encodes a single Guard configuration action in a batch
-     */
-    struct GuardConfigAction {
-        GuardConfigActionType actionType;
-        bytes data;
-    }
-
-    // ============ EVENTS ============
-    
-    /**
-     * @dev Unified event for all Guard configuration changes applied via batches
-     *
-     * - actionType: the high-level type of configuration action
-     * - functionSelector: affected function selector (if applicable, otherwise 0)
-     * - target: affected target address (if applicable, otherwise 0)
-     * - data: optional action-specific payload (kept minimal for size; decoded off-chain if needed)
-     */
-    event GuardConfigApplied(
-        GuardConfigActionType indexed actionType,
-        bytes4 indexed functionSelector,
-        address indexed target,
-        bytes data
-    );
-
     /**
      * @notice Initializer to initialize GuardController
      * @param initialOwner The initial owner address
@@ -118,7 +82,8 @@ abstract contract GuardController is BaseStateMachine {
         _loadDefinitions(
             GuardControllerDefinitions.getFunctionSchemas(),
             guardControllerPermissions.roleHashes,
-            guardControllerPermissions.functionPermissions
+            guardControllerPermissions.functionPermissions,
+            true // Allow protected schemas for factory settings
         );
     }
 
@@ -155,10 +120,7 @@ abstract contract GuardController is BaseStateMachine {
         bytes memory params,
         uint256 gasLimit,
         bytes32 operationType
-    ) public returns (EngineBlox.TxRecord memory) {
-        // Validate inputs
-        SharedValidation.validateNotZeroAddress(target);
-        
+    ) public returns (uint256 txId) {
         // SECURITY: Prevent access to internal execution functions
         _validateNotInternalFunction(target, functionSelector);
         
@@ -172,7 +134,44 @@ abstract contract GuardController is BaseStateMachine {
             functionSelector,
             params
         );
-        return txRecord;
+        return txRecord.txId;
+    }
+
+    /**
+     * @dev Requests a time-locked execution with payment details attached (same permissions as executeWithTimeLock)
+     * @param target The address of the target contract
+     * @param value The ETH value to send (0 for standard function calls)
+     * @param functionSelector The function selector to execute (NATIVE_TRANSFER_SELECTOR for simple native token transfers)
+     * @param params The encoded parameters for the function (empty for simple native token transfers)
+     * @param gasLimit The gas limit for execution
+     * @param operationType The operation type hash
+     * @param paymentDetails The payment details to attach to the transaction
+     * @return txId The transaction ID for the requested operation (use getTransaction(txId) for full record)
+     * @notice Creates a time-locked transaction with payment that must be approved after the timelock period
+     * @notice Reuses EXECUTE_TIME_DELAY_REQUEST permission for the execution selector (no new definitions)
+     * @notice Approval/cancel use same flows as executeWithTimeLock (approveTimeLockExecution, cancelTimeLockExecution)
+     */
+    function executeWithPayment(
+        address target,
+        uint256 value,
+        bytes4 functionSelector,
+        bytes memory params,
+        uint256 gasLimit,
+        bytes32 operationType,
+        EngineBlox.PaymentDetails memory paymentDetails
+    ) public returns (uint256 txId) {
+        _validateNotInternalFunction(target, functionSelector);
+        EngineBlox.TxRecord memory txRecord = _requestTransactionWithPayment(
+            msg.sender,
+            target,
+            value,
+            gasLimit,
+            operationType,
+            functionSelector,
+            params,
+            paymentDetails
+        );
+        return txRecord.txId;
     }
     
     /**
@@ -183,13 +182,14 @@ abstract contract GuardController is BaseStateMachine {
      */
     function approveTimeLockExecution(
         uint256 txId
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         // SECURITY: Prevent access to internal execution functions
         EngineBlox.TxRecord memory txRecord = _getSecureState().txRecords[txId];
         _validateNotInternalFunction(txRecord.params.target, txRecord.params.executionSelector);
         
         // Approve via BaseStateMachine helper (validates permissions and whitelist in EngineBlox)
-        return _approveTransaction(txId);  
+        txRecord = _approveTransaction(txId);
+        return txRecord.txId;
     }
     
     /**
@@ -200,13 +200,14 @@ abstract contract GuardController is BaseStateMachine {
      */
     function cancelTimeLockExecution(
         uint256 txId
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         // SECURITY: Prevent access to internal execution functions
         EngineBlox.TxRecord memory txRecord = _getSecureState().txRecords[txId];
         _validateNotInternalFunction(txRecord.params.target, txRecord.params.executionSelector);
         
         // Cancel via BaseStateMachine helper (validates permissions in EngineBlox)
-        return _cancelTransaction(txId);
+        txRecord = _cancelTransaction(txId);
+        return txRecord.txId;
     }
     
     /**
@@ -217,12 +218,13 @@ abstract contract GuardController is BaseStateMachine {
      */
     function approveTimeLockExecutionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         // SECURITY: Prevent access to internal execution functions
         _validateNotInternalFunction(metaTx.txRecord.params.target, metaTx.txRecord.params.executionSelector);
         
         // Approve via BaseStateMachine helper (validates permissions and whitelist in EngineBlox)
-        return _approveTransactionWithMetaTx(metaTx);
+        EngineBlox.TxRecord memory txRecord = _approveTransactionWithMetaTx(metaTx);
+        return txRecord.txId;
     }
     
     /**
@@ -233,12 +235,13 @@ abstract contract GuardController is BaseStateMachine {
      */
     function cancelTimeLockExecutionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         // SECURITY: Prevent access to internal execution functions
         _validateNotInternalFunction(metaTx.txRecord.params.target, metaTx.txRecord.params.executionSelector);
         
         // Cancel via BaseStateMachine helper (validates permissions and whitelist in EngineBlox)
-        return _cancelTransactionWithMetaTx(metaTx);
+        EngineBlox.TxRecord memory txRecord = _cancelTransactionWithMetaTx(metaTx);
+        return txRecord.txId;
     }
     
     /**
@@ -251,12 +254,13 @@ abstract contract GuardController is BaseStateMachine {
      */
     function requestAndApproveExecution(
         EngineBlox.MetaTransaction memory metaTx
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         // SECURITY: Prevent access to internal execution functions
         _validateNotInternalFunction(metaTx.txRecord.params.target, metaTx.txRecord.params.executionSelector);
         
         // Request and approve via BaseStateMachine helper (validates permissions and whitelist in EngineBlox)
-        return _requestAndApproveTransaction(metaTx);
+        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
+        return txRecord.txId;
     }
     
     // Note: Meta-transaction utility functions (createMetaTxParams, 
@@ -268,20 +272,6 @@ abstract contract GuardController is BaseStateMachine {
 
     // ============ INTERNAL VALIDATION HELPERS ============
 
-    /**
-     * @dev Checks if a function selector is a known system macro selector
-     * @param functionSelector The function selector to check
-     * @return true if the selector is a known system macro selector, false otherwise
-     * @notice System macro selectors are special selectors that represent system-level operations
-     *         and are allowed to bypass certain security restrictions
-     * @notice Currently known macro selectors:
-     *         - NATIVE_TRANSFER_SELECTOR: For native token transfers
-     */
-    function _isSystemMacroSelector(bytes4 functionSelector) internal pure returns (bool) {
-        return functionSelector == EngineBlox.NATIVE_TRANSFER_SELECTOR
-            || functionSelector == EngineBlox.UPDATE_PAYMENT_SELECTOR;
-    }
-
     /**
      * @dev Validates that GuardController is not attempting to access internal execution functions
      * @param target The target contract address
@@ -304,7 +294,7 @@ abstract contract GuardController is BaseStateMachine {
         if (target == address(this)) {
             // Allow system macro selectors (e.g., NATIVE_TRANSFER_SELECTOR for native token deposits)
             // These are special system-level operations that are safe to execute on address(this)
-            if (_isSystemMacroSelector(functionSelector)) {
+            if (_isMacroSelector(functionSelector)) {
                 return; // Allow system macro selectors
             }
             
@@ -315,17 +305,6 @@ abstract contract GuardController is BaseStateMachine {
 
     // ============ GUARD CONFIGURATION BATCH INTERFACE ============
 
-    /**
-     * @dev Creates execution params for a Guard configuration batch
-     * @param actions Encoded guard configuration actions
-     * @return The execution params for EngineBlox
-     */
-    function guardConfigBatchExecutionParams(
-        GuardConfigAction[] memory actions
-    ) public pure returns (bytes memory) {
-        return abi.encode(actions);
-    }
-
     /**
      * @dev Requests and approves a Guard configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
@@ -334,19 +313,18 @@ abstract contract GuardController is BaseStateMachine {
      */
     function guardConfigBatchRequestAndApprove(
         EngineBlox.MetaTransaction memory metaTx
-    ) public returns (EngineBlox.TxRecord memory) {
+    ) public returns (uint256) {
         _validateBroadcaster(msg.sender);
-        SharedValidation.validateOwnerIsSigner(metaTx.params.signer, owner());
-        
-        return _requestAndApproveTransaction(metaTx);
+        EngineBlox.TxRecord memory txRecord = _requestAndApproveTransaction(metaTx);
+        return txRecord.txId;
     }
 
     /**
      * @dev External function that can only be called by the contract itself to execute a Guard configuration batch
      * @param actions Encoded guard configuration actions
      */
-    function executeGuardConfigBatch(GuardConfigAction[] calldata actions) external {
-        SharedValidation.validateInternalCall(address(this));
+    function executeGuardConfigBatch(IGuardController.GuardConfigAction[] calldata actions) external {
+        _validateExecuteBySelf();
         _executeGuardConfigBatch(actions);
     }
 
@@ -356,43 +334,29 @@ abstract contract GuardController is BaseStateMachine {
      * @dev Internal helper to execute a Guard configuration batch
      * @param actions Encoded guard configuration actions
      */
-    function _executeGuardConfigBatch(GuardConfigAction[] calldata actions) internal {
-        // Validate batch size limit
-        SharedValidation.validateBatchSize(
-            actions.length,
-            EngineBlox.MAX_BATCH_SIZE
-        );
-        
+    function _executeGuardConfigBatch(IGuardController.GuardConfigAction[] calldata actions) internal {
+        _validateBatchSize(actions.length);
+
         for (uint256 i = 0; i < actions.length; i++) {
-            GuardConfigAction calldata action = actions[i];
+            IGuardController.GuardConfigAction calldata action = actions[i];
 
-            if (action.actionType == GuardConfigActionType.ADD_TARGET_TO_WHITELIST) {
+            if (action.actionType == IGuardController.GuardConfigActionType.ADD_TARGET_TO_WHITELIST) {
                 // Decode ADD_TARGET_TO_WHITELIST action data
                 // Format: (bytes4 functionSelector, address target)
                 (bytes4 functionSelector, address target) = abi.decode(action.data, (bytes4, address));
 
                 _addTargetToFunctionWhitelist(functionSelector, target);
 
-                emit GuardConfigApplied(
-                    GuardConfigActionType.ADD_TARGET_TO_WHITELIST,
-                    functionSelector,
-                    target,
-                    "" // optional: could encode additional data if needed
-                );
-            } else if (action.actionType == GuardConfigActionType.REMOVE_TARGET_FROM_WHITELIST) {
+                _logComponentEvent(_encodeGuardConfigEvent(IGuardController.GuardConfigActionType.ADD_TARGET_TO_WHITELIST, functionSelector, target));
+            } else if (action.actionType == IGuardController.GuardConfigActionType.REMOVE_TARGET_FROM_WHITELIST) {
                 // Decode REMOVE_TARGET_FROM_WHITELIST action data
                 // Format: (bytes4 functionSelector, address target)
                 (bytes4 functionSelector, address target) = abi.decode(action.data, (bytes4, address));
 
                 _removeTargetFromFunctionWhitelist(functionSelector, target);
 
-                emit GuardConfigApplied(
-                    GuardConfigActionType.REMOVE_TARGET_FROM_WHITELIST,
-                    functionSelector,
-                    target,
-                    ""
-                );
-            } else if (action.actionType == GuardConfigActionType.REGISTER_FUNCTION) {
+                _logComponentEvent(_encodeGuardConfigEvent(IGuardController.GuardConfigActionType.REMOVE_TARGET_FROM_WHITELIST, functionSelector, target));
+            } else if (action.actionType == IGuardController.GuardConfigActionType.REGISTER_FUNCTION) {
                 // Decode REGISTER_FUNCTION action data
                 // Format: (string functionSignature, string operationName, TxAction[] supportedActions)
                 (
@@ -403,31 +367,32 @@ abstract contract GuardController is BaseStateMachine {
 
                 bytes4 functionSelector = _registerFunction(functionSignature, operationName, supportedActions);
 
-                emit GuardConfigApplied(
-                    GuardConfigActionType.REGISTER_FUNCTION,
-                    functionSelector,
-                    address(0),
-                    "" // optional: abi.encode(operationName)
-                );
-            } else if (action.actionType == GuardConfigActionType.UNREGISTER_FUNCTION) {
+                _logComponentEvent(_encodeGuardConfigEvent(IGuardController.GuardConfigActionType.REGISTER_FUNCTION, functionSelector, address(0)));
+            } else if (action.actionType == IGuardController.GuardConfigActionType.UNREGISTER_FUNCTION) {
                 // Decode UNREGISTER_FUNCTION action data
                 // Format: (bytes4 functionSelector, bool safeRemoval)
                 (bytes4 functionSelector, bool safeRemoval) = abi.decode(action.data, (bytes4, bool));
 
                 _unregisterFunction(functionSelector, safeRemoval);
 
-                emit GuardConfigApplied(
-                    GuardConfigActionType.UNREGISTER_FUNCTION,
-                    functionSelector,
-                    address(0),
-                    ""
-                );
+                _logComponentEvent(_encodeGuardConfigEvent(IGuardController.GuardConfigActionType.UNREGISTER_FUNCTION, functionSelector, address(0)));
             } else {
                 revert SharedValidation.NotSupported();
             }
         }
     }
 
+    /**
+     * @dev Encodes guard config event payload for ComponentEvent. Decode as (GuardConfigActionType, bytes4 functionSelector, address target).
+     */
+    function _encodeGuardConfigEvent(
+        IGuardController.GuardConfigActionType actionType,
+        bytes4 functionSelector,
+        address target
+    ) internal pure returns (bytes memory) {
+        return abi.encode(actionType, functionSelector, target);
+    }
+
     // ============ INTERNAL FUNCTION SCHEMA HELPERS ============
 
     /**
@@ -445,16 +410,12 @@ abstract contract GuardController is BaseStateMachine {
         // Derive function selector from signature
         functionSelector = bytes4(keccak256(bytes(functionSignature)));
 
-        // Validate that function schema doesn't already exist
-        if (functionSchemaExists(functionSelector)) {
-            revert SharedValidation.ResourceAlreadyExists(bytes32(functionSelector));
-        }
-
         // Convert actions array to bitmap
         uint16 supportedActionsBitmap = _createBitmapFromActions(supportedActions);
 
         // Create function schema directly (always non-protected)
         // Dynamically registered functions are execution selectors (handlerForSelectors must contain self-reference)
+        // EngineBlox.createFunctionSchema validates schema doesn't already exist (ResourceAlreadyExists)
         bytes4[] memory executionHandlerForSelectors = new bytes4[](1);
         executionHandlerForSelectors[0] = functionSelector; // Self-reference for execution selector
         _createFunctionSchema(
@@ -471,37 +432,10 @@ abstract contract GuardController is BaseStateMachine {
      * @dev Internal helper to unregister a function schema
      * @param functionSelector The function selector to unregister
      * @param safeRemoval If true, checks for role references before removal
+     * @notice EngineBlox.removeFunctionSchema validates schema existence (ResourceNotFound) and protected status (CannotModifyProtected)
      */
     function _unregisterFunction(bytes4 functionSelector, bool safeRemoval) internal {
-        // Load schema and validate it exists
-        EngineBlox.FunctionSchema storage schema = _getSecureState().functions[functionSelector];
-        if (schema.functionSelector != functionSelector) {
-            revert SharedValidation.ResourceNotFound(bytes32(functionSelector));
-        }
-
-        // Ensure not protected
-        if (schema.isProtected) {
-            revert SharedValidation.CannotModifyProtected(bytes32(functionSelector));
-        }
-
-        // The safeRemoval check is now handled within EngineBlox.removeFunctionSchema
-        // (avoids getSupportedRolesList/getRoleFunctionPermissions which call _validateAnyRole;
-        // during meta-tx execution msg.sender is the contract, causing NoPermission)
         _removeFunctionSchema(functionSelector, safeRemoval);
     }
 
-    /**
-     * @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 getAllowedTargets(
-        bytes4 functionSelector
-    ) external view returns (address[] memory) {
-        _validateAnyRole();
-        return _getFunctionWhitelistTargets(functionSelector);
-    }
 }
-
-

package/{contracts/core → core}/execution/interface/IGuardController.sol

@@ -7,11 +7,29 @@ import "../../lib/EngineBlox.sol";
  * @title IGuardController
  * @dev Interface for GuardController contract that GuardianSafeV3 and other contracts delegate to
  * @notice This interface defines only GuardController-specific methods
- * @notice Functions from BaseStateMachine (createMetaTxParams, generateUnsignedMetaTransaction*, getTransaction, functionSchemaExists, owner, getBroadcaster, getRecovery) should be accessed via IBaseStateMachine
- * @notice Functions from RuntimeRBAC (registerFunction, unregisterFunction, getFunctionSchema, createNewRole, addWalletToRole, revokeWallet) should be accessed via IRuntimeRBAC
+ * @notice Functions from BaseStateMachine (createMetaTxParams, generateUnsignedMetaTransaction*, getTransaction, functionSchemaExists, getFunctionSchema, owner, getBroadcaster, getRecovery) should be accessed via IBaseStateMachine
+ * @notice Functions from RuntimeRBAC (registerFunction, unregisterFunction, createNewRole, addWalletToRole, revokeWallet) should be accessed via IRuntimeRBAC
  * @custom:security-contact security@particlecrypto.com
  */
 interface IGuardController {
+    /**
+     * @dev Action types for batched Guard configuration
+     */
+    enum GuardConfigActionType {
+        ADD_TARGET_TO_WHITELIST,
+        REMOVE_TARGET_FROM_WHITELIST,
+        REGISTER_FUNCTION,
+        UNREGISTER_FUNCTION
+    }
+
+    /**
+     * @dev Encodes a single Guard configuration action in a batch
+     */
+    struct GuardConfigAction {
+        GuardConfigActionType actionType;
+        bytes data;
+    }
+
     /**
      * @notice Initializer to initialize GuardController
      * @param initialOwner The initial owner address
@@ -51,63 +69,85 @@ interface IGuardController {
         bytes32 operationType
     ) external returns (uint256 txId);
 
+    /**
+     * @dev Requests a time-locked execution with payment details attached (same permissions as executeWithTimeLock)
+     * @param target The address of the target contract
+     * @param value The ETH value to send (0 for standard function calls)
+     * @param functionSelector The function selector to execute (NATIVE_TRANSFER_SELECTOR for simple native token transfers)
+     * @param params The encoded parameters for the function (empty for simple native token transfers)
+     * @param gasLimit The gas limit for execution
+     * @param operationType The operation type hash
+     * @param paymentDetails The payment details to attach to the transaction
+     * @return txId The transaction ID for the requested operation (use getTransaction(txId) for full record)
+     * @notice Reuses EXECUTE_TIME_DELAY_REQUEST permission; approval/cancel same as executeWithTimeLock
+     */
+    function executeWithPayment(
+        address target,
+        uint256 value,
+        bytes4 functionSelector,
+        bytes memory params,
+        uint256 gasLimit,
+        bytes32 operationType,
+        EngineBlox.PaymentDetails memory paymentDetails
+    ) external returns (uint256 txId);
+
     /**
      * @dev Approves and executes a time-locked transaction
      * @param txId The transaction ID
      * @param expectedOperationType The expected operation type for validation
-     * @return result The execution result
+     * @return txId The transaction ID (use getTransaction(txId) for full record and result)
      * @notice Requires STANDARD execution type and EXECUTE_TIME_DELAY_APPROVE permission for the execution function
      */
     function approveTimeLockExecution(
         uint256 txId,
         bytes32 expectedOperationType
-    ) external returns (bytes memory result);
+    ) external returns (uint256);
 
     /**
      * @dev Cancels a time-locked transaction
      * @param txId The transaction ID
      * @param expectedOperationType The expected operation type for validation
-     * @return The updated transaction record
+     * @return txId The transaction ID (use getTransaction(txId) for full record)
      * @notice Requires STANDARD execution type and EXECUTE_TIME_DELAY_CANCEL permission for the execution function
      */
     function cancelTimeLockExecution(
         uint256 txId,
         bytes32 expectedOperationType
-    ) external returns (EngineBlox.TxRecord memory);
+    ) external returns (uint256);
 
     /**
      * @dev Approves a time-locked transaction using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
      * @param expectedOperationType The expected operation type for validation
      * @param requiredSelector The handler selector for validation
-     * @return The updated transaction record
+     * @return The transaction ID (use getTransaction(txId) for full record)
      * @notice Requires STANDARD execution type and EXECUTE_META_APPROVE permission for the execution function
      */
     function approveTimeLockExecutionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx,
         bytes32 expectedOperationType,
         bytes4 requiredSelector
-    ) external returns (EngineBlox.TxRecord memory);
+    ) external returns (uint256);
 
     /**
      * @dev Cancels a time-locked transaction using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
      * @param expectedOperationType The expected operation type for validation
      * @param requiredSelector The handler selector for validation
-     * @return The updated transaction record
+     * @return The transaction ID (use getTransaction(txId) for full record)
      * @notice Requires STANDARD execution type and EXECUTE_META_CANCEL permission for the execution function
      */
     function cancelTimeLockExecutionWithMetaTx(
         EngineBlox.MetaTransaction memory metaTx,
         bytes32 expectedOperationType,
         bytes4 requiredSelector
-    ) external returns (EngineBlox.TxRecord memory);
+    ) external returns (uint256);
 
     /**
      * @dev Requests and approves a transaction in one step using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
      * @param requiredSelector The handler selector for validation
-     * @return The transaction record after request and approval
+     * @return The transaction ID (use getTransaction(txId) for full record)
      * @notice Requires STANDARD execution type
      * @notice Validates function schema and permissions for the execution function (same as executeWithTimeLock)
      * @notice Requires EXECUTE_META_REQUEST_AND_APPROVE permission for the execution function selector
@@ -115,6 +155,6 @@ interface IGuardController {
     function requestAndApproveExecution(
         EngineBlox.MetaTransaction memory metaTx,
         bytes4 requiredSelector
-    ) external returns (EngineBlox.TxRecord memory);
+    ) external returns (uint256);
 }
 

package/{contracts/core → core}/execution/lib/definitions/GuardControllerDefinitions.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 "../../interface/IGuardController.sol";
 
 /**
  * @title GuardControllerDefinitions
@@ -61,7 +63,7 @@ library GuardControllerDefinitions {
     // GuardController: executeGuardConfigBatch((uint8,bytes)[])
     bytes4 public constant GUARD_CONFIG_BATCH_EXECUTE_SELECTOR =
         bytes4(keccak256("executeGuardConfigBatch((uint8,bytes)[])"));
-    
+
     /**
      * @dev Returns predefined function schemas for GuardController execution functions
      * @return Array of function schema definitions
@@ -398,4 +400,91 @@ library GuardControllerDefinitions {
             functionPermissions: functionPermissions
         });
     }
+
+    /**
+     * @dev Returns all available GuardConfig action types and their decode formats for discovery.
+     * @return actionNames Human-readable action names (same order as GuardConfigActionType enum)
+     * @return formats ABI decode format for each action's data, e.g. "(bytes4 functionSelector, address target)"
+     * @notice Use with GuardConfigActionType enum: actionNames[i] and formats[i] describe enum value i
+     */
+    function getGuardConfigActionSpecs() public pure returns (string[] memory actionNames, string[] memory formats) {
+        actionNames = new string[](4);
+        formats = new string[](4);
+
+        actionNames[0] = "ADD_TARGET_TO_WHITELIST";
+        formats[0] = "(bytes4 functionSelector, address target)";
+
+        actionNames[1] = "REMOVE_TARGET_FROM_WHITELIST";
+        formats[1] = "(bytes4 functionSelector, address target)";
+
+        actionNames[2] = "REGISTER_FUNCTION";
+        formats[2] = "(string functionSignature, string operationName, TxAction[] supportedActions)";
+
+        actionNames[3] = "UNREGISTER_FUNCTION";
+        formats[3] = "(bytes4 functionSelector, bool safeRemoval)";
+    }
+
+    // ============ GUARD CONFIG ACTION DATA ENCODERS ============
+    // Use these helpers to build action.data for each GuardConfigActionType without reading the contract.
+    // Each encoder returns bytes suitable for GuardConfigAction(actionType, data).
+
+    /**
+     * @dev Encodes data for ADD_TARGET_TO_WHITELIST. Use with GuardConfigActionType.ADD_TARGET_TO_WHITELIST.
+     * @param functionSelector Function whose whitelist is updated
+     * @param target Address to add to the whitelist
+     */
+    function encodeAddTargetToWhitelist(bytes4 functionSelector, address target) public pure returns (bytes memory) {
+        return abi.encode(functionSelector, target);
+    }
+
+    /**
+     * @dev Encodes data for REMOVE_TARGET_FROM_WHITELIST. Use with GuardConfigActionType.REMOVE_TARGET_FROM_WHITELIST.
+     * @param functionSelector Function whose whitelist is updated
+     * @param target Address to remove from the whitelist
+     */
+    function encodeRemoveTargetFromWhitelist(bytes4 functionSelector, address target) public pure returns (bytes memory) {
+        return abi.encode(functionSelector, target);
+    }
+
+    /**
+     * @dev Encodes data for REGISTER_FUNCTION. Use with GuardConfigActionType.REGISTER_FUNCTION.
+     * @param functionSignature Full function signature string (e.g. "executeWithTimeLock(address,bytes4,bytes,uint256,bytes32)")
+     * @param operationName Human-readable operation name
+     * @param supportedActions TxActions supported by this function (e.g. EXECUTE_TIME_DELAY_REQUEST)
+     */
+    function encodeRegisterFunction(
+        string memory functionSignature,
+        string memory operationName,
+        EngineBlox.TxAction[] memory supportedActions
+    ) public pure returns (bytes memory) {
+        return abi.encode(functionSignature, operationName, supportedActions);
+    }
+
+    /**
+     * @dev Encodes data for UNREGISTER_FUNCTION. Use with GuardConfigActionType.UNREGISTER_FUNCTION.
+     * @param functionSelector Selector of the function to unregister
+     * @param safeRemoval If true, reverts when the function has whitelisted targets
+     */
+    function encodeUnregisterFunction(bytes4 functionSelector, bool safeRemoval) public pure returns (bytes memory) {
+        return abi.encode(functionSelector, safeRemoval);
+    }
+
+    /**
+     * @dev Creates execution params for a Guard configuration batch (pure helper for EngineBlox).
+     * @param actions Encoded guard configuration actions (same layout as IGuardController.GuardConfigAction[])
+     * @return The execution params for EngineBlox
+     */
+    function guardConfigBatchExecutionParams(
+        IGuardController.GuardConfigAction[] memory actions
+    ) public pure returns (bytes memory) {
+        return abi.encode(actions);
+    }
+
+    /**
+     * @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;
+    }
 }