> For the complete documentation index, see [llms.txt](https://docs.zestprotocol.com/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zestprotocol.com/start/stacks-vaults/zvstbtc-vault/architecture.md). # Architecture Explore the contracts, permissions, accounting and risk controls behind the zvstBTC Vault on Stacks. The zvstBTC Vault is built from a small set of focused contracts. Like the rest of Zest Protocol V2, it separates **permanent state** from **upgradeable logic**: the piece that custodies funds is designed to never change, while the strategy logic around it can be improved over time without ever migrating balances. ## Architectural Overview
Users interact with the **engine**. The engine mints and burns **zvstBTC** shares, reads and updates the **state** contract that custodies funds, and directs the **operator** to run the leverage strategy against the lending market and Stacking DAO. ## Design Philosophy The vault mirrors the market's split between a permanent state layer and upgradeable logic: * **State that never changes.** The contract that holds depositor funds and settings is designed to be permanent. Because it never needs replacing, funds never have to be migrated. * **Logic that can improve.** The engine and operator hold no balances of their own. If the strategy or accounting logic needs to change, the state contract can be pointed at a new engine or operator, without any risk to the custodied funds. This is the same reasoning behind keeping market positions in `market-vault.clar` while the `market.clar` logic stays upgradeable: put the money somewhere stable, and keep the brains replaceable. ## Core Components ### zvstBTC Token (`zvstBTC.clar`) The share token that represents ownership in the vault. **What It Does:** * A standard SIP-010 fungible token (8 decimals) that you receive when you deposit and that is burned when you withdraw * Your balance is your proportional claim on the vault's Net Asset Value * Its metadata (name, symbol, token URI) can be updated by the DAO **Access Control:** Minting and burning are restricted to the vault's engine. Shares can only ever be created or destroyed by a real deposit or withdrawal, never issued arbitrarily. ### State Contract (`zv-state-stbtc-0.clar`) The vault's permanent vault: it holds the funds and all the settings. **What It Stores:** * **Custody:** the vault's stBTC and sBTC balances live here, isolated from the strategy logic * **Configuration:** the deposit cap, withdrawal cooldown, fees, and enabled/paused flags * **Roles:** who is allowed to do what (owner, guardian, trader, rewarder, manager) * **Withdrawal claims:** the queue of pending withdrawals and their unlock times **Design Philosophy:** Because this contract custodies the money, it is built to be permanent. Sensitive changes to it (like repointing to a new engine or operator, or moving the fee recipient) are protected by an on-chain timelock, giving the community time to review them before they take effect. ### Engine Contract (`zv-engine-stbtc-0.clar`) The brain of the vault: everything a depositor touches goes through the engine. **What It Does:** * **Deposits:** accepts stBTC or sBTC, mints the right number of shares, and enforces the deposit cap * **Withdrawals:** manages the request → cooldown → claim flow and pays users out in stBTC * **Live NAV:** computes the vault's true value on demand, so the share price is always current * **Fees:** crystallizes the performance fee as new shares to the fee recipient, only on genuine new profit above the high-water mark **Design Philosophy:** The engine holds no balances of its own. This means the strategy and accounting logic can be improved over time by pointing the state contract at a new engine, without any risk to the funds the state contract safely holds. ### Operator Contract (`zv-ops-stbtc-0.clar`) The hands of the vault: it carries out the leverage strategy. **What It Does:** * Opens and manages the looped position, borrowing sBTC on the lending market against the vault's stBTC collateral * Stacks and restacks Bitcoin through StackingDAO to compound the staking yield * Unwinds part of the position when withdrawals need to be funded **Access Control:** Only authorized keeper accounts (the trader role) can trigger strategy actions, and even they can only move funds along the predefined strategy path. The operator can never send funds to an arbitrary destination. ### Traits (`zv-traits.clar`) The shared interface definitions that let these contracts talk to each other in a standardized, type-safe way. For example, the interface the engine uses to call the operator. Traits make the upgrade model possible by defining the contract "shapes" that any replacement must conform to. ## Roles and Permissions The vault spreads authority across several roles so that no single key can both custody funds and unilaterally change the rules: * **Owner**: the highest authority, held by the Zest Protocol DAO (`dao-executor`). Governs the sensitive levers: strategy configuration and, through the timelock, core address changes. * **Guardian**: can instantly pause the vault in an emergency. Pausing is fast because it only ever restricts activity, never moves funds. * **Trader**: a keeper account that runs the looping strategy. It can only act along the predefined strategy path. * **Rewarder**: a keeper account for routine yield-related upkeep. * **Manager**: can adjust the deposit cap and help fund withdrawals, so the vault can be scaled and serviced without invoking the full DAO process. Operational roles are held by dedicated keeper accounts with strictly limited permissions, while the powerful controls sit with the DAO. ## Security Architecture The vault layers several protections: * **Fund isolation**: depositor funds live in the permanent state contract, separate from the replaceable logic. * **Constrained operator**: strategy actions can only follow the predefined path; funds can never be redirected elsewhere. * **Health checks**: the looping strategy always keeps the market position over-collateralized and validates every operation. * **Guardian pause**: an instant emergency stop for deposits, withdrawals, and strategy activity. * **Timelocked governance**: sensitive changes to core addresses and settings must wait out an on-chain delay before taking effect. * **Deposit cap**: external inflows are capped and scaled up deliberately, limiting exposure while the strategy matures. ## Summary The zvstBTC Vault is four focused contracts plus a shared trait definition: a share token, a permanent state contract that custodies funds and settings, an upgradeable engine that handles deposits, withdrawals, valuation, and fees, and a constrained operator that runs the leverage strategy. Authority is split across DAO-owned and keeper roles, and depositor funds stay safe behind fund isolation, health checks, a guardian pause, timelocked governance, and a conservative deposit cap.