> ## 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.

# Swap and claim lifecycle

> Why swap execution and confidential token delivery are separate transactions.

Shield Swap separates pool execution from delivery of confidential token records. A completed swap therefore has an accepted swap transaction and an accepted claim transaction.

```mermaid theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
sequenceDiagram
    participant Wallet
    participant AMM as Shield Swap
    participant Token as Token program
    participant State as Public mappings
    participant Investigator
    Wallet->>AMM: Submit swap with input record and private factor
    AMM->>Token: Transfer input amount from record to public custody
    AMM-->>Investigator: Return encrypted compliance record
    AMM->>State: Update pool, ticks, fees, and SwapOutput
    AMM-->>Wallet: Return swap ID and change record
    Wallet->>State: Read authoritative SwapOutput
    Wallet->>AMM: Submit claim with same signer and factor
    AMM->>Token: Transfer output and refund into records
    AMM->>State: Remove SwapOutput
    AMM-->>Wallet: Return output and refund records
```

## Stage 1: prepare

The client selects an input token record, chooses trade parameters, generates a nonce, chooses a private blinding factor, and derives a public confidential address bound to the signer. The address is submitted publicly, while its relationship to the signer is not disclosed in ordinary public state.

The client must retain the blinding factor. The claim uses the same factor and signer to prove the confidential address relationship.

## Stage 2: execute

The `swap` function verifies the signer-bound confidential address relation and calls the input token program to transfer the requested amount from private to public custody. It also creates an encrypted compliance record for the investigator.

The finalize stage:

* Checks deadline, pause state, pool identity, direction, amount, and price limit
* Normalizes the raw input amount
* Walks initialized ticks
* Updates price, liquidity, fee growth, protocol fees, ticks, and slot pointers
* Checks `amount_out_min`
* Writes a public `SwapOutput`
* Marks the confidential address as used

The stored output includes the output amount and any unspent input in raw token units.

## Stage 3: observe

After acceptance, the client reads `swap_outputs[swap_id]`. These mapping values are the authoritative claim arguments. A client should not rely only on a pre-trade quote because the actual output and remainder depend on finalized state.

## Stage 4: claim

`claim_swap_output` verifies the same signer and blinding factor, requests public-to-private token transfers for output and refund, and passes the exact public values into finalize.

Finalize checks every field against the stored output and removes the mapping entry. Removal prevents a second claim.

## Multi-hop variation

Multi-hop uses the same split settlement model and the same `SwapOutput` shape. Its pending output contains final output and any unspent original route input. `claim_swap_output` returns one output record and one input-refund record.

## Operational consequences

* A wallet must surface pending claims and retry them safely.
* Pauses do not block claim functions, but ordinary validation and token transfer behavior still apply.
* Anyone monitoring public state can see the pending output values and later removal.
* Losing the blinding factor can prevent the signer from constructing the required claim proof.
* Changing the signer also fails confidential address verification.

Wallets should present swap and claim as one workflow with two on-chain transactions.