> For the complete documentation index, see [llms.txt](https://ladder-markets.gitbook.io/ladder-markets-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ladder-markets.gitbook.io/ladder-markets-docs/integrations/architecture.md).

# Architecture

Integrators talk to **handlers** for user flows and **Market** for round/oracle state. Do not send user BT to `Market` or the adaptor.

```mermaid
flowchart TB
  subgraph users [User-facing]
    DH[DepositHandler]
    WH[WithdrawalHandler]
    ST[SeniorTranche ST]
    JT[JuniorTranche JT]
  end

  subgraph core [Core]
    M[Market]
    Q[ConversionQueue]
    FC[FeeCollector]
  end

  A[Adaptor] --> Fund[Underlying fund]
  DH --> M
  WH --> M
  M --> ST
  M --> JT
  M --> Q
  M --> FC
  Q --> A
```

| Contract                          | Role                                                                    | Users call?                                |
| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ |
| `DepositHandler`                  | Collect BT, one request per user per round, pro-rata ST/JT or BT refund | Yes: request + claim                       |
| `WithdrawalHandler`               | Collect ST/JT, pro-rata BT or YT (or LP on halt-cancel)                 | Yes: request + claim                       |
| `Market`                          | Rounds, NAV realloc, `advanceRound`, permissionless `syncRound*`        | Views + sync; owner for policy/advance     |
| `SeniorTranche` / `JuniorTranche` | ERC-20 shares; inventory; ERC-4626-style `totalAssets` in BT-WAD        | Transfers, views; mint/burn is Market-only |
| `ConversionQueue`                 | Fund legs (user deposit/withdraw, releverage, ADL). Not netted          | No (Market only)                           |
| `FeeCollector`                    | Accrued fee YT                                                          | Fee recipient withdraw                     |
| `IAdaptor`                        | Price, adaptor round, submit/status                                     | Queue only for submits                     |

`Market` never stores per-user amounts. Per round it reads aggregates: `totalStDeposit` / `totalJtDeposit` (BT) and `totalStWithdraw` / `totalJtWithdraw` (shares).

## Two round spaces

|         | Ladder `roundId`                    | Adaptor round                                         |
| ------- | ----------------------------------- | ----------------------------------------------------- |
| Issuer  | `Market`                            | Fund / oracle via adaptor                             |
| Shape   | `1, 2, 3, …`                        | Arbitrary, may skip                                   |
| Used by | Handlers, queue attribution, claims | `advanceRound` gating and `marketRoundAdaptorRoundId` |

Handlers store **only** Ladder ids. Claims always use Ladder `roundId`.

## Open-round gate

```
isRoundSync  ⇔  adaptor.getLatestAdaptorRoundId() == lastProcessedAdaptorRoundId
```

`requestDepositForRound` / `requestWithdrawForRound` revert if `!isRoundSync()` or the handler `isSealed`. They never call `advanceRound`.

## Addresses

See the [home page](/ladder-markets-docs/ladder.md) placeholders until live deployment is published.

Solidity: `^0.8.33`. License: BSD-3-Clause.