LiqLocker Documentation

LiqLocker is the contract responsible for locking and vesting the liquidity created when an agent token graduates from its bonding phase. This ensures stable, long-term liquidity in the PancakeSwap V3 pool while rewarding token holders proportionally.

Liquidity Locking & Vesting Overview

  1. Graduated Phase Liquidity

    • When the token graduates, a PancakeSwap V3 position is formed between the graduated token and Renatus.
    • The protocol permanently locks 50% of this liquidity, collecting fees for Renatus.
    • The remaining 50% is apportioned to bonding-phase holders who migrate to the graduated token.

  2. Vesting

    • The user’s half of the liquidity is vested over 12 months.
    • Lock timestamps track when each user’s vesting begins.
    • Users can withdraw partially unlocked liquidity and claim trading fees anytime.

  3. Holder Incentives

    • Encourages a long-term mindset by distributing fees and unlocked liquidity gradually.
    • Early backers are proportionally rewarded, aligning them with the project’s continued growth.

Core Functionality

Position Management

  • Graduated Position Registration
    Once a token graduates, LiqLocker records a “graduated position.” This data structure includes total liquidity, token ID for the V3 NFT, and initial reserves.

  • User Migration
    Each user’s migrated amount determines how much liquidity they are allocated. The system divides the user’s share 50/50 between the user and the admin address (i.e., ADMIN_ADDRESS is used internally to track the admin’s portion).

Vesting Schedule

  • Linear Unlocking
    Over 12 months, user liquidity gradually becomes withdrawable. The formula is:

    unlockableAmount = \left( \frac{initialLiquidity \times timeElapsed}{lockDuration} \right) - alreadyWithdrawn

  • Ongoing Fee Distribution
    Even if the user’s liquidity remains locked, they receive a proportional share of any fees generated by the V3 pool. They can claim these fees whenever they like, as long as remainingLiquidity > 0.

Contract Functions

function withdrawLiquidity(address token, uint128 liquidityAmount) external;
function claimFees(address token) external;
function claimAdminFees(address token) external;
function registerGraduatedPosition(...);
function registerMigration(address user, uint256 userTokenAmount);

Function Details

  • withdrawLiquidity(address token, uint128 liquidityAmount)
    Allows users to withdraw any currently unlocked liquidity from the V3 position. Subtracts from their remainingLiquidity.

  • claimFees(address token)
    Users claim their share of accumulated pool fees, calculated by the ratio of remainingLiquidity / initialLiquidity. Updates user checkpoints (e.g., lastClaimFeeTotal0) to avoid double-counting on future claims.

  • claimAdminFees(address token)
    Special function callable only by the adminFeeCollector address. Distributes the admin’s share of fees from the half locked for the admin’s liquidity portion.

  • registerGraduatedPosition(...)
    Registers the graduated position with the total liquidity and other metadata.

  • registerMigration(address user, uint256 userTokenAmount)
    Called by the graduated token contract to assign a user’s portion of liquidity. Splits allocated liquidity between the user and admin.

Admin & Access Controls

  • Owner (Platform Admin):
    Can pause the contract, set the adminFeeCollector, or configure authorized callers.

  • Admin Fee Collector:
    Entitled to collect the portion of fees allocated to the admin.

  • Authorized Callers:
    Typically includes the token’s contract for registering migrations and the bonding/graduation flow.

Best Practices

  • Regular Fee Claims
    Users can claim their share of capture pooled trading fees.

  • Time Your Liquidity Withdrawals
    Because liquidity unlocks linearly, users might prefer to wait longer for a larger single withdrawal.

By combining LiqLocker with the bonding curve’s structured approach, the Renatus Protocol offers a balanced distribution of liquidity ownership, reduces the likelihood of immediate dumps, and aligns all participants’ incentives around the project’s long-term vision.