LP fee entitlements

Your position earns a share of the fees charged on swaps while its liquidity is active.

What determines your fee income

Shield uses Uniswap v3’s model for sharing fees among active liquidity. Your earnings depend on the fees charged during each part of a swap and your share of the liquidity active at that point. Unlike Uniswap v3’s fixed pool fee, a Shield pool’s current trading fee can change while your position stays in the same pool. An authorized fee reduction can also lower the fee on an individual swap. The protocol takes its share from the fee actually charged, and the rest goes to active liquidity. If the fee is reduced to zero, neither the protocol nor liquidity providers earn fees from that swap. Check the pool’s current trading fee and protocol share when estimating earnings. Multiplying volume by the displayed fee alone can overstate what liquidity providers receive. Earned fees stay collectible until you withdraw them; they do not automatically increase your liquidity.

Read what your position can collect

Prerequisites: Your authenticated mainnet client for Typescript or dex for Python from Setup. Replace POSITION_TOKEN_ID with the position ID returned by mint or listed by shield-swap positions. Run the steps in your language in order. These calls read your position; they do not submit a transaction.

Typescript
Python

Step 1: Find the position

const positions = await client.getOwnedPositions()
const position = positions.find(
  (p) => p.positionTokenId === POSITION_TOKEN_ID,
)
if (!position?.state) {
  throw new Error("position state unavailable; refresh")
}
const state = position.state

Step 2: Read the balances

All amounts are integer native token base units. The SDK’s uncollectedFees0/1 already include the owed balances.

const balances = [
  { tokenId: position.token0Id, owed: state.tokensOwed0, total: state.uncollectedFees0 },
  { tokenId: position.token1Id, owed: state.tokensOwed1, total: state.uncollectedFees1 },
].map((balance) => ({ ...balance, pending: balance.total - balance.owed }))

Step 3: Format the amounts

Continue with balances from step 2. Read each token’s decimals from its metadata.

import { formatUnits } from "@provablehq/shield-swap-sdk"

for (const balance of balances) {
  const token = await client.tokenData(balance.tokenId)
  console.log(`${token.symbol}:`)
  console.log(`  Already owed: ${formatUnits(balance.owed, token.decimals)}`)
  console.log(`  Newly accrued fees: ${formatUnits(balance.pending, token.decimals)}`)
  console.log(`  Total collectible: ${formatUnits(balance.total, token.decimals)}`)
}

Step 1: Find the position

position = dex.get_owned_position(POSITION_TOKEN_ID)
if position is None or position.state is None:
    raise RuntimeError("position state unavailable; refresh")
state = position.state

Step 2: Read the balances

All amounts are integer native token base units. The SDK’s collectible0/1 already include the owed balances.

balances = [
    (position.token0_id, state.tokens_owed0, state.collectible0),
    (position.token1_id, state.tokens_owed1, state.collectible1),
]
balances = [(token_id, owed, total - owed, total) for token_id, owed, total in balances]

Step 3: Format the amounts

Continue with balances from step 2. Integer division and string formatting preserve every base unit, including for tokens with 18 decimals.

def format_units(amount: int, decimals: int) -> str:
    if decimals == 0:
        return str(amount)
    whole, fraction = divmod(amount, 10 ** decimals)
    return f"{whole}.{fraction:0{decimals}d}"

tokens = {token.address: token for token in dex.api.get_tokens()}
for token_id, owed, pending, total in balances:
    token = tokens[token_id]
    print(f"{token.symbol}:")
    print(f"  Already owed: {format_units(owed, token.decimals)}")
    print(f"  Newly accrued fees: {format_units(pending, token.decimals)}")
    print(f"  Total collectible: {format_units(total, token.decimals)}")

For a token with 6 decimals, 7 base units already owed, and 30 newly accrued, the output is:

TOK0:
  Already owed: 0.000007
  Newly accrued fees: 0.000030
  Total collectible: 0.000037

The Typescript formatter may omit trailing zeros. Your output uses the pool’s token symbols and balances. Owed balances can include settled fees, withdrawn principal, and unused deposits. The difference between total collectible and already owed is only the fees accrued since the last checkpoint. Do not report the full collectible balance as fee income. Lifetime fee income requires transaction history. Treat these live reads as estimates: the SDK can read mappings at different heights while swaps continue. For reconciliation, use a consistent state snapshot. Refresh before collecting. In the Python SDK, missing boundary ticks after a full decrease can leave position.state unavailable. That does not mean the position has no funds. Use the zero-liquidity fallback to read its settled balances.

