Rebalancing and fill tracking

This page helps you move a position to a new price range, and, with the SDKs, track the trades that pass through a position’s range.

How a rebalance works

A rebalance replaces your position with a new one in the same pool in one transaction. It reuses the old position’s funds, including earned fees, and you can add funds from your wallet. The new position keeps the owner and withdrawal address and has a new ID. A rebalance does not swap one asset for the other. If the new range needs a different mix, you can add the asset it needs; anything the new position does not use returns to the withdrawal address. Check those amounts in the review before confirming. The reviewed amounts must still match when the transaction executes; there is no slippage setting. If pool activity makes the preview out of date, the rebalance can be rejected. Your old position stays unchanged, though a rejected transaction can still cost a network fee. Refresh the review before trying again.

In the app

Before you startYou’ll need: Shield Wallet connected to Shield Swap, and an open position with liquidity in it.

Move a position to a new range

Open Pools, then select the pool. Under Your Positions, select Manage in the position’s row, then Rebalance. The panel on the right switches to Rebalance with Position loaded showing the position’s ID and its current range.
Select Custom. Choose a preset, drag the handles on the chart, or enter prices in Min and Max. See Choosing a liquidity range for what each preset does.
Check the two amounts. Each shows how much comes from the current position. Raise an amount to add funds from your wallet at the same time.
Select Review Rebalance.
In Review Rebalance, check the New position amounts, the Price range line showing the old and new ranges, and Returns to your wallet, the amount that does not fit the new range. Open Details to see the position funds recovered and the new position’s amounts side by side.
Select Confirm.
In the Transaction request in Shield Wallet, check that the request is from swap.shield.fi, then select Confirm.

The app tracks the transaction, which can take a few minutes. When it finishes, the old position’s row leaves Your Positions and the new one appears with its new ID and range, and Recent Activity lists the rebalance.

Troubleshooting

What you see	Why it happens	What to do
Nothing to rebalance, with Current Range selected	The range has not changed and no funds were added, so there is nothing for a rebalance to do.	Select Custom and choose a new range, or select Go to Increase to add funds at the current range.
Min and Max show very small and very large numbers after you select Custom	The chart opened at the full-range bounds of the current position.	Select a preset or drag the handles. The fields update to the prices you choose.
The rebalance was rejected	The plan may be out of date. Your position is unchanged.	Check the rejection details. If the amounts changed, select Review Rebalance again and confirm the updated amounts.

See the trades your position filled

The app does not show per-trade fills for a position. Recent Activity on the pool page lists your position actions, and Your Trades on the Trade page lists your own swaps. Fee earnings appear as Position Funds on the position’s row. Per-trade fill tracking is available through the TypeScript SDK; see the Developers view of this page.

Next steps

Choosing a liquidity range for what each preset does.
Increasing liquidity to add funds without changing the range.

Plan and submit a rebalance

Prerequisites: Your authenticated mainnet client for TypeScript or dex for Python from Setup, and an existing position with liquidity. The CLI has no rebalance command.Build the plan immediately before submission and submit it unchanged. The contract checks the amounts at execution, so pool activity can invalidate a plan. These examples recenter the range on the current tick, one spacing below and two above, funded only from what the old position returns.Replace POSITION_TOKEN_ID with the ID of the position you intend to change. Define the confirmation helper for your SDK before running these examples.

TypeScript
Python
CLI

Step 1: Read the position and the pool

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

const positions = await client.getOwnedPositions()
const position = positions.find((p) => p.positionTokenId === POSITION_TOKEN_ID)
if (!position?.state) throw new Error("position not ready or not owned by this account")

const [token0, token1, onchain, slot] = await Promise.all([
  client.tokenData(position.token0Id),
  client.tokenData(position.token1Id),
  client.getPosition({ positionTokenId: position.positionTokenId }),
  client.getSlot({ poolKey: position.poolKey }),
])
if (!onchain || onchain.liquidity === 0n) throw new Error("position holds no liquidity")
if (!slot) throw new Error("pool slot missing")

const spacing = Number(slot.tick_spacing)
const active = Math.floor(slot.tick / spacing) * spacing
const tickLower = active - spacing
const tickUpper = active + 2 * spacing

Step 2: Plan

maxFunding0: 0n, maxFunding1: 0n means reuse only what the old position returns. The planner recovers the principal at the current price plus all fees, including those not yet checkpointed, and sizes the new position from that alone. Nothing is spent.

