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

# Mapping queries

> Read and reconcile the public AMM state.

Mappings are the canonical public state for the AMM. An indexer should query them by deterministic keys and retain historical changes outside the contract.

## Core market mappings

* `initialized_pools[pool_key]` indicates that the pool key has been created.
* `pools[pool_key]` holds token IDs, fee, and enabled flag.
* `slots[pool_key]` holds the mutable price, liquidity, fee, and tick-walk state.
* `ticks[hash(pool, tick)]` holds initialized boundaries and sentinels.
* `positions[token_id]` holds public position economics.
* `swap_outputs[swap_id]` holds a pending claim.

## Configuration mappings

Read `fee_tiers`, `tick_spacings`, and `fee_to_tick_spacing` when validating a pool proposal. Read `token_allowed`, `from_wrapper_token_id`, and `to_wrapper_token_id` when validating asset eligibility and router selection. Display decimals live in the deployment registry and API, not an AMM mapping.

## Control mappings

Before an entry or trade, read:

* `global_paused[true]`
* `token_paused[token0]` and `token_paused[token1]`
* `pair_paused[PairKey { sorted token0, sorted token1 }]`
* `pools[pool].enabled`

For position operations, also read `frozen_position[token_id]`.

These reads are advisory. Finalize checks the current values at execution time.

## Missing and removed entries

Use a query path that distinguishes absence from a default value. Many mappings intentionally remove entries:

* `pending_admin` after acceptance
* `ticks` after gross liquidity reaches zero
* `swap_outputs` after claim
* `positions` after burn
* `frozen_position` after unfreeze

An absent freeze entry means not currently frozen. It does not prove that the position was never frozen.

## Historical indexing

Current mapping values are not a durable audit log. Archive transaction and state-change data if you need position history, disclosure reconciliation, freeze history, protocol fee history, or control-change evidence.

## Consistency checks

Useful indexer invariants include:

* Pool tokens are sorted and distinct.
* Pool fee and spacing match the registered binding.
* Slot price lies in the current tick interval.
* Non-sentinel linked ticks have positive gross liquidity.
* Reciprocal tick pointers agree.
* Slot nearest pointers bracket the current tick.
* Pending swap output tokens match the executed route.
* Position liquidity and boundary gross liquidity reconcile across the pool.

Run these checks after every finalized block and alert on divergence before it affects quotes.