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

package/{contracts/core → core}/lib/EngineBlox.sol

@@ -7,8 +7,8 @@ import { MessageHashUtils } from "@openzeppelin/contracts/utils/cryptography/Mes
 import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 
 // Local imports
-import "../../utils/SharedValidation.sol";
-import "../../interfaces/IEventForwarder.sol";
+import "./utils/SharedValidation.sol";
+import "./interfaces/IEventForwarder.sol";
 
 /**
  * @title EngineBlox
@@ -190,6 +190,10 @@ library EngineBlox {
         mapping(bytes4 => EnumerableSet.AddressSet) functionTargetWhitelist;
         // Per-function target hooks (generic pipeline for hook setup)
         mapping(bytes4 => EnumerableSet.AddressSet) functionTargetHooks;
+
+        // ============ SYSTEM MACRO SELECTORS ============
+        // Function selectors that are allowed to target address(this) (e.g. native transfer, update payment)
+        EnumerableSet.Bytes32Set systemMacroSelectorsSet;
     }
 
     bytes32 constant OWNER_ROLE = keccak256(bytes("OWNER_ROLE"));
@@ -200,10 +204,6 @@ library EngineBlox {
     bytes4 public constant NATIVE_TRANSFER_SELECTOR = bytes4(keccak256("__bloxchain_native_transfer__()"));
     bytes32 public constant NATIVE_TRANSFER_OPERATION = keccak256("NATIVE_TRANSFER");
     
-    // Payment update selector (reserved signature for payment detail updates)
-    bytes4 public constant UPDATE_PAYMENT_SELECTOR = bytes4(keccak256("__bloxchain_update_payment__()"));
-    bytes32 public constant UPDATE_PAYMENT_OPERATION = keccak256("UPDATE_PAYMENT");
-
     // 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)");
     bytes32 private constant DOMAIN_SEPARATOR_TYPE_HASH = keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
@@ -255,6 +255,9 @@ library EngineBlox {
         assignWallet(self, OWNER_ROLE, _owner);
         assignWallet(self, BROADCASTER_ROLE, _broadcaster);
         assignWallet(self, RECOVERY_ROLE, _recovery);
+
+        // Register default system macro selectors (allowed to target address(this) for system-level operations)
+        addMacroSelector(self, NATIVE_TRANSFER_SELECTOR);
         
         // Mark as initialized after successful setup
         self.initialized = true;
@@ -318,20 +321,64 @@ library EngineBlox {
             gasLimit,
             operationType,
             executionSelector,
-            executionParams
+            executionParams,
+            _noPayment()
         );
     }
 
     /**
-     * @dev Internal helper function to request a transaction without permission checks.
+     * @dev Requests a transaction with payment details attached from the start.
      * @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 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 paymentDetails The payment details to attach to the transaction.
+     * @return The created TxRecord with payment set.
+     * @notice Validates request permissions (same as txRequest).
+     */
+    function txRequestWithPayment(
+        SecureOperationState storage self,
+        address requester,
+        address target,
+        uint256 value,
+        uint256 gasLimit,
+        bytes32 operationType,
+        bytes4 handlerSelector,
+        bytes4 executionSelector,
+        bytes memory executionParams,
+        PaymentDetails memory paymentDetails
+    ) public returns (TxRecord memory) {
+        // Validate both execution and handler selector permissions (same as txRequest)
+        _validateExecutionAndHandlerPermissions(self, msg.sender, executionSelector, handlerSelector, TxAction.EXECUTE_TIME_DELAY_REQUEST);
+
+        return _txRequest(
+            self,
+            requester,
+            target,
+            value,
+            gasLimit,
+            operationType,
+            executionSelector,
+            executionParams,
+            paymentDetails
+        );
+    }
+
+    /**
+     * @dev Internal helper function to request a transaction without permission checks.
+     * @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 gasLimit The gas limit for the transaction.
+     * @param operationType The type of operation.
+     * @param executionParams The encoded parameters for the function (empty for simple native token transfers).
+     * @param paymentDetails The payment details to attach (use empty struct for no payment).
      * @return The created TxRecord.
      * @notice This function skips permission validation and should only be called from functions
      *         that have already validated permissions.
@@ -344,7 +391,8 @@ library EngineBlox {
         uint256 gasLimit,
         bytes32 operationType,
         bytes4 executionSelector,
-        bytes memory executionParams
+        bytes memory executionParams,
+        PaymentDetails memory paymentDetails
     ) private returns (TxRecord memory) {
         SharedValidation.validateNotZeroAddress(target);
         // enforce that the requested target is whitelisted for this selector.
@@ -358,7 +406,8 @@ library EngineBlox {
             gasLimit,
             operationType,
             executionSelector,
-            executionParams
+            executionParams,
+            paymentDetails
         );
     
         self.txRecords[txRequestRecord.txId] = txRequestRecord;
@@ -499,7 +548,8 @@ library EngineBlox {
             metaTx.txRecord.params.gasLimit,
             metaTx.txRecord.params.operationType,
             metaTx.txRecord.params.executionSelector,
-            metaTx.txRecord.params.executionParams
+            metaTx.txRecord.params.executionParams,
+            metaTx.txRecord.payment
         );
 
         metaTx.txRecord = txRecord;
@@ -643,6 +693,7 @@ library EngineBlox {
      * @param operationType The type of operation being performed
      * @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 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(
@@ -653,8 +704,9 @@ library EngineBlox {
         uint256 gasLimit,
         bytes32 operationType,
         bytes4 executionSelector,
-        bytes memory executionParams
-    ) private view returns (TxRecord memory) {        
+        bytes memory executionParams,
+        PaymentDetails memory payment
+    ) private view returns (TxRecord memory) {
         return TxRecord({
             txId: self.txCounter + 1,
             releaseTime: block.timestamp + self.timeLockPeriodSec * 1 seconds,
@@ -670,12 +722,7 @@ library EngineBlox {
             }),
             message: 0,
             result: "",
-            payment: PaymentDetails({
-                recipient: address(0),
-                nativeTokenAmount: 0,
-                erc20TokenAddress: address(0),
-                erc20TokenAmount: 0
-            })
+            payment: payment
         });
     }
 
@@ -708,42 +755,6 @@ library EngineBlox {
         }
     }
 
-    // ============ PAYMENT MANAGEMENT FUNCTIONS ============
-
-    /**
-     * @dev Updates payment details for a pending transaction
-     * @param self The SecureOperationState to modify
-     * @param txId The transaction ID to update payment for
-     * @param paymentDetails The new payment details
-     * @notice Access control: Requires permission for UPDATE_PAYMENT_SELECTOR and execution selector
-     * @notice This prevents attackers from redirecting funds after transaction request
-     * @notice Contracts must register UPDATE_PAYMENT_SELECTOR schema and grant permissions
-     * @notice Permission check: Both UPDATE_PAYMENT_SELECTOR AND execution selector permissions required
-     */
-    function updatePaymentForTransaction(
-        SecureOperationState storage self,
-        uint256 txId,
-        PaymentDetails memory paymentDetails
-    ) public {
-        _validateTxStatus(self, txId, TxStatus.PENDING);
-        
-        // Permission-based access control using macro selector
-        // Requires permission for UPDATE_PAYMENT_SELECTOR with EXECUTE_TIME_DELAY_REQUEST action
-        if (!hasActionPermission(self, msg.sender, UPDATE_PAYMENT_SELECTOR, TxAction.EXECUTE_TIME_DELAY_REQUEST)) {
-            revert SharedValidation.NoPermission(msg.sender);
-        }
-        
-        // Also verify permission for the transaction's execution selector
-        // This ensures caller has permission for the underlying transaction (dual permission check)
-        if (!hasActionPermission(self, msg.sender, self.txRecords[txId].params.executionSelector, TxAction.EXECUTE_TIME_DELAY_REQUEST)) {
-            revert SharedValidation.NoPermission(msg.sender);
-        }
-           
-        self.txRecords[txId].payment = paymentDetails;
-        
-        logTxEvent(self, txId, self.txRecords[txId].params.executionSelector);
-    }
-
     // ============ ROLE-BASED ACCESS CONTROL FUNCTIONS ============
 
 
