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

# Architecture

> How the Shield Swap program, token programs, records, public mappings, API, and clients interact.

Shield Swap has seven integration layers. A production application normally touches at least four of them.

## Layers

| Layer                            | Role                                                                | Integration concern                                                        |
| -------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Shield Swap program              | Executes AMM state transitions and controls                         | Entrypoints, finalizers, mappings, structs, and exact math                 |
| Swap and LP routers              | Adapt wrapped records to core AMM functions                         | Asset kind, wrapper direction, imports, and router address binding         |
| Dynamic token programs           | Move token value into and out of the AMM                            | Concrete transfer semantics, decimals, record shape, and upgrade authority |
| Freezelist and multisig programs | Supply non-inclusion proofs and upgrade authorization               | Root freshness, proof construction, signer authority, and editions         |
| Encrypted records                | Carry token value, position authority, and investigator attribution | Discovery, decryption, spent state, replacement, backup, and custody       |
| Public mappings                  | Hold current market, position, pending-output, and control state    | Direct reads, parsing, indexing, and reconciliation                        |
| API and client services          | Expose indexed data and build user workflows                        | Authentication, routing, persistence, proving, submission, and recovery    |

## Program execution

`shield_swap.aleo` contains the AMM state machine. User functions validate inputs and construct records or a `Final`. Finalizers execute token futures and update public mappings.

The program imports multisig, freezelist, and a pinned `IARC20` interface. A field identifier selects the concrete token program at runtime. The core accepts calls from only the hardcoded swap-router and LP-router addresses when a router bypass is required.

Successful interface dispatch does not prove that a token is safe or operationally approved. Asset support depends on the deployed token program's code, state, transfer behavior, and authority model.

## Public state and record ownership

Mappings contain pools, slots, ticks, positions, pending swap outputs, configuration, and controls. They support quoting, indexing, and independent accounting. They also expose amounts, routes, ranges, liquidity, fees, timing, and control actions.

Records carry a different kind of state:

* token records carry spendable value
* `PositionNFT` carries position authority
* investigator records carry encrypted mint or swap attribution

A public position row does not prove wallet ownership. A `PositionNFT` alone does not contain the position's latest public economics. Clients must reconcile both.

## Swap data flow

1. The client reads current pool, tick, token, and control state.
2. The client preflights a revisioned protocol snapshot and the wallet selects an input token record.
3. The client selects direct `swap`, `swap_from_wrapped`, or `swap_mh_from_wrapped` from the asset registry.
4. The program moves input value into public custody and updates AMM mappings.
5. Finalization writes `swap_outputs[swap_id]`.
6. The client reads that exact output and constructs a core or router claim with signer freezelist proofs.
7. The program returns output and refund token records.
8. The wallet stores the records and reconciles the final public state.

A pending `swap_outputs` entry is an unsettled user obligation until claim removes it.

## Position data flow

Mint creates both a public position and a `PositionNFT` that binds owner and immutable withdrawal address. Mint, collect, and claim require current non-inclusion proofs. Increase, decrease, and collect consume the current ownership record and return a replacement. Burn removes the public row and consumes the final ownership record.

Custody systems must update record inventory only after transaction acceptance is known.

## Production client boundary

The TypeScript harness demonstrates mapping reads, parsing, record handling, submission, and persistence. It is test-oriented. A production client still needs:

* a quote engine that matches contract rounding and iteration caps
* a record store with reserved, spent, and unknown states
* a pending-claim queue
* deployment-versioned parsers
* a chain indexer or API client
* bounded retry and finality handling
* durable reconciliation and monitoring

Continue with [Transaction execution](./transaction-execution) for client state, or [Protocol boundaries](../start/protocol-boundaries) for ownership across systems.