> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meteora.ag/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidity Locking

> Lock DAMM v2 LP liquidity with cliff + linear vesting schedules or permanently. Two mechanisms: inner vesting (stored in position) and external vesting accounts.

## Overview

DAMM v2 supports two types of liquidity locks, both of which move liquidity from `unlocked_liquidity` into restricted buckets on the position account:

| Type           | Bucket                       | Withdrawable?    |
| -------------- | ---------------------------- | ---------------- |
| Vesting lock   | `vested_liquidity`           | Yes, on schedule |
| Permanent lock | `permanent_locked_liquidity` | Never            |

Both types still earn trading fees and farming rewards at the normal rate — only withdrawal is restricted.

***

## Vesting Lock

Vesting releases liquidity back to `unlocked_liquidity` on a **cliff + periodic** schedule.

### Schedule Parameters

| Parameter                | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `cliff_point`            | Slot or timestamp when first unlock occurs     |
| `period_frequency`       | Slots or seconds between each periodic release |
| `cliff_unlock_liquidity` | How much liquidity unlocks at the cliff        |
| `liquidity_per_period`   | How much unlocks per period after the cliff    |
| `number_of_period`       | Total number of periods                        |

### Total locked amount

```
total_locked = cliff_unlock_liquidity + (liquidity_per_period × number_of_period)
```

### Two vesting account types

<Tabs>
  <Tab title="Inner Vesting">
    Vesting schedule stored directly in the position account. No extra account needed.

    ```
    Position
      └── inner_vesting (InnerVesting)
            ├── cliff_point
            ├── period_frequency
            ├── cliff_unlock_liquidity
            ├── liquidity_per_period
            ├── number_of_period
            └── total_released_liquidity (tracks how much has unlocked so far)
    ```

    **When to use:** Most use cases — simpler, single-account.

    **Limitation:** Only one vesting schedule per position. If you need multiple vesting tranches, split the position first.
  </Tab>

  <Tab title="External Vesting Account">
    A separate `Vesting` account (PDA) holds the schedule. The position just references it.

    **When to use:** When you need multiple external vesting schedules on a position, or when the vesting schedule needs to be managed by a different authority.

    <Note>
      Positions with external vesting accounts cannot use `splitPosition` — you must use `validate_no_external_vesting()` first (`UnsupportPositionHasVestingLock` error if you try).
    </Note>
  </Tab>
</Tabs>

### Refreshing vested liquidity

Vested liquidity doesn't auto-unlock. A transaction that calls any position interaction (add/remove liquidity, claim fees, etc.) triggers `refresh_inner_vesting`, which:

1. Calculates `released_liquidity` based on current slot/timestamp vs cliff/period schedule
2. Moves that amount from `vested_liquidity` → `unlocked_liquidity`
3. Clears the inner vesting struct when fully released

**Event emitted on lock:** `EvtLockPosition`

***

## Permanent Lock

Permanently locked liquidity cannot be withdrawn under any circumstances. It remains in the pool forever, providing a **liquidity floor guarantee**.

This is used by token projects to demonstrate long-term commitment to liquidity:

```typescript theme={"system"}
const tx = await cpAmm.permanentLockPosition({
  owner: wallet.publicKey,
  position: positionAddress,
  pool: poolAddress,
  liquidityDelta: amountToLockPermanently,
});
```

**Event emitted:** `EvtPermanentLockPosition` with:

* `lock_liquidity_amount` — amount just locked
* `total_permanent_locked_liquidity` — new total permanently locked on this position

***

## Locked Liquidity Still Earns

Both vesting and permanently locked liquidity contribute to fee and reward calculations:

```rust theme={"system"}
pub fn get_total_liquidity(&self) -> Result<u128> {
    Ok(self.unlocked_liquidity
        .safe_add(self.vested_liquidity)?
        .safe_add(self.permanent_locked_liquidity)?)
}
```

This total is used for:

* Fee accrual (`fee_a_pending`, `fee_b_pending` checkpoints use total liquidity)
* Farming reward accrual (both reward slots)

***

## Use Cases

<AccordionGroup>
  <Accordion title="Token Launch — Founder LP Lock">
    Lock founder LP for 12 months with a 6-month cliff and monthly releases:

    * `cliff_point` = launch\_timestamp + 6 months
    * `cliff_unlock_liquidity` = 25% of total
    * `liquidity_per_period` = 12.5% of total
    * `number_of_period` = 6 (monthly, for 6 months post-cliff)
  </Accordion>

  <Accordion title="Protocol-Owned Liquidity — Permanent">
    A DAO or protocol wanting to guarantee permanent liquidity depth can lock a portion permanently. The locked liquidity shows on-chain and is verifiable by anyone.
  </Accordion>

  <Accordion title="Airdrop / Ecosystem LP">
    Lock ecosystem-provided liquidity with a vesting schedule that aligns with token emission schedules, ensuring liquidity grows alongside token distribution.
  </Accordion>
</AccordionGroup>