How fees accrue on chain

The contract records your entitlement through cumulative fee growth. Only the liquidity active during a swap step shares that step’s LP fee. The accounting path is:

step fee
  -> protocol share and LP share
  -> global growth for the input token
  -> tick outside-growth checkpoints
  -> growth inside a position's range
  -> position settlement
  -> tokens owed
  -> collect

Fee-bearing token

Fees accrue in the input token:

zero_for_one = true advances token0 fee growth.
zero_for_one = false advances token1 fee growth.

The output token’s global accumulator does not advance merely because the pool paid output in that token. For multi-hop swaps, the rule applies separately to every hop. A route can therefore generate fees in different token programs at different pools during one transaction. The swap uses the current pool fee after any authorized fee reduction, expressed in fee pips, or parts per million. A step first calculates its integer total fee under the swap math. The configured protocol fraction then splits it:

protocol_fee = floor(total_fee * fee_protocol / 16)
lp_fee = total_fee - protocol_fee

fee_protocol may be zero or 4 through 10. The floor remainder belongs to lp_fee. Protocol fees accumulate in separate slot balances. They do not appear in LP fee growth and cannot be claimed by positions.

Global growth

Each swap step divides its LP fee among the liquidity active in that step. The contract records the result as cumulative Q128.128 fee growth for the input token. The 256-bit accumulator wraps by design. A decrease in its raw value does not mean fees were removed. See Q128.128 fee growth for storage, arithmetic, and runnable calculations.

Liquidity epochs

A liquidity epoch is a period during which one active-liquidity set earns fee growth. Epoch boundaries include:

Minting active liquidity
Increasing or decreasing active liquidity
Crossing an initialized tick
Reinitializing a removed boundary

The implementation stores no pool-level residual from fee-growth division. Each step records the floor at 128-bit fractional precision using the liquidity active in that step. The sub-Q128 remainder is discarded, so it cannot cross into a later epoch and be credited to a different active-liquidity set. This rounding can leave surplus in the contract.

Tick outside growth

Each initialized tick stores outside growth for token0 and token1. At a crossing, each checkpoint becomes the token’s global growth minus its previous outside growth, with 256-bit wrapping subtraction. Both tokens flip, even though only the input token generated a fee in the current step. Crossing reverses which side of the tick is considered outside, so both reference frames must change. The current step’s fee is added before the flip. Its LP fee therefore belongs to the pre-crossing active-liquidity set. A crossing also completes when the tick price equals the user’s price limit. The slot finishes with post-crossing liquidity even if the swap stops at that exact price.

Growth inside a range

The contract subtracts growth below and above your range from global growth. The current tick determines which side of each boundary counts as outside. At the lower tick, the range is active. At the upper tick, it is not. The snapshot calculation applies those boundary conditions for each token.

Position checkpoint

A public Position stores its liquidity, an inside-growth checkpoint for each token, and settled tokens_owed0/1 balances. Newly accrued fees come from the growth since those checkpoints, multiplied by position liquidity and rounded down to whole native base units. Pending fees are not continuously written to tokens_owed. They become settled integer amounts during increase, rebalance, decrease, or collect.

Settlement events

Operation	Liquidity used for pending fees	State after settlement
Mint	None	New position snapshots current inside growth
Increase	Old position liquidity	Checkpoint advances, then liquidity increases
Rebalance	Full old position liquidity	Old fees settle, then the replacement starts with a new checkpoint
Decrease	Full pre-decrease liquidity	Checkpoint advances, then liquidity decreases
Collect	Current liquidity	Checkpoint advances, requested amount leaves

This ordering prevents new liquidity from sharing old growth and prevents removed liquidity from losing growth already earned. Burn performs no fee settlement. It removes a position only after liquidity and both owed balances are zero.

Calculate the worked example

Run the Typescript block in an .mts file with Node.js 24 or later, or the Python block in a .py file with Python 3.11 or later. No SDK, account, or network connection is required. The inputs are illustrative: one swap step charges 160 native token0 base units, the protocol takes 4/16, and your position supplies 15 of the 60 active liquidity units throughout that step. It already has 7 base units owed.

Typescript
Python

const Q128 = 1n << 128n
const totalFee = 160n // native token0 base units
const feeProtocol = 4n // numerator of a fraction with denominator 16
const activeLiquidity = 60n
const positionLiquidity = 15n
const previouslyOwed = 7n // native token0 base units

