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

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.35;
+
+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,8 +1,8 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.35;
 
 // Import TxRecord struct from EngineBlox
-import "../core/lib/EngineBlox.sol";
+import "../EngineBlox.sol";
 
 /**
  * @title IEventForwarder
@@ -21,6 +21,7 @@ interface IEventForwarder {
      * @param requester The address of the requester
      * @param target The target contract address
      * @param operationType The type of operation
+     * @param resultHash Commitment to execution returndata (`bytes32(0)` when none). Full bytes: `TxExecutionResult` log.
      */
     function forwardTxEvent(
         uint256 txId,
@@ -28,6 +29,7 @@ interface IEventForwarder {
         EngineBlox.TxStatus status,
         address requester,
         address target,
-        bytes32 operationType
+        bytes32 operationType,
+        bytes32 resultHash
     ) 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.35;
 
 /**
  * @title SharedValidation
@@ -38,7 +38,6 @@ library SharedValidation {
     // Time and deadline errors with context
     error InvalidTimeLockPeriod(uint256 provided);
     error TimeLockPeriodZero(uint256 provided);
-    error DeadlineInPast(uint256 deadline, uint256 currentTime);
     error MetaTxExpired(uint256 deadline, uint256 currentTime);
     error BeforeReleaseTime(uint256 releaseTime, uint256 currentTime);
     error NewTimelockSame(uint256 newPeriod, uint256 currentPeriod);
@@ -51,6 +50,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 +60,7 @@ library SharedValidation {
     error ZeroOperationTypeNotAllowed();
     error TransactionStatusMismatch(uint8 expectedStatus, uint8 currentStatus);
     error AlreadyInitialized();
+    error NotInitialized();
     error TransactionIdMismatch(uint256 expectedTxId, uint256 providedTxId);
     error PendingSecureRequest();
     
@@ -72,23 +74,27 @@ 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);
     error ResourceAlreadyExists(bytes32 resourceId);
     error CannotModifyProtected(bytes32 resourceId);
+    error GrantNotRevocable(bytes4 functionSelector);
     
     // Consolidated item errors (for addresses: wallets, policies, etc.)
     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 ============
     
@@ -169,14 +222,6 @@ library SharedValidation {
         if (timeLockPeriod == 0) revert TimeLockPeriodZero(timeLockPeriod);
     }
     
-    /**
-     * @dev Validates that a deadline is in the future
-     * @param deadline The deadline timestamp to validate
-     */
-    function validateDeadline(uint256 deadline) internal view {
-        if (deadline <= block.timestamp) revert DeadlineInPast(deadline, block.timestamp);
-    }
-    
     /**
      * @dev Validates that a new time lock period is different from the current one
      * @param newPeriod The new time lock period
@@ -196,8 +241,9 @@ library SharedValidation {
     }
     
     /**
-     * @dev Validates that a meta-transaction has not expired
-     * @param deadline The deadline of the meta-transaction
+     * @dev Validates that a meta-transaction deadline has not passed (inclusive boundary: `block.timestamp == deadline` is valid).
+     *      Used both when building unsigned meta-tx payloads (`EngineBlox.generateMetaTransaction`) and when verifying submitted meta-txs.
+     * @param deadline The deadline timestamp from `MetaTxParams`
      */
     function validateMetaTxDeadline(uint256 deadline) internal view {
         if (block.timestamp > deadline) revert MetaTxExpired(deadline, block.timestamp);
@@ -307,11 +353,12 @@ library SharedValidation {
     }
     
     /**
-     * @dev Validates that a transaction exists (has non-zero ID)
+     * @dev Validates that `txId` refers to a minted record: non-zero and at most `txCounter` (inclusive).
      * @param txId The transaction ID to validate
+     * @param txCounter The engine's `txCounter` after the record was allocated (valid ids are `1..txCounter`)
      */
-    function validateTransactionExists(uint256 txId) internal pure {
-        if (txId == 0) revert ResourceNotFound(bytes32(uint256(txId)));
+    function validateTransactionExists(uint256 txId, uint256 txCounter) internal pure {
+        if (txId == 0 || txId > txCounter) revert ResourceNotFound(bytes32(uint256(txId)));
     }
     
     /**
@@ -402,12 +449,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.35;
+
+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();
+    }
+}