@@ -759,6 +770,18 @@ library EngineBlox {
         return self.roles[role];
     }
 
+    /**
+     * @dev Gets the function schema by selector.
+     * @param self The SecureOperationState to read from.
+     * @param functionSelector The function selector to get the schema for.
+     * @return The FunctionSchema struct (memory copy).
+     * @notice Reverts with ResourceNotFound if the schema does not exist.
+     */
+    function getFunctionSchema(SecureOperationState storage self, bytes4 functionSelector) public view returns (FunctionSchema memory) {
+        _validateFunctionSchemaExists(self, functionSelector);
+        return self.functions[functionSelector];
+    }
+
     /**
      * @dev Creates a role with specified function permissions.
      * @param self The SecureOperationState to check.
@@ -772,6 +795,9 @@ library EngineBlox {
         uint256 maxWallets,
         bool isProtected
     ) public {
+        SharedValidation.validateRoleNameNotEmpty(roleName);
+        SharedValidation.validateMaxWalletsGreaterThanZero(maxWallets);
+
         bytes32 roleHash = keccak256(bytes(roleName));
         
         // Validate role count limit
@@ -1110,7 +1136,7 @@ library EngineBlox {
         // 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(functionSignature, functionSelector, isProtected);
+        _validateContractFunctionProtection(functionSelector, isProtected);
 
         // Derive operation type from operation name
         bytes32 derivedOperationType = keccak256(bytes(operationName));
@@ -1331,6 +1357,37 @@ library EngineBlox {
         return _convertAddressSetToArray(set);
     }
 
+    // ============ SYSTEM MACRO SELECTORS ============
+
+    /**
+     * @dev Adds a function selector to the system macro selectors set.
+     *      Macro selectors are allowed to target address(this) for system-level operations (e.g. native transfer).
+     * @param self The SecureOperationState to modify.
+     * @param functionSelector The function selector to add (e.g. NATIVE_TRANSFER_SELECTOR).
+     */
+    function addMacroSelector(
+        SecureOperationState storage self,
+        bytes4 functionSelector
+    ) public {
+        SharedValidation.validateHandlerSelector(functionSelector);
+        bytes32 sel = bytes32(functionSelector);
+        if (!self.systemMacroSelectorsSet.add(sel)) {
+            revert SharedValidation.ResourceAlreadyExists(sel);
+        }
+    }
+
+    /**
+     * @dev Returns true if the given function selector is in the system macro selectors set.
+     * @param self The SecureOperationState to check.
+     * @param functionSelector The function selector to check.
+     */
+    function isMacroSelector(
+        SecureOperationState storage self,
+        bytes4 functionSelector
+    ) public view returns (bool) {
+        return self.systemMacroSelectorsSet.contains(bytes32(functionSelector));
+    }
+
     // ============ FUNCTION TARGET HOOKS MANAGEMENT ============
 
     /**
@@ -1495,6 +1552,28 @@ library EngineBlox {
         return role.authorizedWallets.at(index);
     }
 
+    /**
+     * @dev Gets all authorized wallets for a role
+     * @param self The SecureOperationState to check
+     * @param roleHash The role hash
+     * @return Array of authorized wallet addresses
+     * @notice Access control should be enforced by the calling contract.
+     */
+    function _getAuthorizedWallets(
+        SecureOperationState storage self,
+        bytes32 roleHash
+    ) public view returns (address[] memory) {
+        Role storage role = self.roles[roleHash];
+        uint256 walletCount = role.walletCount;
+
+        address[] memory wallets = new address[](walletCount);
+        for (uint256 i = 0; i < walletCount; i++) {
+            wallets[i] = getAuthorizedWalletAt(self, roleHash, i);
+        }
+
+        return wallets;
+    }
+
     /**
      * @dev Gets all function permissions for a role as an array for backward compatibility
      * @param self The SecureOperationState to check
@@ -1700,7 +1779,8 @@ library EngineBlox {
             txParams.gasLimit,
             txParams.operationType,
             txParams.executionSelector,
-            txParams.executionParams
+            txParams.executionParams,
+            _noPayment()
         );
 
          return generateMetaTransaction(self, txRecord, metaTxParams);
@@ -2005,6 +2085,17 @@ library EngineBlox {
         }
     }
 
+    /**
+     * @dev Validates that a function schema exists for the given selector.
+     * @param self The SecureOperationState to check.
+     * @param functionSelector The function selector to validate.
+     */
+    function _validateFunctionSchemaExists(SecureOperationState storage self, bytes4 functionSelector) internal view {
+        if (!self.supportedFunctionsSet.contains(bytes32(functionSelector))) {
+            revert SharedValidation.ResourceNotFound(bytes32(functionSelector));
+        }
+    }
+
     /**
      * @dev Validates that a transaction is in the expected status
      * @param self The SecureOperationState to check
@@ -2213,7 +2304,6 @@ library EngineBlox {
 
     /**
      * @dev Validates that if a function exists in contract bytecode, it must be protected
-     * @param functionSignature The function signature to check
      * @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
@@ -2222,15 +2312,15 @@ library EngineBlox {
      * @notice Since we're called via delegatecall, address(this) refers to the calling contract
      */
     function _validateContractFunctionProtection(
-        string memory functionSignature,
         bytes4 functionSelector,
         bool isProtected
     ) private view {
-        // 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)) {
-            if (!isProtected) {
-                revert SharedValidation.ContractFunctionMustBeProtected(functionSelector, functionSignature);
+        // 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);
             }
         }
     }
