@towns-protocol/contracts 0.0.451 → 0.0.453

package/docs/membership_architecture.md

@@ -19,8 +19,12 @@ MembershipFacet (external interface)
       ├─ PointsBase (rewards points)
       └─ ERC721ABase (NFT implementation)
 
-SpaceEntitlementGated (result handler)
+SpaceEntitlementGated (xchain/SpaceEntitlementGated.sol)
   └─ Overrides _onEntitlementCheckResultPosted()
+
+ProtocolFeeLib (ProtocolFeeLib.sol)
+  └─ Wraps FeeManager.chargeFee with ERC20 approval handling
+  └─ Used by: MembershipJoin, TippingBase
 ```
 
 ### Storage Architecture
@@ -67,6 +71,8 @@ Memberships can be priced in:
 
 Currency validation happens in `_setMembershipCurrency()` which requires the token to have an enabled fee configuration in FeeManager.
 
+**Note**: Rewards points (`_mintMembershipPoints`) are only minted for native ETH payments. ERC20 payments require an oracle for point calculation.
+
 ## Core Flow: Join → Entitlement Check → Token
 
 ### Happy Path (Local Entitlement)
@@ -84,10 +90,10 @@ User: joinSpace(receiver) + payment
   │   └─ ✓ User has local entitlement → PASS
   │
   ├─ Charge for Join
-  │   ├─ Protocol fee → Platform
+  │   ├─ Protocol fee → Platform (via FeeManager)
   │   ├─ Partner fee → Partner (if any)
   │   ├─ Referral fee → Referrer (if any)
-  │   └─ Base price → Space owner
+  │   └─ Base price remains in contract as revenue
   │
   ├─ Refund Excess (if overpaid)
   │
@@ -218,10 +224,21 @@ function _releaseCapturedValue(bytes32 transactionId, uint256 amount) internal
 ### Fee Distribution
 
 ```solidity
+// MembershipJoin.sol - pays protocol fee via FeeManager
+function _payProtocolFee(address currency, uint256 basePrice, uint256 expectedFee) internal
+
+// ProtocolFeeLib.sol - shared fee charging logic
+function charge(
+    address spaceFactory,    // FeeManager address
+    bytes32 feeType,         // fee type identifier
+    address user,            // payer (msg.sender)
+    address currency,        // NATIVE_TOKEN or ERC20
+    uint256 amount,          // base price for fee calculation
+    uint256 expectedFee      // pre-calculated fee amount
+) internal returns (uint256 protocolFee)
+
 // MembershipBase.sol
