Skip to main content
A Shield Swap trade is two transactions. swap consumes an input token record and writes a public pending output. claim returns the output and any unspent input as token records. A wallet should report success only after the claim is accepted and the returned records are stored. A finalized swap without a finalized claim is still unsettled for the user.

​
Finish line

The workflow is complete when all of these are true:
  • the swap transaction is accepted
  • swap_outputs[swap_id] contains the finalized output used for the claim
  • the claim transaction is accepted
  • output and refund records are stored in the wallet
  • the pending mapping entry is removed
  • local record state and public AMM state reconcile

​
Flow

  1. Confirm the deployment, market, and controls.
  2. Quote with the contract’s integer math and iteration caps.
  3. Reserve the input token record and persist claim recovery material.
  4. Submit swap once and track its terminal state.
  5. Read the finalized SwapOutput from the mapping.
  6. Submit claim with the exact stored fields.
  7. Store returned records and reconcile final state.

​
Before you start

Your client needs deployment identity, chain reads, a record store, exact-value parsing, proof submission, finality monitoring, and durable pending-claim storage. If you only need market data or routes, start with the REST API instead.

​
1. Confirm the market

Before quoting, read the pool and slot from chain state. Confirm:
  • The pool contains the intended token programs in the expected token0 and token1 order.
  • The pool is enabled.
  • Global, token, and pair pause controls do not block trading.
  • The fee tier and tick spacing match the market the user selected.
  • The current square-root price, current tick, active liquidity, and initialized-tick pointers are available.
Do not infer token ordering from symbols. The contract validates the token identifiers passed to swap against the public PoolState, and direction is defined in that canonical order. The token metadata API supplies display names and decimals. Use chain state for pool identity and token eligibility, and operator policy records for market approval.

​
2. Establish direction

zero_for_one determines both the input token and the direction of price movement: Use the same direction when computing the quote, price limit, record token, and token identifiers. A direction mismatch normally fails validation or attempts to spend the wrong input record.

​
3. Prepare a spendable record

Select a token record from the input token program with an amount at least as large as amount_in. The record owner must be the transaction signer, the record must be unspent, and its concrete token program must match the selected pool side. Preserve all record fields, including _nonce and _version. Reconstructing a record without its version can produce a commitment that does not exist on chain. The AMM asks the token program to move exactly amount_in from private to public custody. If the record is larger, the token program returns a change record. The wallet should track the consumed record and the returned change as part of the same state update. See Preparing token records.

​
4. Quote with integer math

Read current state close to submission time and simulate the contract’s fixed-point arithmetic. The quote should include:
  • Expected output in raw token units
  • Expected unspent input
  • Expected end price and tick
  • Expected initialized ticks crossed
  • Expected active liquidity after each crossing
  • Fee and protocol-fee estimates
  • The maximum number of swap iterations available
Single-hop execution performs five fixed swap iterations. If the requested amount needs more initialized-tick steps, execution stops after the fifth step and stores the remaining input for refund. A quote must model this cap. Use an exact transcription of the contract math. Floating-point calculations are suitable for display, not for acceptance-critical parameters. See Swap-step math.

​
5. Set protections

Set all three protections deliberately:
  • sqrt_price_limit caps adverse price movement.
  • amount_out_min sets the minimum acceptable final output in raw output-token units.
  • deadline sets the last acceptable block height.
The price limit must lie inside the contract domain and strictly in the trade direction relative to the current price. It cannot equal the current square-root price. If the limit exactly equals the next initialized tick and the swap reaches that price, the contract completes the tick crossing. It updates active liquidity, tick pointers, and both Q128 fee-growth-outside accumulators, but it does not trade beyond the limit. See Price limits, slippage, and deadlines and Exact-limit tick crossing.

​
6. Create confidential addressing material

Generate a fresh private blinding factor and derive the public confidential address from:
  • The AMM program address
  • The claim-or-swap domain separator
  • The signer address
  • The private blinding factor
Persist the blinding factor, or the deterministic derivation material needed to recover it, before submitting the swap. The same signer and factor are required for the claim. Each accepted confidential swap marks its confidential address as used. Do not reuse a counter or factor combination that derives an address already accepted by the program. The public request exposes the pool, direction, amount, minimum output, price limit, nonce, deadline, and token identifiers. Token records keep funding and delivery confidential, while the confidential address keeps the signer’s account out of the public recipient field. Amounts and routes remain public.

​
7. Submit the swap

The single-hop swap input order is:
  1. Input token record
  2. Private blinding factor
  3. Public confidential address
  4. Public pool key
  5. Public direction
  6. Public input amount
  7. Public minimum output
  8. Public square-root-price limit
  9. Public nonce
  10. Public deadline
  11. Public token0 identifier
  12. Public token1 identifier
Use a unique u64 nonce. The nonce contributes to swap_id; it is distinct from the record nonce and the blinding-factor derivation counter. An accepted transaction returns a public swap_id, a token change record when applicable, and an investigator-owned compliance record. The investigator record contains request and attribution data. Deployment policy determines disclosure authorization and legal eligibility.

​
8. Observe finalized output

After acceptance, read swap_outputs[swap_id]. Do not construct claim arguments from the pre-trade quote. The mapping is authoritative and records:
  • Output token
  • Raw output amount
  • Input token
  • Raw unspent input amount
  • Confidential recipient and caller addresses
Public observers can read the pending output amounts and observe when the mapping is removed.

​
9. Claim output and refund

Call claim_swap_output with the same signer, blinding factor, and confidential address. Pass the exact token identifiers and amounts stored in swap_outputs. On acceptance, the output and refund are returned as token records, and the pending mapping is removed. A second claim fails because the mapping no longer exists. Claims are separate from trading pause checks. A pause that prevents a new swap does not, by itself, remove the normal claim path. Token transfer behavior and exact mapping validation still apply. See Output claims and refunds.

​
10. Reconcile wallet state

A wallet should finish the workflow by recording:
  • The consumed input record as spent
  • Any input change record
  • The accepted swap transaction and swap_id
  • The pending-output mapping state
  • The claimed output record
  • Any refund record
  • The claim transaction and final mapping removal
If transaction status is uncertain, query chain state before retrying. Never submit the same input record twice on the assumption that the first transaction failed. For recovery procedures, see Failures and recovery.