LiqLocker Math & Rationale

The LiqLocker contract employs simple yet robust mathematical models to ensure fairness and predictability in liquidity vesting and fee distribution.

Liquidity Unlock Formula

When a user first migrates to the graduated token, they receive:

  • initialLiquidity: The total portion of liquidity allocated to them.
  • lockTimestamp: The timestamp marking the start of their vesting schedule.

Linear Unlocking over 12 months means: [ \text{timeElapsed} = \max(0, \text{currentTime} - \text{lockTimestamp}) ] [ \text{totalUnlockable} = \left(\frac{\text{initialLiquidity} \times \text{timeElapsed}}{\text{lockDuration}}\right) ] [ \text{alreadyWithdrawn} = \text{initialLiquidity} - \text{remainingLiquidity} ] [ \text{currentlyUnlockable} = \text{totalUnlockable} - \text{alreadyWithdrawn} ]

This ensures the user can only withdraw a fraction of their allocated liquidity, proportional to how long they have waited.

Fee Calculations

  1. Fee Collection

    • The LiqLocker periodically calls collect on the PancakeSwap V3 position to gather accrued fees in token0 and token1.
    • These fees accumulate in the LiqLocker contract’s balances.

  2. Fee Distribution
    Each user’s fee share is determined by: [ \text{userFeeShare} = \left(\frac{\text{remainingLiquidity}}{\text{initialLiquidity}}\right) \times \text{feesSinceLastClaim} ]

    • feesSinceLastClaim is the difference in total fees collected by the contract between the user’s last claim checkpoint and the current state.

  3. Admin Fee Share

    • The admin has a designated “virtual user position” (e.g., 0x000...AD) representing the admin’s locked portion of liquidity.
    • When fees are collected, the admin’s share is computed similarly using the admin’s remainingLiquidity.

Rationale for 50/50 Split

At graduation, exactly 50% of the newly formed V3 liquidity is locked forever, while the other 50% is assigned to token holders (and admin) through vesting. This design aims to:

  • Prevent Rug Pulls: With half locked forever, no single entity can remove all liquidity from the market.
  • Reward Early Participants: By assigning the other half to users, the system incentivizes people who believed in the project from the start.
  • Enable Admin Rewards: A portion of that user half is further split with the admin, reflecting an ongoing stake in the project.

Security Considerations

  1. ReentrancyGuard

    • Functions like withdrawLiquidity and claimFees leverage reentrancy protection to prevent malicious nested calls.

  2. Authorized Caller Model

    • Only the legitimate graduated token contract and other verified addresses can call registerMigration.

  3. Pausable

    • The LiqLocker can be paused by the owner in emergencies, stopping any suspicious calls.

  4. Immutable Code

    • Critical logic around fee distribution, vesting math, and locked liquidity are unchangeable post-deployment. Contract upgrades are not possible, ensuring a stable environment.

Frequently Asked Questions

Q: What happens if a user never migrates?
A: If they never migrate, they do not receive a share of the new liquidity or fees. Their tokens remain in the old contract, which has effectively become obsolete after graduation.

Q: Can the admin forcibly remove user liquidity?
A: No. The LiqLocker’s code disallows any direct transfer of user-allocated liquidity aside from the user’s own actions (withdraw, claim fees) or the admin’s share (claimed via claimAdminFees).

Q: How often should users claim fees?
A: There is no fixed requirement. Users may claim fees as often as they like. If they wait a long time, the next claim will simply accumulate more fees.

By adhering to these clearly defined mathematical relationships and rules, LiqLocker maintains a transparent and secure environment for managing liquidity shares, ensuring every stakeholder has fair access to their vested portion.