> ## Documentation Index
> Fetch the complete documentation index at: https://knot-38d8bd0e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> What each piece is, what it owns, and how a swap moves through it.

## Product architecture

Three contracts and a read-only frontend. Every participating pool is its own hook instance with
its own LPs and its own reserves. The only thing they share is the ledger they all quote against.

```mermaid theme={null}
flowchart TB
    T["Trader"]
    LP["Liquidity provider"]
    UI["Next.js app<br/>read-only, calls preview()"]

    subgraph V4["Uniswap v4 core"]
      PM["PoolManager<br/>holds real tokens<br/>mints ERC-6909 claims"]
    end

    subgraph KNOT["Knot"]
      HA["KnotHook A<br/>deep pool<br/>ERC-20 LP shares"]
      HB["KnotHook B<br/>shallow pool<br/>ERC-20 LP shares"]
      FED["KnotFederation<br/>per-member books<br/>+ O(1) aggregate"]
      MATH["KnotMath<br/>library, inlined<br/>at compile time"]
    end

    T -->|"swap"| PM
    PM -->|"beforeSwap"| HA
    PM -->|"beforeSwap"| HB
    HA -->|"executeSwap"| FED
    HB -->|"executeSwap"| FED
    FED -.->|"inlined"| MATH
    HA <-->|"take / settle claims"| PM
    HB <-->|"take / settle claims"| PM
    LP -->|"addLiquidity / removeLiquidity"| HA
    UI -->|"preview() · reservesOf()"| FED
```

<Note>
  `KnotMath` is a library, inlined into both hooks at compile time. It has no deployed address of
  its own.
</Note>

## Who owns what

| Layer | Owns | Does not own |
| - | - | - |
| `PoolManager` | The real ERC-20 balances | Any Knot accounting |
| `KnotHook` | Its pool's LP shares, its pending deposits, its ERC-6909 claims | The aggregate |
| `KnotFederation` | Every member's reserve book and the aggregate pair | Any tokens at all |
| `KnotMath` | Nothing. Pure functions | Everything |

The federation never custodies a token. It is an accounting authority, so a bug there cannot move
funds directly, only mis-quote them.

## The rule, as a decision

```mermaid theme={null}
flowchart LR
    S["Swap arrives"]
    S --> Q1["Quote against<br/>local reserves"]
    S --> Q2["Quote against<br/>aggregate reserves"]
    Q1 --> D{"Exact input?"}
    Q2 --> D
    D -->|"yes"| MIN["output = min(local, aggregate)"]
    D -->|"no"| MAX["input = max(local, aggregate)"]
    MIN --> W["Difference is never paid out"]
    MAX --> W
    W --> R["It stays in the local reserves<br/>and accrues to that pool's LP shares"]
```

Both branches round against the taker, so rounding can never manufacture the surplus back.

## Liquidity lifecycle

Each provider's request is independent. There is no global lock, so a pending deposit cannot stall
swaps, withdrawals, or another provider.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending: addLiquidity()
    Pending --> Pending: maturity window
    Pending --> ExitLocked: activatePendingLiquidity()
    Pending --> Refundable: cancelPendingLiquidity()
    ExitLocked --> Active: second maturity window
    ExitLocked --> Refundable: excess above current ratio
    Refundable --> [*]: claimLiquidityRefund()
    Active --> [*]: removeLiquidity()
```

Only the provider can activate, cancel or claim their own request. Shares mint at the reserve
ratio current **at activation**, not at deposit, so capital that arrives late cannot capture gains
that accrued before it entered. Newly minted shares then remain non-transferable and
non-withdrawable for a second maturity window. The two windows stop fresh capital from influencing
one quote and exiting immediately afterwards.

## Custody

Custody reduces to one equation, asserted by five stateful invariants over 40,960 default calls and
a 163,840-call high-depth campaign:

```text theme={null}
PoolManager claims held by a hook
    = that pool's active reserves
    + its inactive provider assets
    + its unclaimed provider refunds
```

## Trust boundaries

```mermaid theme={null}
flowchart TB
    subgraph TRUSTED["Permissioned"]
      OWN["Federation owner<br/>registers reviewed hooks<br/>seeds the first deposit"]
    end
    subgraph OPEN["Permissionless"]
      ANY["Anyone<br/>swaps or queues liquidity<br/>providers manage their own requests"]
    end
    OWN -->|"register / unregister"| FED["KnotFederation"]
    ANY -->|"swap"| FED
    FED -->|"only registered members<br/>may mutate reserves"| BOOK["Reserve books"]
```

Membership is the load-bearing control. A coalition that controls a member pool can skew the
aggregate and loosen the bound by roughly half, which is measured and stated in
[Limits](/security/limits). Permissioned membership is therefore security, not administration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.