> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windrose.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Vaults

> The vaultSnapshot and vaultEvent tables: collateral, liability, equity and collateral ratio of every Windrose currency vault, and each mint, redeem, deposit, withdraw and donation.

Each Windrose currency is minted by an `FxVault` that holds the chain's dollar. Two tables describe a vault: `vaultEvent` records what people did, and `vaultSnapshot` records the vault's accounting right after each of those events.

## vaultEvent

| Field                                            | Type    | Unit                | Meaning                                                                              |
| ------------------------------------------------ | ------- | ------------------- | ------------------------------------------------------------------------------------ |
| `id`                                             | text    |                     | `txHash-logIndex`. Primary key.                                                      |
| `vault`                                          | hex     | address             | The `FxVault`.                                                                       |
| `code`                                           | hex     | bytes32             | Currency code, hex encoded.                                                          |
| `type`                                           | enum    |                     | `mint`, `redeem`, `deposit`, `withdraw`, `donate`.                                   |
| `user`                                           | hex     | address             | The `user` argument of the event (the donor for `donate`).                           |
| `usdcAmount`                                     | bigint  | dollar, 6 decimals  | Dollar in (mint, deposit, donate) or out (redeem, withdraw).                         |
| `synthAmount`                                    | bigint  | 18 decimals         | Synthetic minted or burned. `0` for deposit, withdraw and donate.                    |
| `shares`                                         | bigint  | 18 decimals         | Backer shares minted (deposit) or burned (withdraw). `0` otherwise.                  |
| `fee`                                            | bigint  | dollar, 6 decimals  | Fee taken on mint and redeem. `0` otherwise.                                         |
| `rate`                                           | bigint  | units per USD, 1e18 | Rate used, set on mint and redeem, `null` otherwise.                                 |
| `fresh`                                          | boolean |                     | Whether the rate was within the fresh window, set on mint and redeem.                |
| `haircut`                                        | boolean |                     | Redeem only: the payout was scaled down because the vault was below 100% collateral. |
| `timestamp`, `blockNumber`, `txHash`, `logIndex` |         |                     |                                                                                      |

Indexes: `(vault, timestamp)`, `user`.

## vaultSnapshot

One row per vault event, keyed by the same `txHash-logIndex`, holding `vault.status()` plus the two supplies at that block.

| Field                      | Type    | Unit                | Meaning                                                                                           |
| -------------------------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `id`                       | text    |                     | Same id as the triggering `vaultEvent`. Primary key.                                              |
| `vault`                    | hex     | address             |                                                                                                   |
| `code`                     | hex     | bytes32             |                                                                                                   |
| `rate`                     | bigint  | units per USD, 1e18 | Rate `status()` used.                                                                             |
| `fresh`                    | boolean |                     | Rate within the fresh window. `false` when the snapshot fell back to a recomputation (see below). |
| `assets`                   | bigint  | dollar, 6 decimals  | Dollar balance of the vault.                                                                      |
| `liability`                | bigint  | dollar, 6 decimals  | Dollar value of all outstanding synthetic at `rate`.                                              |
| `equity`                   | bigint  | dollar, 6 decimals  | `assets - liability`. Negative when the currency has strengthened past the buffer.                |
| `crBps`                    | bigint  | basis points        | `assets / liability`; `2^256 - 1` when there is no liability.                                     |
| `synthSupply`              | bigint  | 18 decimals         | Total supply of the synthetic token.                                                              |
| `shareSupply`              | bigint  | 18 decimals         | Total backer shares.                                                                              |
| `timestamp`, `blockNumber` |         |                     |                                                                                                   |

Index: `(vault, timestamp)`.

<Note>
  `vault.status()` reverts with `StalePrice` when the oracle's last rate is older than the stale limit (five days). The indexer then recomputes `liability`, `equity` and `crBps` from `vault.assets()` and the last known rate (the event's rate, else the indexed `currency.lastRate`) and writes the row with `fresh: false`, so the series never has a hole.
