@towns-protocol/contracts 0.0.364 → 0.0.366

package/docs/staking_state_machine.md

@@ -0,0 +1,256 @@
+# Staking Position State Machine
+
+This document describes the lifecycle of a staking position in the RewardsDistributionV2 contract.
+
+## State-Determining Fields
+
+A deposit's state is determined by two key properties (once it exists):
+
+- **deposit.delegatee**: Address the stake is delegated to (operator or space)
+- **deposit.pendingWithdrawal**: Amount waiting to be withdrawn
+
+Note: DepositIds are assigned sequentially starting from 0 when stake() is called. The "Non-existent" state refers to the period before calling stake() to create the deposit.
+
+## States
+
+### 1. Non-existent
+- **Condition**: Before calling stake()/permitAndStake()/stakeOnBehalf()
+- **Description**: No deposit has been created yet; depositId will be assigned upon staking
+
+### 2. Active
+- **Condition**: `delegatee != address(0)` AND `pendingWithdrawal == 0`
+- **Description**: Stake is actively delegated to an operator or space, earning rewards
+- **Key behaviors**:
+  - Earning staking rewards based on `deposit.beneficiary`
+  - Delegated voting power goes to `deposit.delegatee`
+  - Can increase stake, redelegate, or change beneficiary
+
+### 3. Withdrawal Initiated
+- **Condition**: `delegatee == address(0)` AND `pendingWithdrawal > 0`
+- **Description**: User has initiated withdrawal, stake is no longer active
+- **Key behaviors**:
+  - No longer earning rewards
+  - Delegation has been removed
+  - Funds held in proxy, waiting for final withdrawal
+  - Can redelegate to restake the pending amount
+
+### 4. Withdrawn
+- **Condition**: `delegatee == address(0)` AND `pendingWithdrawal == 0` AND deposit exists
+- **Description**: Withdrawal completed, deposit shell remains but inactive
+- **Key behaviors**:
+  - No active stake or pending withdrawals
+  - Deposit record persists in storage
+  - Cannot increase stake (would fail delegatee validation)
+  - Could theoretically redelegate with 0 amount
+
+## State Transitions
+
+### From Non-existent → Active
+
+**Functions**: `stake()`, `permitAndStake()`, `stakeOnBehalf()`
+
+Creates a new deposit with:
+- New depositId assigned (sequential, starting from 0)
+- Delegatee set to specified operator/space
+- Beneficiary set for rewards
+- Stake amount transferred to new delegation proxy
+
+---
+
+### Active → Active (State Preserved)
+
+#### Increase Stake
+
+**Functions**: `increaseStake()`, `permitAndIncreaseStake()`
+
+Adds more funds to existing position:
+- Validates existing delegatee is still valid
+- Increases stake amount
+- Updates earning power for rewards
+
+#### Redelegate
+
+**Function**: `redelegate()` (when `pendingWithdrawal == 0`)
+
+Changes delegation target:
+- Validates new delegatee is operator or space
+- Updates rewards with old commission rate
+- Sets new delegatee and commission rate
+- Calls `DelegationProxy.redelegate()` to update on-chain delegation
+
+#### Change Beneficiary
+
+**Function**: `changeBeneficiary()`
+
+Changes who receives rewards:
+- Validates delegatee is still valid
+- Settles existing rewards
+- Transfers earning power to new beneficiary
+
+---
+
+### Active → Withdrawal Initiated
+
+**Function**: `initiateWithdraw()`
+
+Begins withdrawal process:
+- Calls internal withdraw logic that:
+  - Sets `delegatee = address(0)`
+  - Moves stake amount to `pendingWithdrawal`
+  - Claims any pending rewards
+- For external deposits: Calls `DelegationProxy.redelegate(address(0))`
+- For self-owned deposits: Sets `pendingWithdrawal = 0` (immediate withdrawal)
+
+**Special Case**: If `owner == address(this)`, the deposit goes directly to Withdrawn state.
+
+---
+
+### Withdrawal Initiated → Withdrawn
+
+**Function**: `withdraw()`
+
+Completes withdrawal:
+- Validates `pendingWithdrawal > 0`
+- Validates `owner != address(this)` (self-owned deposits cannot withdraw)
+- Sets `pendingWithdrawal = 0`
+- Transfers tokens from proxy to owner
+
+---
+
+### Withdrawal Initiated → Active
+
+**Function**: `redelegate()` (when `pendingWithdrawal > 0`)
+
+Restakes pending withdrawal:
+- Validates new delegatee is operator or space
+- Calls `increaseStake()` with `pendingWithdrawal` amount
+- Sets `deposit.delegatee = newDelegatee`
+- Sets `deposit.pendingWithdrawal = 0`
+- Calls `DelegationProxy.redelegate()` to update delegation
+
+This is a special recovery mechanism allowing users to restake without completing withdrawal.
+
+---
+
+## State Transition Diagram
+
+```
+┌─────────────┐
+│             │
+│ Non-existent│
+│             │
+└──────┬──────┘
+       │ stake(), permitAndStake(), stakeOnBehalf()
+       ▼
+┌─────────────────────────────────────────┐
+│                                         │
+│              Active                     │
+│  • Earning rewards                      │
+│  • Delegated to operator/space          │
+│                                         │◄────┐
+└──┬──────────┬───────────────────────┬──┘     │
+   │          │                       │        │
+   │          │                       │        │
+   │          │ increaseStake()       │        │
+   │          │ permitAndIncreaseStake()       │
+   │          │ redelegate()          │        │
+   │          │ changeBeneficiary()   │        │
+   │          └───────────────────────┘        │
+   │                                           │
+   │ initiateWithdraw()                        │
+   ▼                                           │
+┌─────────────────────────────────────────┐   │
+│                                         │   │
+│       Withdrawal Initiated              │   │
+│  • No rewards                           │   │
+│  • Funds in proxy, pending withdrawal   │   │
+│                                         │   │
+└──┬──────────────────────────────────┬───┘   │
+   │                                  │       │
+   │ withdraw()                       │       │
+   │                                  │       │
+   ▼                                  │       │
+┌─────────────────────────────────────────┐  │
+│                                         │  │
+│            Withdrawn                    │  │
+│  • Empty deposit                        │  │
+│  • No active stake                      │  │
+│                                         │  │
+└─────────────────────────────────────────┘  │
+                                             │
+                  redelegate() ──────────────┘
+```
+
+## Function Availability by State
+
+| Function                 | Non-existent | Active                   | Withdrawal Initiated | Withdrawn    |
+|--------------------------|--------------|--------------------------|----------------------|--------------|
+| stake()                  | ✅ Creates    | ❌                        | ❌                    | ❌            |
+| permitAndStake()         | ✅ Creates    | ❌                        | ❌                    | ❌            |
+| stakeOnBehalf()          | ✅ Creates    | ❌                        | ❌                    | ❌            |
+| increaseStake()          | ❌            | ✅                        | ❌                    | ❌            |
+| permitAndIncreaseStake() | ❌            | ✅                        | ❌                    | ❌            |
+| redelegate()             | ❌            | ✅ Same state             | ✅ → Active           | ⚠️ Edge case |
+| changeBeneficiary()      | ❌            | ✅                        | ❌                    | ❌            |
+| initiateWithdraw()       | ❌            | ✅ → Withdrawal Initiated | ❌                    | ❌            |
+| withdraw()               | ❌            | ❌                        | ✅ → Withdrawn        | ❌            |
+
+## Special Cases
+
+### Self-Owned Deposits (owner == address(this))
+
+When a deposit is owned by the contract itself:
+
+- **No delegation proxy** is used
+- **initiateWithdraw()**: Sets `pendingWithdrawal = 0` immediately (goes straight to Withdrawn)
+- **withdraw()**: Reverts with `RewardsDistribution__CannotWithdrawFromSelf`
+
+This is used internally by the protocol for special staking mechanisms.
+
+### Redelegate with Pending Withdrawal
+
+When `redelegate()` is called on a deposit in "Withdrawal Initiated" state:
+
+- Instead of calling `staking.redelegate()`, it calls `staking.increaseStake()`
+- Treats the `pendingWithdrawal` as a new stake increase
+- Manually sets `deposit.delegatee` to the new delegatee
+- Manually sets `deposit.pendingWithdrawal = 0`
+- Effectively "cancels" the withdrawal and restakes to a new delegatee
+
+This provides a recovery path without requiring users to complete withdrawal and create a new deposit.
+
+## Validation Rules
+
+### Owner Validation
+- All state-changing functions require `msg.sender == deposit.owner` (via `_revertIfNotDepositOwner()`)
+
+### Delegatee Validation
+- `increaseStake()`, `redelegate()`, `changeBeneficiary()`: Require delegatee to be a valid operator or space
+- Validation happens via `_revertIfNotOperatorOrSpace(delegatee)`
+
+### Amount Validation
+- `withdraw()`: Requires `pendingWithdrawal > 0`
+
+## Implementation Notes
+
+### Reward Settlement
+- Most state transitions trigger reward settlement via the internal `StakingRewards` library
+- `_sweepSpaceRewardsIfNecessary()` is called to transfer space delegation rewards to operators
+
+### Delegation Proxy Lifecycle
+- Proxy is deployed when first stake is created (for non-self-owned deposits)
+- Proxy persists through the entire deposit lifecycle
+- Proxy's delegation target is updated via `redelegate()` calls
+- Tokens are transferred from/to proxy during stake/withdrawal operations
+
+### Commission Rates
+- Commission rate is fetched at the time of each operation
+- For space delegatees, the commission rate of their active operator is used
+- Rate changes don't affect existing positions until next state transition
+
+## References
+
+- Main contract: `RewardsDistributionV2.sol` lines 94-242
+- Base implementation: `RewardsDistributionBase.sol`
+- Storage library: `StakingRewards.sol`
+- Proxy implementation: `DelegationProxy.sol`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.364",
+  "version": "0.0.366",
   "packageManager": "yarn@3.8.0",
   "scripts": {
     "build-types": "bash scripts/build-contract-types.sh",
@@ -35,7 +35,7 @@
     "@layerzerolabs/oapp-evm": "^0.3.2",
     "@openzeppelin/merkle-tree": "^1.0.8",
     "@prb/test": "^0.6.4",
-    "@towns-protocol/prettier-config": "^0.0.364",
+    "@towns-protocol/prettier-config": "^0.0.366",
     "@typechain/ethers-v5": "^11.1.2",
     "@wagmi/cli": "^2.2.0",
     "forge-std": "github:foundry-rs/forge-std#v1.10.0",
@@ -57,5 +57,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "14393591e10dacdc499c872086597abae8aa2fe1"
+  "gitHead": "ed5b2f3718b5da967d60c30fc589bdf20568f992"
 }

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