const protocolFee = totalFee * feeProtocol / 16n // floor the split
const lpFee = totalFee - protocolFee
const growthDelta = lpFee * Q128 / activeLiquidity // floor per step
const pendingFee = growthDelta * positionLiquidity / Q128 // floor at settlement
const collectible = previouslyOwed + pendingFee

console.log(`Protocol share: ${protocolFee} base units`)
console.log(`LP share: ${lpFee} base units`)
console.log(`This position earns: ${pendingFee} base units`)
console.log(`Previously owed: ${previouslyOwed} base units`)
console.log(`Total collectible: ${collectible} base units`)

Q128 = 1 << 128
total_fee = 160  # native token0 base units
fee_protocol = 4  # numerator of a fraction with denominator 16
active_liquidity = 60
position_liquidity = 15
previously_owed = 7  # native token0 base units

protocol_fee = total_fee * fee_protocol // 16  # floor the split
lp_fee = total_fee - protocol_fee
growth_delta = lp_fee * Q128 // active_liquidity  # floor per step
pending_fee = growth_delta * position_liquidity // Q128  # floor at settlement
collectible = previously_owed + pending_fee

print(f"Protocol share: {protocol_fee} base units")
print(f"LP share: {lp_fee} base units")
print(f"This position earns: {pending_fee} base units")
print(f"Previously owed: {previously_owed} base units")
print(f"Total collectible: {collectible} base units")

Both print:

Protocol share: 40 base units
LP share: 120 base units
This position earns: 30 base units
Previously owed: 7 base units
Total collectible: 37 base units

This position earns one quarter of the LP fee in this step. For a live position, use growth inside its range since its last checkpoint, as shown in Calculate from a state snapshot.

Rounding and dust

Global growth floors once per fee-bearing step. The aggregate shortfall is less than one native token base unit because active liquidity is a u128 and the fee-growth scale is 2^128. Position settlement floors again. Its shortfall is less than one native base unit for that position and token at that settlement. Advancing the checkpoint discards that position fraction. It is not stored in a residual field and is not reassigned to another LP. The contract has no generic sweep for the resulting surplus. collect_protocol can withdraw only recorded protocol fees. Institutional reconciliation should use:

gross fees
= recorded protocol fees
+ claimable or collected LP fees
+ rounding surplus retained by the contract

Read Rounding, overflow, and invariants.

Public observability

Global growth, tick outside growth, position checkpoints, position liquidity, and settled owed amounts are public mapping state. Collection requests are also public. The PositionNFT record authorizes the holder without storing the owner’s address in Position. The position’s range and fee economics remain public. An observer with a token ID and a consistent state snapshot can estimate pending fees. The estimate does not identify the private immutable withdrawal address.

Off-chain calculation rules

Read the slot, both boundary ticks, and the position from one deployment at one state height. Keep all arithmetic in integers and apply token decimals only for display. The Q128.128 examples decode both limbs, apply wrapping subtraction and range boundaries, and check the resulting balances against u128 limits.

Start

Trade

Provide liquidity

Integration guides

What determines your fee income

Read what your position can collect

Step 1: Find the position

Step 2: Read the balances

Step 3: Format the amounts

Step 1: Find the position

Step 2: Read the balances

Step 3: Format the amounts

How fees accrue on chain

Fee-bearing token

Global growth

Liquidity epochs

Tick outside growth

Growth inside a range

Position checkpoint

Settlement events

Calculate the worked example

Rounding and dust

Public observability

Off-chain calculation rules

​What determines your fee income

​Read what your position can collect

​Step 1: Find the position

​Step 2: Read the balances

​Step 3: Format the amounts

​Step 1: Find the position

​Step 2: Read the balances

​Step 3: Format the amounts

​How fees accrue on chain

​Fee-bearing token

​Trading fee and protocol share

​Global growth

​Liquidity epochs

​Tick outside growth

​Growth inside a range

​Position checkpoint

​Settlement events

​Calculate the worked example

​Rounding and dust

​Public observability

​Off-chain calculation rules

What determines your fee income

Read what your position can collect

Step 1: Find the position

Step 2: Read the balances

Step 3: Format the amounts

Step 1: Find the position

Step 2: Read the balances

Step 3: Format the amounts

How fees accrue on chain

Fee-bearing token

Trading fee and protocol share

Global growth

Liquidity epochs

Tick outside growth

Growth inside a range

Position checkpoint

Settlement events

Calculate the worked example

Rounding and dust

Public observability

Off-chain calculation rules