# Vault Managers

> Canonical: https://docs.velocity.exchange/developers/vault-managers

Vaults are delegated trading pools where **depositors** provide capital and a **manager** (delegate) trades with it under strict withdrawal rules. Velocity Vaults are **first-party**: the `vaults` program (`programs/vaults/`, program ID `vAuLTsyrvSfZRuRB3XgvkPwNGgYSs9YRYymVebLKoxR`) and its TypeScript client, `@velocity-exchange/vaults-sdk`, live directly in the `velocity-v1` monorepo. This section covers the lifecycle and operations a vault manager needs. Vaults are managed either through the CLI (recommended, `packages/vaults-sdk/cli`) or programmatically with the SDK's `VaultClient`.

> **Warning:**
>
> The vaults program is not deployed, and the vaults SDK is not released at the version documented here. These pages describe both ahead of launch: nothing in this section can be run against a live program today. The published `@velocity-exchange/vaults-sdk` on npm is 0.1.3, from 18 June 2026, while the monorepo is at 0.1.24, so installing from npm gets a client well behind what these pages document. The monorepo itself is published only after the audit.

## How it works

Each vault has its own Velocity user account that the manager trades with. The manager has **delegate authority** over this account: they can place and cancel orders and manage positions. Depositors' funds are pooled in this single account; P&L affects all share holders proportionally. Vaults use **share-based accounting**: depositors receive shares when they deposit and redeem them after a cooldown (**redeem period**).

## Roles and lifecycle

- **Manager/delegate**: trades for the vault, updates allowed parameters, collects fees.
- **Depositor**: deposits, requests withdrawals, and completes withdrawals after the redeem period.

Lifecycle: **create → deposit → trade → request withdraw → wait (redeem period) → withdraw**.

> **Warning:**
>
> Creating a vault is permissionless, but having it appear in the Velocity interface is not, and the listing process is not documented publicly yet. Ask in the community Discord for the current process.

## Parameters and fee constraints

**Parameters set at initialization** (and how they can change later):

| Parameter | Notes |
| --------- | ----- |
| **`name`** | Unique identity for the vault. |
| **`management fee`** | Annualized. `update_vault` can only **lower** it immediately; raising it goes through the timelocked `manager_update_fees` path (see below). |
| **`performance fee`** (profit share) | On realized gains. `update_vault` can only **lower** it immediately; raising it goes through the timelocked `manager_update_fees` path. |
| **`hurdle_rate`** | Profit share is only charged on returns above this rate. `update_vault` can only **raise** it immediately; lowering it goes through the timelocked `manager_update_fees` path. |
| **`redemption period`** | Withdrawal cooldown in seconds; after initialization can only be **shortened**. |
| **`permissioned`** | If set, only the manager can initialize new vault depositor accounts. Can be flipped after initialization. |
| **`max_tokens`** / **`max-tokens`** | Capacity limit; can be raised or lowered after init (applies to new deposits only). |
| **`min_deposit_amount`** / **`min-deposit-amount`** | Minimum deposit size; can be changed after init (applies to new deposits only). |

**Fees:** Fee parameters use percentage precision (1e6 = 100%) and are annualized. Management fees apply only when there are non-manager deposits and are charged across the vault; they compound on actions, so more frequent depositor activity slightly reduces the effective annualized fee. Performance fees are calculated per depositor with **watermarks** so drawdowns don't cause double-charging; once charged, this fee is not reclaimed.

**Security and guardrails:**

