> For the complete documentation index, see [llms.txt](https://city-protocol.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://city-protocol.gitbook.io/docs/developers/city-protocol-sdk/vault.md). # Vault Create vaults and handle deposits, mints, withdrawals and redemptions with CityClient. The vault client, `CityClient`, creates vaults and handles deposits, mints, withdrawals and redemptions, including the cooldown flow for vaults that use one. The Portfolio SDK reads indexed vault and activity data alongside it. ## How it works `CityClient` wraps each vault action in one asynchronous call. It takes a Viem wallet client with an active account, sends every write from that account and returns the transaction hash, so each write acts for the participant who owns the wallet. `createVault` deploys a new vault through the `YieldVaultFactory` from the factory address, a name, a symbol and the underlying asset; every other write acts on an existing vault. A vault processes capital in four steps: request, valuation, settlement and claim. The participant acts at the request and at the claim, through `CityClient`. Valuation and settlement belong to the vault's own roles: no `CityClient` call performs them, and the integration reads their results. Because requests settle in batches at one valuation point, every request in a settlement cycle converts at the same price.
The vault's four steps, request, valuation, settlement and claim, with the CityClient writes and reads above each step and the vault roles that act below it

The four vault steps at SDK level. The participant signs the request and the claim through CityClient, the valuation provider and the curator value and settle the batch, and the integration reads the results.

| Step | Who acts | What happens | `CityClient` calls | | ---------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Request | Participant | The vault checks access, limits and pause state, then takes the deposit or starts the exit | `deposit`, `mint`; `cooldownAssets`, `cooldownShares` with the cooldown enabled; `withdraw`, `redeem` with it disabled | | Valuation | Valuation provider and reporters | The valuation provider proposes the NAV that prices each share, and reporters sign it under quorum | Reads only: `totalAssets` and the preview methods | | Settlement | Curator, through the settlement role | Pending requests settle at one valuation point | Reads only: `balanceOf`, `cooldowns`, `maxWithdraw` | | Claim | Participant | Each participant claims the result of their own request | `claimFromAp` for exit assets that matured in the cooldown | ### Request `deposit` takes an amount of the underlying asset in the token's own decimals, and `mint` takes a target amount of vault shares, which carry 18 decimals. Before either call executes, the SDK checks the participant's ERC-20 allowance and requests the approval the vault needs, so one call covers both the approval and the deposit or mint. The exit call depends on the vault's cooldown, which `cooldownDuration` reports. * **Cooldown disabled:** `withdraw` takes an asset amount and `redeem` a share amount, and each exits directly in one call. * **Cooldown enabled:** Direct withdrawals are blocked. `cooldownAssets` starts the exit from an asset amount and `cooldownShares` from a share amount, and the amount is locked in the vault's aging pool until the cooldown ends. Redemption requests are final once submitted, so confirm the amount with `balanceOf` and `previewRedeem` before the participant signs. ### Valuation and settlement The valuation provider proposes the NAV, which sets the price per share and so drives the shares minted, the assets redeemed and the fees applied. A report takes effect only once reporters sign it under quorum and it clears the freshness, timing and deviation checks. The curator then decides when pending requests settle, so the curator chooses the moment and the report fixes the price. The integration reads the outcome: * **Price:** `totalAssets` returns the vault's total assets, and the preview methods convert between assets and shares at the vault's current state. * **Position:** `balanceOf` returns the participant's vault shares, and it reads the connected wallet when `owner` is omitted. * **Exit in progress:** `cooldowns` returns `cooldownEnd` and `lockedAmount`, and `maxWithdraw` returns the assets the owner can withdraw. ### Claim `claimFromAp` claims the matured assets from the aging pool once `cooldownEnd` has passed. The assets go to the connected wallet, or to a `receiver` passed in the call. Each participant triggers their own claim, and the curator cannot claim redemption assets on a participant's behalf. ## Exits with a cooldown In a vault with a cooldown enabled, an exit runs in four steps. {% stepper %} {% step %} ### Read the cooldown `cooldownDuration` returns the vault's cooldown. A value greater than 0 means that direct `withdraw` and `redeem` are blocked, so the interface offers a withdrawal request. {% endstep %} {% step %} ### Start the cooldown The withdrawal request calls `cooldownAssets` with an asset amount or `cooldownShares` with a share amount, and the amount is locked in the aging pool. {% endstep %} {% step %} ### Show the unlock time `cooldowns` returns `cooldownEnd` and `lockedAmount` for the owner, which the interface displays as the unlock time and the locked amount. {% endstep %} {% step %} ### Claim at maturity After `cooldownEnd`, a claim action calls `claimFromAp`, which pays the matured assets to the connected wallet or to the chosen `receiver`. {% endstep %} {% endstepper %} ## Roles outside the SDK Every `CityClient` write acts for the participant. The roles that configure, price and settle a vault are separate, and no participant call exercises them. | Role | Scope | What it does | | ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Vault admin | Configuration and safety | Governs configuration and safety controls, changes critical parameters such as fee rates within their caps and pauses the vault in an emergency; it runs no strategy | | Curator | Strategy and settlement | Manages strategy allocation, validates the valuation proposal and decides when each deposit and redemption batch settles | | Valuation provider | Pricing | Proposes the valuation inputs that set the settlement price per share, which drive the shares minted, the assets redeemed and the fees applied | | Whitelist manager | Access control | Maintains the allowlist of depositors on KYC- or KYB-gated vaults | A write that fails a check these roles control reverts before any asset moves: a deposit into a paused vault, or from a wallet outside the allowlist of a gated vault, never reaches the vault. The contract modules, roles and vault types behind each step are set out in [Vault modules and roles](/docs/platform/product-mechanics/how-curated-vaults-work/vault-modules-and-roles.md), and chain abstraction and the contract-level request flow in [Deposits, capital flow and redemption](/docs/platform/product-mechanics/how-curated-vaults-work/deposits-capital-flow-and-redemption.md). ## Reads before writes Previews quote the result of a call before the participant signs it, and limits show whether the call can go through. | Before | Read | Returns | | ---------------------------- | ------------------------------ | ------------------------------------------------------------------------------------- | | `deposit` | `previewDeposit`, `maxDeposit` | The shares expected for an asset amount, and the most the receiver can deposit | | `mint` | `previewMint` | The assets required for a share amount | | `redeem` or `cooldownShares` | `previewRedeem` | The assets expected for a share amount | | `withdraw` | `maxWithdraw` | The most the owner can withdraw, which shows whether a direct withdrawal is available | | Any exit | `cooldownDuration` | A value greater than 0 when the cooldown is enabled | Metadata reads (`name`, `symbol`, `decimals` and `asset`) describe the vault, and state reads return its total assets (`totalAssets`), the amount still vesting (`getUnvestedAmount`) and the vesting period (`vestingPeriod`). For portfolio screens, `CityClient` supplies live balances, withdrawable assets and cooldown states, and the [Portfolio SDK](/docs/developers/city-protocol-sdk/vault/portfolio-sdk.md) supplies indexed vault lists, transaction history and daily TVL snapshots. {% content-ref url="/pages/BZYzikCuV6Ki7XpcGgmC" %} [Write methods](/docs/developers/city-protocol-sdk/vault/write-methods.md) {% endcontent-ref %} {% content-ref url="/pages/qDDZH4DfO7gdzprEk8vE" %} [Read methods](/docs/developers/city-protocol-sdk/vault/read-methods.md) {% endcontent-ref %} {% content-ref url="/pages/kpQV3RRHXm8nhc2wCmdi" %} [Preview and limit methods](/docs/developers/city-protocol-sdk/vault/preview-and-limit-methods.md) {% endcontent-ref %} {% content-ref url="/pages/G4K5Slw6BW0reXq8zFXL" %} [Common frontend flows](/docs/developers/city-protocol-sdk/vault/common-frontend-flows.md) {% endcontent-ref %} {% content-ref url="/pages/Wp8B6eMQ07YgetpP70Ss" %} [Portfolio SDK](/docs/developers/city-protocol-sdk/vault/portfolio-sdk.md) {% endcontent-ref %}