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

# Increasing liquidity

> How a position adds capital without inheriting or diluting an earlier fee epoch.

`increase_liquidity` adds capital to an existing range. It does not create a second position. The operation consumes the current `PositionNFT` record, transfers additional token value into the AMM, updates the public position, and returns a replacement `PositionNFT` record.

The contract settles fees earned by the old liquidity amount before adding new liquidity. That ordering keeps fee ownership aligned with the liquidity that was active when each fee was earned.

## Outcome

The increase is complete when the transaction is accepted, the public position reflects the added liquidity, the old ownership record is spent, the replacement `PositionNFT` is stored, and both token change records are accounted for.

## Before you start

Read the current public position and fee growth, verify entry controls, reserve the current `PositionNFT`, select token0 and token1 funding records, and quote desired and minimum raw amounts for the position's existing range.

## Inputs and outputs

The transition accepts:

* Current `PositionNFT` record
* Token0 and token1 records
* Public desired token amounts
* Public minimum token amounts
* Public token0 and token1 program IDs
* Public lower and upper insertion hints

The tick range is taken from the ownership record. An increase cannot change the range. Repositioning requires withdrawing from the old range and minting a new position.

A successful transaction returns:

* Public token ID
* Replacement `PositionNFT` record
* Token0 and token1 change records

The operation does not pay pending LP fees to the holder. Settled fees and any `desired - used` funding excess remain in public `tokens_owed` accounting until `collect`. Returned change records contain only input-record value above the desired transfer amounts.

## Preconditions

The public position must match the pool and ticks carried by the ownership record. The position must not be frozen.

Entry controls apply:

* Global pause must be off.
* The pool must be enabled.
* Neither pool token may be paused.
* The token pair may not be paused.

Token IDs must match canonical pool token0 and token1.

The contract derives a positive liquidity amount from current Q128.128 square-root price, fixed range, and native base-unit desired amounts. It rejects an increase that produces zero liquidity or pushes either boundary above `max_liquidity_per_tick`.

## Amount calculation

The increase follows the same inventory rules as mint:

* Below the range, token0 supports the added liquidity.
* In range, both tokens may be required.
* Above the range, token1 supports the added liquidity.

Desired and minimum amounts are native base units. The token calls transfer the full desired amounts into AMM custody. The AMM calculates liquidity and actual used amounts directly in those units, then adds each `desired - used` excess to `tokens_owed`. Dynamic token transfers return change records only for input-record value above the desired amounts.

## Settlement before addition

Before the position's liquidity is increased, the contract derives fee growth inside the range and settles:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
accrued_fee =
    floor(
        wrapping_sub(inside_now, inside_last)
        * old_position_liquidity
        / 2^128
    )
```

It then:

1. Adds the integer accrued fee to `tokens_owed`.
2. Advances the position's inside-growth checkpoint.
3. Adds the new liquidity to the position.
4. Adds each `desired - used` funding excess to `tokens_owed`.
5. Adds that liquidity to the slot if the range is active.

This creates two distinct liquidity epochs:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
before increase: old liquidity earns growth through the checkpoint
after increase:  old plus new liquidity earns later growth
```

The new liquidity does not share in growth that occurred before the increase. The old liquidity does not lose fees because the checkpoint is advanced only after its entitlement is calculated.

Read [Fee entitlements](./fee-entitlements) for the global, outside, and inside calculation.

## Existing and removed boundaries

If both range boundaries are still initialized, the contract increases their gross liquidity and updates signed net liquidity without changing their fee-growth-outside checkpoints.

A position can have zero liquidity while its old boundary entries have been removed from the tick mapping. Increasing such a position reinitializes missing boundaries:

* A new tick at or below the current tick starts with outside growth equal to current global growth.
* A new tick above the current tick starts with zero outside growth.

The caller must supply current predecessor hints for each missing boundary. The contract verifies the linked-list interval before insertion.

This reinitialization starts a new tick epoch. Stale outside growth from the former boundary is not reused.

## Active-liquidity update

If:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
tick_lower <= slot.tick < tick_upper
```

the slot's active liquidity increases by the calculated amount. Otherwise, slot liquidity is unchanged. The boundary changes are enough for the liquidity to become active when price later enters the range.

The nearest initialized-tick pointers may tighten if a reinitialized boundary lies closer to the current tick.

## Rounding effects

An increase has three separate rounding surfaces:

1. Liquidity and required token amounts are integer calculations.
2. Pending fees settle down to whole native base units.
3. Any fractional fee below one base unit is not carried after the checkpoint advances.

Increasing frequently can therefore discard more settlement dust than adding capital less often. This does not transfer the fraction to another position. It leaves an accounting surplus in the contract.

Use token metadata decimals to express one base unit in display terms when deciding whether rounding is operationally material.

Read [Rounding, overflow, and invariants](../math/rounding-overflow-and-invariants).

## Record and custody handling

The input `PositionNFT` and token records are spent by an accepted transaction. Persist the replacement `PositionNFT` record and both change records before marking prior records unavailable in an external custody ledger.

If the transaction is rejected, the submitted records are not replaced by successful outputs. Refresh record spent status rather than assuming a replacement exists.

For routed or institutional execution, associate the accepted transaction with:

* Program ID and checksum
* Position token ID
* Old and new public liquidity
* Raw desired and internal used amounts
* New `tokens_owed` balances
* Input and replacement record identifiers

## Common rejection causes

* Position is frozen.
* Pool or an entry control is paused.
* Token IDs do not match the pool.
* Current price and amounts calculate zero liquidity.
* A boundary exceeds the per-tick liquidity cap.
* A removed boundary is supplied with a stale or invalid hint.
* Minimum amount exceeds actual raw amount used.
* Input ownership or token records are spent or insufficient.

After increasing, monitor [Fee entitlements](./fee-entitlements) and use [Collecting and burning](./collecting-and-burning) when value should leave the AMM.