Vaults

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

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.

Examples

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

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 row, or from the deployment file on the addresses page. Latest snapshot of every vault in one query:

{
  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:

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:

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:

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

Collateral ratio history for a chart:

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

With curl:

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 has the exact accounting.

Overview

GraphQL queries

HTTP endpoints

vaultEvent

vaultSnapshot

Examples

Reading a snapshot

​vaultEvent

​vaultSnapshot

​Examples

​Reading a snapshot

vaultEvent

vaultSnapshot

Examples

Reading a snapshot