Q128.128 fee growth

Global, outside, and position checkpoint fee growth use u256::U256 in Q128.128 form.

U256 { hi: u128, lo: u128 }
packed = hi * 2^128 + lo

Growth per unit of liquidity

growth_delta = floor(lp_fee * 2^128 / active_liquidity)

The input-token global accumulator increases by this value. The addition wraps modulo 2^256. A tick crossing replaces each token’s outside-growth checkpoint with global - outside, also modulo 2^256.

Growth inside a range

The contract derives growth below and above the position from global growth, each boundary’s outside growth, and the current tick. It subtracts both from global growth to get inside growth. Crossing an initialized tick flips its outside accumulator relative to current global growth. This makes the same boundary work in either crossing direction.

Owed amount

owed = floor((inside_now - inside_last) * liquidity / 2^128)

The subtraction wraps modulo 2^256. The wide product is shifted by 128 bits. The result must fit u128. The contract stores u256::U256 directly. It does not declare a separate FeeGrowth struct. Client code can use a semantic wrapper type, but its wire parser must match { hi, lo }.

Calculate from a state snapshot

Read the position, pool slot, and both boundary ticks from the same deployment at the same state height. Use an indexer or stored snapshot that preserves that height. Separate calls for the latest mapping values do not guarantee a consistent snapshot. Run the following calculation once per token. All inputs are required and have no defaults. Parse Leo integer literals into bigint in Typescript or int in Python first; each hi and lo must fit u128.

Input	Type and unit	Source for token N, where N is 0 or 1
`tick_current`	Signed integer tick	Slot `tick`
`tick_lower`, `tick_upper`	Signed integer ticks	Position range bounds
`liquidity`	`u128` liquidity units	Position `liquidity`
`owed`	`u128` native token base units	Position `tokens_owedN`
`global`	`{ hi, lo }`, Q128.128	Slot `fee_growth_globalN_x_128`
`lower_outside`	`{ hi, lo }`, Q128.128	Lower tick `fee_growth_outsideN_x_128`
`upper_outside`	`{ hi, lo }`, Q128.128	Upper tick `fee_growth_outsideN_x_128`
`inside_last`	`{ hi, lo }`, Q128.128	Position `fee_growth_insideN_last_x_128`

The SDKs derive this arithmetic for their position reads. The implementation below lets you inspect a saved snapshot without an SDK or network connection. Run your language’s blocks in order in an .mts file with Node.js 24 or later, or a .py file with Python 3.11 or later.

Typescript
Python

Step 1: Define the calculation

const Q128 = 1n << 128n
const U128_MAX = Q128 - 1n
const U256_MASK = (1n << 256n) - 1n
type U256 = { hi: bigint; lo: bigint }
type FeeSnapshot = {
  tick_current: number; tick_lower: number; tick_upper: number
  liquidity: bigint; owed: bigint
  global: U256; lower_outside: U256; upper_outside: U256; inside_last: U256
}

function pack(value: U256): bigint {
  if (value.hi < 0n || value.hi > U128_MAX || value.lo < 0n || value.lo > U128_MAX) {
    throw new RangeError("fee-growth limb exceeds u128")
  }
  return (value.hi << 128n) | value.lo
}

function calculateFees(s: FeeSnapshot) {
  if (s.liquidity < 0n || s.liquidity > U128_MAX || s.owed < 0n || s.owed > U128_MAX) {
    throw new RangeError("liquidity or owed balance exceeds u128")
  }
  if (s.liquidity === 0n) return { pending: 0n, collectible: s.owed }

  const sub = (a: bigint, b: bigint) => (a - b) & U256_MASK
  const global = pack(s.global)
  const lower = pack(s.lower_outside)
  const upper = pack(s.upper_outside)
  const below = s.tick_current >= s.tick_lower ? lower : sub(global, lower)
  const above = s.tick_current < s.tick_upper ? upper : sub(global, upper)
  const inside = sub(sub(global, below), above)
  const delta = sub(inside, pack(s.inside_last))
  const pending = delta * s.liquidity / Q128 // floor to native token base units
  const collectible = s.owed + pending
  if (pending > U128_MAX || collectible > U128_MAX) {
    throw new RangeError("fee entitlement exceeds u128")
  }
  return { pending, collectible }
}

Step 2: Calculate the snapshot’s balances

Continue with the definitions from step 1. This illustrative token0 snapshot has zero outside growth and a zero previous checkpoint.

const snapshot: FeeSnapshot = {
  tick_current: 0, tick_lower: -100, tick_upper: 100,
  liquidity: 15n, owed: 7n,
  global: { hi: 2n, lo: 0n }, // 2 * 2^128 in Q128.128
  lower_outside: { hi: 0n, lo: 0n },
  upper_outside: { hi: 0n, lo: 0n },
  inside_last: { hi: 0n, lo: 0n },
}
const result = calculateFees(snapshot)
console.log(`Newly accrued fees: ${result.pending} base units`)
console.log(`Total collectible: ${result.collectible} base units`)