const plan = await client.planRebalance({
  poolKey: position.poolKey,
  positionTokenId: position.positionTokenId,
  tickLower,
  tickUpper,
  maxFunding0: 0n,
  maxFunding1: 0n,
})

console.log(`recovering ${formatUnits(plan.recovered0, token0.decimals)} ${token0.symbol}`)
console.log(`           ${formatUnits(plan.recovered1, token1.decimals)} ${token1.symbol}`)
console.log(`refunding  ${formatUnits(plan.refund0, token0.decimals)} ${token0.symbol}`)
console.log(`           ${formatUnits(plan.refund1, token1.decimals)} ${token1.symbol}`)
console.log(`new range  [${plan.tickLower}, ${plan.tickUpper}) at liquidity ${plan.liquidityTarget}`)

Pass positive maxFunding0 and maxFunding1 budgets to add funds from your records, or liquidityTarget for an exact size.

Step 3: Submit the plan

const imports = await client.resolveDexImports({
  tokenPrograms: [token0.ammTokenProgram!, token1.ammTokenProgram!],
})

const result = await client.rebalancePosition({
  ...plan,
  imports,
  deadlineOffsetBlocks: 120,
})
console.log(`submitted ${result.transactionId}`)
console.log(`successor position ${result.positionTokenId}`)
if (!result.positionTokenId) throw new Error("recover the successor ID from the confirmed transaction")
const successor = await waitForPosition(result.transactionId, result.positionTokenId)
console.log(`confirmed: liquidity ${successor.state.liquidity}`)

Spreading the plan keeps the submitted numbers exactly the ones printed. The example allows 120 blocks for proving and inclusion; adjust that window for your prover. The SDK’s default 20-block deadline can expire before delegated proving finishes. A longer deadline does not relax the exact-amount checks. If execution rejects the transaction, the old position stays unchanged. Check the rejection details and build a fresh plan before retrying.

Run these steps in order with dex from Setup and the confirmation helper.

Step 1: Read the position and the pool

position = dex.get_owned_position(POSITION_TOKEN_ID)
if position is None or position.state is None or position.state.liquidity == 0:
    raise ValueError("position not ready or has no liquidity")