-function _collectProtocolFee(address payer, uint256 membershipPrice)
-    internal returns (uint256 protocolFee)
-function _transferIn(address from, uint256 amount) internal returns (uint256)
+function _transferIn(address currency, address from, uint256 amount) internal returns (uint256)
 ```
 
 ### Entitlement Checking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.451",
+  "version": "0.0.453",
   "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.451",
+    "@towns-protocol/prettier-config": "^0.0.453",
     "@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": "ad68c0f2514e44f51293824ebba5ccc2f8a6494c"
+  "gitHead": "f94c8877f1ce645d78158e8367c0c05b171c9141"
 }

package/src/apps/modules/subscription/ISubscriptionModule.sol

@@ -1,17 +1,11 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.23;
 
-// interfaces
-
-// libraries
-
-// contracts
-
 import {Subscription} from "./SubscriptionModuleStorage.sol";
 
 interface ISubscriptionModuleBase {
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                           Structs                          */
+    /*                           STRUCTS                          */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     /// @notice Parameters for renewing a subscription
@@ -23,30 +17,25 @@ interface ISubscriptionModuleBase {
     }
 
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                           Errors                           */
+    /*                           ERRORS                           */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     error SubscriptionModule__InactiveSubscription();
     error SubscriptionModule__InvalidSpace();
-    error SubscriptionModule__RenewalNotDue();
-    error SubscriptionModule__RenewalFailed();
     error SubscriptionModule__InvalidSender();
     error SubscriptionModule__NotSupported();
     error SubscriptionModule__InvalidEntityId();
     error SubscriptionModule__InvalidCaller();
-    error SubscriptionModule__InvalidAddress();
     error SubscriptionModule__ExceedsMaxBatchSize();
     error SubscriptionModule__EmptyBatch();
     error SubscriptionModule__InvalidTokenOwner();
-    error SubscriptionModule__InsufficientBalance();
     error SubscriptionModule__ActiveSubscription();
     error SubscriptionModule__MembershipBanned();
     error SubscriptionModule__MembershipExpired();
     error SubscriptionModule__SubscriptionAlreadyInstalled();
-    error SubscriptionModule__SubscriptionNotInstalled();
 
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                           Events                           */
+    /*                           EVENTS                           */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     event SubscriptionConfigured(
@@ -97,13 +86,45 @@ interface ISubscriptionModuleBase {
 
 interface ISubscriptionModule is ISubscriptionModuleBase {
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                           Functions                          */
+    /*                       ADMIN FUNCTIONS                      */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Sets the space factory
+    /// @param spaceFactory The address of the space factory
+    function setSpaceFactory(address spaceFactory) external;
+
+    /// @notice Grants an operator access to call processRenewal
+    /// @param operator The address of the operator to grant
+    function grantOperator(address operator) external;
+
+    /// @notice Revokes an operator access to call processRenewal
+    /// @param operator The address of the operator to revoke
+    function revokeOperator(address operator) external;
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                  STATE-CHANGING FUNCTIONS                  */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     /// @notice Processes multiple Towns membership renewals in batch
     /// @param params The parameters for the renewals
     function batchProcessRenewals(RenewalParams[] calldata params) external;
 
+    /// @notice Activates a subscription
+    /// @param entityId The entity ID of the subscription to activate
+    function activateSubscription(uint32 entityId) external;
+
+    /// @notice Pauses a subscription
+    /// @param entityId The entity ID of the subscription to pause
+    function pauseSubscription(uint32 entityId) external;
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          GETTERS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Gets the space factory
+    /// @return The address of the space factory
+    function getSpaceFactory() external view returns (address);
+
     /// @notice Gets the subscription for an account and entity ID
     /// @param account The address of the account to get the subscription for
     /// @param entityId The entity ID of the subscription to get
@@ -113,19 +134,6 @@ interface ISubscriptionModule is ISubscriptionModuleBase {
         uint32 entityId
     ) external view returns (Subscription memory);
 
-    /// @notice Gets the renewal buffer for a membership duration
-    /// @param duration The membership duration to get the renewal buffer for
-    /// @return The renewal buffer for the duration
-    function getRenewalBuffer(uint256 duration) external pure returns (uint256);
-
-    /// @notice Activates a subscription
-    /// @param entityId The entity ID of the subscription to activate
-    function activateSubscription(uint32 entityId) external;
-
-    /// @notice Pauses a subscription
-    /// @param entityId The entity ID of the subscription to pause
-    function pauseSubscription(uint32 entityId) external;
-
     /// @notice Gets the entity IDs for an account
     /// @param account The address of the account to get the entity IDs for
     /// @return The entity IDs for the account
@@ -135,19 +143,8 @@ interface ISubscriptionModule is ISubscriptionModuleBase {
     /// @param operator The address of the operator to check
     function isOperator(address operator) external view returns (bool);
 
-    /// @notice Grants an operator access to call processRenewal
-    /// @param operator The address of the operator to grant
-    function grantOperator(address operator) external;
-
-    /// @notice Revokes an operator access to call processRenewal
-    /// @param operator The address of the operator to revoke
-    function revokeOperator(address operator) external;
-
-    /// @notice Sets the space factory
-    /// @param spaceFactory The address of the space factory
-    function setSpaceFactory(address spaceFactory) external;
-
-    /// @notice Gets the space factory
-    /// @return The address of the space factory
-    function getSpaceFactory() external view returns (address);
+    /// @notice Gets the renewal buffer for a membership duration
+    /// @param duration The membership duration to get the renewal buffer for
+    /// @return The renewal buffer for the duration
+    function getRenewalBuffer(uint256 duration) external pure returns (uint256);
 }

package/src/apps/modules/subscription/SubscriptionModuleBase.sol

@@ -2,20 +2,22 @@
 pragma solidity ^0.8.29;
 
 // interfaces
-import {IModularAccount} from "@erc6900/reference-implementation/interfaces/IModularAccount.sol";
+import {IModularAccount, Call} from "@erc6900/reference-implementation/interfaces/IModularAccount.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {IMembership} from "../../../spaces/facets/membership/IMembership.sol";
 import {IBanning} from "../../../spaces/facets/banning/IBanning.sol";
-import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {ISubscriptionModule, ISubscriptionModuleBase} from "./ISubscriptionModule.sol";
 
 // libraries
-import {LibCall} from "solady/utils/LibCall.sol";
 import {ValidationLocatorLib} from "modular-account/src/libraries/ValidationLocatorLib.sol";
+import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
+import {LibCall} from "solady/utils/LibCall.sol";
 import {SafeCastLib} from "solady/utils/SafeCastLib.sol";
+import {CurrencyTransfer} from "../../../utils/libraries/CurrencyTransfer.sol";
 import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {Validator} from "../../../utils/libraries/Validator.sol";
 import {Subscription, SubscriptionModuleStorage} from "./SubscriptionModuleStorage.sol";
-import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
 
 /// @title Subscription Module Base
 /// @notice Base contract with internal logic for subscription management
@@ -34,7 +36,8 @@ abstract contract SubscriptionModuleBase is ISubscriptionModuleBase {
         NOT_OWNER,
         RENEWAL_PRICE_CHANGED,
         INSUFFICIENT_BALANCE,
-        DURATION_CHANGED
+        DURATION_CHANGED,
+        CURRENCY_CHANGED
     }
 
     uint256 public constant GRACE_PERIOD = 3 days;
@@ -72,6 +75,7 @@ abstract contract SubscriptionModuleBase is ISubscriptionModuleBase {
         sub.lastKnownRenewalPrice = membershipFacet.getMembershipRenewalPrice(sub.tokenId);
         sub.lastKnownExpiresAt = expiresAt;
         sub.duration = duration;
+        sub.lastKnownCurrency = membershipFacet.getMembershipCurrency();
         sub.nextRenewalTime = _calculateBaseRenewalTime(expiresAt, duration);
     }
 
@@ -84,19 +88,33 @@ abstract contract SubscriptionModuleBase is ISubscriptionModuleBase {
         IMembership membershipFacet,
         uint256 actualRenewalPrice
     ) internal {
+        address currency = membershipFacet.getMembershipCurrency();
         // Construct the renewal call to space contract
         bytes memory renewalCall = abi.encodeCall(IMembership.renewMembership, (sub.tokenId));
 
         // Create the data parameter for executeWithRuntimeValidation
-        // This should be an execute() call to the space contract
-        bytes memory executeData = abi.encodeCall(
-            IModularAccount.execute,
-            (
-                sub.space, // target
-                actualRenewalPrice, // value
-                renewalCall // data
-            )
-        );
+        bytes memory executeData;
+        if (currency == CurrencyTransfer.NATIVE_TOKEN) {
+            // ETH path: single execute with value
+            executeData = abi.encodeCall(
+                IModularAccount.execute,
+                (
+                    sub.space, // target
+                    actualRenewalPrice, // value
+                    renewalCall // data
+                )
+            );
+        } else {
+            // ERC20 path: batch execute (approve + renewMembership)
+            Call[] memory calls = new Call[](2);
+            calls[0] = Call({
+                target: currency,
+                value: 0,
+                data: abi.encodeCall(IERC20.approve, (sub.space, actualRenewalPrice))
+            });
+            calls[1] = Call({target: sub.space, value: 0, data: renewalCall});
+            executeData = abi.encodeCall(IModularAccount.executeBatch, (calls));
+        }
 
         // Use the proper pack function from ValidationLocatorLib
         bytes memory authorization = ValidationLocatorLib.packSignature(
@@ -228,8 +246,14 @@ abstract contract SubscriptionModuleBase is ISubscriptionModuleBase {
             return (true, true, SkipReason.RENEWAL_PRICE_CHANGED);
         }
 
-        // Check if account has sufficient balance
-        if (account.balance < actualRenewalPrice) {
+        // Check if currency changed
+        address actualCurrency = IMembership(sub.space).getMembershipCurrency();
+        if (sub.lastKnownCurrency != actualCurrency) {
+            return (true, true, SkipReason.CURRENCY_CHANGED);
+        }
+
+        // Check if account has sufficient balance (ETH or ERC20)
+        if (CurrencyTransfer.balanceOf(actualCurrency, account) < actualRenewalPrice) {
             return (true, true, SkipReason.INSUFFICIENT_BALANCE);
         }
 
@@ -253,6 +277,7 @@ abstract contract SubscriptionModuleBase is ISubscriptionModuleBase {
         if (reason == SkipReason.RENEWAL_PRICE_CHANGED) return "RENEWAL_PRICE_CHANGED";
         if (reason == SkipReason.INSUFFICIENT_BALANCE) return "INSUFFICIENT_BALANCE";
         if (reason == SkipReason.DURATION_CHANGED) return "DURATION_CHANGED";
+        if (reason == SkipReason.CURRENCY_CHANGED) return "CURRENCY_CHANGED";
         return "";
     }
 

package/src/apps/modules/subscription/SubscriptionModuleFacet.sol

@@ -6,19 +6,19 @@ import {IModule} from "@erc6900/reference-implementation/interfaces/IModule.sol"
 import {IValidationHookModule} from "@erc6900/reference-implementation/interfaces/IValidationHookModule.sol";
 import {IValidationModule} from "@erc6900/reference-implementation/interfaces/IValidationModule.sol";
 import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
-import {ISubscriptionModule} from "./ISubscriptionModule.sol";
 import {IMembership} from "../../../spaces/facets/membership/IMembership.sol";
 import {IBanning} from "../../../spaces/facets/banning/IBanning.sol";
+import {ISubscriptionModule} from "./ISubscriptionModule.sol";
 
 // libraries
 import {PackedUserOperation} from "@eth-infinitism/account-abstraction/interfaces/PackedUserOperation.sol";
 import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
 import {ReentrancyGuardTransient} from "solady/utils/ReentrancyGuardTransient.sol";
+import {SafeCastLib} from "solady/utils/SafeCastLib.sol";
 import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {Validator} from "../../../utils/libraries/Validator.sol";
 import {IArchitect} from "../../../factory/facets/architect/IArchitect.sol";
 import {Subscription, SubscriptionModuleStorage} from "./SubscriptionModuleStorage.sol";
-import {SafeCastLib} from "solady/utils/SafeCastLib.sol";
 
 // contracts
 import {ModuleBase} from "modular-account/src/modules/ModuleBase.sol";
@@ -38,10 +38,10 @@ contract SubscriptionModuleFacet is
     SubscriptionModuleBase,
     Facet
 {
-    using EnumerableSetLib for EnumerableSetLib.Uint256Set;
     using EnumerableSetLib for EnumerableSetLib.AddressSet;
-    using SafeCastLib for uint256;
+    using EnumerableSetLib for EnumerableSetLib.Uint256Set;
     using CustomRevert for bytes4;
+    using SafeCastLib for uint256;
 
     uint256 internal constant _SIG_VALIDATION_FAILED = 1;
 
@@ -54,14 +54,34 @@ contract SubscriptionModuleFacet is
     }
 
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                           External                         */
+    /*                       ADMIN FUNCTIONS                      */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
-    /// @inheritdoc IModule
-    function moduleId() external pure returns (string memory) {
-        return "towns.subscription-module.1.0.0";
+    /// @inheritdoc ISubscriptionModule
+    function setSpaceFactory(address spaceFactory) external onlyOwner {
+        Validator.checkAddress(spaceFactory);
+        SubscriptionModuleStorage.getLayout().spaceFactory = spaceFactory;
+        emit SpaceFactoryChanged(spaceFactory);
     }
 
+    /// @inheritdoc ISubscriptionModule
+    function grantOperator(address operator) external onlyOwner {
+        Validator.checkAddress(operator);
+        SubscriptionModuleStorage.getLayout().operators.add(operator);
+        emit OperatorGranted(operator);
+    }
+
+    /// @inheritdoc ISubscriptionModule
+    function revokeOperator(address operator) external onlyOwner {
+        Validator.checkAddress(operator);
+        SubscriptionModuleStorage.getLayout().operators.remove(operator);
+        emit OperatorRevoked(operator);
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                      MODULE LIFECYCLE                      */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
     /// @inheritdoc IModule
     function onInstall(bytes calldata data) external override nonReentrant {
         (uint32 entityId, address space, uint256 tokenId) = abi.decode(
@@ -135,69 +155,9 @@ contract SubscriptionModuleFacet is
         emit SubscriptionDeactivated(msg.sender, entityId);
     }
 
-    /// @inheritdoc IValidationModule
-    function validateUserOp(
-        uint32,
-        PackedUserOperation calldata,
-        bytes32
-    ) external pure override returns (uint256) {
-        return _SIG_VALIDATION_FAILED;
-    }
-
-    /// @inheritdoc IValidationModule
-    function validateSignature(
-        address,
-        uint32,
-        address,
-        bytes32,
-        bytes calldata
-    ) external pure override returns (bytes4) {
-        return 0xffffffff;
-    }
-
-    /// @inheritdoc IValidationModule
-    function validateRuntime(
-        address account,
-        uint32 entityId,
-        address sender,
-        uint256,
-        bytes calldata,
-        bytes calldata
-    ) external view override {
-        if (sender != address(this)) SubscriptionModule__InvalidSender.selector.revertWith();
-        bool active = SubscriptionModuleStorage.getLayout().subscriptions[account][entityId].active;
-        if (!active) SubscriptionModule__InactiveSubscription.selector.revertWith();
-    }
-
-    /// @inheritdoc IValidationHookModule
-    function preUserOpValidationHook(
-        uint32 /* entityId */,
-        PackedUserOperation calldata /* userOp */,
-        bytes32 /* userOpHash */
-    ) external pure override returns (uint256) {
-        return _SIG_VALIDATION_FAILED;
-    }
-
-    /// @inheritdoc IValidationHookModule
-    function preRuntimeValidationHook(
-        uint32 /* entityId */,
-        address /* sender */,
-        uint256 /* value */,
-        bytes calldata /* data */,
-        bytes calldata /* authorization */
-    ) external pure override {
-        SubscriptionModule__NotSupported.selector.revertWith();
-    }
-
-    /// @inheritdoc IValidationHookModule
-    function preSignatureValidationHook(
-        uint32 /* entityId */,
-        address /* sender */,
-        bytes32 /* hash */,
-        bytes calldata /* signature */
-    ) external pure override {
-        SubscriptionModule__NotSupported.selector.revertWith();
-    }
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                  STATE-CHANGING FUNCTIONS                  */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
     /// @inheritdoc ISubscriptionModule
     function batchProcessRenewals(RenewalParams[] calldata params) external nonReentrant {
@@ -257,19 +217,6 @@ contract SubscriptionModuleFacet is
         }
     }
 
-    /// @inheritdoc ISubscriptionModule
-    function getSubscription(
-        address account,
-        uint32 entityId
-    ) external view returns (Subscription memory) {
-        return SubscriptionModuleStorage.getLayout().subscriptions[account][entityId];
-    }
-
-    /// @inheritdoc ISubscriptionModule
-    function getRenewalBuffer(uint256 duration) external pure returns (uint256) {
-        return _getRenewalBuffer(duration);
-    }
-
     /// @inheritdoc ISubscriptionModule
     function activateSubscription(uint32 entityId) external nonReentrant {
         SubscriptionModuleStorage.Layout storage $ = SubscriptionModuleStorage.getLayout();
@@ -304,16 +251,26 @@ contract SubscriptionModuleFacet is
         _pauseSubscription(sub, msg.sender, entityId);
     }
 
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          GETTERS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
     /// @inheritdoc ISubscriptionModule
-    function getEntityIds(address account) external view returns (uint256[] memory) {
-        return SubscriptionModuleStorage.getLayout().entityIds[account].values();
+    function getSpaceFactory() external view returns (address) {
+        return SubscriptionModuleStorage.getLayout().spaceFactory;
     }
 
     /// @inheritdoc ISubscriptionModule
-    function grantOperator(address operator) external onlyOwner {
-        Validator.checkAddress(operator);
-        SubscriptionModuleStorage.getLayout().operators.add(operator);
-        emit OperatorGranted(operator);
+    function getSubscription(
+        address account,
+        uint32 entityId
+    ) external view returns (Subscription memory) {
+        return SubscriptionModuleStorage.getLayout().subscriptions[account][entityId];
+    }
+
+    /// @inheritdoc ISubscriptionModule
+    function getEntityIds(address account) external view returns (uint256[] memory) {
+        return SubscriptionModuleStorage.getLayout().entityIds[account].values();
     }
 
     /// @inheritdoc ISubscriptionModule
@@ -321,26 +278,77 @@ contract SubscriptionModuleFacet is
         return SubscriptionModuleStorage.getLayout().operators.contains(operator);
     }
 
-    /// @inheritdoc ISubscriptionModule
-    function revokeOperator(address operator) external onlyOwner {
-        Validator.checkAddress(operator);
-        SubscriptionModuleStorage.getLayout().operators.remove(operator);
-        emit OperatorRevoked(operator);
+    /// @inheritdoc IValidationModule
+    function validateRuntime(
+        address account,
+        uint32 entityId,
+        address sender,
+        uint256,
+        bytes calldata,
+        bytes calldata
+    ) external view override {
+        if (sender != address(this)) SubscriptionModule__InvalidSender.selector.revertWith();
+        bool active = SubscriptionModuleStorage.getLayout().subscriptions[account][entityId].active;
+        if (!active) SubscriptionModule__InactiveSubscription.selector.revertWith();
     }
 
-    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
-    /*                      SPACE FACTORY                         */
-    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+    /// @inheritdoc IModule
+    function moduleId() external pure returns (string memory) {
+        return "towns.subscription-module.1.0.0";
+    }
 
     /// @inheritdoc ISubscriptionModule
-    function setSpaceFactory(address spaceFactory) external onlyOwner {
-        Validator.checkAddress(spaceFactory);
-        SubscriptionModuleStorage.getLayout().spaceFactory = spaceFactory;
-        emit SpaceFactoryChanged(spaceFactory);
+    function getRenewalBuffer(uint256 duration) external pure returns (uint256) {
+        return _getRenewalBuffer(duration);
     }
 
-    /// @inheritdoc ISubscriptionModule
-    function getSpaceFactory() external view returns (address) {
-        return SubscriptionModuleStorage.getLayout().spaceFactory;
+    /// @inheritdoc IValidationModule
+    function validateUserOp(
+        uint32,
+        PackedUserOperation calldata,
+        bytes32
+    ) external pure override returns (uint256) {
+        return _SIG_VALIDATION_FAILED;
+    }
+
+    /// @inheritdoc IValidationModule
+    function validateSignature(
+        address,
+        uint32,
+        address,
+        bytes32,
+        bytes calldata
+    ) external pure override returns (bytes4) {
+        return 0xffffffff;
+    }
+
+    /// @inheritdoc IValidationHookModule
+    function preUserOpValidationHook(
+        uint32 /* entityId */,
+        PackedUserOperation calldata /* userOp */,
+        bytes32 /* userOpHash */
+    ) external pure override returns (uint256) {
+        return _SIG_VALIDATION_FAILED;
+    }
+
+    /// @inheritdoc IValidationHookModule
+    function preRuntimeValidationHook(
+        uint32 /* entityId */,
+        address /* sender */,
+        uint256 /* value */,
+        bytes calldata /* data */,
+        bytes calldata /* authorization */
+    ) external pure override {
+        SubscriptionModule__NotSupported.selector.revertWith();
+    }
+
+    /// @inheritdoc IValidationHookModule
+    function preSignatureValidationHook(
+        uint32 /* entityId */,
+        address /* sender */,
+        bytes32 /* hash */,
+        bytes calldata /* signature */
+    ) external pure override {
+        SubscriptionModule__NotSupported.selector.revertWith();
     }
 }

package/src/apps/modules/subscription/SubscriptionModuleStorage.sol

@@ -14,6 +14,7 @@ struct Subscription {
     uint64 duration; // 8 bytes
     uint256 lastKnownRenewalPrice; // 32 bytes
     uint256 lastKnownExpiresAt; // 32 bytes
+    address lastKnownCurrency; // 20 bytes - currency at install/sync time
 }
 
 struct OperatorConfig {

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

@@ -121,17 +121,36 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
     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[]));
+            // equivalent: abi.decode(data, (address, bytes32, uint256, address[]))
+            address receiver;
+            bytes32 transactionId;
+            uint256 roleId;
+            address[] calldata nodes;
+            assembly {
+                receiver := shr(96, shl(96, calldataload(data.offset)))
+                transactionId := calldataload(add(data.offset, 0x20))
+                roleId := calldataload(add(data.offset, 0x40))
+                // nodes is dynamic: offset at 0x60, array starts at data.offset + offset
+                let nodesPtr := add(data.offset, calldataload(add(data.offset, 0x60)))
+                nodes.length := calldataload(nodesPtr)
+                nodes.offset := add(nodesPtr, 0x20)
+            }
             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));
+            // equivalent: abi.decode(data, (address, bytes32, uint256, bytes))
+            // extraData contains: (address sender)
+            address receiver;
+            bytes32 transactionId;
+            uint256 requestId;
+            address sender;
+            assembly {
+                receiver := shr(96, shl(96, calldataload(data.offset)))
+                transactionId := calldataload(add(data.offset, 0x20))
+                requestId := calldataload(add(data.offset, 0x40))
+                // extraData offset at 0x60, sender is first word after length
+                let extraDataPtr := add(data.offset, calldataload(add(data.offset, 0x60)))
+                sender := shr(96, shl(96, calldataload(add(extraDataPtr, 0x20))))
+            }
             _requestEntitlementCheck(
                 receiver,
                 transactionId,
@@ -141,14 +160,21 @@ contract EntitlementChecker is IEntitlementChecker, Facet {
                 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));
+            // equivalent: abi.decode(data, (address, bytes32, uint256, address, uint256, address))
+            address receiver;
+            bytes32 transactionId;
+            uint256 requestId;
+            address currency;
+            uint256 amount;
+            address sender;
+            assembly {
+                receiver := shr(96, shl(96, calldataload(data.offset)))
+                transactionId := calldataload(add(data.offset, 0x20))
+                requestId := calldataload(add(data.offset, 0x40))
+                currency := shr(96, shl(96, calldataload(add(data.offset, 0x60))))
+                amount := calldataload(add(data.offset, 0x80))
+                sender := shr(96, shl(96, calldataload(add(data.offset, 0xa0))))
+            }
             _requestEntitlementCheck(receiver, transactionId, requestId, currency, amount, sender);
         } else {
             EntitlementChecker_InvalidCheckType.selector.revertWith();

package/src/spaces/facets/ProtocolFeeLib.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
+import {IFeeManager} from "../../factory/facets/fee/IFeeManager.sol";
+import {CurrencyTransfer} from "../../utils/libraries/CurrencyTransfer.sol";
+
+library ProtocolFeeLib {
+    using SafeTransferLib for address;
+
+    /// @notice Charges protocol fee via FeeManager with ERC20 approval handling
+    /// @param spaceFactory The FeeManager address
+    /// @param feeType The type of fee being charged
+    /// @param user The user paying the fee
+    /// @param currency The payment currency (NATIVE_TOKEN or ERC20)
+    /// @param amount The base amount for fee calculation
+    /// @param expectedFee The pre-calculated expected fee
+    /// @return protocolFee The actual fee charged
+    function charge(
+        address spaceFactory,
+        bytes32 feeType,
+        address user,
+        address currency,
+        uint256 amount,
+        uint256 expectedFee
+    ) internal returns (uint256 protocolFee) {
+        if (expectedFee == 0) return 0;
+
+        bool isNative = currency == CurrencyTransfer.NATIVE_TOKEN;
+        if (!isNative) currency.safeApproveWithRetry(spaceFactory, expectedFee);
+
+        protocolFee = IFeeManager(spaceFactory).chargeFee{value: isNative ? expectedFee : 0}(
+            feeType,
+            user,
+            amount,
+            currency,
+            expectedFee,
+            ""
+        );
+
+        if (!isNative) currency.safeApprove(spaceFactory, 0);
+    }
+}

package/src/spaces/facets/membership/IMembership.sol

@@ -75,6 +75,11 @@ interface IMembershipBase {
     event MembershipFreeAllocationUpdated(uint256 indexed allocation);
     event MembershipWithdrawal(address indexed currency, address indexed recipient, uint256 amount);
     event MembershipTokenIssued(address indexed recipient, uint256 indexed tokenId);
+    /// @notice Emitted when a membership payment is processed (new membership or renewal)
+    /// @param currency The currency used for payment (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH)
+    /// @param price The base membership price paid
+    /// @param protocolFee The protocol fee paid
+    event MembershipPaid(address indexed currency, uint256 price, uint256 protocolFee);
     event MembershipTokenRejected(address indexed recipient);
 }
 
@@ -97,7 +102,7 @@ interface IMembership is IMembershipBase {
     /// @param referral The referral data
     function joinSpaceWithReferral(
         address receiver,
-        ReferralTypes memory referral
+        ReferralTypes calldata referral
     ) external payable;
 
     /// @notice Renew a space membership

package/src/spaces/facets/membership/MembershipFacet.sol

@@ -2,8 +2,8 @@
 pragma solidity ^0.8.23;
 
 // interfaces
-import {IMembership} from "./IMembership.sol";
 import {IMembershipPricing} from "./pricing/IMembershipPricing.sol";
+import {IMembership} from "./IMembership.sol";
 
 // libraries
 import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
@@ -26,13 +26,22 @@ contract MembershipFacet is IMembership, MembershipJoin, ReentrancyGuard, Facet
     /// @inheritdoc IMembership
     function joinSpace(JoinType action, bytes calldata data) external payable nonReentrant {
         if (action == JoinType.Basic) {
-            address receiver = abi.decode(data, (address));
+            // equivalent: abi.decode(data, (address))
+            address receiver;
+            assembly {
+                receiver := shr(96, shl(96, calldataload(data.offset)))
+            }
             _joinSpace(receiver);
         } else if (action == JoinType.WithReferral) {
-            (address receiver, ReferralTypes memory referral) = abi.decode(
-                data,
-                (address, ReferralTypes)
-            );
+            // equivalent: abi.decode(data, (address, ReferralTypes))
+            address receiver;
+            ReferralTypes calldata referral;
+            assembly {
+                receiver := shr(96, shl(96, calldataload(data.offset)))
+                // this is a variable length struct, so (data.offset + 0x20) contains
+                // the offset from data.offset at which the struct begins
+                referral := add(data.offset, calldataload(add(data.offset, 0x20)))
+            }
             _joinSpaceWithReferral(receiver, referral);
         } else {
             Membership__InvalidAction.selector.revertWith();
@@ -47,7 +56,7 @@ contract MembershipFacet is IMembership, MembershipJoin, ReentrancyGuard, Facet
     /// @inheritdoc IMembership
     function joinSpaceWithReferral(
         address receiver,
-        ReferralTypes memory referral
+        ReferralTypes calldata referral
     ) external payable nonReentrant {
         _joinSpaceWithReferral(receiver, referral);
     }

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

@@ -16,6 +16,7 @@ import {CurrencyTransfer} from "../../../../utils/libraries/CurrencyTransfer.sol
 import {CustomRevert} from "../../../../utils/libraries/CustomRevert.sol";
 import {MembershipStorage} from "../MembershipStorage.sol";
 import {Permissions} from "../../Permissions.sol";
+import {ProtocolFeeLib} from "../../ProtocolFeeLib.sol";
 
 // contracts
 import {ERC5643Base} from "../../../../diamond/facets/token/ERC5643/ERC5643Base.sol";
@@ -67,6 +68,7 @@ abstract contract MembershipJoin is
 
     struct PricingDetails {
         uint256 basePrice;
+        uint256 protocolFee;
         uint256 amountDue;
         bool shouldCharge;
     }
@@ -100,8 +102,12 @@ abstract contract MembershipJoin is
             return joinDetails;
         }
 
-        (uint256 totalRequired, ) = _getTotalMembershipPayment(membershipPrice);
-        (joinDetails.amountDue, joinDetails.shouldCharge) = (totalRequired, true);
+        (uint256 totalRequired, uint256 protocolFee) = _getTotalMembershipPayment(membershipPrice);
+        (joinDetails.protocolFee, joinDetails.amountDue, joinDetails.shouldCharge) = (
+            protocolFee,
+            totalRequired,
+            true
+        );
     }
 
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
@@ -150,7 +156,7 @@ abstract contract MembershipJoin is
     /// @notice Handles the process of joining a space with a referral
     /// @param receiver The address that will receive the membership token
     /// @param referral The referral information
-    function _joinSpaceWithReferral(address receiver, ReferralTypes memory referral) internal {
+    function _joinSpaceWithReferral(address receiver, ReferralTypes calldata referral) internal {
         _validateJoinSpace(receiver);
 
         PricingDetails memory joinDetails = _getPricingDetails();
@@ -229,7 +235,10 @@ abstract contract MembershipJoin is
         return amountRequired;
     }
 
-    function _validateUserReferral(address receiver, ReferralTypes memory referral) internal view {
+    function _validateUserReferral(
+        address receiver,
+        ReferralTypes calldata referral
+    ) internal view {
         if (referral.userReferral == receiver || referral.userReferral == msg.sender) {
             Membership__InvalidAddress.selector.revertWith();
         }
@@ -341,7 +350,10 @@ abstract contract MembershipJoin is
             Membership__InvalidTransactionType.selector.revertWith();
         }
 
-        _payProtocolFee(_getMembershipCurrency(), joinDetails.basePrice);
+        address currency = _getMembershipCurrency();
+        _payProtocolFee(currency, joinDetails.basePrice, joinDetails.protocolFee);
+
+        emit MembershipPaid(currency, joinDetails.basePrice, joinDetails.protocolFee);
 
         _afterChargeForJoinSpace(transactionId, receiver, joinDetails.amountDue);
     }
@@ -365,7 +377,7 @@ abstract contract MembershipJoin is
         ReferralTypes memory referral = abi.decode(referralData, (ReferralTypes));
 
         address currency = _getMembershipCurrency();
-        _payProtocolFee(currency, joinDetails.basePrice);
+        _payProtocolFee(currency, joinDetails.basePrice, joinDetails.protocolFee);
         _payPartnerFee(currency, referral.partner, joinDetails.basePrice);
         _payReferralFee(
             currency,
@@ -375,6 +387,8 @@ abstract contract MembershipJoin is
             joinDetails.basePrice
         );
 
+        emit MembershipPaid(currency, joinDetails.basePrice, joinDetails.protocolFee);
+
         _afterChargeForJoinSpace(transactionId, receiver, joinDetails.amountDue);
     }
 
@@ -410,7 +424,6 @@ abstract contract MembershipJoin is
         // set expiration of membership
         _renewSubscription(tokenId, _getMembershipDuration());
 
-        // emit event
         emit MembershipTokenIssued(receiver, tokenId);
     }
 
@@ -447,21 +460,18 @@ abstract contract MembershipJoin is
     /*                      FEE DISTRIBUTION                      */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
-    /// @notice Pays the protocol fee to the platform fee recipient
+    /// @notice Pays the protocol fee via FeeManager
     /// @param currency The currency to pay in
-    /// @param membershipPrice The price of the membership
-    /// @return protocolFee The amount of protocol fee paid
-    function _payProtocolFee(
-        address currency,
-        uint256 membershipPrice
-    ) internal returns (uint256 protocolFee) {
-        protocolFee = _getProtocolFee(membershipPrice);
-
-        CurrencyTransfer.transferCurrency(
+    /// @param basePrice The base price of the membership (for fee calculation)
+    /// @param expectedFee The pre-calculated protocol fee
+    function _payProtocolFee(address currency, uint256 basePrice, uint256 expectedFee) internal {
+        ProtocolFeeLib.charge(
+            _getSpaceFactory(),
+            _getMembershipFeeType(currency),
+            msg.sender,
             currency,
-            address(this),
-            _getPlatformRequirements().getFeeRecipient(),
-            protocolFee
+            basePrice,
+            expectedFee
         );
     }
 
@@ -542,13 +552,13 @@ abstract contract MembershipJoin is
             return;
         }
 
-        (uint256 totalRequired, ) = _getTotalMembershipPayment(basePrice);
+        (uint256 totalRequired, uint256 protocolFee) = _getTotalMembershipPayment(basePrice);
 
         if (currency == CurrencyTransfer.NATIVE_TOKEN) {
             // ETH payment: validate msg.value
             if (totalRequired > msg.value) Membership__InvalidPayment.selector.revertWith();
 
-            _payProtocolFee(currency, basePrice);
+            _payProtocolFee(currency, basePrice, protocolFee);
 
             // Handle excess payment
             uint256 excess = msg.value - totalRequired;
@@ -562,9 +572,10 @@ abstract contract MembershipJoin is
             // Transfer ERC20 from payer to contract
             _transferIn(currency, payer, totalRequired);
 
-            _payProtocolFee(currency, basePrice);
+            _payProtocolFee(currency, basePrice, protocolFee);
         }
 
+        emit MembershipPaid(currency, basePrice, protocolFee);
         _mintMembershipPoints(receiver, totalRequired);
         _renewSubscription(tokenId, uint64(duration));
     }

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

@@ -13,8 +13,7 @@ import {CurrencyTransfer} from "../../../utils/libraries/CurrencyTransfer.sol";
 import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {MembershipStorage} from "../membership/MembershipStorage.sol";
 import {TippingStorage} from "./TippingStorage.sol";
-import {BasisPoints} from "../../../utils/libraries/BasisPoints.sol";
-import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
+import {ProtocolFeeLib} from "../ProtocolFeeLib.sol";
 
 // contracts
 import {PointsBase} from "../points/PointsBase.sol";
@@ -23,8 +22,6 @@ abstract contract TippingBase is ITippingBase, PointsBase {
     using EnumerableSet for EnumerableSet.AddressSet;
     using CustomRevert for bytes4;
 
-    uint256 internal constant MAX_FEE_TOLERANCE = 100; // 1% tolerance
-
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
     /*                      Internal Functions                    */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
@@ -205,41 +202,28 @@ abstract contract TippingBase is ITippingBase, PointsBase {
         address currency,
         uint256 amount
     ) internal returns (uint256 protocolFee) {
-        MembershipStorage.Layout storage ds = MembershipStorage.layout();
-        address spaceFactory = ds.spaceFactory;
+        address spaceFactory = MembershipStorage.layout().spaceFactory;
 
-        // Calculate expected fee
-        uint256 expectedFee = IFeeManager(spaceFactory).calculateFee(
+        // Calculate fee first
+        protocolFee = IFeeManager(spaceFactory).calculateFee(
             FeeTypesLib.TIP_MEMBER,
             msg.sender,
             amount,
             ""
         );
 
-        if (expectedFee == 0) return 0;
-
-        // Add slippage tolerance (1%)
-        uint256 maxFee = expectedFee + BasisPoints.calculate(expectedFee, MAX_FEE_TOLERANCE);
-
-        // Approve ERC20 if needed (native token sends value with call)
-        bool isNative = currency == CurrencyTransfer.NATIVE_TOKEN;
-        if (!isNative) SafeTransferLib.safeApproveWithRetry(currency, spaceFactory, maxFee);
-
-        // Charge fee (excess native token will be refunded)
-        protocolFee = IFeeManager(spaceFactory).chargeFee{value: isNative ? maxFee : 0}(
+        // Charge with pre-calculated fee
+        protocolFee = ProtocolFeeLib.charge(
+            spaceFactory,
             FeeTypesLib.TIP_MEMBER,
             msg.sender,
-            amount,
             currency,
-            maxFee,
-            ""
+            amount,
+            protocolFee
         );
 
-        // Reset ERC20 approval
-        if (!isNative) SafeTransferLib.safeApprove(currency, spaceFactory, 0);
-
         // Mint points for fee payment (only for ETH tips)
-        if (isNative) {
+        if (protocolFee > 0 && currency == CurrencyTransfer.NATIVE_TOKEN) {
             address airdropDiamond = _getAirdropDiamond();
             uint256 points = _getPoints(
                 airdropDiamond,

package/src/utils/libraries/CurrencyTransfer.sol

@@ -8,8 +8,6 @@ import {IWETH} from "../interfaces/IWETH.sol";
 import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
 import {CustomRevert} from "./CustomRevert.sol";
 
-// contracts
-
 library CurrencyTransfer {
     using SafeTransferLib for address;
     using CustomRevert for bytes4;
@@ -124,4 +122,10 @@ library CurrencyTransfer {
             if (actualFee > 0) safeTransferERC20(currency, payer, recipient, actualFee);
         }
     }
+
+    /// @dev Returns the balance of `account` in `currency`.
+    function balanceOf(address currency, address account) internal view returns (uint256) {
+        if (currency == NATIVE_TOKEN) return account.balance;
+        return currency.balanceOf(account);
+    }
 }