> For the complete documentation index, see [llms.txt](https://zeit-1.gitbook.io/zeit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zeit-1.gitbook.io/zeit/vaults/mechanics.md).
# Mechanics
How vaults work.
Mechanics
Zeit PPVs are implemented as a **fork and extension of Boring Vaults**, retaining the NAV / PPS share-based accounting model and extending it for prediction-market portfolios, roll-based liquidity events, and low-liquidity execution constraints.
This page explains:
* what is controlled by the **vault manager** vs the **protocol engine**
* how **impact-aware NAV / PPS** is used
* how withdrawals are prepared, checked, and settled
* how rebalancing and rolling between markets works in practice
***
### Roles and responsibilities
#### Vault manager (strategy layer)
The vault manager controls **strategy and execution**, including:
* portfolio construction and rebalancing
* selling positions **before resolution**
* rolling exposure into new markets as others resolve
* preparing liquidity for withdrawals
* choosing execution style (limit orders, staged unwinds, TWAP-style execution)
There is **no automatic rebalancing logic enforced by the protocol**. The manager operates similarly to a traditional fund manager within system constraints.
***
#### Protocol engine and contracts (operations layer)
The protocol enforces **accounting, lifecycle, and safety mechanics**, including:
* deposit and withdrawal queues
* roll scheduling and freeze windows
* impact-aware NAV and PPS computation
* minting and burning PPV shares
* allocation of collateral for redemptions
* forced liquidation fallback, bounded by pro-rata withdrawal size
***
### High Level Architecture
```mermaid
flowchart LR
U[Users] -->|deposit / withdraw| VC[Vault Contract
(Boring Vaults fork)]
M[Vault Manager] -->|strategy + execution| EX[Execution tools]
EX --> V[Venues / CLOBs
(Polymarket + others)]
E[Engine] -->|queues + NAV/PPS| VC
E -->|required USDC.e| M
VC -->|allocate collateral| RA[Redemption Adapter]
RA -->|claim| U
V -->|prices + depth| E
```
***
### Impact-aware NAV (paper vs executable value)
Prediction-market orderbooks are often thin. A mid-price (“paper”) mark can materially overstate realizable value at size.
For operational decisions, the system uses an **impact-aware NAV**:
* **Paper NAV**\
Values positions at a reference price (e.g. mid), ignoring depth.
* **Impact-aware NAV**\
Estimates position value using live orderbook depth — i.e. what the vault would receive if positions were unwound now, accounting for price impact.
Impact-aware NAV is used to:
* determine how much **USDC.e** must be freed for withdrawals
* compute PPS at roll checkpoints for minting, burning, and fee logic
***
### Queues and roll checkpoints
Vaults operate with discrete processing events (“rolls”), consistent with the Boring Vaults share model.
At any time, the engine tracks:
* pending deposits (collateral queued for mint)
* pending withdrawals (locked shares queued for redemption)
* net flow (deposits offsetting withdrawals where possible)
* required redemption liquidity in USDC.e, derived from impact-aware NAV / PPS
***
### Withdrawal liquidity workflow
Withdrawals are processed in batches. Managers are given advance visibility and time to reduce market impact.
#### 1. Queue visibility
When a withdrawal is submitted:
* shares are locked
* the withdrawal queue updates
* the engine computes the **required USDC.e** needed at the next redemption checkpoint
This amount is based on **impact-aware valuation**, not paper NAV.
***
#### 2. Manager preparation window
Before the roll:
* the manager prepares liquidity intentionally
* positions can be reduced or hedged in advance
Typical behavior includes:
* unwinding illiquid positions first
* reducing exposure gradually
* maintaining hedges while de-risking
This mirrors standard fund redemption management in illiquid markets.
***
#### 3. Pre-roll freeze window
Typically **2–3 hours** before a withdrawal checkpoint, the system enforces a **freeze window** (or stricter execution rules).
Purpose:
* stabilize the portfolio state
* prevent last-minute changes from invalidating solvency checks
***
#### 4. Redemption checkpoint
At the roll checkpoint, the engine verifies whether sufficient USDC.e is available.
If sufficient collateral exists:
* the required amount is transferred to the **redemption adapter**
* withdrawals become claimable
***
#### 5. Fallback liquidation (bounded)
If collateral is insufficient:
* the system initiates **forced liquidation**
* positions are reduced via **batched market sells** (e.g. \~10% increments)
* liquidation continues until required USDC.e is reached
Guardrail:\
Forced liquidation is capped to the **pro-rata portion of positions corresponding to the shares being withdrawn**. The system does not unwind more exposure than required.
***
### Rebalancing and rolling (manager-driven)
#### Rebalancing
Rebalancing is fully controlled by the vault manager.
Common triggers include:
* allocation drift
* risk reduction or hedging
* liquidity preparation ahead of withdrawal cycles
* changes in conviction or market information
There is no protocol-imposed rebalance schedule.
***
#### Rolling between markets
Markets resolve or expire. Maintaining perpetual exposure requires rolling into new markets.
Rolling is manager-driven:
* closing or reducing positions as markets approach resolution
* opening replacement exposure in new markets
* exiting positions early if liquidity or risk conditions change
Positions are **not required to be held until resolution**.
***
### Execution tools
Managers may use execution tooling to reduce slippage and impact, including:
* limit orders and staged limits
* time-sliced execution (TWAP-style)
* unwind helpers as roll checkpoints approach
* prioritization of illiquid positions
* alerts tied to required redemption liquidity
Tool availability may vary by vault configuration.
***
### Summary
* Zeit PPVs are a **fork and extension of Boring Vaults** adapted for prediction markets.
* **Managers** control strategy, execution, rebalancing, and rolling.
* The **protocol engine** enforces queues, roll checkpoints, valuation, and withdrawal safety rails.
* Withdrawals follow a **prepare → freeze → check → allocate** flow with **bounded forced liquidation** as a fallback.
***