# Mechanics

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<br/>(Boring Vaults fork)]
  M[Vault Manager] -->|strategy + execution| EX[Execution tools]
  EX --> V[Venues / CLOBs<br/>(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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zeit-1.gitbook.io/zeit/vaults/mechanics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.