</Note>

## Examples

Snapshots (latest first) and recent events for one vault:

```graphql theme={"system"}
query Vault($vault: String!) {
  vaultSnapshots(where: { vault: $vault }, orderBy: "timestamp", orderDirection: "desc", limit: 100) {
    items { assets liability equity crBps synthSupply shareSupply rate fresh timestamp }
  }
  vaultEvents(where: { vault: $vault }, orderBy: "timestamp", orderDirection: "desc", limit: 50) {
    items { type user usdcAmount synthAmount shares fee rate fresh haircut timestamp txHash }
  }
}
```

The vault address for a code comes from the [currency](/api/queries/currencies) row, or from the deployment file on the [addresses](/protocol/addresses) page.

Latest snapshot of every vault in one query:

```graphql theme={"system"}
{
  currencys(where: { tier: 2 }, orderBy: "symbol", orderDirection: "asc", limit: 100) {
    items {
      symbol vault synth
      vaultSnapshots(orderBy: "timestamp", orderDirection: "desc", limit: 1) {
        items { assets liability equity crBps synthSupply shareSupply timestamp }
      }
    }
  }
}
```

One backer's deposits and withdrawals across every vault:

```graphql theme={"system"}
query Backer($user: String!) {
  vaultEvents(where: { user: $user, type_in: ["deposit", "withdraw"] }, orderBy: "timestamp", orderDirection: "desc") {
    items { vault type usdcAmount shares timestamp txHash currencyInfo { symbol } }
  }
}
```

Mints and redeems of a vault in a window, to measure fee income:

```graphql theme={"system"}
query Fees($vault: String!, $since: BigInt!) {
  vaultEvents(where: { vault: $vault, type_in: ["mint", "redeem"], timestamp_gte: $since }, limit: 1000) {
    items { type usdcAmount fee fresh timestamp }
  }
}
```

Redeems that took a haircut:

```graphql theme={"system"}
{ vaultEvents(where: { type: "redeem", haircut: true }, orderBy: "timestamp", orderDirection: "desc") { items { vault user usdcAmount synthAmount rate timestamp } } }
```

Collateral ratio history for a chart:

```graphql theme={"system"}
query CR($vault: String!) {
  vaultSnapshots(where: { vault: $vault }, orderBy: "timestamp", orderDirection: "asc", limit: 1000) {
    items { timestamp crBps equity }
  }
}
```

With `curl`:

```bash theme={"system"}
curl -s https://api.windrose.market/graphql \
  -H 'content-type: application/json' \
  -d '{"query":"query($v:String!){ vaultSnapshots(where:{vault:$v}, orderBy:\"timestamp\", orderDirection:\"desc\", limit:1){ items { assets liability equity crBps synthSupply shareSupply fresh timestamp } } }","variables":{"v":"0x2b55f325a7e84009c659148a36285cafbdf4be85"}}'
```

## Reading a snapshot

* `assets`, `liability` and `equity` are the chain's dollar in 6 decimals: `equity / 1e6` is the dollar buffer backers have put in plus accumulated fees, minus any adverse FX move.
* `crBps / 100` is the collateral ratio in percent. Treat `2^256 - 1` (`115792089237316195423570985008687907853269984665640564039457584007913129639935`) as "no liability" rather than a number.
* Vaults mint at a minimum collateral ratio of 100%, so a fresh vault with no backers sits exactly at 100% after its first mint. Below 100% redeems are paid pro rata (`haircut: true` on the event).
* A backer's share of equity is `shares / shareSupply`; multiply by `equity` for the current dollar value of a position.
* Fee income to backers is the sum of `fee` over mint and redeem events minus the protocol's 20% share, which is tracked inside the contract rather than as separate rows. The [FxVault reference](/protocol/contracts/fx-vault) has the exact accounting.