Step 1: Define the calculation

Q128 = 1 << 128
U128_MAX = Q128 - 1
U256_MASK = (1 << 256) - 1

def pack(value: dict[str, int]) -> int:
    if not (0 <= value["hi"] <= U128_MAX and 0 <= value["lo"] <= U128_MAX):
        raise ValueError("fee-growth limb exceeds u128")
    return (value["hi"] << 128) | value["lo"]

def calculate_fees(s: dict) -> dict[str, int]:
    if not (0 <= s["liquidity"] <= U128_MAX and 0 <= s["owed"] <= U128_MAX):
        raise ValueError("liquidity or owed balance exceeds u128")
    if s["liquidity"] == 0:
        return {"pending": 0, "collectible": s["owed"]}

    def sub(a: int, b: int) -> int:
        return (a - b) & U256_MASK

    global_growth = pack(s["global"])
    lower = pack(s["lower_outside"])
    upper = pack(s["upper_outside"])
    below = lower if s["tick_current"] >= s["tick_lower"] else sub(global_growth, lower)
    above = upper if s["tick_current"] < s["tick_upper"] else sub(global_growth, upper)
    inside = sub(sub(global_growth, below), above)
    delta = sub(inside, pack(s["inside_last"]))
    pending = delta * s["liquidity"] // Q128  # floor to native token base units
    collectible = s["owed"] + pending
    if pending > U128_MAX or collectible > U128_MAX:
        raise ValueError("fee entitlement exceeds u128")
    return {"pending": pending, "collectible": collectible}

Step 2: Calculate the snapshot’s balances

Continue with the definitions from step 1. This illustrative token0 snapshot has zero outside growth and a zero previous checkpoint.

snapshot = {
    "tick_current": 0, "tick_lower": -100, "tick_upper": 100,
    "liquidity": 15, "owed": 7,
    "global": {"hi": 2, "lo": 0},  # 2 * 2^128 in Q128.128
    "lower_outside": {"hi": 0, "lo": 0},
    "upper_outside": {"hi": 0, "lo": 0},
    "inside_last": {"hi": 0, "lo": 0},
}
result = calculate_fees(snapshot)
print(f"Newly accrued fees: {result['pending']} base units")
print(f"Total collectible: {result['collectible']} base units")

Both print:

Newly accrued fees: 30 base units
Total collectible: 37 base units

For token1, supply token1’s global growth, outside growth, checkpoint, and owed balance. Keep the same range, current tick, and liquidity. Apply each token’s decimals only when formatting the returned base units.

Boundary and rounding checks

Case	Expected behavior
Current tick equals the lower bound	The range is active; use the lower tick’s stored outside growth for `below`.
Current tick equals the upper bound	The range is inactive; use `global - upper_outside` for `above`.
The packed accumulator wraps	Subtraction modulo `2^256` recovers the growth delta. Never use an absolute difference.
The product contains a fractional base unit	Integer division discards the fraction at settlement.
Position liquidity is zero	Pending fees are zero; the owed balance remains collectible. Removed boundary ticks are unnecessary. You may supply zero limbs for missing ticks in this case only.
Pending fees or the total exceed `u128`	Stop with an error, matching the contract’s settlement and balance-addition limits.

A range that is out of range now can still have fees earned earlier. The boundary calculation determines its cumulative entitlement; returning zero solely because the current tick is outside the range would lose those fees. An overflow check cannot establish that a snapshot is consistent. A mixed-height checkpoint can also produce an incorrect result that fits u128. See LP fee entitlements for the fee split, settlement events, and the distinction between newly accrued fees and total collectible funds.

Understand Shield Swap

Trading reference

Concepts

Data and confidentiality

Security and controls

Math and accounting

Program reference

Growth per unit of liquidity

Growth inside a range

Owed amount

Calculate from a state snapshot

Step 1: Define the calculation

Step 2: Calculate the snapshot’s balances

Step 1: Define the calculation

Step 2: Calculate the snapshot’s balances

Boundary and rounding checks

​Growth per unit of liquidity

​Growth inside a range

​Owed amount

​Calculate from a state snapshot

​Step 1: Define the calculation

​Step 2: Calculate the snapshot’s balances

​Step 1: Define the calculation

​Step 2: Calculate the snapshot’s balances

​Boundary and rounding checks

Growth per unit of liquidity

Growth inside a range

Owed amount

Calculate from a state snapshot

Step 1: Define the calculation

Step 2: Calculate the snapshot’s balances

Step 1: Define the calculation

Step 2: Calculate the snapshot’s balances

Boundary and rounding checks