@towns-protocol/contracts 0.0.442 → 0.0.444

package/docs/membership_architecture.md

@@ -0,0 +1,237 @@
+# Membership Contract Architecture
+
+## Overview
+
+The Towns Protocol membership system manages space memberships through NFT tokens with time-based expiration. It supports flexible pricing models, role-based entitlements (including cross-chain validation), referral systems, and fee distribution. Built on the Diamond pattern (EIP-2535), the system supports both native ETH and ERC20 (e.g., USDC) payments.
+
+## Architecture
+
+### Contract Hierarchy
+
+```
+MembershipFacet (external interface)
+  └─ MembershipJoin (join + renewal logic)
+      ├─ MembershipBase (pricing, fees, storage)
+      ├─ DispatcherBase (transaction capture)
+      ├─ EntitlementGatedBase (entitlement checks)
+      ├─ ReferralsBase (referral fees)
+      ├─ PrepayBase (prepaid memberships)
+      ├─ PointsBase (rewards points)
+      └─ ERC721ABase (NFT implementation)
+
+SpaceEntitlementGated (result handler)
+  └─ Overrides _onEntitlementCheckResultPosted()
+```
+
+### Storage Architecture
+
+**Diamond Storage Pattern** - Each facet uses isolated storage:
+
+- `MembershipStorage` - pricing, duration, limits, currency
+- `DispatcherStorage` - transactionBalance, transactionData
+- `EntitlementGatedStorage` - crosschain check state
+- `ReferralsStorage` - referral codes and fees
+- `PrepayStorage` - prepaid supply tracking
+
+### Key Facets
+
+| Facet | Responsibility |
+|-------|---------------|
+| `MembershipFacet.sol` | External API (join, renew, setters) |
+| `MembershipJoin.sol` | Join logic, payment processing |
+| `MembershipBase.sol` | Pricing, fees, validation |
+| `DispatcherBase.sol` | Transaction capture (ETH/ERC20) |
+| `EntitlementGatedBase.sol` | Entitlement check requests |
+| `SpaceEntitlementGated.sol` | Entitlement result handling |
+
+## Payment Model
+
+### Fee-Added Pricing
+
+The system uses a **fee-added** pricing model where protocol fees are added on top of the base price:
+
+```
+Total Price = Base Price + Protocol Fee
+
+Example (ETH):
+  Base Price:    1.0 ETH  → Space owner
+  Protocol Fee:  0.1 ETH  → Platform
+  Total:         1.1 ETH  ← User pays this
+```
+
+### Currency Support
+
+Memberships can be priced in:
+- **Native ETH** (`address(0)` or `NATIVE_TOKEN`)
+- **ERC20 tokens** (e.g., USDC) - must be enabled in FeeManager
+
+Currency validation happens in `_setMembershipCurrency()` which requires the token to have an enabled fee configuration in FeeManager.
+
+## Core Flow: Join → Entitlement Check → Token
+
+### Happy Path (Local Entitlement)
+
+```
+User: joinSpace(receiver) + payment
+  │
+  ├─ Validate: supply limit, payment amount
+  │
+  ├─ Register Transaction
+  │   └─ Capture payment in transactionBalance[txId]
+  │   └─ Store: [selector, sender, receiver, referral]
+  │
+  ├─ Check Entitlement (Local)
+  │   └─ ✓ User has local entitlement → PASS
+  │
+  ├─ Charge for Join
+  │   ├─ Protocol fee → Platform
+  │   ├─ Partner fee → Partner (if any)
+  │   ├─ Referral fee → Referrer (if any)
+  │   └─ Base price → Space owner
+  │
+  ├─ Refund Excess (if overpaid)
+  │
+  └─ Issue Token
+      └─ Mint NFT with expiration timestamp
+```
+
+### Crosschain Entitlement Path
+
+```
+User: joinSpace(receiver) + payment
+  │
+  ├─ Validate & Register (same as above)
+  │
+  ├─ Check Entitlement
+  │   ├─ Local entitlements: NONE
+  │   └─ Crosschain entitlements: EXISTS
+  │
+  ├─ Request Crosschain Check
+  │   └─ Send gas fee to EntitlementChecker
+  │   └─ Payment remains locked in transactionBalance[txId]
+  │
+  └─ Return (pending state)
+
+[Later - Entitlement result posted by checker]
+
+EntitlementChecker: postEntitlementCheckResultV2(txId, PASSED)
+  │
+  ├─ _onEntitlementCheckResultPosted(txId, PASSED)
+  │   ├─ Retrieve: payment = transactionBalance[txId]
+  │   ├─ Charge for Join (same fee distribution)
+  │   ├─ Refund Excess
+  │   └─ Issue Token
+  │
+  └─ Delete Transaction
+```
+
+### Rejection Path
+
+```
+Entitlement Check: FAILED
+  │
+  ├─ _rejectMembership(txId, receiver)
+  │   ├─ Delete: transactionData[txId]
+  │   ├─ Refund: full transactionBalance[txId] → receiver
+  │   └─ Emit: MembershipTokenRejected
+  │
+  └─ Transaction cleaned up
+```
+
+## Payment Capture System
+
+### Transaction Registration
+
+Generates unique transaction ID and captures payment amount:
+
+```solidity
+// Called in _joinSpace() or _joinSpaceWithReferral()
+bytes32 txId = _registerTransaction(sender, encodedData, capturedAmount);
+
+// Inside DispatcherBase:
+// 1. Generate txId from sender + block.number + nonce
+// 2. Store: transactionData[txId] = encodedData
+// 3. Capture: transactionBalance[txId] = capturedAmount
+```
+
+### Payment Release
+
+```solidity
+// Release consumed amount (after fee distribution)
+_releaseCapturedValue(txId, amountDue)
+
+// Refund remaining balance
+_refundBalance(txId, receiver)
+  └─ CurrencyTransfer.transferCurrency(currency, address(this), receiver, remaining)
+```
+
+## Entitlement Check System
+
+### Local vs Crosschain
+
+**Local Entitlements**: Immediate validation (same transaction)
+- ERC20/ERC721 ownership checks
+- Token balance thresholds
+- User allowlists
+
+**Crosschain Entitlements**: Async validation
+- Checks on other chains (Ethereum L1, Base L2)
+- Requires ETH for gas (sent to EntitlementChecker)
+- Payment held until result posted
+
+### Check Flow
+
+```
+_checkEntitlement(receiver, sender, txId, amountDue)
+  │
+  ├─ PHASE 1: Check Local Entitlements
+  │   └─ If ANY pass → return (true, false)
+  │
+  └─ PHASE 2: Check Crosschain Entitlements
+      └─ For each crosschain entitlement:
+          ├─ First request: send gas fee
+          └─ return (false, true)  ← pending state
+```
+
+## Appendix: Key Functions
+
+### Join Flow Entry Points
+
+```solidity
+// MembershipFacet.sol
+function joinSpace(address receiver) external payable nonReentrant
+function joinSpace(JoinType joinType, bytes calldata data) external payable nonReentrant
+function joinSpaceWithReferral(address receiver, ReferralTypes memory referral)
+    external payable nonReentrant
+```
+
+### Payment Capture
+
+```solidity
+// DispatcherBase.sol
+function _registerTransaction(address sender, bytes memory data, uint256 capturedAmount)
+    internal returns (bytes32 transactionId)
+function _getCapturedValue(bytes32 transactionId) internal view returns (uint256)
+function _releaseCapturedValue(bytes32 transactionId, uint256 amount) internal
+```
+
+### Fee Distribution
+
+```solidity
+// MembershipBase.sol
+function _collectProtocolFee(address payer, uint256 membershipPrice)
+    internal returns (uint256 protocolFee)
+function _transferIn(address from, uint256 amount) internal returns (uint256)
+```
+
+### Entitlement Checking
+
+```solidity
+// MembershipJoin.sol
+function _checkEntitlement(address receiver, address sender, bytes32 txId, uint256 amount)
+    internal returns (bool isEntitled, bool isCrosschainPending)
+
+// EntitlementGatedBase.sol
+function _requestEntitlementCheckV2(...)
+function _postEntitlementCheckResultV2(bytes32 txId, uint256 roleId, NodeVoteStatus result)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.442",
+  "version": "0.0.444",
   "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.442",
+    "@towns-protocol/prettier-config": "^0.0.444",
     "@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": "d2e07ef0deb899067d0d1a47e30c4edd5bb22547"
+  "gitHead": "bed6929e87d5aec54647c2b7fdb8e703401aa99f"
 }

package/scripts/deployments/diamonds/DeploySpaceFactory.s.sol

@@ -223,7 +223,7 @@ contract DeploySpaceFactory is IDiamondInitHelper, DiamondHelper, Deployer {
             facet,
             DeployPlatformRequirements.makeInitData(
                 deployer, // feeRecipient
-                500, // membershipBps 5%
+                1000, // membershipBps 10%
                 0.0005 ether, // membershipFee
                 1000, // membershipFreeAllocation
                 365 days, // membershipDuration
@@ -354,7 +354,7 @@ contract DeploySpaceFactory is IDiamondInitHelper, DiamondHelper, Deployer {
                     facet,
                     DeployPlatformRequirements.makeInitData(
                         deployer, // feeRecipient
-                        500, // membershipBps 5%
+                        1000, // membershipBps 10%
                         0.0005 ether, // membershipFee
                         1000, // membershipFreeAllocation
                         365 days, // membershipDuration

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

@@ -13,7 +13,7 @@ library DeployMembership {
     using DynamicArrayLib for DynamicArrayLib.DynamicArray;
 
     function selectors() internal pure returns (bytes4[] memory res) {
-        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(22);
+        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(23);
 
         // Funds
         arr.p(IMembership.revenue.selector);
@@ -50,6 +50,7 @@ library DeployMembership {
 
         // Currency
         arr.p(IMembership.getMembershipCurrency.selector);
+        arr.p(IMembership.setMembershipCurrency.selector);
 
         // Image
         arr.p(IMembership.setMembershipImage.selector);

package/scripts/deployments/utils/DeployMockERC20.s.sol

@@ -16,7 +16,7 @@ contract DeployMockERC20 is Deployer {
         // address predeterminedAddress = vm.computeCreate2Address(salt, initCodeHash);
 
         vm.startBroadcast(deployer);
-        MockERC20 deployment = new MockERC20("TownsTest", "TToken");
+        MockERC20 deployment = new MockERC20("TownsTest", "TToken", 18);
         vm.stopBroadcast();
 
         return address(deployment);

package/scripts/deployments/utils/DeployMockUSDC.s.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {Deployer} from "scripts/common/Deployer.s.sol";
+import {MockERC20} from "test/mocks/MockERC20.sol";
+
+contract DeployMockUSDC is Deployer {
+    function versionName() public pure override returns (string memory) {
+        return "utils/mockUSDC";
+    }
+
+    function __deploy(address deployer) internal override returns (address) {
+        vm.startBroadcast(deployer);
+        MockERC20 deployment = new MockERC20("USD Coin", "USDC", 6);
+        vm.stopBroadcast();
+
+        return address(deployment);
+    }
+}

package/scripts/interactions/InteractPostDeploy.s.sol

@@ -39,6 +39,7 @@ contract InteractPostDeploy is Interaction {
         address riverAirdrop = getDeployment("riverAirdrop");
         address appRegistry = getDeployment("appRegistry");
         address subscriptionModule = getDeployment("subscriptionModule");
+        address mockUSDC = getDeployment("mockUSDC");
         address townsBase = deployTownsBase.deploy(deployer);
         address proxyDelegation = deployProxyDelegation.deploy(deployer);
 
@@ -59,6 +60,16 @@ contract InteractPostDeploy is Interaction {
         INodeOperator operatorFacet = INodeOperator(baseRegistry);
         operatorFacet.registerOperator(OPERATOR);
         operatorFacet.setOperatorStatus(OPERATOR, NodeOperatorStatus.Approved);
+
+        // Configure membership fee for mock USDC
+        IFeeManager(spaceFactory).setFeeConfig(
+            FeeTypesLib.membership(mockUSDC),
+            deployer,
+            FeeCalculationMethod.HYBRID,
+            1000, // 10%
+            1_500_000, // $1.50 (6 decimals)
+            true
+        );
         vm.stopBroadcast();
     }
 }

package/src/factory/facets/feature/FeatureManagerFacet.sol

@@ -2,12 +2,10 @@
 pragma solidity ^0.8.23;
 
 // interfaces
-import {IFeatureManagerFacet} from "./IFeatureManagerFacet.sol";
-import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
+import {IFeatureManager} from "./IFeatureManager.sol";
 
 // libraries
-import {FeatureManagerBase} from "./FeatureManagerBase.sol";
-import {FeatureCondition} from "./IFeatureManagerFacet.sol";
+import "./FeatureManagerMod.sol" as FeatureManagerMod;
 
 // contracts
 import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
@@ -16,61 +14,66 @@ import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
 /// @title FeatureManagerFacet
 /// @notice Manages feature conditions and checks for spaces
 /// @dev This facet is responsible for managing feature conditions and checking if a space meets the condition for a feature to be enabled
-contract FeatureManagerFacet is IFeatureManagerFacet, OwnableBase, Facet, FeatureManagerBase {
+contract FeatureManagerFacet is IFeatureManager, OwnableBase, Facet {
     function __FeatureManagerFacet_init() external onlyInitializing {
-        _addInterface(type(IFeatureManagerFacet).interfaceId);
+        _addInterface(type(IFeatureManager).interfaceId);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
+    /// @inheritdoc IFeatureManager
     function setFeatureCondition(
         bytes32 featureId,
-        FeatureCondition calldata condition
+        FeatureManagerMod.FeatureCondition calldata condition
     ) external onlyOwner {
-        _upsertFeatureCondition(featureId, condition, true);
-        emit FeatureConditionSet(featureId, condition);
+        FeatureManagerMod.upsertFeatureCondition(featureId, condition, true);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
+    /// @inheritdoc IFeatureManager
     function updateFeatureCondition(
         bytes32 featureId,
-        FeatureCondition calldata condition
+        FeatureManagerMod.FeatureCondition calldata condition
     ) external onlyOwner {
-        _upsertFeatureCondition(featureId, condition, false);
-        emit FeatureConditionSet(featureId, condition);
+        FeatureManagerMod.upsertFeatureCondition(featureId, condition, false);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
+    /// @inheritdoc IFeatureManager
     function disableFeatureCondition(bytes32 featureId) external onlyOwner {
-        _disableFeatureCondition(featureId);
-        emit FeatureConditionDisabled(featureId);
+        FeatureManagerMod.disableFeatureCondition(featureId);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
+    /// @inheritdoc IFeatureManager
     function getFeatureCondition(
         bytes32 featureId
-    ) external view returns (FeatureCondition memory result) {
+    ) external view returns (FeatureManagerMod.FeatureCondition memory result) {
         // Gas optimization: Reclaim implicit memory allocation for return variable
         // since we're loading from storage, not using the pre-allocated memory
         assembly ("memory-safe") {
             mstore(0x40, result)
         }
-        result = _getFeatureCondition(featureId);
+        result = FeatureManagerMod.getFeatureCondition(featureId);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
-    function getFeatureConditions() external view returns (FeatureCondition[] memory) {
-        return _getFeatureConditions();
+    /// @inheritdoc IFeatureManager
+    function getFeatureConditions()
+        external
+        view
+        returns (FeatureManagerMod.FeatureCondition[] memory)
+    {
+        return FeatureManagerMod.getFeatureConditions();
     }
 
-    /// @inheritdoc IFeatureManagerFacet
+    /// @inheritdoc IFeatureManager
     function getFeatureConditionsForSpace(
         address space
-    ) external view returns (FeatureCondition[] memory) {
-        return _getFeatureConditionsForSpace(space);
+    ) external view returns (FeatureManagerMod.FeatureCondition[] memory) {
+        return FeatureManagerMod.getFeatureConditionsForAddress(space);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
-    function checkFeatureCondition(bytes32 featureId, address space) external view returns (bool) {
-        return _isValidCondition(_getFeatureCondition(featureId), space);
+    /// @inheritdoc IFeatureManager
+    function checkFeatureCondition(bytes32 featureId, address addr) external view returns (bool) {
+        return
+            FeatureManagerMod.isValidCondition(
+                FeatureManagerMod.getFeatureCondition(featureId),
+                addr
+            );
     }
 }