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:
- Transfers amount to receiver
- Calls callback.callback(amount, fee, data)
- 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