# Vaults **Purpose:** Individual asset vaults issuing ztokens (vault shares). Manages lending, interest accrual, flashloans. All 6 vaults share the same interface. ## Vault Contracts * **vault-stx**: STX vault, issues zSTX (6 decimals) * **vault-sbtc**: sBTC vault, issues zsBTC (8 decimals) * **vault-ststx**: stSTX vault, issues zstSTX (6 decimals) * **vault-usdc**: USDC vault, issues zUSDC (6 decimals) * **vault-usdh**: USDH vault, issues zUSDH (6 decimals) * **vault-ststxbtc**: stSTXbtc vault, issues zstSTXbtc (6 decimals) Note: All vaults are 6 decimals except vault-sbtc (8 decimals, matching Bitcoin). *** ## List of Core Functions SIP-10 Token Standard: * get-name — Vault token name * get-symbol — Vault token symbol * get-token-uri — Token metadata URI * get-decimals — Token decimals * get-total-supply — Total zToken shares * get-balance — User's zToken balance * transfer — Transfer zTokens Configuration: * initialize — Initialize vault (one-time, deployer only) * set-authorized-contract — Authorize contract for special permissions * set-flashloan-permissions — Set flashloan permissions for account * set-flashloan-permissions-many — Batch set flashloan permissions * set-cap-debt — Update borrow cap * set-cap-supply — Update supply cap * set-fee-flash — Update flashloan fee * set-fee-reserve — Update reserve fee * set-default-flashloan-permissions — Set default flashloan permissions * set-points-util — Update utilization breakpoints * set-points-rate — Update interest rates * set-token-uri — Update token URI * set-pause-states — Pause/unpause operations Queries: * is-authorized-contract — Check if contract is authorized * get-cap-debt — Get borrow cap * get-cap-supply — Get supply cap * get-fee-flash — Get flashloan fee (BPS) * get-fee-reserve — Get reserve fee (BPS) * get-default-flashloan-permissions — Get default flashloan permissions * get-flashloan-permissions — Get account-specific flashloan permissions * get-points-util — Get utilization breakpoints * get-points-rate — Get interest rates * get-pause-states — Get pause configuration * get-available-assets — Get available liquidity for borrowing Vault Operations: * get-assets — Total underlying assets in vault * get-total-assets — Preview total assets (includes accrued interest) * convert-to-shares — Convert underlying to zToken shares * convert-to-assets — Convert zToken shares to underlying * deposit — Supply underlying, receive zTokens * redeem — Burn zTokens, receive underlying Lending Operations: * get-principal-scaled — Scaled debt (principal) * get-index — Borrow index (compound interest accrual) * get-last-update — Last accrual timestamp * get-debt — Total borrowed * get-utilization — Utilization ratio (borrowed / assets) * get-interest-rate — Current borrow APR (BPS) * get-next-index — Next borrow index after accrual * get-principal-ratio-reduction — Ratio reduction calculation * get-liquidity-index — Liquidity index (for zToken pricing) * get-underlying — Underlying token contract * accrue — Accrue interest and update indexes * system-borrow — Borrow (market auth only) * system-repay — Repay (market auth only) * socialize-debt — Distribute bad debt to suppliers (market auth only) Flashloan: * flashloan — Execute flashloan with callback *** ## Function Parameters ### SIP-10 Functions #### get-name Get vault token name (e.g., "Zest STX"). Parameters: none Returns: (response (string-ascii 32) uint) — Token name *** #### get-symbol Get vault token symbol (e.g., "zSTX"). Parameters: none Returns: (response (string-ascii 32) uint) — Token symbol *** #### get-token-uri Get token metadata URI. Parameters: none Returns: (response (optional (string-utf8 256)) uint) — Token URI or none *** #### get-decimals Get token decimals (6 for most vaults, 8 for sBTC). Parameters: none Returns: (response uint uint) — Decimals *** #### get-total-supply Get total zToken shares outstanding. Parameters: none Returns: (response uint uint) — Total supply *** #### get-balance Get user's zToken balance. Parameters: * account — principal — User address Returns: (response uint uint) — Balance *** #### transfer Transfer zTokens between accounts. Parameters: * amount — uint — Amount to transfer * from — principal — Sender address * to — principal — Recipient address * memo — (optional (buff 34)) — Optional memo Returns: (response bool uint) — Success or error Authorization: Must be called by 'from' address *** ### Configuration Functions #### initialize Initialize vault. One-time setup by deployer. Parameters: none Returns: (response bool uint) — Success or error Authorization: Deployer only, one-time *** #### set-authorized-contract Authorize contract for special permissions (e.g., whitelisted flashloan access). Parameters: * contract — principal — Contract address * authorized — bool — True to authorize, false to revoke Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-flashloan-permissions Set flashloan permissions for specific account. Parameters: * account — principal — Account address * perms — { allowed: bool, fee: uint } — Permissions (allowed flag + custom fee in BPS) Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-flashloan-permissions-many Batch set flashloan permissions for multiple accounts. Parameters: * entries — (list 64 { account: principal, perms: {...} }) — List of account permission pairs Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-cap-debt Update borrow cap for vault. Parameters: * val — uint — New borrow cap (max total debt allowed) Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-cap-supply Update supply cap for vault. Parameters: * val — uint — New supply cap (max total assets allowed) Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-fee-flash Update flashloan fee. Parameters: * val — uint — New flashloan fee (BPS, e.g., 9 = 0.09%) Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-default-flashloan-permissions Set default flashloan permissions for accounts without specific settings. Parameters: * perms — { allowed: bool, fee: uint } — Default permissions Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-fee-reserve Update reserve fee (protocol fee on interest). Parameters: * val — uint — New reserve fee (BPS, e.g., 1000 = 10% of interest) Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-points-util Update utilization breakpoints for interest rate curve. Parameters: * points — (list 8 uint) — List of 8 utilization breakpoints (BPS, ascending order) Returns: (response bool uint) — Success or error Authorization: DAO executor only Example: \[0, 4000, 7000, 9000, 10000, 10000, 10000, 10000] = \[0%, 40%, 70%, 90%, 100%, ...] *** #### set-points-rate Update interest rates at utilization breakpoints. Parameters: * points — (list 8 uint) — List of 8 interest rates (BPS APR) at corresponding utilization breakpoints Returns: (response bool uint) — Success or error Authorization: DAO executor only Example: \[200, 500, 1000, 2000, 3000, 3000, 3000, 3000] = \[2%, 5%, 10%, 20%, 30%, ...] *** #### set-token-uri Update token metadata URI. Parameters: * new-uri — (optional (string-utf8 256)) — New URI or none Returns: (response bool uint) — Success or error Authorization: DAO executor only *** #### set-pause-states Configure pause states for operations. Parameters: * states — { deposit: bool, redeem: bool, borrow: bool, repay: bool, accrue: bool, flashloan: bool } — Pause configuration for each operation Returns: (response bool uint) — Success or error Authorization: DAO executor only *** ### Query Functions #### is-authorized-contract Check if contract is authorized for special permissions. Parameters: * contract — principal — Contract address Returns: bool — True if authorized *** #### get-cap-debt Get current borrow cap. Parameters: none Returns: (response uint uint) — Borrow cap *** #### get-cap-supply Get current supply cap. Parameters: none Returns: (response uint uint) — Supply cap *** #### get-fee-flash Get flashloan fee in basis points. Parameters: none Returns: (response uint uint) — Fee (BPS) *** #### get-fee-reserve Get reserve fee in basis points. Parameters: none Returns: (response uint uint) — Fee (BPS) *** #### get-default-flashloan-permissions Get default flashloan permissions. Parameters: none Returns: { allowed: bool, fee: uint } — Default permissions *** #### get-flashloan-permissions Get flashloan permissions for specific account. Parameters: * account — principal — Account address Returns: { allowed: bool, fee: uint } — Permissions (falls back to default if not set) *** #### get-points-util Get utilization breakpoints for interest rate curve. Parameters: none Returns: (response (list 8 uint) uint) — Utilization breakpoints (BPS) *** #### get-points-rate Get interest rates at utilization breakpoints. Parameters: none Returns: (response (list 8 uint) uint) — Interest rates (BPS APR) *** #### get-pause-states Get pause configuration for operations. Parameters: none Returns: (response {...} uint) — Pause states for all operations *** #### get-available-assets Get available liquidity for borrowing (total assets - debt). Parameters: none Returns: (response uint uint) — Available assets *** ### Vault Operations #### get-assets Get total underlying assets in vault (excludes accrued interest). Parameters: none Returns: (response uint uint) — Total assets *** #### get-total-assets Preview total assets including accrued interest (without updating state). Parameters: none Returns: (response uint uint) — Total assets with accrued interest *** #### convert-to-shares Convert underlying amount to zToken shares. Parameters: * amount — uint — Underlying amount Returns: (response uint uint) — zToken shares Formula: shares = amount × total\_supply / total\_assets *** #### convert-to-assets Convert zToken shares to underlying amount. Parameters: * amount — uint — zToken shares Returns: (response uint uint) — Underlying amount Formula: assets = shares × total\_assets / total\_supply *** #### deposit Supply underlying tokens, receive zToken shares. Parameters: * amount — uint — Underlying amount to deposit * min-out — uint — Minimum zToken shares expected (slippage protection) * recipient — principal — Address to receive zTokens Returns: (response uint uint) — zToken shares minted Note: Transfers underlying from caller to vault, mints zTokens to recipient *** #### redeem Burn zToken shares, receive underlying tokens. Parameters: * amount — uint — zToken shares to redeem * min-out — uint — Minimum underlying expected (slippage protection) * recipient — principal — Address to receive underlying Returns: (response uint uint) — Underlying tokens received Note: Burns zTokens from caller, transfers underlying to recipient *** ### Lending Operations #### get-principal-scaled Get scaled debt principal (before interest accrual). Parameters: none Returns: (response uint uint) — Scaled debt *** #### get-index Get current borrow index for compound interest accrual. Parameters: none Returns: (response uint uint) — Borrow index *** #### get-last-update Get timestamp of last interest accrual. Parameters: none Returns: (response uint uint) — Timestamp *** #### get-debt Get total actual debt (scaled × index, includes accrued interest). Parameters: none Returns: (response uint uint) — Total debt *** #### get-utilization Get utilization ratio (borrowed / total\_assets). Parameters: none Returns: (response uint uint) — Utilization (BPS, 10000 = 100%) *** #### get-interest-rate Get current borrow APR based on utilization and interest rate curve. Parameters: none Returns: (response uint uint) — Borrow APR (BPS) *** #### get-next-index Preview next borrow index after accrual (without updating state). Parameters: none Returns: (response uint uint) — Next index *** #### get-principal-ratio-reduction Calculate principal ratio reduction for given amount. Parameters: * amount — uint — Amount to calculate ratio for Returns: (response uint uint) — Ratio reduction *** #### get-liquidity-index Get liquidity index for zToken pricing (supply side interest accrual). Parameters: none Returns: (response uint uint) — Liquidity index *** #### get-underlying Get underlying token contract address. Parameters: none Returns: (response principal uint) — Underlying token address *** #### accrue Accrue interest and update borrow and liquidity indexes. Parameters: none Returns: (response { index: uint, lindex: uint } uint) — Updated indexes Note: Public function, anyone can call to update interest accrual *** #### system-borrow Borrow underlying from vault. Market contract authorization required. Parameters: * amount — uint — Amount to borrow * receiver — principal — Address to receive borrowed tokens Returns: (response bool uint) — Success or error Authorization: Market contract only Note: Increases scaled debt, transfers underlying to receiver *** #### system-repay Repay borrowed debt. Market contract authorization required. Parameters: * amount — uint — Amount to repay Returns: (response bool uint) — Success or error Authorization: Market contract only Note: Decreases scaled debt, transfers tokens from market-vault to vault *** #### socialize-debt Distribute bad debt across all suppliers. Market contract authorization required. Parameters: * scaled-amount — uint — Scaled debt amount to socialize Returns: (response bool uint) — Success or error Authorization: Market contract only Note: Reduces scaled debt without repayment, socializing loss to zToken holders *** ### Flashloan #### flashloan Execute flashloan with callback. Borrower must repay amount + fee in same transaction. Parameters: * amount — uint — Amount to borrow * receiver — (optional principal) — Optional recipient (defaults to caller) * callback — — Callback contract implementing flash-callback trait * data — (optional (buff 4096)) — Optional data passed to callback Returns: (response bool uint) — Success or error Process: 1. Transfers amount to receiver 2. Calls callback.callback(amount, fee, data) 3. Verifies amount + fee repaid Note: Flashloan permissions and fees checked per account or default settings *** ## Vault Traits ### tokenized-vault SIP-10 + vault share operations: get-name, get-symbol, get-token-uri, get-decimals, get-total-supply, get-balance, transfer, get-assets, convert-to-shares, convert-to-assets, deposit, redeem ### flash-callback Callback interface for flashloan recipients. Must implement: callback(amount, fee, data) -> (response bool uint) ### flashloan Flashloan interface. Must implement: flashloan(amount, receiver, callback, data) -> (response bool uint) ### lending Lending operations interface: get-principal-scaled, get-index, get-last-update, get-debt, get-utilization, get-interest-rate, get-next-index, get-principal-ratio-reduction, get-liquidity-index, get-underlying, accrue, system-borrow, system-repay, socialize-debt ### reserve Reserve configuration interface (caps, fees, interest curve): get-cap-debt, get-cap-supply, set-cap-debt, set-cap-supply, get-fee-flash, get-fee-reserve, set-fee-flash, set-fee-reserve, get-points-util, get-points-rate, set-points-util, set-points-rate --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zestprotocol.com/start/stacks-market-v2-smart-contracts-overview/v2-contracts/vaults.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.