> 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/platform/product-mechanics/how-curated-vaults-work/vault-modules-and-roles.md). # Vault modules and roles The contracts behind each Curated Vault, the nine service modules they implement, the roles that operate them and the governance layer above them. A Curated Vault is its own set of contracts with its own mandate. The vault contract sits at the centre, taking requests and issuing Receipt Tokens, and one module for each control surrounds it: the access policy, the limit module, the report oracle, the settlement module, the fee manager, the strategy manager and the vault registry. Operating duties are split across separate roles, and a security governance layer of multisig approval, timelocks, signer quorums, whitelists and pause controls sits above them. ## The vault at contract level The Curated Vault contracts implement tokenized-vault share accounting with asynchronous requests, following three interface standards.
StandardWhat it defines in a Curated Vault
ERC-4626Share accounting: deposits, withdrawals and conversion between the vault asset and Receipt Tokens
ERC-7540Asynchronous requests: a deposit or redemption request stays pending until its epoch settles and then becomes claimable
ERC-7575Share discovery: integrators locate the share token and its vault through a standard interface
The vault contract runs in one of four liquidity configurations. Its contract surface includes `Base7540Vault`, `FullyAsyncVault`, `SyncDepositAsyncRedeemVault`, `AsyncDepositVault` and `AsyncRedeemVault`: a fully asynchronous vault takes deposits and redemptions as requests, and a synchronous-deposit, asynchronous-redemption vault mints Receipt Tokens at once at the current share price and takes redemptions as requests. * **Receipt Tokens:** Receipt Tokens follow ERC-20 semantics with 18-decimal share precision. Investor-to-investor transfers can be disabled through `shareTransferEnabled` for permissioned products that restrict secondary transfer. * **Atomic actions:** A deposit, redemption, settlement or strategy execution either passes every check or reverts as a whole, so no partial deposit, partially priced redemption, partially minted share or partially executed strategy call can exist. * **Immutable code:** The vault contracts are not proxy-upgradeable. Change runs through role-governed configuration, manager replacement, oracle replacement, strategy policy and registry state, and a new contract version is deployed as a new vault, leaving existing positions under their original code. ## Vault types The infrastructure supports four vault types, and each type carries its own operating requirements. | Vault type | Where capital goes | What the type requires | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | RWA-backed lending | Loans or receivables backed by real-world or digital-asset collateral, for private credit, secured lending, invoice finance or structured credit | Collateral monitoring, borrower reporting, reserve verification, liquidation policies and redemption scheduling | | Market-neutral strategy | Strategies that reduce directional exposure while capturing trading inefficiencies, funding spreads, liquidity premiums or statistical arbitrage | Approved exchange lists, position monitoring, leverage limits, drawdown controls and frequent NAV reporting | | Treasury and cash management | Low-duration, high-liquidity instruments or cash-equivalent strategies | Reserve verification, clear asset eligibility rules, conservative duration limits and fast redemption design | | DeFi yield | Approved lending markets, liquidity venues, restaking strategies or structured DeFi positions | Smart contract risk monitoring, protocol whitelisting, oracle checks and strategy exposure reporting | The infrastructure also supports three vault product lines, each with its own risk profile. * **Core strategy vault:** An isolated, programmable vault that encodes one complete onchain strategy together with its execution, risk limits and withdrawal logic. * **Multi-vault:** A top-level vault that aggregates several isolated sub-vaults, so the curator can rebalance liquidity across protocols. * **Yield-bearing stable vault:** The most conservative of the three, earning the base yield of DeFi lending markets and overcollateralized stablecoin strategies. The mandate that each vault carries and the parameters it configures are set out in [Mandate, execution and parameters](/docs/platform/product-mechanics/how-curated-vaults-work/mandate-execution-and-parameters.md). ## Service modules At the service level, the vault infrastructure consists of nine modules. Seven are implemented by the contract modules deployed with each vault. The indexing layer and the operations dashboard are offchain services that read the events the contracts emit, and they hold no role in any vault contract. | Module | Function | Implemented by | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Vault contract | Receives deposits, issues Receipt Tokens, tracks balances, processes withdrawals and enforces the core vault rules | Vault contract | | Policy controller | Stores the configurable parameters: deposit caps, accepted assets, fee rates, redemption windows and risk thresholds | Vault contract, limit module, fee manager, report oracle and strategy manager, each holding its own parameters | | Security layer | Checks permissions, deposit limits, allocation rules, approved strategies and emergency conditions | Access policy and limit module, with the vault's pause flags | | Strategy registry | Defines whitelisted strategies, approved venues, allocation quotas and strategy-specific limits | Strategy manager | | NAV oracle | Publishes validated NAV updates under signer, quorum and deviation policies | Report oracle, with its pricing module | | Accounting engine | Tracks total assets, liabilities, fees, strategy debt, yield accrual and share pricing | Vault contract, settlement module, fee manager and strategy manager | | Redemption manager | Handles redemption requests, epoch closures, price locks, liquidity checks and claim execution | Settlement module, with the vault's request flow | | Indexing layer | Indexes deposits, withdrawals, fees, NAV reports, strategy debt, settlement records, permission changes and vault events | Offchain indexer, discovering vaults through the vault registry | | Operations dashboard | Displays live data feeds, monitoring views, reports, alerts and vault status for operators and partners | Offchain service reading the indexing layer |
The vault contract at the centre of one vault's contracts, with the policy controller above, the security layer and strategy registry on either side, and the NAV oracle, redemption manager and accounting engine below; events flow out to the offchain indexing layer and operations dashboard

