Protocol overview

Shield Swap is a concentrated-liquidity AMM. An integration touches more than the core program: token programs move value, encrypted records carry ownership, public mappings hold market state, and off-chain clients build and track Shield transactions.

​

System at a glance

The current frontend implements these boundaries behind its internal SDK layer. That internal API is application code, not a stable public package contract.

​

A trade is two transactions

1. swap consumes an input token record and updates public AMM state. Finalization writes the output and any unspent input to swap_outputs.
2. claim reads that pending output and returns output and refund token records to the signer.

A wallet should report the trade as complete only after the claim is accepted and the returned records are stored. A finalized swap with no finalized claim is still unsettled for the user. Read Trader workflow for the complete sequence.

​

A position has public economics and confidential ownership

The public positions mapping stores the range, liquidity, fee checkpoints, and owed tokens. A PositionNFT record proves authority over that position. Increase, decrease, and collect consume the current PositionNFT and return a replacement. Burn consumes it permanently. A wallet must reconcile the latest ownership record with the latest public mapping state. Read Liquidity provider workflow before building position management.

​

Rebalance a position

Use Rebalance to replace a complete position in one Shield transaction. Use Increase to keep the current range. Use Decrease to reduce liquidity. Rebalance keeps the same pool and withdrawal address. It removes the old position ID and creates a new position ID that the signer owns. The transaction can use recovered position funds and additional wallet funds. Unused wallet funds remain in the wallet. Recovered refunds go to the immutable withdrawal address. The operation is atomic. A failed transaction leaves the old position unchanged. The app requires another review when pool state changes. Read Rebalance a position for the complete app flow.

​

What remains public

Public state exposes:

• pool and token identifiers
• prices, ticks, liquidity, and fees
• trade amounts, routes, outputs, refunds, and timing
• position ranges and public accounting
• configuration and control actions

Token and position records keep ownership confidential in the intended flow. Investigator-owned records can support authorized participant attribution. They do not hide market activity. Read Protocol boundaries for the complete responsibility and visibility model.

​

Controls and deployment identity

The administrator can configure fee tiers, tick spacings, token eligibility, pool creation, protocol fee shares, pause layers, and position freeze state. An operational action can delay access or market activity even when accounting remains intact. Every integration must bind itself to a network, program ID, edition, checksum, dependencies, and storage schema. The current two-limb Q128.128 fee-growth layout cannot replace a scalar fee-growth deployment in place; it requires a fresh deployment.

​

Choose the next page