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

# Pools and identifiers

> Canonical token ordering, pool keys, pair keys, tick keys, and position identifiers.

Shield Swap uses deterministic hashes for pools, ticks, swaps, and positions. Integrators must reproduce the same preimages and canonical ordering.

## Pool key

`create_pool` accepts two token identifiers, a fee tier, an initial square-root price, a tick spacing, and an initial tick. The program sorts the token identifiers before hashing:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
pool_key = BHP256(PoolKey {
  token0: min(input_token_a, input_token_b),
  token1: max(input_token_a, input_token_b),
  fee
})
```

The same token pair can have multiple pools when the fee tier differs. Reversing the input token order produces the same key because sorting happens before the hash.

## Pair key

`PairKey` contains only sorted token0 and token1. It is used by `pair_paused`, so one pair pause affects every fee tier for that pair.

## Tick key

Each tick mapping entry is keyed by the hash of:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
TickKey { pool, tick }
```

Tick keys are pool-specific. The same tick number in two pools has a different mapping key.

## Position token ID

Mint computes the position identifier from:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
TokenIDPreimage {
  request: MintPositionRequest,
  recipient,
  nonce
}
```

The request and resulting `token_id` are public. The recipient and nonce are private inputs. The token ID is therefore an opaque public handle, but it is stable across the position lifecycle. Anyone can follow public updates for that handle until burn removes the mapping entry.

The token ID is not derived from the confidential address formula used for swaps. It is also not, by itself, proof of ownership. The `PositionNFT` ownership record is the authority consumed by position entry points.

## Swap ID

Single-hop swap hashes a `SwapKey` that includes pool, direction, amount, price limit, recipient, nonce, and caller. The recipient and caller slots both contain the same public confidential address. Its relationship to the signer is not disclosed in ordinary public state. Multi-hop swap hashes the complete `SwapMultiHopRequest`.

The contract rejects creation when `swap_outputs` already contains the resulting ID. Nonces should therefore be unique for the relevant request and address.

## Token identifiers

Token identifiers are `field` values used for dynamic dispatch through `IARC20`. The token-seeding script encodes a bare program name into a field by packing its UTF-8 bytes little-endian. That script is an API database utility, not a separate on-chain identifier rule.

Production integrations should obtain token identifiers from an approved registry or deployment manifest and verify that the field decodes to the intended program. Do not infer asset identity from a ticker symbol.