@towns-protocol/contracts 0.0.449 → 0.0.451

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.449",
+  "version": "0.0.451",
   "scripts": {
     "clean": "forge clean",
     "compile": "forge build",
@@ -33,7 +33,7 @@
     "@layerzerolabs/oapp-evm": "^0.3.2",
     "@openzeppelin/merkle-tree": "^1.0.8",
     "@prb/test": "^0.6.4",
-    "@towns-protocol/prettier-config": "^0.0.449",
+    "@towns-protocol/prettier-config": "^0.0.451",
     "@wagmi/cli": "^2.2.0",
     "forge-std": "github:foundry-rs/forge-std#v1.10.0",
     "prettier": "^3.5.3",
@@ -50,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "268f44c69d00993f57e702b176a9a9c34ea8f6cc"
+  "gitHead": "ad68c0f2514e44f51293824ebba5ccc2f8a6494c"
 }

package/scripts/deployments/facets/DeployEntitlementChecker.s.sol

@@ -15,14 +15,17 @@ library DeployEntitlementChecker {
     using DynamicArrayLib for DynamicArrayLib.DynamicArray;
 
     function selectors() internal pure returns (bytes4[] memory res) {
-        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(9);
+        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(10);
         arr.p(EntitlementChecker.registerNode.selector);
         arr.p(EntitlementChecker.unregisterNode.selector);
         arr.p(EntitlementChecker.isValidNode.selector);
         arr.p(EntitlementChecker.getNodeCount.selector);
         arr.p(EntitlementChecker.getNodeAtIndex.selector);
         arr.p(EntitlementChecker.getRandomNodes.selector);
-        arr.p(EntitlementChecker.requestEntitlementCheck.selector);
+        // requestEntitlementCheck V1 (legacy)
+        arr.p(bytes4(keccak256("requestEntitlementCheck(address,bytes32,uint256,address[])")));
+        // requestEntitlementCheck unified (enum dispatch)
+        arr.p(bytes4(keccak256("requestEntitlementCheck(uint8,bytes)")));
         arr.p(EntitlementChecker.requestEntitlementCheckV2.selector);
         arr.p(EntitlementChecker.getNodesByOperator.selector);
 

package/src/base/registry/facets/checker/EntitlementChecker.sol

@@ -2,41 +2,40 @@
 pragma solidity ^0.8.23;
 
 // interfaces
+import {IEntitlementGatedBase} from "../../../../spaces/facets/gated/IEntitlementGated.sol";
 import {IEntitlementChecker} from "./IEntitlementChecker.sol";
-import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
 
 // libraries
-
-import {EntitlementCheckerStorage} from "./EntitlementCheckerStorage.sol";
 import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
-import {NodeOperatorStatus, NodeOperatorStorage} from "src/base/registry/facets/operator/NodeOperatorStorage.sol";
-import {XChainLib} from "src/base/registry/facets/xchain/XChainLib.sol";
-import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
+import {CustomRevert} from "../../../../utils/libraries/CustomRevert.sol";
+import {CurrencyTransfer} from "../../../../utils/libraries/CurrencyTransfer.sol";
+import {NodeOperatorStatus, NodeOperatorStorage} from "../operator/NodeOperatorStorage.sol";
+import {XChainLib} from "../xchain/XChainLib.sol";
+import {EntitlementCheckerStorage} from "./EntitlementCheckerStorage.sol";
 
 // contracts
 import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
 
 contract EntitlementChecker is IEntitlementChecker, Facet {
     using EnumerableSet for EnumerableSet.AddressSet;
-    using EnumerableSet for EnumerableSet.UintSet;
     using EnumerableSet for EnumerableSet.Bytes32Set;
+    using EnumerableSet for EnumerableSet.UintSet;
     using CustomRevert for bytes4;
-
-    // =============================================================
-    //                           Initializer
-    // =============================================================
+    using SafeTransferLib for address;
 
     function __EntitlementChecker_init() external onlyInitializing {
         _addInterface(type(IEntitlementChecker).interfaceId);
     }
 
-    // =============================================================
-    //                           Modifiers
-    // =============================================================
-    modifier onlyNodeOperator(address node, address operator) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                        MODIFIERS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    modifier onlyNodeOperator(address node) {
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
 
-        if (layout.operatorByNode[node] != operator) {
+        if (msg.sender != $.operatorByNode[node]) {
             EntitlementChecker_InvalidNodeOperator.selector.revertWith();
         }
         _;
@@ -48,63 +47,134 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
         if (!nodeOperatorLayout.operators.contains(msg.sender)) {
             EntitlementChecker_InvalidOperator.selector.revertWith();
         }
-        _;
-
         if (nodeOperatorLayout.statusByOperator[msg.sender] != NodeOperatorStatus.Approved) {
             EntitlementChecker_OperatorNotActive.selector.revertWith();
         }
+        _;
     }
 
-    // =============================================================
-    //                           External
-    // =============================================================
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                       ADMIN FUNCTIONS                      */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     /// @inheritdoc IEntitlementChecker
     function registerNode(address node) external onlyRegisteredApprovedOperator {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
 
-        if (layout.nodes.contains(node)) {
+        if ($.nodes.contains(node)) {
             EntitlementChecker_NodeAlreadyRegistered.selector.revertWith();
         }
 
-        layout.nodes.add(node);
-        layout.operatorByNode[node] = msg.sender;
+        $.nodes.add(node);
+        $.operatorByNode[node] = msg.sender;
 
         emit NodeRegistered(node);
     }
 
     /// @inheritdoc IEntitlementChecker
-    function unregisterNode(address node) external onlyNodeOperator(node, msg.sender) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+    function unregisterNode(address node) external onlyNodeOperator(node) {
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
 
-        if (!layout.nodes.contains(node)) {
+        if (!$.nodes.contains(node)) {
             EntitlementChecker_NodeNotRegistered.selector.revertWith();
         }
 
-        layout.nodes.remove(node);
-        delete layout.operatorByNode[node];
+        $.nodes.remove(node);
+        delete $.operatorByNode[node];
 
         emit NodeUnregistered(node);
     }
 
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                         ENTITLEMENT                        */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheck(
+        address receiver,
+        bytes32 transactionId,
+        uint256 roleId,
+        address[] memory nodes
+    ) external {
+        emit EntitlementCheckRequested(receiver, msg.sender, transactionId, roleId, nodes);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheckV2(
+        address receiver,
+        bytes32 transactionId,
+        uint256 requestId,
+        bytes memory extraData
+    ) external payable {
+        address sender = abi.decode(extraData, (address));
+        _requestEntitlementCheck(
+            receiver,
+            transactionId,
+            requestId,
+            CurrencyTransfer.NATIVE_TOKEN,
+            msg.value,
+            sender
+        );
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheck(CheckType checkType, bytes calldata data) external payable {
+        if (checkType == CheckType.V1) {
+            if (msg.value != 0) EntitlementChecker_InvalidValue.selector.revertWith();
+            (address receiver, bytes32 transactionId, uint256 roleId, address[] memory nodes) = abi
+                .decode(data, (address, bytes32, uint256, address[]));
+            emit EntitlementCheckRequested(receiver, msg.sender, transactionId, roleId, nodes);
+        } else if (checkType == CheckType.V2) {
+            (
+                address receiver,
+                bytes32 transactionId,
+                uint256 requestId,
+                bytes memory extraData
+            ) = abi.decode(data, (address, bytes32, uint256, bytes));
+            address sender = abi.decode(extraData, (address));
+            _requestEntitlementCheck(
+                receiver,
+                transactionId,
+                requestId,
+                CurrencyTransfer.NATIVE_TOKEN,
+                msg.value,
+                sender
+            );
+        } else if (checkType == CheckType.V3) {
+            (
+                address receiver,
+                bytes32 transactionId,
+                uint256 requestId,
+                address currency,
+                uint256 amount,
+                address sender
+            ) = abi.decode(data, (address, bytes32, uint256, address, uint256, address));
+            _requestEntitlementCheck(receiver, transactionId, requestId, currency, amount, sender);
+        } else {
+            EntitlementChecker_InvalidCheckType.selector.revertWith();
+        }
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          GETTERS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
     /// @inheritdoc IEntitlementChecker
     function isValidNode(address node) external view returns (bool) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
-        return layout.nodes.contains(node);
+        return EntitlementCheckerStorage.layout().nodes.contains(node);
     }
 
     /// @inheritdoc IEntitlementChecker
     function getNodeCount() external view returns (uint256) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
-        return layout.nodes.length();
+        return EntitlementCheckerStorage.layout().nodes.length();
     }
 
     /// @inheritdoc IEntitlementChecker
     function getNodeAtIndex(uint256 index) external view returns (address) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
 
-        require(index < layout.nodes.length(), "Index out of bounds");
-        return layout.nodes.at(index);
+        require(index < $.nodes.length(), "Index out of bounds");
+        return $.nodes.at(index);
     }
 
     /// @inheritdoc IEntitlementChecker
@@ -113,51 +183,74 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
     }
 
     /// @inheritdoc IEntitlementChecker
-    function requestEntitlementCheck(
-        address walletAddress,
-        bytes32 transactionId,
-        uint256 roleId,
-        address[] memory nodes
-    ) external {
-        emit EntitlementCheckRequested(walletAddress, msg.sender, transactionId, roleId, nodes);
+    function getNodesByOperator(address operator) external view returns (address[] memory nodes) {
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
+        address[] memory allNodes = $.nodes.values();
+        uint256 totalNodeCount = allNodes.length;
+        nodes = new address[](totalNodeCount);
+        uint256 nodeCount;
+        for (uint256 i; i < totalNodeCount; ++i) {
+            address node = allNodes[i];
+            if ($.operatorByNode[node] == operator) {
+                unchecked {
+                    nodes[nodeCount++] = node;
+                }
+            }
+        }
+        assembly ("memory-safe") {
+            mstore(nodes, nodeCount)
+        }
     }
 
-    /// @inheritdoc IEntitlementChecker
-    function requestEntitlementCheckV2(
-        address walletAddress,
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          INTERNAL                          */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    function _requestEntitlementCheck(
+        address receiver,
         bytes32 transactionId,
         uint256 requestId,
-        bytes memory extraData
-    ) external payable {
+        address currency,
+        uint256 amount,
+        address sender
+    ) internal {
         address space = msg.sender;
-        address senderAddress = abi.decode(extraData, (address));
 
         XChainLib.Layout storage layout = XChainLib.layout();
 
-        layout.requestsBySender[senderAddress].add(transactionId);
+        layout.requestsBySender[sender].add(transactionId);
 
         // Only create the request if it doesn't exist yet
         XChainLib.Request storage request = layout.requests[transactionId];
         if (request.caller == address(0)) {
-            // First time creating this request
-            layout.requests[transactionId] = XChainLib.Request({
-                caller: space,
-                blockNumber: block.number,
-                value: msg.value,
-                completed: false,
-                receiver: walletAddress
-            });
-        } else {
-            if (msg.value != 0) {
-                EntitlementChecker_InvalidValue.selector.revertWith();
+            request.caller = space;
+            request.blockNumber = block.number;
+            request.value = amount;
+            request.receiver = receiver;
+            request.currency = currency;
+
+            if (currency == CurrencyTransfer.NATIVE_TOKEN) {
+                if (amount != msg.value) EntitlementChecker_InvalidValue.selector.revertWith();
+            } else {
+                // ERC20: reject any ETH sent
+                if (msg.value != 0) EntitlementChecker_InvalidValue.selector.revertWith();
+                // ERC20: pull tokens from Space
+                if (amount != 0) currency.safeTransferFrom(space, address(this), amount);
             }
+        } else {
+            // Request already exists from a previous requestId on this transactionId.
+            // Escrow was established on the first request - reject any additional ETH
+            // to prevent funds being sent but not tracked.
+            if (msg.value != 0) EntitlementChecker_InvalidValue.selector.revertWith();
         }
 
         address[] memory randomNodes = _getRandomNodes(5);
 
-        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+        XChainLib.Check storage check = layout.checks[transactionId];
 
-        check.requestIds.add(requestId);
+        if (!check.requestIds.add(requestId)) {
+            EntitlementChecker_DuplicateRequestId.selector.revertWith();
+        }
 
         for (uint256 i; i < randomNodes.length; ++i) {
             check.nodes[requestId].add(randomNodes[i]);
@@ -170,7 +263,7 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
         }
 
         emit EntitlementCheckRequestedV2(
-            walletAddress,
+            receiver,
             space,
             address(this),
             transactionId,
@@ -179,36 +272,12 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
         );
     }
 
-    /// @inheritdoc IEntitlementChecker
-    function getNodesByOperator(address operator) external view returns (address[] memory nodes) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
-        uint256 totalNodeCount = layout.nodes.length();
-        nodes = new address[](totalNodeCount);
-        uint256 nodeCount;
-        for (uint256 i; i < totalNodeCount; ++i) {
-            address node = layout.nodes.at(i);
-            if (layout.operatorByNode[node] == operator) {
-                unchecked {
-                    nodes[nodeCount++] = node;
-                }
-            }
-        }
-        assembly ("memory-safe") {
-            mstore(nodes, nodeCount) // Update the length of the array
-        }
-    }
-
-    // =============================================================
-    //                           Internal
-    // =============================================================
     function _getRandomNodes(uint256 count) internal view returns (address[] memory randomNodes) {
-        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        EntitlementCheckerStorage.Layout storage $ = EntitlementCheckerStorage.layout();
 
-        uint256 nodeCount = layout.nodes.length();
+        uint256 nodeCount = $.nodes.length();
 
-        if (count > nodeCount) {
-            EntitlementChecker_InsufficientNumberOfNodes.selector.revertWith();
-        }
+        if (count > nodeCount) EntitlementChecker_InsufficientNumberOfNodes.selector.revertWith();
 
         randomNodes = new address[](count);
         uint256[] memory indices = new uint256[](nodeCount);
@@ -221,7 +290,7 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
             for (uint256 i; i < count; ++i) {
                 // Adjust random function to generate within range 0 to n-1
                 uint256 rand = _pseudoRandom(i, nodeCount);
-                randomNodes[i] = layout.nodes.at(indices[rand]);
+                randomNodes[i] = $.nodes.at(indices[rand]);
                 // Move the last element to the used slot and reduce the pool size
                 indices[rand] = indices[--nodeCount];
             }

package/src/base/registry/facets/checker/IEntitlementChecker.sol

@@ -2,6 +2,24 @@
 pragma solidity ^0.8.23;
 
 interface IEntitlementCheckerBase {
+    /// @notice CheckType enum for unified entitlement check dispatch
+    /// @dev To encode data for each type:
+    ///   switch (checkType) {
+    ///     case CheckType.V1:
+    ///       data = abi.encode(receiver, transactionId, roleId, nodes);
+    ///     case CheckType.V2:
+    ///       data = abi.encode(receiver, transactionId, requestId, extraData);
+    ///       // where extraData = abi.encode(sender)
+    ///     case CheckType.V3:
+    ///       data = abi.encode(receiver, transactionId, requestId, currency, amount, sender);
+    ///   }
+    enum CheckType {
+        V1, // Legacy check with explicit nodes
+        V2, // ETH escrow (uses msg.value, currency is always NATIVE_TOKEN)
+        V3 // ETH or ERC20 escrow (uses currency + amount)
+    }
+
+    error EntitlementChecker_InvalidCheckType();
     error EntitlementChecker_NodeAlreadyRegistered();
     error EntitlementChecker_NodeNotRegistered();
     error EntitlementChecker_InsufficientNumberOfNodes();
@@ -12,6 +30,7 @@ interface IEntitlementCheckerBase {
     error EntitlementChecker_InsufficientFunds();
     error EntitlementChecker_NoRefundsAvailable();
     error EntitlementChecker_InvalidValue();
+    error EntitlementChecker_DuplicateRequestId();
 
     // Events
     event NodeRegistered(address indexed nodeAddress);
@@ -19,17 +38,17 @@ interface IEntitlementCheckerBase {
 
     /// @notice Event emitted when an entitlement check is requested
     event EntitlementCheckRequested(
-        address callerAddress,
-        address contractAddress,
+        address receiver,
+        address space,
         bytes32 transactionId,
         uint256 roleId,
         address[] selectedNodes
     );
 
     event EntitlementCheckRequestedV2(
-        address walletAddress,
-        address spaceAddress,
-        address resolverAddress,
+        address receiver,
+        address space,
+        address resolver,
         bytes32 transactionId,
         uint256 roleId,
         address[] selectedNodes
@@ -45,49 +64,54 @@ interface IEntitlementChecker is IEntitlementCheckerBase {
     /// @param node The address of the node to unregister
     function unregisterNode(address node) external;
 
-    /// @notice Check if a node address is registered and valid
-    /// @param node The address of the node to check
-    /// @return bool True if the node is valid, false otherwise
-    function isValidNode(address node) external view returns (bool);
-
-    /// @notice Get the total number of registered nodes
-    /// @return uint256 The count of registered nodes
-    function getNodeCount() external view returns (uint256);
-
-    /// @notice Get the node address at a specific index
-    /// @param index The index of the node to retrieve
-    /// @return address The address of the node at the given index
-    function getNodeAtIndex(uint256 index) external view returns (address);
-
-    /// @notice Get a random selection of registered nodes
-    /// @param count The number of random nodes to return
-    /// @return address[] Array of randomly selected node addresses
-    function getRandomNodes(uint256 count) external view returns (address[] memory);
-
     /// @notice Request an entitlement check for a transaction
-    /// @param callerAddress The address initiating the check
+    /// @param receiver The address to check entitlements for (membership recipient)
     /// @param transactionId The unique identifier of the transaction
     /// @param roleId The role ID to check entitlements against
     /// @param nodes Array of node addresses that will perform the check
     function requestEntitlementCheck(
-        address callerAddress,
+        address receiver,
         bytes32 transactionId,
         uint256 roleId,
         address[] memory nodes
     ) external;
 
     /// @notice Request an entitlement check with additional data (V2)
-    /// @param walletAddress The wallet address to check entitlements for
+    /// @param receiver The address to check entitlements for (membership recipient)
     /// @param transactionId The unique identifier of the transaction
     /// @param requestId The unique identifier for this specific request
     /// @param extraData Additional data required for the check
     function requestEntitlementCheckV2(
-        address walletAddress,
+        address receiver,
         bytes32 transactionId,
         uint256 requestId,
         bytes memory extraData
     ) external payable;
 
+    /// @notice Unified entitlement check request with enum-based dispatch
+    /// @param checkType The type of check to perform (V1, V2, or V3)
+    /// @param data Encoded parameters specific to the check type (see CheckType enum docs)
+    function requestEntitlementCheck(CheckType checkType, bytes calldata data) external payable;
+
+    /// @notice Check if a node address is registered and valid
+    /// @param node The address of the node to check
+    /// @return bool True if the node is valid, false otherwise
+    function isValidNode(address node) external view returns (bool);
+
+    /// @notice Get the total number of registered nodes
+    /// @return uint256 The count of registered nodes
+    function getNodeCount() external view returns (uint256);
+
+    /// @notice Get the node address at a specific index
+    /// @param index The index of the node to retrieve
+    /// @return address The address of the node at the given index
+    function getNodeAtIndex(uint256 index) external view returns (address);
+
+    /// @notice Get a random selection of registered nodes
+    /// @param count The number of random nodes to return
+    /// @return address[] Array of randomly selected node addresses
+    function getRandomNodes(uint256 count) external view returns (address[] memory);
+
     /// @notice Get all nodes registered to a specific operator
     /// @param operator The address of the operator
     /// @return address[] Array of node addresses registered to the operator

package/src/base/registry/facets/xchain/IXChain.sol

@@ -2,20 +2,21 @@
 pragma solidity ^0.8.23;
 
 // interfaces
-
 import {IEntitlementCheckerBase} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
 import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
 
-// libraries
-
-// contracts
-
 /// @dev Struct to hold voting context and avoid stack too deep
+/// @param transactionId The unique identifier of the transaction
+/// @param caller The space contract that initiated the request
+/// @param value Amount escrowed (ETH or ERC20)
+/// @param completed Whether the transaction has been finalized
+/// @param currency Token address (NATIVE_TOKEN for ETH)
 struct VotingContext {
     bytes32 transactionId;
     address caller;
     uint256 value;
     bool completed;
+    address currency;
 }
 
 /// @dev Struct to hold vote counting results

package/src/base/registry/facets/xchain/XChain.sol

@@ -2,21 +2,20 @@
 pragma solidity ^0.8.23;
 
 // interfaces
+import {IEntitlementGated} from "../../../../spaces/facets/gated/IEntitlementGated.sol";
 import {IXChain, VotingContext, VoteResults} from "./IXChain.sol";
-import {IEntitlementGated} from "src/spaces/facets/gated/IEntitlementGated.sol";
 
 // libraries
-import {XChainLib} from "./XChainLib.sol";
 import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
-import {CurrencyTransfer} from "src/utils/libraries/CurrencyTransfer.sol";
-import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+import {CurrencyTransfer} from "../../../../utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "../../../../utils/libraries/CustomRevert.sol";
 import {XChainCheckLib} from "./XChainCheckLib.sol";
+import {XChainLib} from "./XChainLib.sol";
 
 // contracts
 import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
-import {EntitlementGated} from "src/spaces/facets/gated/EntitlementGated.sol";
-import {ReentrancyGuard} from "solady/utils/ReentrancyGuard.sol";
 import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
+import {ReentrancyGuard} from "solady/utils/ReentrancyGuard.sol";
 
 contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
     using EnumerableSet for EnumerableSet.AddressSet;
@@ -39,11 +38,13 @@ contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
 
     /// @inheritdoc IXChain
     function provideXChainRefund(address senderAddress, bytes32 transactionId) external onlyOwner {
-        if (!XChainLib.layout().requestsBySender[senderAddress].remove(transactionId)) {
+        XChainLib.Layout storage layout = XChainLib.layout();
+
+        if (!layout.requestsBySender[senderAddress].remove(transactionId)) {
             EntitlementGated_TransactionCheckAlreadyCompleted.selector.revertWith();
         }
 
-        XChainLib.Request storage request = XChainLib.layout().requests[transactionId];
+        XChainLib.Request storage request = layout.requests[transactionId];
 
         if (request.completed) {
             EntitlementGated_TransactionCheckAlreadyCompleted.selector.revertWith();
@@ -55,23 +56,19 @@ contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
 
         request.completed = true;
 
-        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+        XChainLib.Check storage check = layout.checks[transactionId];
 
         // clean up checks if any
-        uint256 requestIdsLength = check.requestIds.length();
-        if (requestIdsLength > 0) {
-            for (uint256 i; i < requestIdsLength; ++i) {
-                uint256 requestId = check.requestIds.at(i);
-                check.voteCompleted[requestId] = true;
-            }
+        uint256[] memory requestIds = check.requestIds.values();
+        for (uint256 i; i < requestIds.length; ++i) {
+            check.voteCompleted[requestIds[i]] = true;
         }
 
-        CurrencyTransfer.transferCurrency(
-            CurrencyTransfer.NATIVE_TOKEN,
-            address(this),
-            senderAddress,
-            request.value
-        );
+        // normalize address(0) to NATIVE_TOKEN for pre-upgrade requests
+        address currency = request.currency;
+        currency = currency == address(0) ? CurrencyTransfer.NATIVE_TOKEN : currency;
+        // refund escrowed amount
+        CurrencyTransfer.transferCurrency(currency, address(this), senderAddress, request.value);
     }
 
     /// @inheritdoc IXChain
@@ -80,8 +77,9 @@ contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
         uint256 requestId,
         NodeVoteStatus result
     ) external nonReentrant {
-        XChainLib.Request storage request = XChainLib.layout().requests[transactionId];
-        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+        XChainLib.Layout storage layout = XChainLib.layout();
+        XChainLib.Request storage request = layout.requests[transactionId];
+        XChainLib.Check storage check = layout.checks[transactionId];
 
         VotingContext memory context = check.validateVotingEligibility(
             request,
@@ -129,11 +127,18 @@ contract XChain is IXChain, ReentrancyGuard, OwnableBase, Facet {
         NodeVoteStatus finalStatus
     ) internal {
         // Mark transaction as completed and clean up
-        XChainLib.layout().requests[context.transactionId].completed = true;
-        XChainLib.layout().requestsBySender[context.caller].remove(context.transactionId);
+        XChainLib.Layout storage layout = XChainLib.layout();
+        layout.requests[context.transactionId].completed = true;
+        layout.requestsBySender[context.caller].remove(context.transactionId);
 
-        // Call back to the original caller with the result
-        EntitlementGated(context.caller).postEntitlementCheckResultV2{value: context.value}(
+        // return escrowed funds to Space, then callback
+        CurrencyTransfer.transferCurrency(
+            context.currency,
+            address(this),
+            context.caller,
+            context.value
+        );
+        IEntitlementGated(context.caller).postEntitlementCheckResultV2(
             context.transactionId,
             0,
             finalStatus

package/src/base/registry/facets/xchain/XChainCheckLib.sol

@@ -2,15 +2,14 @@
 pragma solidity ^0.8.23;
 
 // interfaces
+import {IEntitlementGatedBase} from "../../../../spaces/facets/gated/IEntitlementGated.sol";
+import {VoteResults, VotingContext} from "./IXChain.sol";
 
 // libraries
-
-// contracts
-import {XChainLib} from "./XChainLib.sol";
-import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
-import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
 import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
-import {VoteResults, VotingContext} from "./IXChain.sol";
+import {CurrencyTransfer} from "../../../../utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "../../../../utils/libraries/CustomRevert.sol";
+import {XChainLib} from "./XChainLib.sol";
 
 library XChainCheckLib {
     using CustomRevert for bytes4;
@@ -50,6 +49,9 @@ library XChainCheckLib {
         context.caller = request.caller;
         context.value = request.value;
         context.completed = request.completed;
+        // normalize address(0) to NATIVE_TOKEN for pre-upgrade requests
+        address currency = request.currency;
+        context.currency = currency == address(0) ? CurrencyTransfer.NATIVE_TOKEN : currency;
     }
 
     function processNodeVote(

package/src/base/registry/facets/xchain/XChainLib.sol

@@ -2,13 +2,12 @@
 pragma solidity ^0.8.23;
 
 // interfaces
-import {IEntitlementChecker} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
-import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
+import {IEntitlementGatedBase} from "../../../../spaces/facets/gated/IEntitlementGated.sol";
+import {IEntitlementChecker} from "../checker/IEntitlementChecker.sol";
+
 // libraries
 import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 
-// contracts
-
 library XChainLib {
     // keccak256(abi.encode(uint256(keccak256("xchain.entitlement.transactions.storage")) - 1)) &
     // ~bytes32(uint256(0xff))
@@ -22,12 +21,20 @@ library XChainLib {
         mapping(uint256 requestId => bool voteCompleted) voteCompleted;
     }
 
+    /// @dev Stores crosschain entitlement check request data
+    /// @param value Amount escrowed (ETH or ERC20)
+    /// @param blockNumber Block when request was created
+    /// @param caller Space contract that initiated the request
+    /// @param completed Whether the request has been finalized
+    /// @param receiver Wallet address being checked for entitlement
+    /// @param currency Token address (NATIVE_TOKEN for ETH)
     struct Request {
         uint256 value;
         uint256 blockNumber;
         address caller;
         bool completed;
         address receiver;
+        address currency;
     }
 
     struct Layout {

package/src/spaces/facets/gated/EntitlementGated.sol

@@ -2,16 +2,14 @@
 pragma solidity ^0.8.23;
 
 // interfaces
+import {IEntitlementChecker} from "../../../base/registry/facets/checker/IEntitlementChecker.sol";
+import {IRuleEntitlement} from "../../entitlements/rule/IRuleEntitlement.sol";
 import {IEntitlementGated} from "./IEntitlementGated.sol";
-import {IEntitlementChecker} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
-import {IRuleEntitlement} from "src/spaces/entitlements/rule/IRuleEntitlement.sol";
-
-// libraries
 
 // contracts
-import {EntitlementGatedBase} from "./EntitlementGatedBase.sol";
 import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
 import {ReentrancyGuard} from "solady/utils/ReentrancyGuard.sol";
+import {EntitlementGatedBase} from "./EntitlementGatedBase.sol";
 
 abstract contract EntitlementGated is
     IEntitlementGated,
@@ -30,8 +28,7 @@ abstract contract EntitlementGated is
         _setEntitlementChecker(entitlementChecker);
     }
 
-    /// @notice Called by the xchain node to post the result of the entitlement check
-    /// @dev the internal function validates the transactionId and the result
+    /// @inheritdoc IEntitlementGated
     function postEntitlementCheckResult(
         bytes32 transactionId,
         uint256 roleId,
@@ -40,11 +37,7 @@ abstract contract EntitlementGated is
         _postEntitlementCheckResult(transactionId, roleId, result);
     }
 
-    /// @notice Post the result of the entitlement check for a specific role
-    /// @dev Only the entitlement checker can call this function
-    /// @param transactionId The unique identifier for the transaction
-    /// @param roleId The role ID for the entitlement check
-    /// @param result The result of the entitlement check (PASSED or FAILED)
+    /// @inheritdoc IEntitlementGated
     function postEntitlementCheckResultV2(
         bytes32 transactionId,
         uint256 roleId,
@@ -53,7 +46,7 @@ abstract contract EntitlementGated is
         _postEntitlementCheckResultV2(transactionId, roleId, result);
     }
 
-    /// @dev deprecated Use EntitlementDataQueryable.getCrossChainEntitlementData instead
+    /// @inheritdoc IEntitlementGated
     function getRuleData(
         bytes32 transactionId,
         uint256 roleId

package/src/spaces/facets/gated/EntitlementGatedBase.sol

@@ -2,23 +2,25 @@
 pragma solidity ^0.8.23;
 
 // interfaces
+import {IEntitlementChecker, IEntitlementCheckerBase} from "../../../base/registry/facets/checker/IEntitlementChecker.sol";
+import {IImplementationRegistry} from "../../../factory/facets/registry/IImplementationRegistry.sol";
+import {IRuleEntitlement} from "../../entitlements/rule/IRuleEntitlement.sol";
 import {IEntitlementGatedBase} from "./IEntitlementGated.sol";
 
-import {IEntitlementChecker} from "src/base/registry/facets/checker/IEntitlementChecker.sol";
-import {IImplementationRegistry} from "src/factory/facets/registry/IImplementationRegistry.sol";
-import {IRuleEntitlement} from "src/spaces/entitlements/rule/IRuleEntitlement.sol";
-
 // libraries
+import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
+import {CurrencyTransfer} from "../../../utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
+import {MembershipStorage} from "../membership/MembershipStorage.sol";
 import {EntitlementGatedStorage} from "./EntitlementGatedStorage.sol";
-import {MembershipStorage} from "src/spaces/facets/membership/MembershipStorage.sol";
-import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
 
 abstract contract EntitlementGatedBase is IEntitlementGatedBase {
     using CustomRevert for bytes4;
+    using SafeTransferLib for address;
 
     modifier onlyEntitlementChecker() {
         if (msg.sender != address(EntitlementGatedStorage.layout().entitlementChecker)) {
-            CustomRevert.revertWith(EntitlementGated_OnlyEntitlementChecker.selector);
+            EntitlementGated_OnlyEntitlementChecker.selector.revertWith();
         }
         _;
     }
@@ -33,9 +35,7 @@ abstract contract EntitlementGatedBase is IEntitlementGatedBase {
         IRuleEntitlement entitlement,
         uint256 roleId
     ) internal {
-        if (callerAddress == address(0)) {
-            CustomRevert.revertWith(EntitlementGated_InvalidAddress.selector);
-        }
+        if (callerAddress == address(0)) EntitlementGated_InvalidAddress.selector.revertWith();
 
         EntitlementGatedStorage.Layout storage ds = EntitlementGatedStorage.layout();
         Transaction storage transaction = ds.transactions[transactionId];
@@ -43,7 +43,7 @@ abstract contract EntitlementGatedBase is IEntitlementGatedBase {
             uint256 _length = transaction.roleIds.length;
             for (uint256 i; i < _length; ++i) {
                 if (transaction.roleIds[i] == roleId) {
-                    revert EntitlementGated_TransactionCheckAlreadyRegistered();
+                    EntitlementGated_TransactionCheckAlreadyRegistered.selector.revertWith();
                 }
             }
         }
@@ -155,94 +155,51 @@ abstract contract EntitlementGatedBase is IEntitlementGatedBase {
     /*                           V2                               */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
-    /// @notice Requests a V2 entitlement check with optimized validation and execution
-    /// @param walletAddress The wallet address to check entitlements for
-    /// @param senderAddress The original sender address (encoded in extraData)
-    /// @param transactionId The unique transaction identifier
-    /// @param entitlement The entitlement contract to use for checking
-    /// @param requestId The specific request identifier
-    /// @param value The amount of ETH to send with the request (if any)
-    function _requestEntitlementCheckV2(
+    /// @notice Requests a crosschain entitlement check with payment escrow
+    /// @dev Stores entitlement reference for RuleData queries, escrows payment with
+    /// EntitlementChecker, and emits event for off-chain nodes to process.
+    function _requestEntitlementCheck(
         address walletAddress,
         address senderAddress,
         bytes32 transactionId,
         IRuleEntitlement entitlement,
         uint256 requestId,
-        uint256 value
+        address currency,
+        uint256 amount
     ) internal {
-        // Validate all inputs upfront
-        _validateEntitlementCheckInputs(walletAddress, entitlement, value);
-
-        // Setup transaction state
-        EntitlementGatedStorage.Layout storage $ = EntitlementGatedStorage.layout();
-        _setupTransaction($.transactions[transactionId], entitlement);
-
-        // Execute the entitlement check request
-        _executeEntitlementCheckRequest(
-            $.entitlementChecker,
-            walletAddress,
-            transactionId,
-            requestId,
-            value,
-            abi.encode(senderAddress)
-        );
-    }
-
-    /// @notice Validates inputs for entitlement check request
-    /// @param walletAddress The wallet address being checked
-    /// @param entitlement The entitlement contract
-    /// @param value The ETH value being sent
-    function _validateEntitlementCheckInputs(
-        address walletAddress,
-        IRuleEntitlement entitlement,
-        uint256 value
-    ) private view {
-        if (value > msg.value) {
-            EntitlementGated_InvalidValue.selector.revertWith();
-        }
         if (walletAddress == address(0)) {
             EntitlementGated_InvalidAddress.selector.revertWith();
         }
         if (address(entitlement) == address(0)) {
             EntitlementGated_InvalidEntitlement.selector.revertWith();
         }
-    }
 
-    /// @notice Sets up transaction state for entitlement checking
-    /// @param transaction Storage reference to the transaction
-    /// @param entitlement The entitlement contract to associate
-    function _setupTransaction(
-        Transaction storage transaction,
-        IRuleEntitlement entitlement
-    ) private {
-        transaction.finalized = true;
-        transaction.entitlement = entitlement;
-    }
+        EntitlementGatedStorage.Layout storage $ = EntitlementGatedStorage.layout();
+        Transaction storage transaction = $.transactions[transactionId];
+        // Only set on first call; subsequent calls for other roleIds reuse existing state
+        if (!transaction.finalized) {
+            transaction.finalized = true;
+            transaction.entitlement = entitlement;
+        }
 
-    /// @notice Executes the entitlement check request with optimized call pattern
-    /// @param checker The entitlement checker contract
-    /// @param walletAddress The wallet address to check
-    /// @param transactionId The transaction identifier
-    /// @param requestId The request identifier
-    /// @param value The ETH value to send
-    /// @param extraData Encoded additional data
-    function _executeEntitlementCheckRequest(
-        IEntitlementChecker checker,
-        address walletAddress,
-        bytes32 transactionId,
-        uint256 requestId,
-        uint256 value,
-        bytes memory extraData
-    ) private {
-        if (value > 0) {
-            checker.requestEntitlementCheckV2{value: value}(
-                walletAddress,
-                transactionId,
-                requestId,
-                extraData
+        IEntitlementChecker checker = $.entitlementChecker;
+        bytes memory data = abi.encode(
+            walletAddress,
+            transactionId,
+            requestId,
+            currency,
+            amount,
+            senderAddress
+        );
+
+        if (currency == CurrencyTransfer.NATIVE_TOKEN) {
+            checker.requestEntitlementCheck{value: amount}(
+                IEntitlementCheckerBase.CheckType.V3,
+                data
             );
         } else {
-            checker.requestEntitlementCheckV2(walletAddress, transactionId, requestId, extraData);
+            if (amount != 0) currency.safeApproveWithRetry(address(checker), amount);
+            checker.requestEntitlementCheck(IEntitlementCheckerBase.CheckType.V3, data);
         }
     }
 

package/src/spaces/facets/gated/IEntitlementGated.sol

@@ -42,12 +42,32 @@ interface IEntitlementGatedBase {
 }
 
 interface IEntitlementGated is IEntitlementGatedBase {
+    /// @notice Called by the xchain node to post the result of the entitlement check
+    /// @param transactionId The unique identifier for the transaction
+    /// @param roleId The role ID for the entitlement check
+    /// @param result The result of the entitlement check (PASSED or FAILED)
     function postEntitlementCheckResult(
         bytes32 transactionId,
         uint256 roleId,
         NodeVoteStatus result
     ) external;
 
+    /// @notice Post the result of the entitlement check for a specific role
+    /// @dev Only the entitlement checker can call this function
+    /// @param transactionId The unique identifier for the transaction
+    /// @param roleId The role ID for the entitlement check
+    /// @param result The result of the entitlement check (PASSED or FAILED)
+    function postEntitlementCheckResultV2(
+        bytes32 transactionId,
+        uint256 roleId,
+        NodeVoteStatus result
+    ) external payable;
+
+    /// @notice Get the rule data for a specific transaction and role
+    /// @dev Deprecated: Use EntitlementDataQueryable.getCrossChainEntitlementData instead
+    /// @param transactionId The unique identifier for the transaction
+    /// @param roleId The role ID for the entitlement check
+    /// @return The rule data for the transaction and role
     function getRuleData(
         bytes32 transactionId,
         uint256 roleId

package/src/spaces/facets/membership/join/MembershipJoin.sol

@@ -289,13 +289,8 @@ abstract contract MembershipJoin is
         return false;
     }
 
-    /// @notice Handles crosschain entitlement checks with proper payment distribution
-    /// @param receiver The address to check entitlements for
-    /// @param sender The address sending the transaction
-    /// @param transactionId The transaction identifier
-    /// @param requiredAmount The required payment amount
-    /// @return isEntitled Whether user is entitled (always false for crosschain)
-    /// @return isCrosschainPending Whether crosschain checks are pending
+    /// @dev Checks all crosschain entitlements across roles. User passes if any check succeeds.
+    /// Payment is escrowed only once (on first check) and returned when any check completes.
     function _checkCrosschainEntitlements(
         IRolesBase.Role[] memory roles,
         address receiver,
@@ -303,7 +298,7 @@ abstract contract MembershipJoin is
         bytes32 transactionId,
         uint256 requiredAmount
     ) internal returns (bool isEntitled, bool isCrosschainPending) {
-        bool paymentSent = false;
+        bool paymentSent;
 
         for (uint256 i; i < roles.length; ++i) {
             if (roles[i].disabled) continue;
@@ -312,28 +307,16 @@ abstract contract MembershipJoin is
                 IEntitlement entitlement = IEntitlement(roles[i].entitlements[j]);
 
                 if (entitlement.isCrosschain()) {
-                    if (!paymentSent) {
-                        // Send only the required amount to crosschain check
-                        // Excess will be handled by existing refund mechanisms
-                        _requestEntitlementCheckV2(
-                            receiver,
-                            sender,
-                            transactionId,
-                            IRuleEntitlement(address(entitlement)),
-                            roles[i].id,
-                            requiredAmount
-                        );
-                        paymentSent = true;
-                    } else {
-                        _requestEntitlementCheckV2(
-                            receiver,
-                            sender,
-                            transactionId,
-                            IRuleEntitlement(address(entitlement)),
-                            roles[i].id,
-                            0
-                        );
-                    }
+                    _requestEntitlementCheck(
+                        receiver,
+                        sender,
+                        transactionId,
+                        IRuleEntitlement(address(entitlement)),
+                        roles[i].id,
+                        _getMembershipCurrency(),
+                        paymentSent ? 0 : requiredAmount
+                    );
+                    paymentSent = true;
                     isCrosschainPending = true;
                 }
             }