# 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