@bloxchain/contracts 1.0.0-alpha.2 → 1.0.0-alpha.20

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

@@ -1,49 +1,49 @@
-// SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
-
-import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
-import "../core/lib/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 is IERC165 {
-    /**
-     * @dev Struct to hold role permission data
-     * @param roleHashes Array of role hashes
-     * @param functionPermissions Array of function permissions (parallel to roleHashes)
-     */
-    struct RolePermission {
-        bytes32[] roleHashes;
-        EngineBlox.FunctionPermission[] functionPermissions;
-    }
-
-    /**
-     * @dev Returns all function schema definitions
-     * @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);
-}
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+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 is IERC165 {
+    /**
+     * @dev Struct to hold role permission data
+     * @param roleHashes Array of role hashes
+     * @param functionPermissions Array of function permissions (parallel to roleHashes)
+     */
+    struct RolePermission {
+        bytes32[] roleHashes;
+        EngineBlox.FunctionPermission[] functionPermissions;
+    }
+
+    /**
+     * @dev Returns all function schema definitions
+     * @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/{interfaces → core/lib/interfaces}/IEventForwarder.sol

@@ -1,33 +1,33 @@
-// SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
-
-// Import TxRecord struct from EngineBlox
-import "../core/lib/EngineBlox.sol";
-
-/**
- * @title IEventForwarder
- * @dev Interface for the event forwarder contract
- * 
- * This interface defines the contract for forwarding events from deployed instances
- * to a centralized event monitoring system. It uses function selectors for efficient
- * event identification and categorization.
- */
-interface IEventForwarder {
-    /**
-     * @dev Forward a transaction event from a deployed instance
-     * @param txId The transaction ID
-     * @param functionSelector The function selector for the event (bytes4)
-     * @param status The transaction status
-     * @param requester The address of the requester
-     * @param target The target contract address
-     * @param operationType The type of operation
-     */
-    function forwardTxEvent(
-        uint256 txId,
-        bytes4 functionSelector,
-        EngineBlox.TxStatus status,
-        address requester,
-        address target,
-        bytes32 operationType
-    ) external;
-}
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+// Import TxRecord struct from EngineBlox
+import "../EngineBlox.sol";
+
+/**
+ * @title IEventForwarder
+ * @dev Interface for the event forwarder contract
+ * 
+ * This interface defines the contract for forwarding events from deployed instances
+ * to a centralized event monitoring system. It uses function selectors for efficient
+ * event identification and categorization.
+ */
+interface IEventForwarder {
+    /**
+     * @dev Forward a transaction event from a deployed instance
+     * @param txId The transaction ID
+     * @param functionSelector The function selector for the event (bytes4)
+     * @param status The transaction status
+     * @param requester The address of the requester
+     * @param target The target contract address
+     * @param operationType The type of operation
+     */
+    function forwardTxEvent(
+        uint256 txId,
+        bytes4 functionSelector,
+        EngineBlox.TxStatus status,
+        address requester,
+        address target,
+        bytes32 operationType
+    ) external;
+}

