@bloxchain/contracts 1.0.0-alpha.6 → 1.0.0

package/core/lib/EngineBlox.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.35;
 
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
-import { MessageHashUtils } from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
 import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 
 // Local imports
@@ -29,13 +28,18 @@ import "./interfaces/IEventForwarder.sol";
  * 
  * The library is designed to be used as a building block for secure smart contract systems
  * that require high levels of security and flexibility through state abstraction.
+ *
+ * @notice Enumeration vs execution gas: Whitelist enforcement (`_validateTargetWhitelist`) uses set membership
+ *         (`contains`) and is O(1) in whitelist length. Helpers that return full sets (`getSupportedRoles`,
+ *         `getPendingTransactions`, `getFunctionWhitelistTargets`, `_convert*SetToArray`, etc.) allocate and iterate
+ *         in O(set size)—primarily view/RPC or admin cleanup cost, not unbounded execution scans of those sets.
+ *         Immutable `MAX_ROLES`, `MAX_FUNCTIONS`, `MAX_HOOKS_PER_SELECTOR`, and `MAX_BATCH_SIZE` cap their domains;
+ *         per-role `maxWallets` is operator-chosen (only required > 0) and scales `removeRole` gas linearly.
  */
 library EngineBlox {
     // ============ VERSION INFORMATION ============
     bytes32 public constant PROTOCOL_NAME_HASH = keccak256("Bloxchain");
-    uint8 public constant VERSION_MAJOR = 1;
-    uint8 public constant VERSION_MINOR = 0;
-    uint8 public constant VERSION_PATCH = 0;
+    string public constant VERSION = "1.0.0";
     
     // ============ SYSTEM SAFETY LIMITS ============
     // These constants define the safety range limits for system operations
@@ -53,7 +57,6 @@ library EngineBlox {
     /// @dev Maximum total number of functions allowed in the system (prevents gas exhaustion in function operations)
     uint256 public constant MAX_FUNCTIONS = 2000;
     
-    using MessageHashUtils for bytes32;
     using SharedValidation for *;
     using EnumerableSet for EnumerableSet.UintSet;
     using EnumerableSet for EnumerableSet.Bytes32Set;
@@ -67,8 +70,7 @@ library EngineBlox {
         PROCESSING_PAYMENT,
         CANCELLED,
         COMPLETED,
-        FAILED,
-        REJECTED
+        FAILED
     }
 
     enum TxAction {
@@ -110,7 +112,9 @@ library EngineBlox {
         TxStatus status;
         TxParams params;
         bytes32 message;
-        bytes result;
+        /// @dev Commitment to execution returndata: `bytes32(0)` when empty, else `keccak256(returndata)`.
+        ///      Full returndata is emitted in `TxExecutionResult` on terminal execution (COMPLETED/FAILED).
+        bytes32 resultHash;
         PaymentDetails payment;
     }
 
@@ -152,8 +156,14 @@ library EngineBlox {
         bytes32 operationType;
         string operationName;
         uint16 supportedActionsBitmap; // Bitmap for TxAction enum (9 bits max)
+        /// @dev When true (strict mode): handlerForSelectors in role permissions must match this schema's handlerForSelectors at use time.
+        ///      When false (flexible mode): no such check; forward references and unregistered selectors in handlerForSelectors are allowed at registration.
+        bool enforceHandlerRelations;
         bool isProtected;
-        bytes4[] handlerForSelectors; 
+        /// @dev When false, `removeFunctionFromRole` cannot remove this selector from any role (revoke + re-add updates blocked).
+        ///      When true, grants may be removed from any role, including protected system roles; `isProtected` still blocks `unregisterFunction` for the schema.
+        bool isGrantRevocable;
+        bytes4[] handlerForSelectors;
     }
 
     // ============ DEFINITION STRUCTS ============
@@ -202,10 +212,38 @@ library EngineBlox {
 
     // Native token transfer selector (reserved signature unlikely to exist in real contracts)
     bytes4 public constant NATIVE_TRANSFER_SELECTOR = bytes4(keccak256("__bloxchain_native_transfer__()"));
-    bytes32 public constant NATIVE_TRANSFER_OPERATION = keccak256("NATIVE_TRANSFER");
+
+    /// @dev Reserved pseudo-selector: whitelist key for `PaymentDetails.recipient` (native and ERC20 attached payments).
+    ///      Function schema is registered by `GuardControllerDefinitions` (and tests/helpers that mirror it), not in `initialize`.
+    bytes4 public constant ATTACHED_PAYMENT_RECIPIENT_SELECTOR = bytes4(keccak256("__bloxchain_attached_payment_recipient__()"));
+
+    /// @dev Standard IERC20 `transfer(address,uint256)`; whitelist key for token contracts used in attached ERC20 payments.
+    ///      Function schema is registered by `GuardControllerDefinitions` (and tests/helpers that mirror it), not in `initialize`.
+    bytes4 public constant ERC20_TRANSFER_SELECTOR = bytes4(keccak256("transfer(address,uint256)"));
     
-    // EIP-712 Type Hashes
-    bytes32 private constant TYPE_HASH = keccak256("MetaTransaction(TxRecord txRecord,MetaTxParams params,bytes data)TxRecord(uint256 txId,uint256 releaseTime,uint8 status,TxParams params,bytes32 message,bytes result,PaymentDetails payment)TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)");
+    // EIP-712 Type Hashes (selective meta-tx payload: MetaTxRecord = txId + params + payment only)
+    // These follow the canonical EIP-712 convention so that eth_signTypedData_v4 and equivalent
+    // wallet typed-data signers can reproduce the same hashes when given matching type definitions.
+    //
+    // Canonical primary type string for MetaTransaction (primary type + all referenced types,
+    // appended in alphabetical order by type name
+    bytes32 private constant META_TX_TYPE_HASH = keccak256(
+        "MetaTransaction(MetaTxRecord txRecord,MetaTxParams params,bytes data)"
+        "MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)"
+        "MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)"
+        "PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)"
+        "TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)"
+    );
+
+    // Canonical primary type string for MetaTxRecord (primary type + its referenced types).
+    bytes32 private constant META_TX_RECORD_TYPE_HASH = keccak256(
+        "MetaTxRecord(uint256 txId,TxParams params,PaymentDetails payment)"
+        "PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)"
+        "TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)"
+    );
+    bytes32 private constant TX_PARAMS_TYPE_HASH = keccak256("TxParams(address requester,address target,uint256 value,uint256 gasLimit,bytes32 operationType,bytes4 executionSelector,bytes executionParams)");
+    bytes32 private constant META_TX_PARAMS_TYPE_HASH = keccak256("MetaTxParams(uint256 chainId,uint256 nonce,address handlerContract,bytes4 handlerSelector,uint8 action,uint256 deadline,uint256 maxGasPrice,address signer)");
+    bytes32 private constant PAYMENT_DETAILS_TYPE_HASH = keccak256("PaymentDetails(address recipient,uint256 nativeTokenAmount,address erc20TokenAddress,uint256 erc20TokenAmount)");
     bytes32 private constant DOMAIN_SEPARATOR_TYPE_HASH = keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
 
 
@@ -215,9 +253,15 @@ library EngineBlox {
         TxStatus status,
         address indexed requester,
         address target,
-        bytes32 operationType
+        bytes32 operationType,
+        bytes32 resultHash
     );
 
+    /// @dev Emitted only on terminal execution (COMPLETED/FAILED). Full execution returndata (`result` may be empty).
+    ///      Verify against `TxRecord.resultHash` from the same tx: `result.length == 0` implies `resultHash == bytes32(0)`;
+    ///      otherwise `keccak256(result) == resultHash` (see `_executionResultHash`).
+    event TxExecutionResult(uint256 indexed txId, bytes result);
+
     // ============ SYSTEM STATE FUNCTIONS ============
 
     /**
@@ -266,11 +310,11 @@ library EngineBlox {
     /**
      * @dev Updates the time lock period for the SecureOperationState.
      * @param self The SecureOperationState to modify.
-     * @param _newTimeLockPeriodSec The new time lock period in seconds.
+     * @param periodSec The new time lock period in seconds.
      */
-    function updateTimeLockPeriod(SecureOperationState storage self, uint256 _newTimeLockPeriodSec) public {
-        SharedValidation.validateTimeLockPeriod(_newTimeLockPeriodSec);
-        self.timeLockPeriodSec = _newTimeLockPeriodSec;
+    function updateTimeLockPeriod(SecureOperationState storage self, uint256 periodSec) public {
+        SharedValidation.validateTimeLockPeriod(periodSec);
+        self.timeLockPeriodSec = periodSec;
     }
 
     // ============ TRANSACTION MANAGEMENT FUNCTIONS ============
@@ -291,12 +335,12 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param requester The address of the requester.
      * @param target The target contract address for the transaction.
-     * @param value The value to send with the transaction.
+     * @param value The value to send with the transaction (typically 0 for standard calls; non-zero allowed when intentionally forwarding native ETH).
      * @param gasLimit The gas limit for the transaction.
      * @param operationType The type of operation.
      * @param handlerSelector The function selector of the handler/request function.
-     * @param executionSelector The function selector to execute (NATIVE_TRANSFER_SELECTOR for simple native token transfers).
-     * @param executionParams The encoded parameters for the function (empty for simple native token transfers).
+     * @param executionSelector The function selector to execute (NATIVE_TRANSFER_SELECTOR is a convenience selector for native-only transfers).
+     * @param executionParams The encoded parameters for the function (must be empty when using NATIVE_TRANSFER_SELECTOR).
      * @return The created TxRecord.
      */
     function txRequest(
@@ -322,7 +366,7 @@ library EngineBlox {
             operationType,
             executionSelector,
             executionParams,
-            _noPayment()
+            _emptyPayment()
         );
     }
 
@@ -331,7 +375,7 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param requester The address of the requester.
      * @param target The target contract address for the transaction.
-     * @param value The value to send with the transaction.
+     * @param value The value to send with the transaction (typically 0 for standard calls; non-zero allowed when intentionally forwarding native ETH).
      * @param gasLimit The gas limit for the transaction.
      * @param operationType The type of operation.
      * @param handlerSelector The function selector of the handler/request function.
@@ -356,6 +400,8 @@ library EngineBlox {
         // Validate both execution and handler selector permissions (same as txRequest)
         _validateExecutionAndHandlerPermissions(self, msg.sender, executionSelector, handlerSelector, TxAction.EXECUTE_TIME_DELAY_REQUEST);
 
+        _validateAttachedPaymentPolicy(self, paymentDetails);
+
         return _txRequest(
             self,
             requester,
@@ -394,11 +440,10 @@ library EngineBlox {
         bytes memory executionParams,
         PaymentDetails memory paymentDetails
     ) private returns (TxRecord memory) {
-        SharedValidation.validateNotZeroAddress(target);
-        // enforce that the requested target is whitelisted for this selector.
-        _validateFunctionTargetWhitelist(self, executionSelector, target);
+        // Target non-zero and whitelist enforced in `_validateTargetWhitelist`.
+        _validateTargetWhitelist(self, executionSelector, target);
 
-        TxRecord memory txRequestRecord = createNewTxRecord(
+        TxRecord memory txRequestRecord = createTxRecord(
             self,
             requester,
             target,
@@ -414,7 +459,7 @@ library EngineBlox {
         self.txCounter++;
 
         // Add to pending transactions list
-        addToPendingTransactionsList(self, txRequestRecord.txId);
+        addPendingTx(self, txRequestRecord.txId);
 
         logTxEvent(self, txRequestRecord.txId, executionSelector);
         
@@ -433,14 +478,15 @@ library EngineBlox {
         uint256 txId,
         bytes4 handlerSelector
     ) public returns (TxRecord memory) {
-        // Validate both execution and handler selector permissions
+        // CHECK: Validate both execution and handler selector permissions
         _validateExecutionAndHandlerPermissions(self, msg.sender, self.txRecords[txId].params.executionSelector, handlerSelector, TxAction.EXECUTE_TIME_DELAY_APPROVE);
         _validateTxStatus(self, txId, TxStatus.PENDING);
+        _validateTargetWhitelist(self, self.txRecords[txId].params.executionSelector, self.txRecords[txId].params.target);
         SharedValidation.validateReleaseTime(self.txRecords[txId].releaseTime);
-        
+
         // EFFECT: Update status to EXECUTING before external call to prevent reentrancy
         self.txRecords[txId].status = TxStatus.EXECUTING;
-        
+
         // INTERACT: External call after state update
         (bool success, bytes memory result) = executeTransaction(self, self.txRecords[txId]);
         
@@ -477,9 +523,13 @@ library EngineBlox {
      */
     function txCancellationWithMetaTx(SecureOperationState storage self, MetaTransaction memory metaTx) public returns (TxRecord memory) {
         uint256 txId = metaTx.txRecord.txId;
+        _validateMetaTxAction(metaTx, TxAction.SIGN_META_CANCEL);
+
         // Validate both execution and handler selector permissions
         _validateExecutionAndHandlerPermissions(self, msg.sender, metaTx.txRecord.params.executionSelector, metaTx.params.handlerSelector, TxAction.EXECUTE_META_CANCEL);
         _validateTxStatus(self, txId, TxStatus.PENDING);
+        _validateMetaTxMatchRecord(self, txId, metaTx.txRecord);
+        _validateMetaTxPaymentMatchRecord(self, txId, metaTx.txRecord);
         if (!verifySignature(self, metaTx)) revert SharedValidation.InvalidSignature(metaTx.signature);
         
         incrementSignerNonce(self, metaTx.params.signer);
@@ -495,6 +545,8 @@ library EngineBlox {
      * @return The updated TxRecord.
      */
     function txApprovalWithMetaTx(SecureOperationState storage self, MetaTransaction memory metaTx) public returns (TxRecord memory) {
+        _validateMetaTxAction(metaTx, TxAction.SIGN_META_APPROVE);
+
         // Validate both execution and handler selector permissions
         _validateExecutionAndHandlerPermissions(self, msg.sender, metaTx.txRecord.params.executionSelector, metaTx.params.handlerSelector, TxAction.EXECUTE_META_APPROVE);
         
@@ -508,17 +560,25 @@ library EngineBlox {
      * @return The updated TxRecord.
      * @notice This function skips permission validation and should only be called from functions
      *         that have already validated permissions.
+     * @custom:security TIMELOCK: The releaseTime (timelock) is intentionally NOT enforced on this path.
+     *         This is by design: the meta-tx workflow allows authorized signers to approve execution
+     *         without waiting for releaseTime, providing a hybrid synergy between timelock workflows
+     *         (direct path enforces releaseTime) and meta-tx workflows (delegated, time-flexible approval).
      */
     function _txApprovalWithMetaTx(SecureOperationState storage self, MetaTransaction memory metaTx) private returns (TxRecord memory) {
+        // CHECK: Validate transaction parameters
         uint256 txId = metaTx.txRecord.txId;
         _validateTxStatus(self, txId, TxStatus.PENDING);
+        _validateTargetWhitelist(self, self.txRecords[txId].params.executionSelector, self.txRecords[txId].params.target);
+        _validateMetaTxMatchRecord(self, txId, metaTx.txRecord);
+        _validateMetaTxPaymentMatchRecord(self, txId, metaTx.txRecord);
         if (!verifySignature(self, metaTx)) revert SharedValidation.InvalidSignature(metaTx.signature);
-        
+
         incrementSignerNonce(self, metaTx.params.signer);
-        
+
         // EFFECT: Update status to EXECUTING before external call to prevent reentrancy
         self.txRecords[txId].status = TxStatus.EXECUTING;
-        
+
         // INTERACT: External call after state update
         (bool success, bytes memory result) = executeTransaction(self, self.txRecords[txId]);
         
@@ -537,9 +597,13 @@ library EngineBlox {
         SecureOperationState storage self,
         MetaTransaction memory metaTx
     ) public returns (TxRecord memory) {
+        _validateMetaTxAction(metaTx, TxAction.SIGN_META_REQUEST_AND_APPROVE);
+
         // Validate both execution and handler selector permissions
         _validateExecutionAndHandlerPermissions(self, msg.sender, metaTx.txRecord.params.executionSelector, metaTx.params.handlerSelector, TxAction.EXECUTE_META_REQUEST_AND_APPROVE);
-        
+
+        _validateAttachedPaymentPolicy(self, metaTx.txRecord.payment);
+
         TxRecord memory txRecord = _txRequest(
             self,
             metaTx.txRecord.params.requester,
@@ -570,13 +634,21 @@ library EngineBlox {
      *            causing _validateTxPending to revert in entry functions
      *         4. Status flow is one-way: PENDING → EXECUTING → (COMPLETED/FAILED)
      *         This creates an effective reentrancy guard without additional storage overhead.
+     * @notice **Atomicity:** If the main call succeeds but `executeAttachedPayment` reverts (e.g.
+     *         insufficient balance, whitelist mismatch), the **entire** approval/execute transaction reverts—main
+     *         effect included. This is **intentional all-or-nothing** semantics; splitting finalize vs payment
+     *         would require a separate design with reentrancy and state-machine implications.
+     * @notice `record` is a memory copy: final `status` and `resultHash` are written to storage by `_completeTransaction`;
+     *         full returndata is emitted in `TxExecutionResult`.
      */
     function executeTransaction(SecureOperationState storage self, TxRecord memory record) private returns (bool, bytes memory) {
         // Validate that transaction is in EXECUTING status (set by caller before this function)
         // This proves reentrancy protection is active at entry point
         _validateTxStatus(self, record.txId, TxStatus.EXECUTING);
 
-        bytes memory txData = prepareTransactionData(record);
+        bytes memory txData = buildCallData(record);
+        // gasLimit == 0 → forward all remaining gas (conventional "no cap"). Integrators that want
+        // a strict upper bound must set a positive gasLimit in TxParams at request time.
         uint gas = record.params.gasLimit;
         if (gas == 0) {
             gas = gasleft();
@@ -590,16 +662,10 @@ library EngineBlox {
         );
 
         if (success) {
-            record.status = TxStatus.COMPLETED;
-            record.result = result;
-            
             // Execute attached payment if transaction was successful
             if (record.payment.recipient != address(0)) {
                 executeAttachedPayment(self, record);
             }
-        } else {
-            record.status = TxStatus.FAILED;
-            record.result = result;
         }
 
         return (success, result);
@@ -618,6 +684,13 @@ library EngineBlox {
      *         4. All entry functions check for PENDING status first, so reentry fails
      *         The external calls (native token transfer, ERC20 transfer) cannot reenter
      *         critical functions because the transaction is no longer in PENDING state.
+     * @notice When payment amounts are non-zero, `payment.recipient` is validated against
+     *         `ATTACHED_PAYMENT_RECIPIENT_SELECTOR`; non-zero ERC20 amounts also require
+     *         `payment.erc20TokenAddress` on `ERC20_TRANSFER_SELECTOR` whitelist.
+     * @notice **ERC20 attached payouts** use `safeTransfer` with the **nominal** `erc20TokenAmount`.
+     *         **Fee-on-transfer, rebasing, or other non-standard ERC20s are not supported:** the protocol does not
+     *         measure balance deltas at the recipient; operators must only attach **standard** tokens where
+     *         transferred amount equals the requested amount.
      */
     function executeAttachedPayment(
         SecureOperationState storage self,
@@ -626,6 +699,9 @@ library EngineBlox {
         // Validate that transaction is still in EXECUTING status
         // This ensures reentrancy protection is maintained throughout payment execution
         _validateTxStatus(self, record.txId, TxStatus.EXECUTING);
+
+        _validateAttachedPaymentPolicy(self, record.payment);
+
         self.txRecords[record.txId].status = TxStatus.PROCESSING_PAYMENT;
         
         PaymentDetails memory payment = record.payment;
@@ -662,11 +738,11 @@ library EngineBlox {
     }
 
     /**
-     * @dev Prepares transaction data from execution selector and params without executing it.
+     * @dev Builds transaction call data from execution selector and params without executing it.
      * @param record The transaction record to prepare data for.
      * @return The prepared transaction data.
      */
-    function prepareTransactionData(TxRecord memory record) private pure returns (bytes memory) {
+    function buildCallData(TxRecord memory record) private pure returns (bytes memory) {
         // If executionSelector is NATIVE_TRANSFER_SELECTOR, it's a simple native token transfer (no function call)
         if (record.params.executionSelector == NATIVE_TRANSFER_SELECTOR) {
             // SECURITY: Validate empty params to prevent confusion with real function calls
@@ -683,7 +759,7 @@ library EngineBlox {
 
 
     /**
-     * @notice Creates a new transaction record with basic fields populated
+     * @notice Creates a transaction record with basic fields populated
      * @dev Initializes a TxRecord struct with the provided parameters and default values
      * @param self The SecureOperationState to reference for txId and timelock
      * @param requester The address initiating the transaction
@@ -696,7 +772,7 @@ library EngineBlox {
      * @param payment The payment details to attach to the record (use empty struct for no payment)
      * @return TxRecord A new transaction record with populated fields
      */
-    function createNewTxRecord(
+    function createTxRecord(
         SecureOperationState storage self,
         address requester,
         address target,
@@ -721,7 +797,7 @@ library EngineBlox {
                 executionParams: executionParams
             }),
             message: 0,
-            result: "",
+            resultHash: bytes32(0),
             payment: payment
         });
     }
@@ -731,9 +807,8 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param txId The transaction ID to add to the pending set.
      */
-    function addToPendingTransactionsList(SecureOperationState storage self, uint256 txId) private {
-        SharedValidation.validateTransactionExists(txId);
-        _validateTxStatus(self, txId, TxStatus.PENDING);
+    function addPendingTx(SecureOperationState storage self, uint256 txId) private {
+        SharedValidation.validateTransactionExists(txId, self.txCounter);
         
         // Try to add transaction ID to the set - add() returns false if already exists
         if (!self.pendingTransactionsSet.add(txId)) {
@@ -746,8 +821,8 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param txId The transaction ID to remove from the pending set.
      */
-    function removeFromPendingTransactionsList(SecureOperationState storage self, uint256 txId) private {
-        SharedValidation.validateTransactionExists(txId);
+    function removePendingTx(SecureOperationState storage self, uint256 txId) private {
+        SharedValidation.validateTransactionExists(txId, self.txCounter);
         
         // Remove the transaction ID from the set (O(1) operation)
         if (!self.pendingTransactionsSet.remove(txId)) {
@@ -786,7 +861,8 @@ library EngineBlox {
      * @dev Creates a role with specified function permissions.
      * @param self The SecureOperationState to check.
      * @param roleName Name of the role.
-     * @param maxWallets Maximum number of wallets allowed for this role.
+     * @param maxWallets Maximum number of wallets allowed for this role. Not capped by a protocol-wide constant;
+     *        very large values increase gas for `removeRole` and for view helpers that list this role's wallets.
      * @param isProtected Whether the role is protected from removal.
      */
     function createRole(
@@ -831,6 +907,10 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param roleHash The hash of the role to remove.
      * @notice Security: Cannot remove protected roles to maintain system integrity.
+     * @notice Gas: Iterates all authorized wallets and function selectors on this role (linear in role size).
+     * @custom:security PROTECTED-ROLE POLICY: This library enforces the protected-role check for
+     *         REMOVE_ROLE. RuntimeRBAC does not duplicate this check; defense is in layers. The
+     *         only component authorized to modify system wallets (protected roles) is SecureOwnable.
      */
     function removeRole(
         SecureOperationState storage self,
@@ -861,19 +941,27 @@ library EngineBlox {
             self.walletRoles[wallets[i]].remove(roleHash);
         }
         
-        // Clear the role data from roles mapping
-        // Remove the role from the supported roles set (O(1) operation)
-        // NOTE: Mappings (functionPermissions, authorizedWallets, functionSelectorsSet)
-        // are not deleted by Solidity's delete operator. This is acceptable because:
-        // 1. Role is removed from supportedRolesSet, making it inaccessible via role queries
-        // 2. Reverse index (walletRoles) is cleaned up above, so permission checks won't find this role
-        // 3. All access checks use the reverse index (walletRoles) for O(1) lookups, so orphaned data is unreachable
-        // 4. Role recreation with same name would pass roleHash check but mappings
-        //    would be effectively reset since role is reinitialized from scratch
-        delete self.roles[roleHash];  
+        // Clear the role's authorizedWallets set so storage is clean if role is recreated with same name
+        for (uint256 i = 0; i < walletCount; i++) {
+            roleData.authorizedWallets.remove(wallets[i]);
+        }
+        
+        // Clear function permissions and functionSelectorsSet (same reason: no stale data on role recreation)
+        uint256 selectorCount = roleData.functionSelectorsSet.length();
+        bytes32[] memory selectors = new bytes32[](selectorCount);
+        for (uint256 i = 0; i < selectorCount; i++) {
+            selectors[i] = roleData.functionSelectorsSet.at(i);
+        }
+        for (uint256 i = 0; i < selectorCount; i++) {
+            roleData.functionSelectorsSet.remove(selectors[i]);
+            delete roleData.functionPermissions[bytes4(selectors[i])];
+        }
+        
+        // Delete role and remove from supported set (cleanup above ensures no stale RBAC data)
+        delete self.roles[roleHash];
         if (!self.supportedRolesSet.remove(roleHash)) {
             revert SharedValidation.ResourceNotFound(roleHash);
-        }   
+        }
     }
 
     /**
@@ -914,13 +1002,13 @@ library EngineBlox {
     }
 
     /**
-     * @dev Updates a role from an old address to a new address.
+     * @dev Updates a wallet in a role (replaces oldWallet with newWallet).
      * @param self The SecureOperationState to modify.
      * @param role The role to update.
      * @param newWallet The new wallet address to assign the role to.
      * @param oldWallet The old wallet address to remove from the role.
      */
-    function updateAssignedWallet(SecureOperationState storage self, bytes32 role, address newWallet, address oldWallet) public {
+    function updateWallet(SecureOperationState storage self, bytes32 role, address newWallet, address oldWallet) public {
         _validateRoleExists(self, role);
         SharedValidation.validateNotZeroAddress(newWallet);
         SharedValidation.validateNewAddress(newWallet, oldWallet);
@@ -975,6 +1063,10 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param roleHash The role hash to add the function permission to.
      * @param functionPermission The function permission to add.
+     * @notice Reverts **`ResourceAlreadyExists`** if the selector is already present on the role. To update
+     *         bitmap or `handlerForSelectors`, **`removeFunctionFromRole`** first then re-add.
+     *         **`removeFunctionFromRole`** succeeds only when the schema's **`isGrantRevocable`** is true (see there);
+     *         **`isProtected`** on the schema does not, by itself, block removing a grant from a role.
      */
     function addFunctionToRole(
         SecureOperationState storage self,
@@ -1007,6 +1099,10 @@ library EngineBlox {
      * @param self The SecureOperationState to modify.
      * @param roleHash The role hash to remove the function permission from.
      * @param functionSelector The function selector to remove from the role.
+     * @notice When the selector is registered, reverts **`GrantNotRevocable`** if **`isGrantRevocable == false`**
+     *         (no role may drop this grant). When **`isGrantRevocable == true`**, the grant may be removed from
+     *         any role, including protected system roles; **`isProtected`** on the schema still blocks
+     *         **`unregisterFunction`** independently, and **`removeRole`** still blocks protected roles.
      */
     function removeFunctionFromRole(
         SecureOperationState storage self,
@@ -1016,12 +1112,10 @@ library EngineBlox {
         // Check if role exists (checks both roles mapping and supportedRolesSet)
         _validateRoleExists(self, roleHash);
         
-        // Security check: Prevent removing protected functions from roles
-        // Check if function exists and is protected
         if (self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
             FunctionSchema memory functionSchema = self.functions[functionSelector];
-            if (functionSchema.isProtected) {
-                revert SharedValidation.CannotModifyProtected(bytes32(functionSelector));
+            if (!functionSchema.isGrantRevocable) {
+                revert SharedValidation.GrantNotRevocable(functionSelector);
             }
         }
         
@@ -1040,6 +1134,9 @@ library EngineBlox {
      * @param functionSelector The function selector to check permissions for.
      * @param requestedAction The specific action being requested.
      * @return True if the wallet has permission for the function and action, false otherwise.
+     * @notice Gas scales with the number of roles assigned to `wallet` (reverse index), not with total system roles.
+     *         Total distinct roles in the system is bounded by `MAX_ROLES`. Each step uses `functionSelectorsSet.contains`
+     *         for the given selector (O(1) in permissions count for that role).
      */
     function hasActionPermission(
         SecureOperationState storage self,
@@ -1047,8 +1144,7 @@ library EngineBlox {
         bytes4 functionSelector,
         TxAction requestedAction
     ) public view returns (bool) {
-        // OPTIMIZED: Use reverse index instead of iterating all roles (O(n) -> O(1) lookup)
-        // This provides significant gas savings when there are many roles
+        // OPTIMIZED: walletRoles[wallet] lists only this wallet's roles instead of scanning every role in the system.
         EnumerableSet.Bytes32Set storage walletRolesSet = self.walletRoles[wallet];
         uint256 rolesLength = walletRolesSet.length();
         
@@ -1085,6 +1181,10 @@ library EngineBlox {
      * @param functionSelector The function selector to check permissions for.
      * @param requestedAction The specific action being requested.
      * @return True if the role has permission for the function and action, false otherwise.
+     * @notice Uses only whether the role lists `functionSelector` and the action bitmap. It does **not** read
+     *         `FunctionPermission.handlerForSelectors` at runtime; that array is validated at **`addFunctionToRole`**
+     *         against the function schema (`_validateHandlerForSelectors`). Handler↔execution wiring at use time is
+     *         enforced **globally** in strict mode via **`_validateExecutionAndHandlerPermissions`**, not per stored role row.
      */
     function roleHasActionPermission(
         SecureOperationState storage self,
@@ -1107,22 +1207,29 @@ library EngineBlox {
     // ============ FUNCTION MANAGEMENT FUNCTIONS ============
 
     /**
-     * @dev Creates a function access control with specified permissions.
+     * @dev Registers a function access control with specified permissions.
      * @param self The SecureOperationState to check.
      * @param functionSignature Function signature (e.g., "transfer(address,uint256)") or function name.
      * @param functionSelector Hash identifier for the function.
      * @param operationName The name of the operation type.
      * @param supportedActionsBitmap Bitmap of permissions required to execute this function.
-     * @param isProtected Whether the function schema is protected from removal.
-     * @param handlerForSelectors Non-empty array required - execution selectors must contain self-reference, handler selectors must point to execution selectors
-     */
-    function createFunctionSchema(
+     * @param enforceHandlerRelations When true (strict mode), handlerForSelectors in role permissions must match this schema's handlerForSelectors at use time. When false (flexible mode), forward references are allowed.
+     * @param isProtected Whether the function schema is protected from **unregister** (`unregisterFunction`).
+     * @param isGrantRevocable When false, `removeFunctionFromRole` cannot remove this selector from any role; when true, grants may be removed from any role, including protected system roles.
+     * @param handlerForSelectors Non-empty array required - execution selectors must contain self-reference, handler selectors must point to execution selectors.
+     * @custom:security OPERATIONAL MODES: We do not require handlerForSelectors[i] to be in supportedFunctionsSet at registration.
+     *         - Strict mode (enforceHandlerRelations == true): at use time (_validateHandlerForSelectors) we require role permissions' handlerForSelectors to match this schema's handlerForSelectors; registration order is flexible.
+     *         - Flexible mode (enforceHandlerRelations == false): validation is skipped; forward references and unregistered selectors are allowed by design. Callers select the mode per schema.
+     */
+    function registerFunction(
         SecureOperationState storage self,
         string memory functionSignature,
         bytes4 functionSelector,
         string memory operationName,
         uint16 supportedActionsBitmap,
+        bool enforceHandlerRelations,
         bool isProtected,
+        bool isGrantRevocable,
         bytes4[] memory handlerForSelectors
     ) public {
         // Validate that functionSignature matches functionSelector
@@ -1132,21 +1239,13 @@ library EngineBlox {
         if (derivedSelector != functionSelector) {
             revert SharedValidation.FunctionSelectorMismatch(functionSelector, derivedSelector);
         }
-
-        // SECURITY: Validate that functions existing in contract bytecode must be protected
-        // This checks if the function selector exists in the contract's bytecode
-        // If it exists, it must be protected to prevent accidental removal of system-critical functions
-        _validateContractFunctionProtection(functionSelector, isProtected);
-
         // Derive operation type from operation name
         bytes32 derivedOperationType = keccak256(bytes(operationName));
 
-        // Validate handlerForSelectors: non-empty and all selectors are non-zero
-        // NOTE:
-        // - Empty arrays are NOT allowed anymore. Execution selectors must have
-        //   at least one entry pointing to themselves (self-reference), and
-        //   handler selectors must point to valid execution selectors.
-        // - bytes4(0) is never allowed in this array.
+        // Validate handlerForSelectors: non-empty and all selectors are non-zero.
+        // We do NOT require handlerForSelectors[i] to be in supportedFunctionsSet here.
+        // Operational mode is controlled by enforceHandlerRelations: strict mode validates at use time;
+        // flexible mode allows forward references and unregistered selectors by design. See @custom:security OPERATIONAL MODES above.
         if (handlerForSelectors.length == 0) {
             revert SharedValidation.OperationFailed();
         }
@@ -1179,7 +1278,9 @@ library EngineBlox {
         schema.operationType = derivedOperationType;
         schema.operationName = operationName;
         schema.supportedActionsBitmap = supportedActionsBitmap;
+        schema.enforceHandlerRelations = enforceHandlerRelations;
         schema.isProtected = isProtected;
+        schema.isGrantRevocable = isGrantRevocable;
         schema.handlerForSelectors = handlerForSelectors;
         
         // Add to supportedFunctionsSet
@@ -1189,15 +1290,24 @@ library EngineBlox {
     }
 
     /**
-     * @dev Removes a function schema from the system.
+     * @dev Unregisters a function schema from the system.
      * @param self The SecureOperationState to modify.
-     * @param functionSelector The function selector to remove.
+     * @param functionSelector The function selector to unregister.
      * @param safeRemoval If true, reverts with ResourceAlreadyExists when any role still references this function.
      *        The safeRemoval check is done inside this function (iterating supportedRolesSet directly) for efficiency.
-     * @notice Security: Cannot remove protected function schemas to maintain system integrity.
+     * @notice Security: Cannot unregister protected function schemas to maintain system integrity.
      * @notice Cleanup: Automatically removes unused operation types from supportedOperationTypesSet.
-     */
-    function removeFunctionSchema(
+     * @notice **Whitelist / hooks:** Per-selector `functionTargetWhitelist` and `functionTargetHooks` are **not**
+     *         cleared on unregister. Stale entries are inert while the selector is absent from
+     *         `supportedFunctionsSet` (whitelist checks revert `ResourceNotFound`). If the selector is re-registered
+     *         later, prior whitelist/hook rows reappear. Operators should clear these via `REMOVE_TARGET_FROM_WHITELIST`
+     *         / `clearHook` before or after unregister if a clean slate is desired.
+     * @notice **Role grants with `safeRemoval == false`:** Roles may retain `FunctionPermission` entries for the
+     *         unregistered selector; execution paths will revert because the schema no longer exists, but
+     *         `roleHasActionPermission` still returns true for the orphan row. Use `safeRemoval == true` or
+     *         strip role grants before unregister when state consistency matters.
+     */
+    function unregisterFunction(
         SecureOperationState storage self,
         bytes4 functionSelector,
         bool safeRemoval
@@ -1244,34 +1354,15 @@ library EngineBlox {
         }
     }
 
-    /**
-     * @dev Checks if a specific action is supported by a function.
-     * @param self The SecureOperationState to check.
-     * @param functionSelector The function selector to check.
-     * @param action The action to check for support.
-     * @return True if the action is supported by the function, false otherwise.
-     */
-    function isActionSupportedByFunction(
-        SecureOperationState storage self,
-        bytes4 functionSelector,
-        TxAction action
-    ) public view returns (bool) {
-        // Check if function exists in supportedFunctionsSet
-        if (!self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
-            return false;
-        }
-        
-        FunctionSchema memory functionSchema = self.functions[functionSelector];
-        return hasActionInBitmap(functionSchema.supportedActionsBitmap, action);
-    }
-
     /**
      * @dev Adds a target address to the whitelist for a function selector.
      * @param self The SecureOperationState to modify.
      * @param functionSelector The function selector whose whitelist will be updated.
      * @param target The target address to add to the whitelist.
+     * @notice There is no on-chain cap on how many targets may be listed per selector (unlike `MAX_HOOKS_PER_SELECTOR`
+     *         for hooks). Execution still uses O(1) membership checks; only enumeration helpers scale with set size.
      */
-    function addTargetToFunctionWhitelist(
+    function addTargetToWhitelist(
         SecureOperationState storage self,
         bytes4 functionSelector,
         address target
@@ -1295,34 +1386,64 @@ library EngineBlox {
      * @param functionSelector The function selector whose whitelist will be updated.
      * @param target The target address to remove from the whitelist.
      */
-    function removeTargetFromFunctionWhitelist(
+    function removeTargetFromWhitelist(
         SecureOperationState storage self,
         bytes4 functionSelector,
         address target
     ) public {
+        SharedValidation.validateNotZeroAddress(target);
+
         EnumerableSet.AddressSet storage set = self.functionTargetWhitelist[functionSelector];
         if (!set.remove(target)) {
             revert SharedValidation.ItemNotFound(target);
         }
     }
 
+    /**
+     * @notice Validates attached `PaymentDetails` at request and execution (whitelist policy).
+     * @dev No-op when both amounts are zero. Otherwise `_validateTargetWhitelist` for
+     *      `ATTACHED_PAYMENT_RECIPIENT_SELECTOR` and, when `erc20TokenAmount > 0`, `ERC20_TRANSFER_SELECTOR` (non-zero
+     *      target enforced inside `_validateTargetWhitelist`). Invoked from `txRequestWithPayment`, `requestAndApprove`,
+     *      and `executeAttachedPayment`.
+     * @param self The secure operation state.
+     * @param payment Attached payment fields.
+     */
+    function _validateAttachedPaymentPolicy(
+        SecureOperationState storage self,
+        PaymentDetails memory payment
+    ) private view {
+        if (payment.nativeTokenAmount == 0 && payment.erc20TokenAmount == 0) {
+            return;
+        }
+        _validateTargetWhitelist(self, ATTACHED_PAYMENT_RECIPIENT_SELECTOR, payment.recipient);
+        if (payment.erc20TokenAmount > 0) {
+            _validateTargetWhitelist(self, ERC20_TRANSFER_SELECTOR, payment.erc20TokenAddress);
+        }
+    }
+
     /**
      * @dev Validates that the target address is whitelisted for the given function selector.
-     *      Internal contract calls (address(this)) are always allowed.
+     *      Reverts if `target` is the zero address (`validateNotZeroAddress`) first.
+     *      Reverts if `functionSelector` is not registered in `supportedFunctionsSet` (no silent skip).
+     *      Internal contract calls (`target == address(this)`) are always allowed once the selector is registered.
      * @param self The SecureOperationState to check.
      * @param functionSelector The function selector being executed.
      * @param target The target contract address.
      * @notice Target MUST be present in functionTargetWhitelist[functionSelector] unless target is address(this).
      *         If whitelist is empty (no entries), no targets are allowed - explicit deny for security.
+     * @notice Attached payments use `ATTACHED_PAYMENT_RECIPIENT_SELECTOR` and `ERC20_TRANSFER_SELECTOR`;
+     *         see `_validateAttachedPaymentPolicy`. Deployments using attached payouts must register those schemas.
+     * @notice Gas: Membership check only (`EnumerableSet.contains`); does not scan the full whitelist.
      */
-    function _validateFunctionTargetWhitelist(
+    function _validateTargetWhitelist(
         SecureOperationState storage self,
         bytes4 functionSelector,
         address target
     ) internal view {
-        // Fast path: selector not registered, skip validation
+        SharedValidation.validateNotZeroAddress(target);
+
         if (!self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
-            return;
+            revert SharedValidation.ResourceNotFound(bytes32(functionSelector));
         }
 
         // SECURITY: Internal contract calls are always allowed
@@ -1348,6 +1469,7 @@ library EngineBlox {
      * @param functionSelector The function selector to query.
      * @return Array of whitelisted target addresses.
      * @notice Access control should be enforced by the calling contract.
+     * @notice Gas / return size scale linearly with whitelist length (full set materialization).
      */
     function getFunctionWhitelistTargets(
         SecureOperationState storage self,
@@ -1391,17 +1513,17 @@ library EngineBlox {
     // ============ FUNCTION TARGET HOOKS MANAGEMENT ============
 
     /**
-     * @dev Adds a target address to the hooks for a function selector.
+     * @dev Sets (adds) a hook contract for a function selector.
      * @param self The SecureOperationState to modify.
      * @param functionSelector The function selector whose hooks will be updated.
-     * @param target The target address to add to the hooks.
+     * @param hook The hook contract address to add (must not be zero).
      */
-    function addTargetToFunctionHooks(
+    function setHook(
         SecureOperationState storage self,
         bytes4 functionSelector,
-        address target
+        address hook
     ) public {
-        SharedValidation.validateNotZeroAddress(target);
+        SharedValidation.validateNotZeroAddress(hook);
 
         // Function selector must be registered in the schema set
         if (!self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
@@ -1416,36 +1538,38 @@ library EngineBlox {
             MAX_HOOKS_PER_SELECTOR
         );
         
-        if (!set.add(target)) {
-            revert SharedValidation.ItemAlreadyExists(target);
+        if (!set.add(hook)) {
+            revert SharedValidation.ItemAlreadyExists(hook);
         }
     }
 
     /**
-     * @dev Removes a target address from the hooks for a function selector.
+     * @dev Clears (removes) a hook contract for a function selector.
      * @param self The SecureOperationState to modify.
      * @param functionSelector The function selector whose hooks will be updated.
-     * @param target The target address to remove from the hooks.
+     * @param hook The hook contract address to remove (must not be zero).
      */
-    function removeTargetFromFunctionHooks(
+    function clearHook(
         SecureOperationState storage self,
         bytes4 functionSelector,
-        address target
+        address hook
     ) public {
+        SharedValidation.validateNotZeroAddress(hook);
+
         EnumerableSet.AddressSet storage set = self.functionTargetHooks[functionSelector];
-        if (!set.remove(target)) {
-            revert SharedValidation.ItemNotFound(target);
+        if (!set.remove(hook)) {
+            revert SharedValidation.ItemNotFound(hook);
         }
     }
 
     /**
-     * @dev Returns all hook target addresses for a function selector.
+     * @dev Returns all configured hooks for a function selector.
      * @param self The SecureOperationState to check.
      * @param functionSelector The function selector to query.
-     * @return Array of hook target addresses.
+     * @return Array of hook contract addresses.
      * @notice Access control should be enforced by the calling contract.
      */
-    function getFunctionHookTargets(
+    function getHooks(
         SecureOperationState storage self,
         bytes4 functionSelector
     ) public view returns (address[] memory) {
@@ -1469,7 +1593,7 @@ library EngineBlox {
 
     /**
      * @dev Internal: Returns all function schemas that use a specific operation type.
-     * Used by removeFunctionSchema and getFunctionsByOperationType.
+     * Used by unregisterFunction and getFunctionsByOperationType.
      */
     function _getFunctionsByOperationType(
         SecureOperationState storage self,
@@ -1500,42 +1624,44 @@ library EngineBlox {
     // ============ BACKWARD COMPATIBILITY FUNCTIONS ============
 
     /**
-     * @dev Gets all pending transaction IDs as an array for backward compatibility
+     * @dev Gets all pending transaction IDs
      * @param self The SecureOperationState to check
      * @return Array of pending transaction IDs
      * @notice Access control should be enforced by the calling contract.
+     * @notice Full enumeration of `pendingTransactionsSet`. State-changing engine paths add/remove by id only and
+     *         do not walk the entire pending set.
      */
-    function getPendingTransactionsList(SecureOperationState storage self) public view returns (uint256[] memory) {
+    function getPendingTransactions(SecureOperationState storage self) public view returns (uint256[] memory) {
         return _convertUintSetToArray(self.pendingTransactionsSet);
     }
 
     /**
-     * @dev Gets all supported roles as an array for backward compatibility
+     * @dev Gets all supported roles as an array
      * @param self The SecureOperationState to check
      * @return Array of supported role hashes
      * @notice Access control should be enforced by the calling contract.
      */
-    function getSupportedRolesList(SecureOperationState storage self) public view returns (bytes32[] memory) {
+    function getSupportedRoles(SecureOperationState storage self) public view returns (bytes32[] memory) {
         return _convertBytes32SetToArray(self.supportedRolesSet);
     }
 
     /**
-     * @dev Gets all supported function selectors as an array for backward compatibility
+     * @dev Gets all supported function selectors as an array
      * @param self The SecureOperationState to check
      * @return Array of supported function selectors
      * @notice Access control should be enforced by the calling contract.
      */
-    function getSupportedFunctionsList(SecureOperationState storage self) public view returns (bytes4[] memory) {
+    function getSupportedFunctions(SecureOperationState storage self) public view returns (bytes4[] memory) {
         return _convertBytes4SetToArray(self.supportedFunctionsSet);
     }
 
     /**
-     * @dev Gets all supported operation types as an array for backward compatibility
+     * @dev Gets all supported operation types as an array
      * @param self The SecureOperationState to check
      * @return Array of supported operation type hashes
      * @notice Access control should be enforced by the calling contract.
      */
-    function getSupportedOperationTypesList(SecureOperationState storage self) public view returns (bytes32[] memory) {
+    function getSupportedOperationTypes(SecureOperationState storage self) public view returns (bytes32[] memory) {
         return _convertBytes32SetToArray(self.supportedOperationTypesSet);
     }
 
@@ -1559,7 +1685,7 @@ library EngineBlox {
      * @return Array of authorized wallet addresses
      * @notice Access control should be enforced by the calling contract.
      */
-    function _getAuthorizedWallets(
+    function getAuthorizedWallets(
         SecureOperationState storage self,
         bytes32 roleHash
     ) public view returns (address[] memory) {
@@ -1635,6 +1761,8 @@ library EngineBlox {
      * @param self The SecureOperationState to check against
      * @param metaTx The meta-transaction containing the signature to verify
      * @return True if the signature is valid, false otherwise
+     * @notice Nonce is **per signer** and **strictly sequential** for replay protection (`nonce` must equal `signerNonces[signer]`).
+     *         Different signers have independent counters; same-signer submissions must be ordered by relayers—by design.
      */
     function verifySignature(
         SecureOperationState storage self,
@@ -1662,11 +1790,17 @@ library EngineBlox {
             SharedValidation.validateTransactionId(metaTx.txRecord.txId, self.txCounter);
         }
 
+        // Bind signed handlerContract to the verifying contract (EIP-712 verifyingContract).
+        // NOTE: Entrypoint binding to the wrapper selector (msg.sig) must be enforced in the wrapper context
+        // (e.g. BaseStateMachine), not here, because EngineBlox execute via external-library DELEGATECALL.
+        if (metaTx.params.handlerContract != address(this)) {
+            revert SharedValidation.MetaTxHandlerContractMismatch(metaTx.params.handlerContract, address(this));
+        }
+
         // Authorization check - verify signer has meta-transaction signing permissions for the function and action
-        bool isSignAction = metaTx.params.action == TxAction.SIGN_META_REQUEST_AND_APPROVE || metaTx.params.action == TxAction.SIGN_META_APPROVE || metaTx.params.action == TxAction.SIGN_META_CANCEL;
         bool isHandlerAuthorized = hasActionPermission(self, metaTx.params.signer, metaTx.params.handlerSelector, metaTx.params.action);
         bool isExecutionAuthorized = hasActionPermission(self, metaTx.params.signer, metaTx.txRecord.params.executionSelector, metaTx.params.action);
-        if (!isSignAction || !isHandlerAuthorized || !isExecutionAuthorized) {
+        if (!isHandlerAuthorized || !isExecutionAuthorized) {
             revert SharedValidation.SignerNotAuthorized(metaTx.params.signer);
         }
           
@@ -1679,39 +1813,84 @@ library EngineBlox {
     }
 
     /**
-     * @dev Generates a message hash for the specified meta-transaction following EIP-712
+     * @dev Generates the EIP-712 message hash for the meta-transaction.
+     *      Uses selective MetaTxRecord (txId, params, payment only) with standard EIP-712 type hashes
+     *      so that eth_signTypedData_v4 (and equivalent) can reproduce the same digest when given
+     *      matching domain + types:
+     *
+     *      - primaryType: MetaTransaction
+     *      - domain: { name: "Bloxchain", version: "1.0.0", chainId, verifyingContract }
+     *      - types: MetaTransaction, MetaTxRecord, TxParams, MetaTxParams, PaymentDetails
+     *
+     *      Integrators MAY:
+     *      - use typed-data signing (eth_signTypedData_v4 / signTypedData) with the above domain/types, or
+     *      - sign the resulting digest as a raw hash (e.g. account.sign({ hash: contractDigest })).
+     *
+     *      In all cases, on-chain verification uses recoverSigner(messageHash, signature) which applies
+     *      ecrecover(messageHash, v, r, s) with no personal_sign / EIP-191 prefix.
+     *
+     *      The resulting digest is also written into the `message` field of helper-built `MetaTransaction`
+     *      structs so integrators can use it directly without recomputing the hash client-side.
      * @param metaTx The meta-transaction to generate the hash for
-     * @return The generated message hash
+     * @return The EIP-712 digest (no prefix; use standard recovery)
      */
     function generateMessageHash(MetaTransaction memory metaTx) private view returns (bytes32) {
-        bytes32 domainSeparator = keccak256(abi.encode(
-            DOMAIN_SEPARATOR_TYPE_HASH,
-            PROTOCOL_NAME_HASH,
-            keccak256(abi.encodePacked(VERSION_MAJOR, ".", VERSION_MINOR, ".", VERSION_PATCH)),
-            block.chainid,
-            address(this)
+        bytes32 domainSeparator = keccak256(
+            abi.encode(
+                DOMAIN_SEPARATOR_TYPE_HASH,
+                PROTOCOL_NAME_HASH,
+                keccak256(bytes(VERSION)),
+                block.chainid,
+                address(this)
+            )
+        );
+
+        TxParams memory tp = metaTx.txRecord.params;
+        bytes32 txParamsStructHash = keccak256(abi.encode(
+            TX_PARAMS_TYPE_HASH,
+            tp.requester,
+            tp.target,
+            tp.value,
+            tp.gasLimit,
+            tp.operationType,
+            tp.executionSelector,
+            keccak256(tp.executionParams)
+        ));
+
+        PaymentDetails memory payment = metaTx.txRecord.payment;
+        bytes32 paymentStructHash = keccak256(abi.encode(
+            PAYMENT_DETAILS_TYPE_HASH,
+            payment.recipient,
+            payment.nativeTokenAmount,
+            payment.erc20TokenAddress,
+            payment.erc20TokenAmount
+        ));
+
+        bytes32 metaTxRecordStructHash = keccak256(abi.encode(
+            META_TX_RECORD_TYPE_HASH,
+            metaTx.txRecord.txId,
+            txParamsStructHash,
+            paymentStructHash
+        ));
+
+        MetaTxParams memory mp = metaTx.params;
+        bytes32 metaTxParamsStructHash = keccak256(abi.encode(
+            META_TX_PARAMS_TYPE_HASH,
+            mp.chainId,
+            mp.nonce,
+            mp.handlerContract,
+            mp.handlerSelector,
+            uint8(mp.action),
+            mp.deadline,
+            mp.maxGasPrice,
+            mp.signer
         ));
 
         bytes32 structHash = keccak256(abi.encode(
-            TYPE_HASH,
-            keccak256(abi.encode(
-                metaTx.txRecord.txId,
-                metaTx.txRecord.params.requester,
-                metaTx.txRecord.params.target,
-                metaTx.txRecord.params.value,
-                metaTx.txRecord.params.gasLimit,
-                metaTx.txRecord.params.operationType,
-                metaTx.txRecord.params.executionSelector,
-                keccak256(metaTx.txRecord.params.executionParams)
-            )),
-            metaTx.params.chainId,
-            metaTx.params.nonce,
-            metaTx.params.handlerContract,
-            metaTx.params.handlerSelector,
-            uint8(metaTx.params.action),
-            metaTx.params.deadline,
-            metaTx.params.maxGasPrice,
-            metaTx.params.signer
+            META_TX_TYPE_HASH,
+            metaTxRecordStructHash,
+            metaTxParamsStructHash,
+            keccak256(metaTx.data)
         ));
 
         return keccak256(abi.encodePacked(
@@ -1722,10 +1901,24 @@ library EngineBlox {
     }
 
     /**
-     * @dev Recovers the signer address from a message hash and signature.
-     * @param messageHash The hash of the message that was signed.
-     * @param signature The signature to recover the address from.
-     * @return The address of the signer.
+     * @dev Recovers the signer from the EIP-712 digest and signature. Uses standard EIP-712 recovery (no message prefix).
+     *
+     *      Integrators have two equivalent options:
+     *      - Use typed-data signing (eth_signTypedData_v4 / signTypedData) with:
+     *          - primaryType: MetaTransaction
+     *          - domain: { name: "Bloxchain", version: "1.0.0", chainId, verifyingContract }
+     *          - types: MetaTransaction, MetaTxRecord, TxParams, MetaTxParams, PaymentDetails
+     *        In this case the wallet computes the same digest as generateMessageHash and signs it.
+     *      - Sign the digest returned by generateMessageHash as a raw hash—e.g.
+     *        account.sign({ hash: contractDigest }) or equivalent raw-hash signing API—with no
+     *        EIP-191/personal prefix.
+     *
+     *      In all cases, this function applies ecrecover(messageHash, v, r, s) over the raw EIP-712 digest.
+     *      personal_sign / EIP-191-prefixed signatures remain incompatible.
+     *
+     * @param messageHash The EIP-712 digest (keccak256("\x19\x01" || domainSeparator || structHash))
+     * @param signature The signature (r, s, v)
+     * @return The address of the signer
      */
     function recoverSigner(bytes32 messageHash, bytes memory signature) public pure returns (address) {
         SharedValidation.validateSignatureLength(signature);
@@ -1754,7 +1947,7 @@ library EngineBlox {
         // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}
         SharedValidation.validateSignatureParams(s, v);
 
-        address signer = ecrecover(messageHash.toEthSignedMessageHash(), v, r, s);
+        address signer = ecrecover(messageHash, v, r, s);
         SharedValidation.validateRecoveredSigner(signer);
 
         return signer;
@@ -1771,7 +1964,7 @@ library EngineBlox {
     ) public view returns (MetaTransaction memory) {
         SharedValidation.validateNotZeroAddress(txParams.target);
         
-        TxRecord memory txRecord = createNewTxRecord(
+        TxRecord memory txRecord = createTxRecord(
             self,
             txParams.requester,
             txParams.target,
@@ -1780,7 +1973,7 @@ library EngineBlox {
             txParams.operationType,
             txParams.executionSelector,
             txParams.executionParams,
-            _noPayment()
+            _emptyPayment()
         );
 
          return generateMetaTransaction(self, txRecord, metaTxParams);
@@ -1821,9 +2014,9 @@ library EngineBlox {
         MetaTxParams memory metaTxParams
     ) private view returns (MetaTransaction memory) {
         SharedValidation.validateChainId(metaTxParams.chainId);
-        SharedValidation.validateHandlerContract(metaTxParams.handlerContract);
+        SharedValidation.validateMetaTxHandlerContractBinding(metaTxParams.handlerContract);
         SharedValidation.validateHandlerSelector(metaTxParams.handlerSelector);
-        SharedValidation.validateDeadline(metaTxParams.deadline);
+        SharedValidation.validateMetaTxDeadline(metaTxParams.deadline);
         SharedValidation.validateNotZeroAddress(metaTxParams.signer);
 
         // Populate the nonce directly from storage for security
@@ -1834,7 +2027,7 @@ library EngineBlox {
             params: metaTxParams,
             message: 0,
             signature: "",
-            data: prepareTransactionData(txRecord)
+            data: buildCallData(txRecord)
         });
 
         // Generate the message hash for ready to sign meta-transaction
@@ -1885,6 +2078,16 @@ library EngineBlox {
      * @param self The SecureOperationState
      * @param txId The transaction ID
      * @param functionSelector The function selector to emit in the event
+     * @notice **Trust model:** `eventForwarder` is operator-configured (`setEventForwarder` / init). Treat it as a
+     *         **trusted** integration point—malicious or pathological callees can waste gas in the outer tx budget.
+     * @notice **Silent failure:** The `forwardTxEvent` external call is wrapped in `try` / `catch`; reverts or
+     *         panics in the forwarder do **not** revert this contract’s state transitions that already completed.
+     *         Monitoring cannot assume off-chain delivery succeeded; rely on `TransactionEvent` logs on-chain.
+     * @notice **Gas tradeoff:** There is no explicit `{gas: ...}` stipend; the subcall receives the usual EIP-150
+     *         bounded share of remaining gas (not the entire tx). Primary state updates in callers run **before**
+     *         `logTxEvent` where applicable. Optional hardening: configurable stipend + explicit failure event.
+     * @notice **Execution returndata:** full bytes are emitted only via `TxExecutionResult` from `_completeTransaction`;
+     *         this function emits lifecycle `TransactionEvent` with `resultHash` (zero on request/cancel).
      * @custom:security REENTRANCY PROTECTION: This function is safe from reentrancy because:
      *         1. It is called AFTER all state changes are complete (in _completeTransaction,
      *            _cancelTransaction, and txRequest)
@@ -1902,21 +2105,17 @@ library EngineBlox {
         bytes4 functionSelector
     ) public {
         TxRecord memory txRecord = self.txRecords[txId];
-        
-        // Emit only non-sensitive public data
+
         emit TransactionEvent(
             txId,
             functionSelector,
             txRecord.status,
             txRecord.params.requester,
             txRecord.params.target,
-            txRecord.params.operationType
+            txRecord.params.operationType,
+            txRecord.resultHash
         );
-        
-        // Forward event data to event forwarder
-        // REENTRANCY SAFE: External call is wrapped in try-catch and doesn't modify
-        // critical state. Even if eventForwarder is malicious, reentry attempts fail
-        // because transactions are no longer in PENDING status (they're COMPLETED/CANCELLED).
+
         if (self.eventForwarder != address(0)) {
             try IEventForwarder(self.eventForwarder).forwardTxEvent(
                 txId,
@@ -1924,12 +2123,9 @@ library EngineBlox {
                 txRecord.status,
                 txRecord.params.requester,
                 txRecord.params.target,
-                txRecord.params.operationType
-            ) {
-                // Event forwarded successfully
-            } catch {
-                // Forwarding failed, continue execution (non-critical operation)
-            }
+                txRecord.params.operationType,
+                txRecord.resultHash
+            ) {} catch {}
         }
     }
 
@@ -2015,33 +2211,26 @@ library EngineBlox {
      * @param self The SecureOperationState to modify
      * @param txId The transaction ID to complete
      * @param success Whether the transaction execution was successful
-     * @param result The result of the transaction execution
+     * @param executionResult Returndata from the main target call (emitted in `TxExecutionResult`).
      */
     function _completeTransaction(
         SecureOperationState storage self,
         uint256 txId,
         bool success,
-        bytes memory result
+        bytes memory executionResult
     ) private {
-        // enforce that the requested target is whitelisted for this selector.
-        _validateFunctionTargetWhitelist(self, self.txRecords[txId].params.executionSelector, self.txRecords[txId].params.target);
-        
-        // Update storage with new status and result
+        bytes32 resultHash = _executionResultHash(executionResult);
         if (success) {
             self.txRecords[txId].status = TxStatus.COMPLETED;
-            self.txRecords[txId].result = result;
         } else {
             self.txRecords[txId].status = TxStatus.FAILED;
-            self.txRecords[txId].result = result; // Store failure reason for debugging
-            // Note: FAILED status is intentional - transactions can be valid when requested
-            // but fail when executed (e.g., conditions changed, insufficient balance, etc.)
-            // Users can query status via getTransaction() or listen to TransactionEvent
         }
-        
-        // Remove from pending transactions list
-        removeFromPendingTransactionsList(self, txId);
-        
+        self.txRecords[txId].resultHash = resultHash;
+
+        removePendingTx(self, txId);
+
         logTxEvent(self, txId, self.txRecords[txId].params.executionSelector);
+        emit TxExecutionResult(txId, executionResult);
     }
 
     /**
@@ -2053,18 +2242,24 @@ library EngineBlox {
         SecureOperationState storage self,
         uint256 txId
     ) private {
-        // enforce that the requested target is whitelisted for this selector.
-        _validateFunctionTargetWhitelist(self, self.txRecords[txId].params.executionSelector, self.txRecords[txId].params.target);
-        
         self.txRecords[txId].status = TxStatus.CANCELLED;
         
         // Remove from pending transactions list
-        removeFromPendingTransactionsList(self, txId);
+        removePendingTx(self, txId);
         
         logTxEvent(self, txId, self.txRecords[txId].params.executionSelector);
     }
 
-        /**
+    /**
+     * @dev Commitment to execution returndata for storage and `TransactionEvent.resultHash`.
+     * @param executionResult The execution returndata to hash
+     * @return `bytes32(0)` when empty, else `keccak256(executionResult)`
+     */
+    function _executionResultHash(bytes memory executionResult) private pure returns (bytes32) {
+        return executionResult.length == 0 ? bytes32(0) : keccak256(executionResult);
+    }
+
+    /**
      * @dev Validates that the caller has any role permission
      * @param self The SecureOperationState to check
      * @notice This function consolidates the repeated permission check pattern to reduce contract size
@@ -2123,14 +2318,77 @@ library EngineBlox {
     }
 
     /**
-     * @dev Validates that a wallet has permission for both execution selector and handler selector for a given action
-     * @param self The SecureOperationState to check
-     * @param wallet The wallet address to check permissions for
-     * @param executionSelector The execution function selector (underlying operation)
-     * @param handlerSelector The handler/calling function selector
-     * @param action The action to validate permissions for
-     * @notice This function consolidates the repeated dual permission check pattern to reduce contract size
-     * @notice Reverts with NoPermission if either permission check fails
+     * @dev Validates that the meta-transaction txRecord matches the stored record for the given txId.
+     *      Ensures the signer's intent (as reflected in the stored tx from the request phase) is what
+     *      is approved or cancelled; override by meta-tx payload is not allowed for approve/cancel flows.
+     * @param self The SecureOperationState containing the stored tx record.
+     * @param txId The transaction ID.
+     * @param metaTxRecord The TxRecord from the meta-transaction calldata.
+     * @notice Reverts with MetaTxRecordMismatchStoredTx if any execution-affecting or permission-affecting field differs.
+     */
+    function _validateMetaTxMatchRecord(
+        SecureOperationState storage self,
+        uint256 txId,
+        TxRecord memory metaTxRecord
+    ) internal view {
+        TxRecord storage stored = self.txRecords[txId];
+        TxParams storage sp = stored.params;
+        TxParams memory mp = metaTxRecord.params;
+        if (
+            sp.executionSelector != mp.executionSelector ||
+            sp.target != mp.target ||
+            sp.value != mp.value ||
+            sp.requester != mp.requester ||
+            sp.gasLimit != mp.gasLimit ||
+            sp.operationType != mp.operationType ||
+            keccak256(sp.executionParams) != keccak256(mp.executionParams) ||
+            stored.releaseTime != metaTxRecord.releaseTime ||
+            metaTxRecord.resultHash != bytes32(0)
+        ) {
+            revert SharedValidation.MetaTxRecordMismatchStoredTx(txId);
+        }
+    }
+
+    /**
+     * @dev Validates that the meta-transaction payment matches the stored record for the given txId.
+     *      Ensures the signed payment (recipient, amounts, token) equals what will be executed.
+     * @param self The SecureOperationState containing the stored tx record.
+     * @param txId The transaction ID.
+     * @param metaTxRecord The TxRecord from the meta-transaction calldata.
+     * @notice Reverts with MetaTxPaymentMismatchStoredTx if any payment field differs from stored.
+     */
+    function _validateMetaTxPaymentMatchRecord(
+        SecureOperationState storage self,
+        uint256 txId,
+        TxRecord memory metaTxRecord
+    ) internal view {
+        PaymentDetails storage storedPayment = self.txRecords[txId].payment;
+        PaymentDetails memory metaPayment = metaTxRecord.payment;
+        if (
+            storedPayment.recipient != metaPayment.recipient ||
+            storedPayment.nativeTokenAmount != metaPayment.nativeTokenAmount ||
+            storedPayment.erc20TokenAddress != metaPayment.erc20TokenAddress ||
+            storedPayment.erc20TokenAmount != metaPayment.erc20TokenAmount
+        ) {
+            revert SharedValidation.MetaTxPaymentMismatchStoredTx(txId);
+        }
+    }
+
+    /**
+     * @dev Validates that a wallet has permission for both execution selector and handler selector for a given action.
+     * @param self The SecureOperationState to check.
+     * @param wallet The wallet address to check permissions for.
+     * @param executionSelector The execution function selector (underlying operation).
+     * @param handlerSelector The handler/calling function selector.
+     * @param action The action to validate permissions for.
+     * @notice This function consolidates the repeated dual permission check pattern to reduce contract size.
+     * @notice Reverts with NoPermission if either permission check fails.
+     * @notice **Strict mode (`enforceHandlerRelations` on the handler schema):** requires `executionSelector` to appear
+     *         in **`functions[handlerSelector].handlerForSelectors`** — a **global** graph on the handler’s `FunctionSchema`,
+     *         not a lookup of each role’s stored `FunctionPermission.handlerForSelectors` at runtime.
+     * @notice **Role rows:** `FunctionPermission.handlerForSelectors` is enforced when permissions are **granted**
+     *         (`addFunctionToRole` → `_validateHandlerForSelectors`); `hasActionPermission` / `roleHasActionPermission` do not
+     *         re-apply that list per call. Narrowing is by **which selectors and actions** you grant, plus dual checks here.
      */
     function _validateExecutionAndHandlerPermissions(
         SecureOperationState storage self,
@@ -2139,6 +2397,10 @@ library EngineBlox {
         bytes4 handlerSelector,
         TxAction action
     ) internal view {
+        // Ensure both execution and handler selectors have registered function schemas
+        _validateFunctionSchemaExists(self, executionSelector);
+        _validateFunctionSchemaExists(self, handlerSelector);
+
         // Validate permission for the execution selector (underlying operation)
         if (!hasActionPermission(self, wallet, executionSelector, action)) {
             revert SharedValidation.NoPermission(wallet);
@@ -2147,47 +2409,50 @@ library EngineBlox {
         if (!hasActionPermission(self, wallet, handlerSelector, action)) {
             revert SharedValidation.NoPermission(wallet);
         }
+
+        // In strict mode, enforce that the executionSelector is part of the handlerSelector's schema-level flow.
+        // Handler schemas declare which execution selectors they are allowed to trigger globally. Role grants still
+        // require hasActionPermission on both selectors; per-role FunctionPermission.handlerForSelectors is validated at addFunctionToRole, not re-read here.
+        FunctionSchema storage handlerSchema = self.functions[handlerSelector];
+        if (handlerSchema.enforceHandlerRelations) {
+            if (!_schemaHasHandlerSelector(handlerSchema, executionSelector)) {
+                revert SharedValidation.HandlerForSelectorMismatch(
+                    executionSelector,
+                    handlerSelector
+                );
+            }
+        }
     }
 
     /**
-     * @dev Validates that all handlerForSelectors are present in the schema's handlerForSelectors array
+     * @dev Validates that all handlerForSelectors are present in the schema's handlerForSelectors array.
+     *      When schema.enforceHandlerRelations is false (flexible mode), validation is skipped and this function returns immediately.
+     *      When true (strict mode), every permission handlerForSelector must appear in the schema's handlerForSelectors.
      * @param self The SecureOperationState to validate against
      * @param functionSelector The function selector for which the permission is defined
      * @param handlerForSelectors The handlerForSelectors array from the permission to validate
-     * @notice Reverts with HandlerForSelectorMismatch if any handlerForSelector is not found in the schema's array
-     * @notice Special case: Execution function permissions should include functionSelector in handlerForSelectors (self-reference)
+     * @notice Reverts with HandlerForSelectorMismatch if any handlerForSelector is not found in the schema's array (strict mode only).
+     * @notice Special case: Execution function permissions should include functionSelector in handlerForSelectors (self-reference).
      */
     function _validateHandlerForSelectors(
         SecureOperationState storage self,
         bytes4 functionSelector,
         bytes4[] memory handlerForSelectors
     ) internal view {
-        bytes32 functionSelectorHash = bytes32(functionSelector);
-
-        // Ensure the function schema exists
-        if (!self.supportedFunctionsSet.contains(functionSelectorHash)) {
-            revert SharedValidation.ResourceNotFound(functionSelectorHash);
-        }
+        _validateFunctionSchemaExists(self, functionSelector);
 
         FunctionSchema storage schema = self.functions[functionSelector];
 
+        // If this function schema does not enforce handler relations, skip validation.
+        if (!schema.enforceHandlerRelations) {
+            return;
+        }
+
         // Validate each handlerForSelector in the array
         for (uint256 j = 0; j < handlerForSelectors.length; j++) {
             bytes4 handlerForSelector = handlerForSelectors[j];
-            
-            // Special case: execution function permissions use handlerForSelector == functionSelector (self-reference)
-            if (handlerForSelector == functionSelector) {
-                continue; // Valid execution function permission
-            }
 
-            bool found = false;
-            for (uint256 i = 0; i < schema.handlerForSelectors.length; i++) {
-                if (schema.handlerForSelectors[i] == handlerForSelector) {
-                    found = true;
-                    break;
-                }
-            }
-            if (!found) {
+            if (!_schemaHasHandlerSelector(schema, handlerForSelector)) {
                 revert SharedValidation.HandlerForSelectorMismatch(
                     bytes4(0), // Cannot return array, use 0 as placeholder
                     handlerForSelector
@@ -2196,6 +2461,24 @@ library EngineBlox {
         }
     }
 
+    /**
+     * @dev Checks whether a given handler selector is present in a function schema's handlerForSelectors array.
+     * @param schema The function schema to inspect.
+     * @param handlerSelector The handler selector to search for.
+     * @return True if the handler selector is present, false otherwise.
+     */
+    function _schemaHasHandlerSelector(
+        FunctionSchema storage schema,
+        bytes4 handlerSelector
+    ) internal view returns (bool) {
+        for (uint256 i = 0; i < schema.handlerForSelectors.length; i++) {
+            if (schema.handlerForSelectors[i] == handlerSelector) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /**
      * @dev Validates meta-transaction permissions for a function permission
      * @param self The secure operation state
@@ -2231,14 +2514,48 @@ library EngineBlox {
             revert SharedValidation.ConflictingMetaTxPermissions(functionPermission.functionSelector);
         }
         
-        // Validate that each action in the bitmap is supported by the function
-        // This still requires iteration, but we can optimize it
-        for (uint i = 0; i < 9; i++) { // TxAction enum has 9 values (0-8)
-            if (hasActionInBitmap(bitmap, TxAction(i))) {
-                if (!isActionSupportedByFunction(self, functionPermission.functionSelector, TxAction(i))) {
-                    revert SharedValidation.NotSupported();
-                }
-            }
+        _validateActionsSupportedByFunction(self, functionPermission.functionSelector, bitmap);
+    }
+
+    /**
+     * @dev Validates that the meta-transaction uses the expected signer action for the current workflow.
+     * @param metaTx The meta-transaction to validate.
+     * @param expectedAction The TxAction that must be used as the signer action.
+     * @custom:security Enforces strict separation between SIGN_META_REQUEST_AND_APPROVE,
+     *                  SIGN_META_APPROVE and SIGN_META_CANCEL workflows.
+     */
+    function _validateMetaTxAction(
+        MetaTransaction memory metaTx,
+        TxAction expectedAction
+    ) internal pure {
+        if (metaTx.params.action != expectedAction) {
+            revert SharedValidation.NotSupported();
+        }
+    }
+
+    /**
+     * @dev Validates that all actions present in the bitmap are supported by the function schema.
+     * @param self The SecureOperationState to check.
+     * @param functionSelector The function selector to check.
+     * @param bitmap The granted actions bitmap to validate.
+     */
+    function _validateActionsSupportedByFunction(
+        SecureOperationState storage self,
+        bytes4 functionSelector,
+        uint16 bitmap
+    ) internal view {
+        // If the function itself is not supported, none of its actions can be considered valid
+        if (!self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
+            revert SharedValidation.NotSupported();
+        }
+
+        uint16 granted = bitmap;
+        uint16 supported = self.functions[functionSelector].supportedActionsBitmap;
+
+        // Any bit set in granted but not in supported is invalid
+        uint16 invalid = granted & ~supported;
+        if (invalid != 0) {
+            revert SharedValidation.NotSupported();
         }
     }
 
@@ -2246,6 +2563,7 @@ library EngineBlox {
      * @dev Generic helper to convert AddressSet to array
      * @param set The EnumerableSet.AddressSet to convert
      * @return Array of address values
+     * @notice Allocates `length` slots and reads each element—O(set.length()). Used by several public getters.
      */
     function _convertAddressSetToArray(EnumerableSet.AddressSet storage set) 
         internal view returns (address[] memory) {
@@ -2302,79 +2620,11 @@ library EngineBlox {
         return result;
     }
 
-    /**
-     * @dev Validates that if a function exists in contract bytecode, it must be protected
-     * @param functionSelector The function selector
-     * @param isProtected Whether the function is marked as protected
-     * @notice Checks if the function selector exists in the contract's bytecode function selector table
-     * @notice If the selector exists in the contract, it must be protected to prevent accidental removal
-     * @notice This uses low-level bytecode inspection instead of relying on naming conventions
-     * @notice Since we're called via delegatecall, address(this) refers to the calling contract
-     */
-    function _validateContractFunctionProtection(
-        bytes4 functionSelector,
-        bool isProtected
-    ) private view {
-        // Check cheaper condition first: skip expensive bytecode check when already protected
-        if (!isProtected) {
-            // Check if the function selector exists in the contract's bytecode
-            // Since we're called via delegatecall, address(this) refers to the calling contract
-            if (selectorExistsInContract(address(this), functionSelector)) {
-                revert SharedValidation.ContractFunctionMustBeProtected(functionSelector);
-            }
-        }
-    }
-
-    /**
-     * @dev Checks if a function selector exists in a contract's bytecode
-     * @param contractAddress The address of the contract to check
-     * @param selector The 4-byte function selector to search for
-     * @return true if the selector is found in the contract's function selector dispatch table area
-     * @notice Searches the first 2KB where function selectors are stored in the dispatch table
-     * @notice This is a heuristic check - false positives are possible but unlikely
-     * @notice Uses loop unrolling for gas efficiency
-     * @notice Can be used to query any contract's function selector table
-     */
-    function selectorExistsInContract(address contractAddress, bytes4 selector) public view returns (bool) {
-        // Get the contract's bytecode
-        bytes memory code = contractAddress.code;
-        
-        if (code.length < 5) { // Need at least PUSH4 (1 byte) + selector (4 bytes)
-            return false;
-        }
-        
-        // Function selectors are in the dispatch table at the beginning
-        // Typical dispatch tables are < 2KB even for large contracts
-        // Searching only this area reduces gas cost and false positives from metadata/data
-        uint256 searchLength = code.length < 2048 ? code.length : 2048;
-        
-        // Scan for PUSH4 opcode (0x63) with 1-byte sliding window
-        // PUSH4 opcode is followed by 4 bytes which is the function selector
-        // Function selectors in EVM bytecode are emitted as PUSH4 <selector> instructions
-        // These can start at any byte offset, not just 4-byte-aligned positions
-        for (uint256 i = 0; i + 4 < searchLength; i++) {
-            // Check if current byte is PUSH4 opcode (0x63)
-            if (uint8(code[i]) == 0x63) {
-                // Extract the 4-byte selector following the PUSH4 opcode
-                bytes4 candidate;
-                assembly {
-                    let codePtr := add(add(code, 0x20), add(i, 1))
-                    candidate := mload(codePtr)
-                }
-                if (candidate == selector) {
-                    return true;
-                }
-            }
-        }
-        
-        return false;
-    }
-
     /**
      * @dev Returns an empty PaymentDetails struct for use when no payment is attached.
      * @return payment Empty payment details (recipient and amounts zero).
      */
-    function _noPayment() internal pure returns (PaymentDetails memory payment) {
+    function _emptyPayment() internal pure returns (PaymentDetails memory payment) {
         return PaymentDetails({
             recipient: address(0),
             nativeTokenAmount: 0,