> ## Documentation Index
> Fetch the complete documentation index at: https://docs.railnet.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Vault 7540 mechanics
> How the ERC-7540 vault handles deposits, redemptions, settlement, fees, and access control
export const VaultRoles = () => {
const CSS = `
.vr-bg{fill:#F8F8F8;rx:4;ry:4}.dark .vr-bg{fill:#141414}
.vr-t{fill:#374151;font-family:"Inter Tight","Inter",system-ui,sans-serif}.dark .vr-t{fill:#D1D5DB}
.vr-tm{fill:#6B7280;font-family:"Inter Tight","Inter",system-ui,sans-serif}.dark .vr-tm{fill:#9CA3AF}
.vr-h{fill:#111827;font-family:"Inter Tight","Inter",system-ui,sans-serif}.dark .vr-h{fill:#E5E7EB}
.vr-fn{fill:#6B7280;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.dark .vr-fn{fill:#9CA3AF}
.vr-cont{fill:#fff;stroke:#D1D5DB;stroke-width:1.5;rx:8;ry:8;stroke-dasharray:8 4}.dark .vr-cont{fill:#1F2937;stroke:#4B5563}
.vr-ln{stroke:#ACACAC;fill:none;stroke-width:1;color:#ACACAC}.dark .vr-ln{stroke:#666;color:#666}
.vr-ln-d{stroke:#ACACAC;fill:none;stroke-width:1;color:#ACACAC;stroke-dasharray:6 3}.dark .vr-ln-d{stroke:#666;color:#666}
.vr-proxy{fill:#E8E0F0;stroke:#C4B5D9;stroke-width:1;rx:3;ry:3}.dark .vr-proxy{fill:#2D2540;stroke:#4A3B6B}
.vr-admin{fill:#FFE4D2;stroke:#E5C4A8;stroke-width:1;rx:3;ry:3}.dark .vr-admin{fill:#3D2510;stroke:#5C3A1E}
.vr-valuation{fill:#FEF3C7;stroke:#E5D5A0;stroke-width:1;rx:3;ry:3}.dark .vr-valuation{fill:#422006;stroke:#5C4A1E}
.vr-strategy{fill:#E0E7FF;stroke:#B4C0E8;stroke-width:1;rx:3;ry:3}.dark .vr-strategy{fill:#1E2A4A;stroke:#2E3F6A}
.vr-whitelist{fill:#D1FAE5;stroke:#9DB8B0;stroke-width:1;rx:3;ry:3}.dark .vr-whitelist{fill:#1A3535;stroke:#2D5050}
.vr-fee{fill:#F3F4F6;stroke:#D1D5DB;stroke-width:1;rx:3;ry:3}.dark .vr-fee{fill:#1F2937;stroke:#4B5563}
.vr-registry{fill:#CCE5E6;stroke:#9DB8B0;stroke-width:1;rx:3;ry:3}.dark .vr-registry{fill:#1A3535;stroke:#2D5050}
.vr-plat{fill:#FFE4D2;stroke:#E5C4A8;stroke-width:1;rx:3;ry:3}.dark .vr-plat{fill:#3D2510;stroke:#5C3A1E}
.vr-splitter{fill:#F3F4F6;stroke:#D1D5DB;stroke-width:1;rx:3;ry:3}.dark .vr-splitter{fill:#1F2937;stroke:#4B5563}
.vr-dot-proxy{fill:#C4B5D9}.dark .vr-dot-proxy{fill:#6B5A8E}
.vr-dot-admin{fill:#E5C4A8}.dark .vr-dot-admin{fill:#8B6E4A}
.vr-dot-val{fill:#E5D5A0}.dark .vr-dot-val{fill:#8B7A3E}
.vr-dot-strat{fill:#B4C0E8}.dark .vr-dot-strat{fill:#4A5A8E}
.vr-dot-wl{fill:#6EE7B7}.dark .vr-dot-wl{fill:#34D399}
`;
return
;
};
## Overview
The 7540 Vault is the capital entry point for every Advanced Strategy. It implements the [ERC-7540](https://eips.ethereum.org/EIPS/eip-7540) standard handling deposits, redemptions, share pricing, fee collection, and access control through a single contract.
This page covers the vault's internal mechanics. For a high-level overview of how the vault fits into the Advanced Strategy architecture, see [Advanced Strategies](/strategies/advanced).
## Deposits
The vault automatically selects between sync and async deposit paths based on **NAV validity**. After each settlement, the NAV is considered valid for a configurable time window (`totalAssetsLifespan`). While valid, the vault has a reliable exchange rate and can process instant operations. Once the window expires, the vault can no longer guarantee a fair price — deposits are queued until the next valuation cycle.
### Sync deposits
When the NAV is valid, investors can deposit and receive shares instantly in a single transaction by calling `syncDeposit()`. The share price is computed using the vault's current NAV — no waiting, no claim step.
Sync deposits:
* Transfer the deposited assets directly into the **Strategy wallet** (the Safe multisig that holds the fund's capital)
* Mint shares to the investor at the current price
* Deduct an entry fee (if configured) from the minted shares
* Enforce the maximum deposit cap (if configured)
### Async deposits
When the NAV has expired, deposits switch to the async path. This is a multi-step flow:
1. **Request** — The investor calls `requestDeposit(assets, controller, owner)`. Assets move into the Silo escrow (a separate holding contract). No shares are minted yet, and the share price is not fixed.
2. **Wait** — The request stays pending until the next NAV cycle. The investor can cancel during this window by calling `cancelRequestDeposit()`, as long as the epoch hasn't rolled.
3. **Settlement** — The valuation manager proposes a NAV, the Strategy confirms and settles. The share price is locked at this point, shares become claimable, and the deposited assets move from the Silo into the **Strategy wallet**.
4. **Claim** — The investor calls `deposit()` or `mint()` to receive their shares. An entry fee is deducted using the rate that was active at settlement time — not the current rate — protecting investors from fee changes between settlement and claim.
Each address can only have one pending deposit request at a time. If a previous request from an older epoch is already claimable, the vault auto-claims it before accepting a new request.
### Maximum deposit cap
The vault can enforce a maximum deposit limit at the **vault level** via `updateMaxCap(newCap)` (Strategy-only). This is a global cap on total TVL — not per user. The check compares `totalAssets + new deposit + pending deposits in escrow` against the cap. It is enforced on both `syncDeposit()` and `requestDeposit()`. If a deposit would push the vault above the cap, it reverts.
## Redemptions
Redemptions follow the same NAV validity model as deposits — sync redemptions require a valid NAV, while async redemptions can be requested at any time regardless of NAV status. However, unlike deposits, async redemption **requests** are not gated by NAV expiration — investors can submit a request whether the NAV is fresh or expired.
### Async redemptions
Async redemptions are the default withdrawal path. The flow mirrors async deposits:
1. **Request** — The investor calls `requestRedeem(shares, controller, owner)`. Shares move into the Silo escrow. The redemption price is not fixed yet.
2. **Wait** — The request stays pending until the next NAV cycle. Unlike deposit requests, redemption requests **cannot be canceled**.
3. **Settlement** — The Strategy confirms the NAV and settles. The redemption price is locked, the escrowed shares are burned, and the equivalent assets are pulled from the **Strategy wallet** into the vault — provided the Strategy holds enough liquid assets.
4. **Claim** — The investor calls `redeem()` or `withdraw()` to receive their assets from the vault. An exit fee is deducted using the rate recorded at settlement time. Partial claims are allowed.
### Sync redemptions — instant liquidity buffer
Sync redemptions allow investors to exit the vault instantly in a single transaction, without going through the async request/settle/claim cycle. This creates an **instant liquidity buffer** for platforms and investors that need immediate withdrawals.
When an investor calls `syncRedeem(shares, receiver, minimumAssets)`, the vault:
1. Deducts an **exit fee** from the shares (collected as fee shares, split with the protocol)
2. Applies a **haircut fee** on the remaining shares — these shares are **burned, not collected by anyone**. This raises the price-per-share for all remaining holders, creating an economic disincentive for instant withdrawals that benefits patient investors.
3. Converts the net shares to assets at the current price
4. Pulls those assets directly from the **Strategy wallet** and transfers them to the receiver
The `minimumAssets` parameter provides slippage protection — if the computed output falls below this threshold, the transaction reverts.
**Prerequisites for sync redemptions:**
* The vault must be open (not closing or closed)
* The sync mode must include redemptions
* The NAV must be valid (not expired)
* The Strategy must hold enough liquid assets to cover the redemption
Unlike async redemption settlement (which silently defers when the Strategy lacks funds), sync redeem hard reverts if the Strategy doesn't have enough liquid assets. There is no graceful fallback.
### Sync vs async redemptions
| Aspect | Sync redeem | Async redeem |
| ---------------------- | -------------------------------------- | -------------------------------------------------- |
| **Transactions** | 1 (instant) | 3+ (request, settle, claim) |
| **Wait time** | None | At least one settlement cycle |
| **Exit fee** | Yes (current rate) | Yes (rate recorded at settlement) |
| **Haircut fee** | Yes (burned) | No |
| **Strategy liquidity** | Required (hard revert if insufficient) | Not required at request time |
| **Best for** | Urgency, small positions | Cost sensitivity, large positions, patient capital |
## NAV update — two-phase valuation
The vault's Net Asset Value (NAV) determines share pricing for every operation. NAV updates follow a **two-phase commit** designed to separate the valuation responsibility from the settlement authority.
### Phase 1 — Valuation manager proposes
The valuation manager calls `updateNewTotalAssets(newTotalAssets)` to propose a new NAV. This function:
* Snapshots all pending deposit and redemption requests from the escrow (Silo)
* Creates an epoch boundary — all requests submitted before this point are included in this settlement batch
* Stores the proposed value for the Strategy to confirm
This function can only be called when the current NAV has expired. If the NAV is still valid, the call reverts. The Strategy can force expiration at any time by calling `expireTotalAssets()`.
If [NAV guardrails](#nav-guardrails) are active, the proposed value is validated against the price-per-share bounds before being accepted.
### Phase 2 — Strategy confirms and settles
The Strategy confirms the proposed NAV by calling either `settleDeposit(newTotalAssets)` or `settleRedeem(newTotalAssets)`. The value passed must exactly match what the valuation manager proposed. This function:
* Finalizes the NAV into the vault's `totalAssets`
* Takes management and performance fees (minting fee shares)
* Records the current entry and exit fee rates for the settlement epoch
* Refreshes the NAV validity window — sync operations become available again until the new expiration
Settlement cannot happen without a prior valuation proposal. The two-phase design ensures that no single role can both propose and finalize a NAV — the valuation manager proposes, and the Strategy confirms.
### NAV validity and sync window
After settlement, the NAV remains valid for a configurable lifespan (`totalAssetsLifespan`). During this window, sync deposits and sync redemptions are available. Once the lifespan expires, the vault switches to async-only mode until the next NAV cycle.
The Strategy can update the lifespan via `updateTotalAssetsLifespan(lifespan)`, or force immediate expiration via `expireTotalAssets()` to trigger async mode on demand.
## Settlement
Settlement is the process of converting pending requests into claimable shares (for deposits) or claimable assets (for redemptions). It always happens as part of the NAV confirmation step — there is no way to settle without updating the NAV.
### Settling deposits — `settleDeposit()`
When the Strategy calls `settleDeposit(newTotalAssets)`, the vault:
1. Finalizes the NAV and takes fees
2. Converts pending deposit assets into shares at the newly confirmed price
3. Mints those shares to the vault contract (held until users claim)
4. Moves the deposited assets from the Silo escrow to the Strategy
5. Attempts to settle pending redemptions as well (best-effort)
After settlement, depositors can claim their shares via `deposit()` or `mint()`.
The Strategy can also push shares to users directly by calling `claimSharesOnBehalf([controllers])`, which batch-claims for multiple depositors without requiring each user to submit a transaction.
### Settling redemptions — `settleRedeem()`
When the Strategy calls `settleRedeem(newTotalAssets)`, the vault:
1. Finalizes the NAV and takes fees
2. Converts pending redemption shares into the equivalent asset amount at the confirmed price
3. Checks whether the Strategy holds enough liquid assets to cover the full redemption amount
4. If sufficient — burns the escrowed shares and pulls assets from the Strategy into the vault for claiming
5. If insufficient — the redemption settlement is skipped entirely (no partial fills)
After settlement, redeemers can claim their assets via `redeem()` or `withdraw()`. The Strategy can also batch-claim via `claimAssetsOnBehalf([controllers])`.
Redemption settlement is all-or-nothing. The Strategy must hold enough liquid assets to cover all pending redemptions at the confirmed price. If liquidity is insufficient, no redemptions are settled in that cycle — they carry over to the next NAV update.
### Which settlement function to use
| Function | Settles deposits | Settles redemptions | When to use |
| ----------------- | ---------------- | ------------------- | ---------------------------------------- |
| `settleDeposit()` | Yes | Yes (best-effort) | Default — handles both queues |
| `settleRedeem()` | No | Yes (best-effort) | When you only want to settle redemptions |
In most cases, `settleDeposit()` is the right choice because it processes both queues in a single transaction.
## Fee framework
The vault collects fees at settlement time and during sync operations. All fees flow to a single fee receiver address, with a protocol fee split applied across all fee types.
### Fee types
| Fee | Max rate | When applied | Destination |
| --------------- | -------------- | --------------------------------------------------- | ----------------------------------- |
| **Management** | 10% (1000 bps) | On settlement — time-weighted based on total assets | Fee receiver |
| **Performance** | 50% (5000 bps) | On settlement — charged only above high-water mark | Fee receiver |
| **Entry** | 2% (200 bps) | On deposit (sync and async claim) | Fee receiver |
| **Exit** | 2% (200 bps) | On redeem/withdraw (sync and async claim) | Fee receiver |
| **Haircut** | 20% (2000 bps) | On sync redeem only | Burned (benefits remaining holders) |
### How fees are computed
**Management fees** accrue based on total assets under management and time elapsed since the last settlement. They are proportional to AUM and the configured annual rate.
**Performance fees** are charged only when the price-per-share exceeds the high-water mark (HWM) — ensuring fees are only taken on net new gains. After fees are collected, the HWM is updated if the current price-per-share is higher. The HWM never decreases under normal operation, but the Strategy can reset it via `resetHighWaterMark()` if enabled at initialization (useful for vault migrations).
**Entry and exit fees** are recorded per settlement epoch. When an investor claims shares or assets, the fee rate used is the one that was active at the time of settlement — not the current rate. This protects investors from fee changes between settlement and claim.
**Haircut fees** are unique to sync redemptions. The haircut shares are burned rather than collected, which reduces total supply and increases the price-per-share for remaining holders.
### Fee splitter
All vault fees are sent to a single fee receiver address on-chain. The **Fee Splitter** is an off-chain module that distributes the collected fees proportionally between the **Asset Manager** and **Railnet**. The split ratio is configured per strategy and applied automatically — the Asset Manager receives their share of management, performance, entry, and exit fees, while Railnet receives its portion as a protocol fee.
## Access control
The vault supports configurable access control to gate who can deposit, redeem, and transfer shares.
### Access modes
| Mode | Behavior |
| ------------- | -------------------------------------------------------------- |
| **Allowlist** | Only explicitly approved addresses can interact with the vault |
| **Blocklist** | All addresses are allowed except those explicitly blocked |
The vault owner can switch between modes at any time via `switchAccessMode()`.
### Allowlist mode
The whitelist manager adds or removes addresses using `addToWhitelist()` and `revokeFromWhitelist()`. Only whitelisted addresses can deposit and redeem.
### Blocklist mode
The whitelist manager manages blocked addresses using `addToBlacklist()` and `revokeFromBlacklist()`. Blocklisted addresses cannot deposit, redeem, **or transfer vault shares** — both sending and receiving are restricted.
### External sanctions list
The vault can integrate with an external sanctions oracle (e.g., Chainalysis OFAC sanctions list) via `setExternalSanctionsList()`. When configured, an address must pass **both** the internal access check and the external sanctions check to be allowed.
### What access control gates
| Action | What is checked |
| ------------------------------------------------ | --------------------------------------- |
| `requestDeposit()` | Owner and controller must be allowed |
| `syncDeposit()` | Caller must be allowed |
| `requestRedeem()` | Owner and controller must be allowed |
| `syncRedeem()` | Caller and receiver must be allowed |
| `transfer()` / `transferFrom()` (blocklist mode) | Sender and receiver must not be blocked |
## Vault admin
The vault owner (admin) is set at initialization and has exclusive control over the vault's configuration. The admin manages roles, fee rates, access control, and vault lifecycle — but cannot move funds or execute strategy operations.
### Role management
The admin assigns and updates the addresses for each vault role:
| Function | What it sets |
| -------------------------- | --------------------------------------------------------- |
| `updateValuationManager()` | Who can propose NAV updates |
| `updateWhitelistManager()` | Who can manage allowlist/blocklist entries |
| `updateFeeReceiver()` | Where fee shares are sent |
| `updateSafe()` | Which Strategy wallet the vault is connected to |
| `updateSecurityCouncil()` | Who can set NAV guardrails and perform emergency bypasses |
| `updateSuperOperator()` | Who can act on behalf of any user for claims and requests |
### Fee configuration
The admin updates fee rates via `updateRates()`. Management and performance rates can be changed freely. Entry and exit rates can only be **decreased** after initial configuration — protecting investors from fee increases post-deployment.
### Vault lifecycle and operations
| Function | What it does |
| --------------------------------- | -------------------------------------------------------- |
| `switchAccessMode()` | Toggle between allowlist and blocklist modes |
| `activateAsyncOnly()` | Permanently and irreversibly disable all sync operations |
| `pause()` | Halt all core operations (deposits, redemptions, claims) |
| `unpause()` | Resume operations |
| `initiateClosing()` | Start the vault closing process |
| `updateName()` / `updateSymbol()` | Update the vault's share token name and symbol |
### Roles recap
| Role | Who sets it | Key responsibilities |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------ |
| **Vault owner (Admin)** | Set at initialization | Assign roles, update fees, pause/unpause, switch access mode |
| **Strategy (Safe)** | Vault owner | Confirm NAV, settle queues, update lifespan, set sync mode, manage deposit cap |
| **Valuation manager** | Vault owner | Propose NAV updates |
| **Whitelist manager** | Vault owner | Manage allowlist/blocklist entries, set external sanctions list |
| **Security Council** | Vault owner | Set NAV guardrails, emergency NAV bypass |
| **Super Operator** | Vault owner | Act on behalf of any user for claims and requests |
| **Fee receiver** | Vault owner | Receives all fee shares (split by Fee Splitter) |
| **Delay Proxy Admin** | Set at deployment | Propose and execute vault upgrades (separate from vault owner) |
### Ownership transfer
Ownership uses a two-step transfer pattern for safety — the current owner calls `transferOwnership(newOwner)`, and the new owner must explicitly call `acceptOwnership()` to complete the transfer. This prevents accidental transfers to incorrect addresses.
## NAV guardrails
NAV guardrails protect the vault against erroneous or malicious NAV updates by enforcing on-chain bounds on price-per-share changes.
### How it works
A **Security Council** role sets upper and lower bounds on annualized price-per-share changes via `updateGuardrails()`. When the valuation manager calls `updateNewTotalAssets()`, the vault:
1. Computes the current price-per-share and the proposed price-per-share
2. Annualizes the change based on time elapsed since the last update
3. Rejects the proposal if the annualized change exceeds the upper bound or falls below the lower bound
The Security Council can activate or deactivate guardrails at any time. The first NAV update after vault initialization is always exempt.
### Emergency bypass
In extreme market scenarios where guardrails would block a legitimate NAV update, the Security Council can call `securityCouncilUpdateTotalAssets()` to propose a NAV **without guardrails checking**. This bypasses the price-per-share bounds entirely.
### Why guardrails matter
* Prevent malicious NAV proposals from a compromised valuation manager
* Protect against oracle manipulation or flash loan attacks on NAV pricing
* Provide a circuit breaker for extreme market events while maintaining an emergency override
## Vault upgrades
The 7540 Vault is an upgradeable proxy contract. A **Delay Proxy Admin** is deployed alongside each vault at creation, enforcing a mandatory timelock (up to 30 days) between proposing and executing any implementation upgrade. The Delay Proxy Admin owner can be different from the vault owner — typically a quorum consisting of Railnet and the Asset Manager — so that no single party can upgrade the vault unilaterally. New implementations must also be whitelisted in a protocol-wide Logic Registry before any upgrade can proceed.
## What to read next
High-level overview of how the vault fits into the Advanced Strategy architecture.
How the Policy Engine enforces on-chain permissions, spending limits, and guardian governance.
Day-to-day operations — execute transactions, manage spending limits, update permissions.
Guardrails, allocation caps, and risk frameworks for strategy operations.