@@ -40,6 +40,7 @@ interface ISubscriptionModuleBase {
     error SubscriptionModule__InvalidTokenOwner();
     error SubscriptionModule__InsufficientBalance();
     error SubscriptionModule__ActiveSubscription();
+    error SubscriptionModule__MembershipBanned();
     /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
     /*                           Events                           */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
@@ -107,10 +108,10 @@ interface ISubscriptionModule is ISubscriptionModuleBase {
         uint32 entityId
     ) external view returns (Subscription memory);
 
-    /// @notice Gets the renewal buffer for an expiration time
-    /// @param expirationTime The expiration time to get the renewal buffer for
-    /// @return The renewal buffer for the expiration time
-    function getRenewalBuffer(uint256 expirationTime) external view returns (uint256);
+    /// @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

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

@@ -9,6 +9,7 @@ import {IValidationModule} from "@erc6900/reference-implementation/interfaces/IV
 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";
 
 // libraries
 import {PackedUserOperation} from "@eth-infinitism/account-abstraction/interfaces/PackedUserOperation.sol";
@@ -19,6 +20,7 @@ import {ReentrancyGuardTransient} from "solady/utils/ReentrancyGuardTransient.so
 import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {Validator} from "../../../utils/libraries/Validator.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,6 +40,7 @@ contract SubscriptionModuleFacet is
 {
     using EnumerableSetLib for EnumerableSetLib.Uint256Set;
     using EnumerableSetLib for EnumerableSetLib.AddressSet;
+    using SafeCastLib for uint256;
     using CustomRevert for bytes4;
 
     uint256 internal constant _SIG_VALIDATION_FAILED = 1;
@@ -77,23 +80,27 @@ contract SubscriptionModuleFacet is
 
         if (entityId == 0) SubscriptionModule__InvalidEntityId.selector.revertWith();
 
+        if (IBanning(space).isBanned(tokenId))
+            SubscriptionModule__MembershipBanned.selector.revertWith();
+
         if (IERC721(space).ownerOf(tokenId) != msg.sender)
             SubscriptionModule__InvalidTokenOwner.selector.revertWith();
 
-        IMembership membershipFacet = IMembership(space);
-        uint256 expiresAt = membershipFacet.expiresAt(tokenId);
-
         SubscriptionModuleStorage.Layout storage $ = SubscriptionModuleStorage.getLayout();
 
         if (!$.entityIds[msg.sender].add(entityId))
             SubscriptionModule__InvalidEntityId.selector.revertWith();
 
+        IMembership membershipFacet = IMembership(space);
+        uint256 expiresAt = membershipFacet.expiresAt(tokenId);
+        uint256 duration = membershipFacet.getMembershipDuration();
+
         Subscription storage sub = $.subscriptions[msg.sender][entityId];
         sub.space = space;
         sub.active = true;
         sub.tokenId = tokenId;
-        sub.installTime = uint40(block.timestamp);
-        sub.nextRenewalTime = _calculateNextRenewalTime(expiresAt, sub.installTime);
+        sub.installTime = block.timestamp.toUint40();
+        sub.nextRenewalTime = _calculateBaseRenewalTime(expiresAt, duration);
 
         emit SubscriptionConfigured(
             msg.sender,
@@ -220,6 +227,16 @@ contract SubscriptionModuleFacet is
                 continue;
             }
 
+            if (IBanning(sub.space).isBanned(sub.tokenId)) {
+                _pauseSubscription(sub, params[i].account, params[i].entityId);
+                emit BatchRenewalSkipped(
+                    params[i].account,
+                    params[i].entityId,
+                    "MEMBERSHIP_BANNED"
+                );
+                continue;
+            }
+
             // Skip if account isn't owner anymore (for safety)
             if (IERC721(sub.space).ownerOf(sub.tokenId) != params[i].account) {
                 _pauseSubscription(sub, params[i].account, params[i].entityId);
@@ -242,10 +259,11 @@ contract SubscriptionModuleFacet is
             }
 
             uint256 expiresAt = membershipFacet.expiresAt(sub.tokenId);
-            uint40 correctNextRenewalTime = _calculateNextRenewalTime(expiresAt, sub.installTime);
+            uint256 duration = membershipFacet.getMembershipDuration();
+            uint40 nextRenewalTime = _calculateBaseRenewalTime(expiresAt, duration);
 
-            if (sub.nextRenewalTime != correctNextRenewalTime) {
-                sub.nextRenewalTime = correctNextRenewalTime;
+            if (sub.nextRenewalTime != nextRenewalTime) {
+                sub.nextRenewalTime = nextRenewalTime;
                 emit SubscriptionSynced(params[i].account, params[i].entityId, sub.nextRenewalTime);
             }
 
@@ -262,8 +280,8 @@ contract SubscriptionModuleFacet is
     }
 
     /// @inheritdoc ISubscriptionModule
-    function getRenewalBuffer(uint256 expirationTime) external view returns (uint256) {
-        return _getRenewalBuffer(expirationTime);
+    function getRenewalBuffer(uint256 duration) external pure returns (uint256) {
+        return _getRenewalBuffer(duration);
     }
 
     /// @inheritdoc ISubscriptionModule
@@ -282,9 +300,10 @@ contract SubscriptionModuleFacet is
 
         IMembership membershipFacet = IMembership(sub.space);
         uint256 expiresAt = membershipFacet.expiresAt(sub.tokenId);
+        uint256 duration = membershipFacet.getMembershipDuration();
 
         // 6. Always sync renewal time to current membership state
-        uint40 correctNextRenewalTime = _calculateNextRenewalTime(expiresAt, sub.installTime);
+        uint40 correctNextRenewalTime = _calculateBaseRenewalTime(expiresAt, duration);
         if (sub.nextRenewalTime != correctNextRenewalTime) {
             sub.nextRenewalTime = correctNextRenewalTime;
             emit SubscriptionSynced(msg.sender, entityId, sub.nextRenewalTime);
@@ -388,8 +407,15 @@ contract SubscriptionModuleFacet is
 
         // Get the actual new expiration time after successful renewal
         uint256 newExpiresAt = membershipFacet.expiresAt(sub.tokenId);
-        sub.nextRenewalTime = _calculateNextRenewalTime(newExpiresAt, sub.installTime);
-        sub.lastRenewalTime = uint40(block.timestamp);
+
+        // Calculate next renewal time ensuring it's strictly in the future
+        uint256 duration = membershipFacet.getMembershipDuration();
+        sub.nextRenewalTime = _enforceMinimumBuffer(
+            _calculateBaseRenewalTime(newExpiresAt, duration),
+            newExpiresAt,
+            duration
+        );
+        sub.lastRenewalTime = block.timestamp.toUint40();
         sub.spent += actualRenewalPrice;
 
         emit SubscriptionRenewed(
@@ -403,59 +429,75 @@ contract SubscriptionModuleFacet is
         emit SubscriptionSpent(params.account, params.entityId, actualRenewalPrice, sub.spent);
     }
 
-    /// @dev Determines the appropriate renewal buffer time based on original membership duration
-    /// @param expirationTime The expiration timestamp of the membership
-    /// @param installTime The time when the subscription was installed
+    /// @dev Determines the appropriate renewal buffer time based on membership duration
+    /// @param duration The membership duration in seconds
     /// @return The appropriate buffer time in seconds before expiration
-    function _getRenewalBuffer(
-        uint256 expirationTime,
-        uint256 installTime
-    ) internal pure returns (uint256) {
-        uint256 originalDuration = expirationTime >= installTime ? expirationTime - installTime : 0;
-
+    function _getRenewalBuffer(uint256 duration) internal pure returns (uint256) {
         // For memberships shorter than 1 hour, use immediate buffer (2 minutes)
-        if (originalDuration <= 1 hours) return BUFFER_IMMEDIATE;
+        if (duration <= 1 hours) return BUFFER_IMMEDIATE;
 
         // For memberships shorter than 6 hours, use short buffer (1 hour)
-        if (originalDuration <= 6 hours) return BUFFER_SHORT;
+        if (duration <= 6 hours) return BUFFER_SHORT;
 
         // For memberships shorter than 24 hours, use medium buffer (6 hours)
-        if (originalDuration <= 24 hours) return BUFFER_MEDIUM;
+        if (duration <= 24 hours) return BUFFER_MEDIUM;
 
         // For memberships longer than 24 hours, use long buffer (12 hours)
         return BUFFER_LONG;
     }
 
-    /// @dev Legacy function for backward compatibility - uses current time as install time
+    /// @dev Calculates the base renewal time without minimum buffer enforcement
     /// @param expirationTime The expiration timestamp of the membership
-    /// @return The appropriate buffer time in seconds before expiration
-    function _getRenewalBuffer(uint256 expirationTime) internal view returns (uint256) {
-        return _getRenewalBuffer(expirationTime, block.timestamp);
-    }
-
-    /// @dev Calculates the correct next renewal time for a given expiration using install time
-    /// @param expirationTime The expiration timestamp of the membership
-    /// @param installTime The time when the subscription was installed
-    /// @return The next renewal time as uint40
-    function _calculateNextRenewalTime(
+    /// @param duration The membership duration in seconds
+    /// @return The base renewal time as uint40
+    function _calculateBaseRenewalTime(
         uint256 expirationTime,
-        uint256 installTime
+        uint256 duration
     ) internal view returns (uint40) {
-        if (expirationTime <= block.timestamp) return uint40(block.timestamp);
+        // If membership is already expired, schedule for the future
+        if (expirationTime <= block.timestamp) {
+            return (block.timestamp + duration).toUint40();
+        }
 
-        uint256 buffer = _getRenewalBuffer(expirationTime, installTime);
+        uint256 buffer = _getRenewalBuffer(duration);
         uint256 timeUntilExpiration = expirationTime - block.timestamp;
 
-        if (buffer >= timeUntilExpiration) return uint40(block.timestamp);
+        if (buffer >= timeUntilExpiration) {
+            // If buffer is larger than time until expiration,
+            // schedule for after the expiration by the same amount
+            return (expirationTime + (buffer - timeUntilExpiration)).toUint40();
+        }
 
-        return uint40(expirationTime - buffer);
+        return (expirationTime - buffer).toUint40();
     }
 
-    /// @dev Legacy function for backward compatibility - uses current time as install time
+    /// @dev Enforces minimum buffer to prevent double renewals
+    /// @param baseTime The base calculated renewal time
     /// @param expirationTime The expiration timestamp of the membership
-    /// @return The next renewal time as uint40
-    function _calculateNextRenewalTime(uint256 expirationTime) internal view returns (uint40) {
-        return _calculateNextRenewalTime(expirationTime, block.timestamp);
+    /// @param duration The membership duration in seconds
+    /// @return The adjusted renewal time with minimum buffer enforced
+    function _enforceMinimumBuffer(
+        uint40 baseTime,
+        uint256 expirationTime,
+        uint256 duration
+    ) internal view returns (uint40) {
+        uint256 operatorBuffer = SubscriptionModuleStorage.getOperatorBuffer(msg.sender);
+
+        // If base time is far enough in the future, use it
+        if (baseTime > block.timestamp + operatorBuffer) {
+            return baseTime;
+        }
+
+        // For very short durations, schedule close to expiration with minimum buffer
+        if (duration <= 1 hours) {
+            return (expirationTime - operatorBuffer).toUint40();
+        }
+
+        // For longer durations, use standard calculation with minimum buffer
+        uint256 buffer = _getRenewalBuffer(duration);
+        uint256 minFutureTime = block.timestamp + duration - buffer;
+
+        return (minFutureTime > baseTime ? minFutureTime : baseTime).toUint40();
     }
 
     /// @dev Creates the runtime final data for the renewal

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

@@ -11,17 +11,27 @@ struct Subscription {
     uint40 lastRenewalTime; // 5 bytes
     uint40 nextRenewalTime; // 5 bytes
     bool active; // 1 byte
+    uint64 duration;
+}
+
+struct OperatorConfig {
+    uint256 interval;
+    uint256 buffer;
 }
 
 library SubscriptionModuleStorage {
     using EnumerableSetLib for EnumerableSetLib.Uint256Set;
     using EnumerableSetLib for EnumerableSetLib.AddressSet;
 
+    uint256 public constant KEEPER_INTERVAL = 5 minutes;
+    uint256 public constant MIN_RENEWAL_BUFFER = KEEPER_INTERVAL + 1 minutes; // Minimum buffer to prevent double renewals
+
     /// @custom:storage-location erc7201:towns.subscription.validation.module.storage
     struct Layout {
         EnumerableSetLib.AddressSet operators;
         mapping(address account => mapping(uint32 entityId => Subscription)) subscriptions;
         mapping(address account => EnumerableSetLib.Uint256Set entityIds) entityIds;
+        mapping(address operator => OperatorConfig) operatorConfig;
     }
 
     // keccak256(abi.encode(uint256(keccak256("towns.subscription.validation.module.storage")) - 1)) & ~bytes32(uint256(0xff))
@@ -33,4 +43,10 @@ library SubscriptionModuleStorage {
             $.slot := STORAGE_SLOT
         }
     }
+
+    function getOperatorBuffer(address operator) internal view returns (uint256) {
+        OperatorConfig storage config = getLayout().operatorConfig[operator];
+        if (config.interval == 0) return MIN_RENEWAL_BUFFER;
+        return config.buffer;
+    }
 }