- In a Normal-class vault, managers **cannot** withdraw user funds directly; withdrawals are governed by **redeem period** and **share accounting**. In a Trusted-class vault, the manager can move assets out via `manager_borrow`, tracked only as `manager_borrowed_value` against the vault's equity (see [Trusted vaults](/developers/vault-managers/trusted-vaults.md)).
- Managers can **decrease** (but not increase) the redeem period immediately, and can only **lower** fees (or raise the hurdle rate) immediately. Raising fees or lowering the hurdle rate requires the timelocked `manager_update_fees` path, described in [Changing vault fees](#changing-vault-fees).

## Changing vault fees

There are two fee-change paths, and which one applies depends on the direction of the change.

### One-way changes that apply at once

`update_vault` (CLI `manager-update-vault`) applies immediately, but only in the direction that favours depositors. Each field is checked with a strict inequality, so a no-op value is rejected too:

| Field | `update_vault` accepts | Error on the wrong direction |
| --- | --- | --- |
| `management_fee` | strictly lower than the current fee | `InvalidVaultUpdate` |
| `profit_share` | strictly lower than the current share | `InvalidVaultUpdate` |
| `hurdle_rate` | strictly higher than the current rate | `InvalidVaultUpdate` |
| `redeem_period` | shorter than the current period | `InvalidVaultUpdate` |

A raised hurdle rate counts as depositor-friendly because profit share is only charged above the hurdle, so a higher hurdle means less fee.

### Raises go through a timelock

To raise the management fee or the profit share, or to lower the hurdle rate, the manager queues the new policy with `manager_update_fees`. The queue lives in a separate `FeeUpdate` account, which an admin must create first with `admin_init_fee_update`.

Rules the program enforces on the queue:

- `timelock_duration` must be greater than 0 and at least `max(1 week, 2 x redeem_period)`. A shorter duration fails with `InvalidVaultUpdate`.
- The queued values are bounds-checked with the same rules as vault initialization: management fee below 100% and profit share below 100%. Protocol vaults must queue `hurdle_rate == 0`.
- Only one update can be pending at a time, and the vault must not be in liquidation (`OngoingLiquidation`).
- Any field left unset in the params keeps its current value.

Nothing changes when the queue is created. The new policy installs when `manager_update_fees` is called again after `incoming_update_ts` has passed. That second call settles the management fee up to the current instant at the **old** rate first, then installs the new policy and clears the queue. Because installation needs a settled vault, other share-moving instructions (deposit, withdraw, request withdraw, tokenize, share transfer) also install a matured update as a side effect.

The manager can withdraw a pending queue with `manager_cancel_fee_update`. An admin can delete the `FeeUpdate` account with `admin_delete_fee_update`, and can force a matured update through `manager_update_fees` when one is already pending.

### Hurdle rate

`hurdle_rate` is a return threshold on the depositor's cost basis, in percentage precision (1e6 = 100%). Profit share is charged only when a depositor's unrealized profit exceeds `cost_basis x hurdle_rate / 1e6`, where cost basis is the depositor's net deposits plus its cumulative profit-share amount. Below that threshold the manager takes no profit share. A hurdle rate of 0 means every gain above the high-water mark is charged.

### Grandfathering

Each depositor records the profit share and hurdle rate that were in force when its high-water mark was last set. The policy actually applied to a depositor's unpriced gain is `min(vault profit share, depositor's stored profit share)` and `max(vault hurdle rate, depositor's stored hurdle rate)`, so a queued raise never prices gain earned before it existed, and a depositor-friendly change applies at once.

A depositor moves onto the vault's current policy only when its gain is realized at the old policy. The manager can force that with `apply_profit_share`, described in [Manager operations](/developers/vault-managers/manager-operations.md).

## Accounting

**Share price** is implied as `vault_equity / total_shares` in the vault's deposit asset. Vault equity is the value of vault assets (and for Trusted vaults includes the manager's borrowed value). Depositor and manager shares are tracked on the vault and depositor accounts.

## What to monitor and risks

**Liquidations:** If a depositor has waited the redeem period and their withdrawal would breach the vault's initial margin requirement (e.g. the delegate is over-leveraged), a permissioned liquidator can temporarily assume delegate control and close positions in reduce-only mode (until withdrawal is processed or for up to 1 hour), then restore the original delegate. Monitor **total outstanding withdrawal requests** (stored on the vault account) and keep margin usage in check so depositor withdrawals don't trigger takeovers; the redeem period leaves time to unwind positions.

**Trust and incentives:** The design is not trustless between depositors and managers. Without reputation or stake, incentives can be misaligned (e.g. moving value via losing trades). Depositors have no onchain recourse, so they must trust the manager. Operate with clear terms and consider reputation or skin-in-the-game where appropriate.

## In this section

Building the depositor side of a vault instead? See [Vault Depositors](/developers/vault-depositors.md).

## Related Resources

- `@velocity-exchange/vaults-sdk`, the CLI and TypeScript client for vault operations. These pages are written against the in-repo version, not the older one on npm
- [Protocol Concepts](/developers/concepts.md), accounts and onchain data model
- [Velocity SDK](/developers/velocity-sdk/setup.md), core trading and positions SDK