One Curated Vault and its service modules. Requests pass the security layer on entry, reports reach settlement through the NAV oracle, allocations leave through the strategy registry, and every module emits events to the offchain services.

### Vault contract The vault contract is the participant-facing surface of the vault, implemented by `Base7540Vault` and its liquidity configurations. * **Holds:** Idle assets, pending deposit assets until settlement, Receipt Tokens submitted for redemption until they are burned, the Receipt Tokens and assets claimable from settled epochs, and the controller and epoch of every request. * **Checks:** Every user-facing call passes the security layer, product status and the pause flags for the global vault, deposits, redemptions and share transfers before any state changes. * **Emits:** An event for each deposit, redemption request, claim, share transfer and pause change. * **Called by:** Participants, directly or through an integration partner's interface, for requests and claims; holders of the settlement role for epoch settlement; holders of `DEFAULT_ADMIN_ROLE` for `rescueToken`, which recovers unrelated tokens sent to the vault by mistake, requires a nonzero recipient and cannot touch the underlying vault asset. * **On failure:** The call reverts as a whole, and no partial deposit, partial mint or partial redemption is recorded. ### Policy controller No single contract holds every parameter: each parameter lives in the module that enforces it, under the role that governs it. * **Holds:** The accepted asset in the vault contract; `maxTotalAssets`, `maxPendingDepositAssets`, `minDepositAssets` and `minRedeemShares` in the limit module; fee rates, the protocol split and the `feeReceiver` in the fee manager; the quorum, `maxReportAge` and `maxNavPriceDeviationBps` in the report oracle and pricing module; allowlists and debt caps in the strategy manager. * **Checks:** Each value against its hard-coded bound: fees cannot exceed the caps written into the fee manager, entry and exit fees can only decrease once the vault is initialized, and the deviation tolerance cannot rise above 10,000 bps. * **Emits:** Fee changes, quorum updates, strategy policy updates and role changes, so every parameter change is visible to monitoring. * **Called by:** The role that governs each parameter, such as fee management for fees, `PRICING_ROLE` for the deviation tolerance and the oracle roles for quorum and freshness. Sensitive changes need the multisig, and high-impact changes also pass through the timelock. * **On failure:** A value outside its bound reverts, and a change queued in the timelock takes effect only after the delay. ### Security layer The security layer is the entry gate: every deposit and redemption request passes it before any asset moves. * **Holds:** The access mode, `Open` or `Policy`; the allowlist, denylist and signed-authorization policies with their nonces; and the limits held in the limit module. * **Checks:** In policy mode, every user-facing flow calls `validateAccess` or `validateAccessPair`, which lets the policy update state, consume a nonce or verify an EIP-712 signature bound to the call data, the vault, the account, a nonce, an expiration block, the chain identifier and the verifying contract domain. The limit module checks each request against the caps on total assets and pending deposits and the minimum deposit and redemption sizes, and the vault reads its pause flags before any state change. * **Emits:** Role changes and pause events. The access mode, the policy and the limits are readable onchain, and read-only previews call `canAccess`. * **Called by:** The vault, on every deposit and redemption request; the whitelist manager, through the access policy management role, for list changes. * **On failure:** The request reverts before any asset moves. A successful signed authorization increments the nonce, so the same signature cannot be replayed. ### Strategy registry The strategy manager module implements the strategy registry and bounds every action taken with vault capital. * **Holds:** The strategy allowlist with each strategy's kind, the per-strategy and total strategy debt caps, the allowed call targets and selectors, and each strategy's current debt. * **Checks:** Strategy kind validation; adapter `vault()` and `asset()` binding; the debt caps on every allocation; an allowed strategy, an onchain adapter kind, an approved target and an approved selector on every call; return values; and the vault's balance delta after every action. Claimable redemption assets are excluded from `availableIdleAssetsForStrategy`, and pending deposit assets stay excluded from strategy availability until settlement. * **Emits:** Strategy policy updates and changes in strategy debt, and monitoring watches idle strategy availability for unexpected changes. * **Called by:** Separate roles for strategy configuration, allocation, execution, verifier management, pause and unpause. * **On failure:** Any failed check reverts the entire transaction, and the allocation pause and the execution pause halt allocation or execution on their own. ### NAV oracle The report oracle and its pricing module decide which NAV report settlement can use. * **Holds:** The enabled reporters, the quorum, `maxReportAge`, versioned NAV reports with their approvals and optional metadata hashes, the active NAV and the settlement price-deviation tolerance, at most 10,000 bps. * **Checks:** Only enabled reporters can submit or approve a report; enough distinct reporters must approve the same digest; each reporter approves a report once; a report cannot be computed in the future, be older than `maxReportAge` or predate the close of its epoch; the digest binds the network identifier and the oracle contract address; and settlement reverts when the price moves beyond the tolerance. * **Emits:** Reporter changes, quorum updates and NAV updates. * **Called by:** Authorized reporters, who submit and approve reports once the valuation provider proposes the NAV; the oracle roles, for reporter membership, quorum and freshness policy; and `PRICING_ROLE`, which can raise the tolerance to at most 10,000 bps. * **On failure:** The report never becomes eligible and settlement cannot consume it, and the product pauses subscriptions, redemptions or both until the issue is resolved. The valuation process behind each report is set out in [NAV, oracle and proof of deployment](/docs/platform/product-mechanics/how-curated-vaults-work/nav-oracle-and-proof-of-deployment.md). ### Accounting engine The accounting engine is the vault's ledger, spread across the modules that own each figure. * **Holds:** Total assets and the Receipt Tokens outstanding in the vault contract; strategy debt in the strategy manager; accrued fees and the high-water mark on assets per share in the fee manager; and each epoch's settlement snapshot of report identifier, price, fees, protocol split and timestamp in the settlement module. * **Checks:** Fees accrue under the hard caps; the performance fee accrues only on new profits above the high-water mark; deposit epochs snapshot the entry fee and the protocol split, and redemption epochs snapshot the exit fee and the protocol split. * **Emits:** Epoch price and settle events and fee changes. * **Called by:** Vault-controlled calls, which accrue the management and performance fees; the settlement module, which writes each snapshot; the fee manager, which mints fee shares to the fee receiver at settlement. * **On failure:** A later NAV report, fee change or strategy event never alters a settled epoch, because settled claims read only their own snapshot. NAV and NAV per share follow the formula in [How Curated Vaults work](/docs/platform/product-mechanics/how-curated-vaults-work.md#nav-and-share-price), and fees are set out in [Fees](/docs/platform/product-mechanics/fees.md). ### Redemption manager The settlement module, together with the vault's request flow, runs every epoch from close to claim. * **Holds:** The open epoch, the closed epochs awaiting pricing, the assets owed for each settled epoch and whether each epoch is fulfilled. * **Checks:** That the epoch has closed, that an eligible report exists for it, and that idle settlement assets cover the whole epoch before it is marked fulfilled. * **Emits:** Epoch close, price and settle events, and a claim event for each participant. * **Called by:** Holders of the settlement role, who decide when each batch is priced; each participant, who claims their own redemption. * **On failure:** An epoch without an eligible report stays unpriced, and an epoch whose idle assets fall short stays pending until the settlement assets arrive, so no claim is paid against unavailable funds. The redemption stages are set out in [Deposits, capital flow and redemption](/docs/platform/product-mechanics/how-curated-vaults-work/deposits-capital-flow-and-redemption.md#redemption-architecture). ### Indexing layer The indexing layer turns contract events into a queryable history for reporting and integration. * **Holds:** An indexed history of deposits, withdrawals, fees, NAV reports, strategy debt, settlement records, permission changes and vault events, with vault lists and daily TVL snapshots. * **Checks:** It discovers vaults through the vault registry, which records each vault's address, underlying asset, strategy manager, report oracle, type, name, symbol and active flag; registration requires `REGISTRAR_ROLE` and validates that the strategy manager is bound to the same vault and asset. * **Emits:** Query results for partner applications and for the [Portfolio SDK](/docs/developers/city-protocol-sdk/vault/portfolio-sdk.md), whose `CityPortfolioClient` serves `getVaults`, `getUserTransactions` and `getVaultTvls`. * **Called by:** Partner applications, dashboards and integrators, which read indexed history through the Portfolio SDK and live state through `CityClient`. * **On failure:** It holds no assets and no role, so an outage delays reporting and leaves settlement, claims and every onchain check unchanged; live state stays readable onchain. ### Operations dashboard The operations dashboard gives operators, risk teams and partners a live view of each vault's operational health. * **Holds:** Live data feeds, monitoring views, reports, alerts and vault status. * **Checks:** Role changes, reporter changes, quorum updates, NAV updates, epoch close, price and settle events, pause events, fee changes, strategy policy updates and registry changes, and any unexpected change in idle strategy availability, claimable redemptions, pending deposits or cached NAV. * **Emits:** Alerts to operators and risk teams, and the views that participants and partners read: onchain event logs, strategy exposure, vault capacity, redemption queue depth, NAV history, settlement records, fee accrual and emergency pause status. An independent proof-of-solvency dashboard lets anyone verify Curated Vault TVL in real time, and live vault data is published at [dune.com/cityprotocol/venzo-vaults](https://dune.com/cityprotocol/venzo-vaults). * **Called by:** Operators, risk teams, integrators and partner applications. * **On failure:** It holds no role in any vault contract. An operator who acts on an alert does so through the pause role, and the contracts enforce every check whether or not the dashboard is online. ## Participants and roles Each participant in a Curated Vault holds a limited scope, and the contracts enforce the boundary of each one. | Role | Scope | Can | Cannot | | ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Participant (LP) | Capital and claims | Deposit an accepted asset, hold Receipt Tokens or a pending request, monitor the vault, redeem under its liquidity terms and cancel a deposit request before settlement where the configuration allows it | Bypass the access policy, limits or pause state, or cancel a redemption request once submitted | | Vault creator or curator | Mandate and settlement timing | Define the mandate, eligible assets, strategy rules, fee policy within the caps, risk limits and distribution policy, and decide when each deposit and redemption batch settles | Set the settlement price, exceed a fee cap, alter a settled epoch or claim redemption assets for a participant | | Strategy manager | Tactical execution | Allocate idle assets to allowlisted strategies within debt caps, choose among approved venues, rebalance inside the mandate and return capital for redemptions | Change accepted assets, bypass investor permissions, exceed allocation quotas, use unapproved venues, alter redemption logic or oracle policy, or remove emergency controls | | Valuation provider | Pricing inputs | Propose the NAV that sets the settlement price per share, which drives the Receipt Tokens minted, the assets redeemed and the fees applied | Make a report eligible without reporter quorum, settle an epoch or allocate capital | | NAV signers or reporters | NAV approval | Submit and approve NAV reports, each reporter once per report | Make a report eligible alone, or have settlement accept a stale report, an early report or a price beyond the tolerance | | Third-party verifier | Independent verification | Verify reserves, collateralization, service-provider data, strategy exposure, settlement records and proof of deployment | Move assets, change configuration or publish a NAV on its own | | Governance or guardian | High-sensitivity actions | Approve parameter changes, strategy approvals, oracle or manager replacement and new vault deployments through the multisig and the timelock, and trigger emergency pauses | Alter a settled epoch, lift a fee cap written into the fee manager or change the code of a deployed vault | | Whitelist manager | Access control | Maintain the allowlist of depositors on KYC- or KYB-gated vaults through the access policy management role | Price, settle, allocate or change fees | | Vault admin | Configuration and safety | Govern configuration and safety controls, change critical parameters such as fee rates within the caps and pause the vault in an emergency | Run the strategy, raise a fee above its hard cap or rescue the underlying vault asset | | Integration partner | Distribution | List the vault in a partner application, wallet or API and SDK integration, and pass each participant's requests to the vault | Bypass the access policy, limits or pause state, which apply to every request whatever interface submits it | The strategy manager module is the contract; the strategy manager in the table is the operator that calls it through the allocation and execution roles. ### Separated roles Permissions are assigned by function and by contract through OpenZeppelin `AccessControl`. Settlement, pricing, access policy, fee management, strategy configuration, strategy execution, oracle membership, pause and unpause are separate roles. * **Vault contract:** Default administration, settlement, pricing, access policy management, emergency pause, unpause, fee management and protocol fee management. * **Strategy manager:** Strategy configuration, allocation, execution, verifier management, pause and unpause. * **Report oracle:** Reporter membership, quorum and freshness policy. * **Vault registry:** Registration and metadata refresh, under `REGISTRAR_ROLE`. The split limits the reach of any single role: a settlement operator cannot update access policy, a pricing operator cannot allocate capital, and a strategy executor cannot change debt caps. Deployment scripts assign administration to the deployer at first, and operational setup transfers sensitive roles to a multisig or the timelock before a product goes live.
A deposit request passes reporters, the settlement role, the allocation role and the execution role before it reaches a strategy, while the access policy, oracle, pricing and strategy configuration roles set the bounds of each gate, and pause and unpause are separate roles

