@towns-protocol/contracts 0.0.448 → 0.0.450

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.448",
+  "version": "0.0.450",
   "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.448",
+    "@towns-protocol/prettier-config": "^0.0.450",
     "@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": "165feaa79f39a38ce8d928e8fc5ffc09c3d42733"
+  "gitHead": "cbbeb47f3b927004f889268ab727858eab3f1cf9"
 }

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,16 +2,17 @@
 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";
@@ -21,6 +22,7 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
     using EnumerableSet for EnumerableSet.UintSet;
     using EnumerableSet for EnumerableSet.Bytes32Set;
     using CustomRevert for bytes4;
+    using SafeTransferLib for address;
 
     // =============================================================
     //                           Initializer
@@ -129,8 +131,79 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
         uint256 requestId,
         bytes memory extraData
     ) external payable {
-        address space = msg.sender;
         address senderAddress = abi.decode(extraData, (address));
+        _requestEntitlementCheck(
+            walletAddress,
+            transactionId,
+            requestId,
+            CurrencyTransfer.NATIVE_TOKEN,
+            msg.value,
+            senderAddress
+        );
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheck(CheckType checkType, bytes calldata data) external payable {
+        if (checkType == CheckType.V1) {
+            if (msg.value != 0) EntitlementChecker_InvalidValue.selector.revertWith();
+            (
+                address walletAddress,
+                bytes32 transactionId,
+                uint256 roleId,
+                address[] memory nodes
+            ) = abi.decode(data, (address, bytes32, uint256, address[]));
+            emit EntitlementCheckRequested(walletAddress, msg.sender, transactionId, roleId, nodes);
+        } else if (checkType == CheckType.V2) {
+            (
+                address walletAddress,
+                bytes32 transactionId,
+                uint256 requestId,
+                bytes memory extraData
+            ) = abi.decode(data, (address, bytes32, uint256, bytes));
+            address senderAddress = abi.decode(extraData, (address));
+            _requestEntitlementCheck(
+                walletAddress,
+                transactionId,
+                requestId,
+                CurrencyTransfer.NATIVE_TOKEN,
+                msg.value,
+                senderAddress
+            );
+        } else if (checkType == CheckType.V3) {
+            (
+                address walletAddress,
+                bytes32 transactionId,
+                uint256 requestId,
+                address currency,
+                uint256 amount,
+                address senderAddress
+            ) = abi.decode(data, (address, bytes32, uint256, address, uint256, address));
+            _requestEntitlementCheck(
+                walletAddress,
+                transactionId,
+                requestId,
+                currency,
+                amount,
+                senderAddress
+            );
+        } else {
+            EntitlementChecker_InvalidCheckType.selector.revertWith();
+        }
+    }
+
+    // =============================================================
+    //                           Internal
+    // =============================================================
+
+    function _requestEntitlementCheck(
+        address walletAddress,
+        bytes32 transactionId,
+        uint256 requestId,
+        address currency,
+        uint256 amount,
+        address senderAddress
+    ) internal {
+        address space = msg.sender;
 
         XChainLib.Layout storage layout = XChainLib.layout();
 
@@ -139,25 +212,34 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
         // 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 = walletAddress;
+            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]);

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(walletAddress, transactionId, roleId, nodes);
+    ///     case CheckType.V2:
+    ///       data = abi.encode(walletAddress, transactionId, requestId, extraData);
+    ///       // where extraData = abi.encode(senderAddress)
+    ///     case CheckType.V3:
+    ///       data = abi.encode(walletAddress, transactionId, requestId, currency, amount, senderAddress);
+    ///   }
+    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);
@@ -88,6 +107,11 @@ interface IEntitlementChecker is IEntitlementCheckerBase {
         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 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;
                 }
             }

package/src/spaces/facets/tipping/TippingBase.sol

@@ -238,14 +238,16 @@ abstract contract TippingBase is ITippingBase, PointsBase {
         // Reset ERC20 approval
         if (!isNative) SafeTransferLib.safeApprove(currency, spaceFactory, 0);
 
-        // Mint points for fee payment
-        address airdropDiamond = _getAirdropDiamond();
-        uint256 points = _getPoints(
-            airdropDiamond,
-            ITownsPointsBase.Action.Tip,
-            abi.encode(protocolFee)
-        );
-        _mintPoints(airdropDiamond, msg.sender, points);
+        // Mint points for fee payment (only for ETH tips)
+        if (isNative) {
+            address airdropDiamond = _getAirdropDiamond();
+            uint256 points = _getPoints(
+                airdropDiamond,
+                ITownsPointsBase.Action.Tip,
+                abi.encode(protocolFee)
+            );
+            _mintPoints(airdropDiamond, msg.sender, points);
+        }
     }
 
     /// @dev Validates common tip requirements