slot = dex.get_slot(position.pool_key)
spacing = slot.tick_spacing
active = (slot.tick // spacing) * spacing
tick_lower = active - spacing
tick_upper = active + 2 * spacing

Step 2: Plan

plan_rebalance reads only. Set both funding budgets to zero to reuse only what the old position returns; positive budgets add funds in token base units.

plan = dex.plan_rebalance(
    pool_key=position.pool_key,
    position_token_id=position.position_token_id,
    tick_lower=tick_lower,
    tick_upper=tick_upper,
    max_funding0=0,
    max_funding1=0,
)
print(f"recovering: {plan.recovered0} token0 base units, {plan.recovered1} token1 base units")
print(f"refunding: {plan.refund0} token0 base units, {plan.refund1} token1 base units")
print(f"new range: [{plan.tick_lower}, {plan.tick_upper}) at liquidity {plan.liquidity_target}")

Use either liquidity_target for an exact size or the max_funding0 and max_funding1 budgets.

Step 3: Submit the plan

Pass the plan from step 2 unchanged and save the returned transaction and successor position IDs.

result = dex.rebalance_position(
    plan=plan,
    position_record=position.record,
    deadline_offset_blocks=120,
).delegate(wait=True)

print(f"transaction: {result.transaction_id}")
print(f"successor position: {result.position_token_id}")
if not result.position_token_id:
    raise RuntimeError("recover the successor ID from the confirmed transaction")
successor = wait_for_position(result.position_token_id)
if successor.state is None:
    raise RuntimeError("successor state not readable; refresh before another operation")
print(f"confirmed liquidity: {successor.state.liquidity}")

The example allows 120 blocks for proving and inclusion; adjust it for your prover because the default 20-block window can expire during delegated proving. Build the plan immediately before rebalance_position. If execution rejects it, check the rejection details and build a fresh plan before retrying.

Track the fills a position takes

A position fill is the change in the two asset amounts backing a position’s liquidity between two consecutive pool prices. Each swap that moves the pool’s price through the position’s range changes that inventory, and the sequence of those changes is the position’s fill history. Fills describe inventory, not fees; fee earnings are separate.The TypeScript example lp-fill-tracker.ts replays pool trades against a position’s current range and liquidity, then follows live trades. It reads the position on chain, takes prices from REST trade history, uses Aleo blocks to order swaps and route legs, and listens for WebSocket messages to backfill new trades. It reads up to 20 swaps on start; the first establishes a starting price, leaving up to 19 inventory changes to report.Historical replay holds the current range and liquidity fixed. It can include swaps from before the position was minted and does not reconstruct earlier increases or decreases. Treat it as an inventory calculation for that configuration, not a record of fills the position actually received. Live tracking stops if the position’s range or liquidity changes.Run it from a Veil checkout with Node.js 22 or later and pnpm:

export VEIL_E2E_PRIVATE_KEY='YOUR_PRIVATE_KEY'
pnpm exec tsx examples/shield-swap/lp-fill-tracker.ts POSITION_TOKEN_ID
pnpm exec tsx examples/shield-swap/lp-fill-tracker.ts POSITION_TOKEN_ID --history-size 50

Replace YOUR_PRIVATE_KEY with the account’s private key and POSITION_TOKEN_ID with the position’s token ID from getOwnedPositions. Mainnet is the default; pass --network testnet to track a testnet position. Each fill it prints carries the trade and transaction IDs, the block and leg order, the position’s liquidity and range, the pool’s tick and square-root price before and after, the swap direction, and the position’s token0 and token1 amounts before and after.The example exports calculatePositionFill, which values a position’s liquidity and range at two prices without reading the network, and trackLiquidityPosition, which runs the full tracker. Import either into your own application. See the fill tracker source for the options it accepts.The Python SDK has no fill tracker.

How it works on chain

A rebalance runs through shield_swap_rebalance_router.aleo and replaces your position in one transaction. It reuses the old position’s principal and fees, adds any planned funding, and pays out the surplus. No swap takes place.

What changes

Item	After a successful rebalance
Old position	Its `PositionNFT` is consumed and its public state is removed.
Successor position	A new `PositionNFT` and position ID, with the planned range and liquidity.
Owner and withdrawal address	Preserved from the old position.
Funding	Supplied from the signer’s token records where recovered funds are insufficient.
Surplus	Paid to the fixed withdrawal address as token records.

How the position is replaced

The contract removes all old liquidity and settles pending fees. Recovered funds include the principal, newly settled fees, and any balance already owed.
It checks the recovered amounts against the plan and closes the old position.
It mints the successor using the recovered funds plus any planned funding.
It pays any surplus to the withdrawal address. For each token, recovered funds plus funding must equal the amount used plus the refund.

A different range can need more of one token and less of the other. The router handles that with funding and refunds; it does not trade one token for the other.

When the plan no longer matches

Execution checks the recovered amounts and the amounts required for the planned successor liquidity. There is no slippage tolerance: if either token’s recovered or required amount differs from the plan, the transaction is rejected. It must also execute by the plan’s block-height deadline.If rejected, the old position stays unchanged. Check the rejection details and build a fresh plan before retrying. After acceptance, save the successor’s ID and record for later operations.Position accounting, both ranges, and the amounts are public; ownership and the withdrawal address are confidential. See Public data.

Next steps

Choosing a liquidity range for how to pick the new range.
LP workflow for the full lifecycle and the client state to keep.
Market maker operations for rebalancing at desk scale.
The TypeScript rebalance example is the runnable version of the steps above.

Start

Trade

Provide liquidity

Integration guides

Rebalancing and fill tracking

How a rebalance works

In the app

Move a position to a new range

Troubleshooting

See the trades your position filled

Next steps

Plan and submit a rebalance

Step 1: Read the position and the pool

Step 2: Plan

Step 3: Submit the plan

Step 1: Read the position and the pool

Step 2: Plan

Step 3: Submit the plan

Track the fills a position takes

How it works on chain

What changes

How the position is replaced

When the plan no longer matches

Next steps

​How a rebalance works

​In the app

​Move a position to a new range

​Troubleshooting

​See the trades your position filled

​Next steps

​Plan and submit a rebalance

​Step 1: Read the position and the pool

​Step 2: Plan

​Step 3: Submit the plan

​Step 1: Read the position and the pool

​Step 2: Plan

​Step 3: Submit the plan

​Track the fills a position takes

​How it works on chain

​What changes

​How the position is replaced

​When the plan no longer matches

​Next steps

How a rebalance works

In the app

Move a position to a new range

Troubleshooting

See the trades your position filled

Next steps

Plan and submit a rebalance

Step 1: Read the position and the pool

Step 2: Plan

Step 3: Submit the plan

Step 1: Read the position and the pool

Step 2: Plan

Step 3: Submit the plan

Track the fills a position takes

How it works on chain

What changes

How the position is replaced

When the plan no longer matches

Next steps