@@ -2280,4 +2370,17 @@ library EngineBlox {
         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) {
+        return PaymentDetails({
+            recipient: address(0),
+            nativeTokenAmount: 0,
+            erc20TokenAddress: address(0),
+            erc20TokenAmount: 0
+        });
+    }
+
 }

package/{contracts → core/lib}/interfaces/IDefinition.sol

@@ -1,20 +1,25 @@
 // SPDX-License-Identifier: MPL-2.0
 pragma solidity 0.8.33;
 
-import "../core/lib/EngineBlox.sol";
+import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import "../EngineBlox.sol";
 
 /**
  * @dev Interface for definition contracts that provide operation types, function schemas, and role permissions
- * 
+ *
  * This interface allows contracts to dynamically load their configuration from external
  * definition contracts, enabling modular and extensible contract initialization.
- * 
+ *
+ * Definition contracts (or deployed definition libraries) used by address should implement
+ * ERC165 and return true for type(IDefinition).interfaceId so consumers can validate
+ * before calling getFunctionSchemas() / getRolePermissions().
+ *
  * Definition contracts should implement this interface to provide:
  * - Operation type definitions (what operations are supported)
  * - Function schema definitions (how functions are structured)
  * - Role permission definitions (who can do what)
  */
-interface IDefinition {
+interface IDefinition is IERC165 {
     /**
      * @dev Struct to hold role permission data
      * @param roleHashes Array of role hashes
@@ -30,11 +35,15 @@ interface IDefinition {
      * @return Array of function schema definitions
      */
     function getFunctionSchemas() external pure returns (EngineBlox.FunctionSchema[] memory);
-    
+
     /**
      * @dev Returns all role hashes and their corresponding function permissions
      * @return RolePermission struct containing roleHashes and functionPermissions arrays
      */
     function getRolePermissions() external pure returns (RolePermission memory);
-    
+
+    /**
+     * @dev ERC165: return true for type(IDefinition).interfaceId
+     */
+    function supportsInterface(bytes4 interfaceId) external view returns (bool);
 }

package/{contracts → core/lib}/interfaces/IEventForwarder.sol

@@ -2,7 +2,7 @@
 pragma solidity 0.8.33;
 
 // Import TxRecord struct from EngineBlox
-import "../core/lib/EngineBlox.sol";
+import "../EngineBlox.sol";
 
 /**
  * @title IEventForwarder