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

# Protocol overview

> The program, public state, records, API, and client responsibilities that make up Shield Swap.

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.

<Warning>
  Latest source and deployed bytecode are separate version boundaries. Select testnet or mainnet first, then verify the matching registry, program edition, and artifact hash before constructing a transaction.
</Warning>

## System at a glance

| Layer                        | What it does                                                               | What an integrator uses                                              |
| ---------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `shield_swap.aleo`           | Validates swaps, positions, fee accounting, claims, and controls           | Entrypoints, mappings, structs, and exact math                       |
| `shield_swap_router.aleo`    | Wraps swap inputs and unwraps outputs or refunds                           | Wrapped-asset swap and claim entry points                            |
| `shield_swap_lp_router.aleo` | Wraps LP inputs and unwraps collected assets                               | Wrapped-asset mint, increase, collect, and protocol-fee entry points |
| Token programs               | Transfer token value into and out of the AMM                               | Token records and the dynamic `IARC20` interface                     |
| Public mappings              | Store pools, prices, ticks, positions, fees, pending outputs, and controls | Chain reads, indexers, quotes, and reconciliation                    |
| REST API and indexer         | Expose indexed data, routes, history, and transaction input schemas        | HTTPS and WebSocket clients                                          |
| Wallet or proving client     | Owns records, signs, proves, submits, recovers, and reconciles             | Wallet SDK or equivalent client code                                 |

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](../trading/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](../liquidity/lp-workflow) before building position management.

## 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](./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

| If you need to                      | Read                                                         |
| ----------------------------------- | ------------------------------------------------------------ |
| Query data or routes                | [REST API overview](../rest/overview)                        |
| Decide how to integrate             | [Choose an integration path](../developers/integration-path) |
| Build a wallet trade                | [Trader workflow](../trading/trader-workflow)                |
| Build position management           | [Liquidity provider workflow](../liquidity/lp-workflow)      |
| Review trust and failure boundaries | [Security model](../security/security-model)                 |