> ## Documentation Index
> Fetch the complete documentation index at: https://shield.fi/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trader workflow

> Build a wallet flow that quotes, submits, claims, and reconciles a Shield Swap trade.

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](../rest/overview) 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:

| `zero_for_one` | Input  | Output | Square-root price movement |
| -------------- | ------ | ------ | -------------------------- |
| `true`         | token0 | token1 | Down                       |
| `false`        | token1 | token0 | Up                         |

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](./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](../math/swap-step).

## 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](./price-limits-slippage-deadlines) and [Exact-limit tick crossing](../math/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](./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](./failures-and-recovery).