package/{utils → core/lib/utils}/SharedValidation.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.34;
 
 /**
  * @title SharedValidation
@@ -51,6 +51,8 @@ library SharedValidation {
     error RestrictedRecovery(address caller, address recovery);
     error RestrictedBroadcaster(address caller, address broadcaster);
     error SignerNotAuthorized(address signer);
+    error MetaTxHandlerSelectorMismatch(bytes4 signedSelector, bytes4 entrySelector);
+    error MetaTxHandlerContractMismatch(address signedContract, address entryContract);
     error OnlyCallableByContract(address caller, address contractAddress);
     
     // Transaction and operation errors with context
@@ -59,6 +61,7 @@ library SharedValidation {
     error ZeroOperationTypeNotAllowed();
     error TransactionStatusMismatch(uint8 expectedStatus, uint8 currentStatus);
     error AlreadyInitialized();
+    error NotInitialized();
     error TransactionIdMismatch(uint256 expectedTxId, uint256 providedTxId);
     error PendingSecureRequest();
     
@@ -72,6 +75,8 @@ library SharedValidation {
     error InvalidVValue(uint8 v);
     error ECDSAInvalidSignature(address recoveredSigner);
     error GasPriceExceedsMax(uint256 currentGasPrice, uint256 maxGasPrice);
+    error MetaTxRecordMismatchStoredTx(uint256 txId);
+    error MetaTxPaymentMismatchStoredTx(uint256 txId);
     
     // Consolidated resource errors
     error ResourceNotFound(bytes32 resourceId);
@@ -82,13 +87,14 @@ library SharedValidation {
     error ItemAlreadyExists(address item);
     error ItemNotFound(address item);
     error InvalidOperation(address item);
+    error DefinitionNotIDefinition(address definition);
     
     // Role and function errors with context
     error RoleWalletLimitReached(uint256 currentCount, uint256 maxWallets);
     error MaxWalletsZero(uint256 provided);
     error ConflictingMetaTxPermissions(bytes4 functionSelector);
     error InternalFunctionNotAccessible(bytes4 functionSelector);
-    error ContractFunctionMustBeProtected(bytes4 functionSelector, string functionSignature);
+    error ContractFunctionMustBeProtected(bytes4 functionSelector);
     error TargetNotWhitelisted(address target, bytes4 functionSelector);
     error FunctionSelectorMismatch(bytes4 providedSelector, bytes4 derivedSelector);
     error HandlerForSelectorMismatch(bytes4 schemaHandlerForSelector, bytes4 permissionHandlerForSelector);
@@ -96,6 +102,7 @@ library SharedValidation {
     error OperationFailed();
     
     // Payment and balance errors with context
+    error InvalidPayment();
     error InsufficientBalance(uint256 currentBalance, uint256 requiredAmount);
     error PaymentFailed(address recipient, uint256 amount, bytes reason);
     
@@ -119,8 +126,28 @@ library SharedValidation {
     function validateNotZeroAddress(address addr) internal pure {
         if (addr == address(0)) revert InvalidAddress(addr);
     }
-    
-    
+
+    /**
+     * @dev Validates that payment details are empty (no attached payment).
+     * @param recipient The payment recipient address
+     * @param nativeTokenAmount The native token payment amount
+     * @param erc20TokenAddress The ERC20 token address
+     * @param erc20TokenAmount The ERC20 payment amount
+     */
+    function validateEmptyPayment(
+        address recipient,
+        uint256 nativeTokenAmount,
+        address erc20TokenAddress,
+        uint256 erc20TokenAmount
+    ) internal pure {
+        if (
+            recipient != address(0) ||
+            nativeTokenAmount != 0 ||
+            erc20TokenAddress != address(0) ||
+            erc20TokenAmount != 0
+        ) revert InvalidPayment();
+    }
+
     /**
      * @dev Validates that a new address is different from the current address
      * @param newAddress The proposed new address
@@ -158,6 +185,32 @@ library SharedValidation {
     function validateHandlerContract(address handler) internal pure {
         if (handler == address(0)) revert InvalidAddress(handler);
     }
+
+    /**
+     * @dev Validates that the signed handler selector matches the live wrapper entrypoint selector.
+     *      IMPORTANT: pass the wrapper selector from wrapper context (`bytes4(msg.sig)` in the wrapper),
+     *      not from external-library context.
+     * @param handlerSelector Selector embedded in signed MetaTxParams
+     * @param entrySelector Selector of the wrapper entrypoint executing the meta-tx
+     */
+    function validateMetaTxHandlerSelectorBinding(
+        bytes4 handlerSelector,
+        bytes4 entrySelector
+    ) internal pure {
+        if (handlerSelector != entrySelector) {
+            revert MetaTxHandlerSelectorMismatch(handlerSelector, entrySelector);
+        }
+    }
+
+    /**
+     * @dev Validates that the signed handler contract matches the active verifying contract (`address(this)`).
+     * @param handlerContract Address embedded in signed MetaTxParams
+     */
+    function validateMetaTxHandlerContractBinding(address handlerContract) internal view {
+        if (handlerContract != address(this)) {
+            revert MetaTxHandlerContractMismatch(handlerContract, address(this));
+        }
+    }
     
     // ============ TIME AND DEADLINE VALIDATION FUNCTIONS ============
     