Separation of duties. Four different roles stand between a deposit request and a strategy, other roles set the bounds each one enforces, and no single role moves participant assets.

{% hint style="success" %} **Separated control:** Moving participant assets requires more than one role. **Why it holds:** Assets reach a strategy only through the allocation role, within debt caps that the strategy configuration role sets, and only through calls that the execution role makes to approved targets with approved selectors. Prices come from reports that reporters sign under quorum, and the settlement role can apply only such a report. The whitelist confers execution rights only, `rescueToken` cannot touch the underlying vault asset, and each participant claims their own redemption. {% endhint %} ## Security governance layer A security governance layer reduces operational and key-person risk. Six controls make it up, and each guards a different surface of the vault. | Control | What it guards | How it is enforced | | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 3-of-5 multisig | Sensitive governance actions on the vault infrastructure, against the compromise of a single key | Sensitive roles move to multisig wallets or the timelock before a product goes live | | Execution timelock | High-impact changes, which participants and monitoring systems can observe before they take effect | An OpenZeppelin TimelockController with a configurable delay, proposer and administrator and an optional open executor; the default delay is 24 hours, with longer delays for high-impact actions | | NAV signer quorum | NAV updates, which need approval from several authorized parties | Distinct reporters approve the same report digest; a vault can require several independent signers, for example a three-of-three quorum | | Strategy whitelisting | Capital deployment, restricted to approved strategies and venues | Strategy allowlists, approved targets and selectors, and per-strategy and total debt caps; the whitelist confers execution rights only | | Emergency pause | Deposits, redemptions, share transfers, allocation and strategy execution during extreme market or security events | Layered pause flags, with separate pause and unpause roles so that emergency response is fast and resumption requires review | | Role-based permissions | Every privileged function, with limited privileges for curators, strategy managers, signers, guardians and operators | OpenZeppelin AccessControl assigns each permission by function and by contract |
Configuration changes, NAV updates, capital deployment and emergencies each pass role-based permissions and then their own control, the multisig and timelock, the signer quorum, strategy whitelisting, or the separate pause and unpause roles, before they reach the Curated Vault

The security governance layer. Every surface that can change a vault passes role-based permissions and then a control of its own before it reaches participant assets and settled economics.

Automated circuit breakers act under the same layer. They pause the affected functions on NAV deviation beyond policy, collateralization below the minimum, stale oracle data, unauthorized strategy debt, allocation above quota, abnormal withdrawal pressure, signer quorum failure, suspicious transaction patterns or an emergency governance action. The pause layers and the unwind rules are set out in [Risk isolation and emergency controls](/docs/security/security-and-risk/risk-isolation-and-emergency-controls.md). Before production deployment, each product is checked for multisig or timelock role transfer, deployer role handling, oracle reporter and quorum policy, `maxReportAge`, `maxNavPriceDeviationBps`, fee disclosures, strategy allowlists and caps, pause and unpause separation, registry records and block explorer source verification. Together, these controls place each vault under stricter management than an unrestricted contract or a discretionary offchain account. The contract-level detail of each control is set out in [Contract security](/docs/security/security-and-risk/contract-security.md), and the decision levels that hold the protocol roles in [Governance](broken://pages/HxPJhRHljsfK0c1wCWbs).