Skip to main content
Collect and burn perform different jobs.
  • collect transfers requested owed amounts into token records and advances fee checkpoints.
  • burn consumes an empty ownership record and removes the public position row.
Neither operation removes active liquidity. Liquidity must be reduced first.

​
Outcome

Collection is complete when the transaction is accepted, requested owed amounts are transferred into token records, the replacement PositionNFT is stored, and the wallet has discovered both payout records. Burning is complete only after liquidity and owed amounts are zero and the public position row is removed.

​
Before you start

Read the public position and current inside fee growth, verify the position is not frozen, reserve the current PositionNFT, choose base-unit collection amounts within the settled and pending entitlement, and obtain non-inclusion proofs for the NFT owner and immutable withdrawal address.

​
What can be collected

A position can have value from:
  • Pending LP fees not yet reflected in tokens_owed
  • Previously settled LP fees
  • Principal credited by decrease or freeze
The public tokens_owed0 and tokens_owed1 fields include only amounts already settled. A collect transaction also calculates pending fees from current inside growth before checking the requested amounts.

​
Collect inputs and outputs

collect accepts:
  • Current PositionNFT record
  • Public base-unit token0 amount requested
  • Public base-unit token1 amount requested
  • Public token0 and token1 program IDs
  • Two owner and two withdrawal MerkleProof values
It returns:
  • Replacement PositionNFT record
  • Token0 payout record
  • Token1 payout record
The token IDs must match the pool. Payout always goes to the immutable withdrawal address in the NFT. That address cannot be the AMM, router, or zero address. Collection amounts and position accounting are public. The withdrawal address and payout token records are confidential under Aleo’s record model, but the investigator-owned mint record contains the withdrawal address. Read Public data for the broader observability boundary.

​
Amount validation

Collection requests use native token base units. The contract checks each request directly against total owed after pending fee settlement.

​
Pending-fee settlement

For each token:
The contract stores current inside growth as the new checkpoint even if part of total_owed remains uncollected. The uncollected integer amount is preserved in tokens_owed. The fractional remainder below one native base unit is discarded when the checkpoint advances. Collect changes fee checkpoints and owed balances. Read Fee entitlements and Q128.128 fee growth.

​
Choosing requested amounts

A caller may request less than the available amount. This is useful when:
  • Keeping part of the balance in the AMM’s owed accounting
  • Matching a custody or treasury instruction
  • Avoiding an overestimate caused by stale off-chain state
  • Collecting one token without collecting the other
To request the full amount, calculate pending fees from a consistent slot, tick, and position snapshot. The integer result is already in native base units. A swap accepted before collect can only increase eligible growth for an active position, but tick movement can change the inside-growth derivation. Use modular arithmetic and current boundaries. A conservative request below the calculated total can succeed while leaving the remainder owed. An overestimate is rejected.

​
Settlement dust

Each step’s LP fee is recorded with 128 fractional bits and no cross-epoch residual. This prevents a later LP set from receiving an earlier set’s fractional fee. Two floors still matter:
  1. Step growth is floor(lp_fee * 2^128 / active_liquidity).
  2. Position settlement is floor(delta_growth * position_liquidity / 2^128).
The first leaves less than one native token base unit unallocated across the active set for that step. The second leaves less than one base unit for the position at settlement. Because collect advances the checkpoint, repeated small collections can leave more settlement dust than a less frequent schedule. The contract has no generic sweep for this surplus. Protocol collection is limited to recorded protocol_fees0 and protocol_fees1. See Rounding, overflow, and invariants.

​
Collect under controls

Collect does not apply the pool entry-pause hierarchy. Disabling a pool or pausing trading does not by itself trap an LP’s settled value. A position freeze is different. Frozen positions cannot collect. If a live position is frozen, the freeze path first removes its liquidity and settles principal and fees into tokens_owed. Unfreeze makes that value collectable but does not restore liquidity.

​
Burn prerequisites

burn succeeds only when:
Burn consumes the PositionNFT and removes the public positions[token_id] entry. It returns no replacement ownership record. The transition does not inspect pending fee growth. With zero position liquidity, later fee growth creates no additional position entitlement. Any fees earned before liquidity reached zero were settled by the decrease or freeze operation that removed the liquidity.

​
Complete closeout

Use this sequence:
  1. Decrease all remaining liquidity.
  2. Wait for acceptance and save the replacement PositionNFT.
  3. Read public tokens_owed balances.
  4. Include any pending fee estimate if liquidity was not actually zero.
  5. Collect token0 and token1 in native base units.
  6. Save the replacement ownership record from collect.
  7. Verify liquidity and both owed balances are zero.
  8. Burn using the latest record.
  9. Mark the token ID closed in the custody and accounting systems.
Do not submit burn with the pre-collect record. It has been spent.

​
Closeout records

An institutional closeout record should retain:
  • Deployment ID and program checksum
  • Position token ID and pool key
  • Decrease transaction and credited principal
  • Fee calculation inputs and rounding policy
  • Public requested collection amounts
  • Payout record custody references
  • Final zero position state
  • Burn transaction removing the mapping row
The chain demonstrates the state transitions. Legal ownership, valuation policy, and accounting classification remain operator responsibilities.