@@ -402,12 +455,12 @@ library SharedValidation {
     // ============ UTILITY FUNCTIONS ============
     
     /**
-     * @dev Validates that the first value is less than the second value
-     * @param from The first value (should be less than 'to')
-     * @param to The second value (should be greater than 'from')
+     * @dev Validates that the first value is not greater than the second (allows inclusive range: from <= to)
+     * @param from The first value (must be <= 'to' for a valid range)
+     * @param to The second value (must be >= 'from')
      */
     function validateLessThan(uint256 from, uint256 to) internal pure {
-        if (from >= to) revert InvalidRange(from, to);
+        if (from > to) revert InvalidRange(from, to);
     }
     
     /**

package/core/pattern/Account.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+import "../execution/GuardController.sol";
+import "../execution/interface/IGuardController.sol";
+import "../access/RuntimeRBAC.sol";
+import "../access/interface/IRuntimeRBAC.sol";
+import "../security/SecureOwnable.sol";
+import "../security/interface/ISecureOwnable.sol";
+import "../lib/utils/SharedValidation.sol";
+
+/**
+ * @title Account
+ * @dev Abstract account pattern combining GuardController, RuntimeRBAC, and SecureOwnable.
+ *
+ * Use this as the base for account-style contracts (e.g. AccountBlox) to avoid duplicating
+ * initialization, interface support, and receive/fallback boilerplate.
+ *
+ * Combines:
+ * - GuardController: Execution workflows and time-locked transactions
+ * - RuntimeRBAC: Runtime role creation and management
+ * - SecureOwnable: Secure ownership transfer and management
+ *
+ * @custom:security-contact security@particlecs.com
+ */
+abstract contract Account is GuardController, RuntimeRBAC, SecureOwnable {
+    /**
+     * @dev Emitted when plain ETH is received (receive()).
+     * @param sender Address that sent the ETH
+     * @param value Amount of wei received
+     * @custom:security Gas-efficient so receive() stays within 2,300 gas stipend (transfer/send compatible).
+     */
+    event EthReceived(address indexed sender, uint256 value);
+
+    /**
+     * @notice Initializer for the Account pattern (GuardController + RuntimeRBAC + SecureOwnable).
+     * @param initialOwner The initial owner address
+     * @param broadcaster The broadcaster address
+     * @param recovery The recovery address
+     * @param timeLockPeriodSec The timelock period in seconds
+     * @param eventForwarder The event forwarder address (optional)
+     */
+    function initialize(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,
+        address eventForwarder
+    ) public virtual override(GuardController, RuntimeRBAC, SecureOwnable) onlyInitializing {
+        GuardController.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        RuntimeRBAC.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        SecureOwnable.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+    }
+
+    /**
+     * @dev See {IERC165-supportsInterface}.
+     * @notice GuardController, RuntimeRBAC, and SecureOwnable each extend BaseStateMachine directly; a single
+     *         `super` chain only walks one branch. We OR the three component interface IDs here, then delegate
+     *         once to `super` for IBaseStateMachine / ERC165 — avoids tripling BaseStateMachine+ERC165 work.
+     */
+    function supportsInterface(bytes4 interfaceId) public view virtual override(GuardController, RuntimeRBAC, SecureOwnable) returns (bool) {
+        return interfaceId == type(IGuardController).interfaceId
+            || interfaceId == type(IRuntimeRBAC).interfaceId
+            || interfaceId == type(ISecureOwnable).interfaceId
+            || super.supportsInterface(interfaceId);
+    }
+
+    /**
+     * @dev Accepts plain ETH transfers (no calldata).
+     * @notice General-use wallet: ETH can be sent naturally; balance is credited.
+     * @custom:security No external calls—reentrancy-safe; outgoing ETH only via GuardController execution. Uses simple emit to stay within 2,300 gas stipend (transfer/send compatible).
+     */
+    receive() external payable virtual {
+        emit EthReceived(msg.sender, msg.value);
+    }
+
+    /**
+     * @dev Rejects calls with unknown selector (with or without value).
+     * @notice Only plain transfers hit receive(); all other calls revert.
+     */
+    fallback() external payable virtual {
+        revert SharedValidation.NotSupported();
+    }
+}