Skip to main content

​
Architecture

BTCVault’s smart contract system is built on Cairo 2.14.0 for StarkNet, implementing a comprehensive suite of DeFi vault strategies centered around Bitcoin yield generation. The contracts follow the ERC-4626 tokenized vault standard, enabling composable yield strategies across multiple protocols.

​
Core Design Principles

ERC-4626 Vault Standard: All vaults implement the standardized vault interface, allowing users to deposit assets and receive yield-bearing share tokens. The share price increases as the vault accrues yield from underlying strategies. Curator Pattern: Each vault has an owner (curator) who manages strategy execution, including deploying capital to lending protocols, executing leverage loops, and harvesting yield. Users maintain custody of their vault shares. Ownable & Upgradeable: Contracts use a 2-step ownership transfer pattern for security and implement upgradeable proxies via StarkNet’s replace_class_syscall mechanism. Flash Loan Unwind: Leveraged vaults use Vesu flash loans to atomically unwind positions, ensuring users can always withdraw their funds without manual deleverage steps.

​
Contract Inventory

The following Cairo contracts implement the BTCVault protocol:
ContractLinesPurpose
btcvault.cairo1,210Core BTC yield vault: deposits WBTC into Vesu lending pools with 3x leverage loops for amplified yield
apex.cairo1,502Advanced multi-strategy vault aggregator with dynamic allocation
delta_neutral.cairo1,095Delta-neutral strategy vault combining long BTC collateral with short perpetual positions
trident.cairo1,003Liquidity provision strategy for concentrated liquidity pools (Ekubo)
citadel.cairo751Vault manager and registry for protocol-level coordination
stablecoin_vault.cairo622USDC lending vault on Vesu RE7 USDC Core pool (no leverage)
sentinel.cairo625Simple WBTC lending vault on Vesu without leverage
shielded_pool_v4.cairo660Latest version of privacy-preserving pool using Garaga ZK proofs
shielded_pool_v3.cairo639Privacy pool v3 with Groth16 verification
shielded_pool.cairo490Initial privacy pool implementation
shielded_pool_v2.cairo459Privacy pool v2 iteration
shielded_swap_pool.cairo499Privacy-preserving token swap pool
dca.cairo549Dollar-cost averaging vault for automated periodic purchases
cdp.cairo447Collateralized debt position vault
interfaces.cairo362Interface definitions for Vesu, AVNU, Ekubo, Garaga, Pragma
strategy.cairo47Strategy helper utilities and constants
lib.cairo16Module declarations
Total: 17 contracts, ~10,976 lines of Cairo code

​
Common Patterns

​
Ownable Pattern

All vaults implement 2-step ownership transfer for security: 
fn transfer_ownership(ref self: ContractState, new_owner: ContractAddress) {
    self._assert_owner();
    self.pending_owner.write(new_owner);
}

fn accept_ownership(ref self: ContractState) {
    let caller = get_caller_address();
    assert(caller == self.pending_owner.read(), 'Not pending owner');
    let prev = self.owner.read();
    self.owner.write(caller);
    self.pending_owner.write(Zero::zero());
    self.emit(OwnershipTransferred { previous_owner: prev, new_owner: caller });
}

​
Upgradeable Pattern

Contracts can be upgraded by the curator using StarkNet’s class replacement mechanism: 
fn upgrade(ref self: ContractState, new_class_hash: ClassHash) {
    self._assert_owner();
    starknet::syscalls::replace_class_syscall(new_class_hash).unwrap_syscall();
}

​
Flash Loan Unwind Pattern

Leveraged vaults implement IFlashloanReceiver to enable atomic position unwinding: 
fn on_flash_loan(
    ref self: ContractState,
    sender: ContractAddress,
    asset: ContractAddress,
    amount: u256,
    data: Span<felt252>,
) {
    // 1. Repay all debt using flash loan funds
    // 2. Withdraw all collateral from Vesu
    // 3. Swap collateral to repay flash loan
    // 4. Remaining collateral becomes idle for user withdrawals
}
This pattern ensures users can always exit positions without manual intervention, even when the vault is fully leveraged.

​
Technology Stack

​
Core Dependencies

Cairo 2.14.0: StarkNet’s native smart contract language, providing provable computation and low gas costs. Scarb 2.14.0: Cairo package manager and build tool, similar to Cargo for Rust. Garaga 1.0.1: Zero-knowledge proof verification library for StarkNet, enabling privacy features through Groth16 (BN254) and UltraHonk proof systems. StarkNet 2.14.0: Layer 2 scaling solution for Ethereum with native account abstraction.

​
Protocol Integrations

The contracts integrate with the following StarkNet protocols:
  • Vesu: Lending protocol for collateral deposits and debt borrowing (primary yield source)
  • AVNU: DEX aggregator for optimal swap routing between WBTC and USDC
  • Ekubo: Concentrated liquidity AMM for efficient swaps and LP positions
  • Pragma: Oracle network providing BTC/USD and other price feeds
  • OpenZeppelin: Standard contract implementations (via StarkNet dependency)

​
External Interfaces

Key external interfaces defined in interfaces.cairo:
  • IVesuPool: Lending pool operations (deposit, borrow, modify_position, flash_loan)
  • IERC4626: Tokenized vault standard (deposit, withdraw, redeem, mint)
  • IAvnuExchange: Multi-route swap aggregator
  • IEkuboCore: Concentrated liquidity pool management
  • IGaragaVerifier: Zero-knowledge proof verification (UltraHonk)
  • IGroth16Verifier: Groth16 BN254 proof verification
  • IPragmaOracle: Price feed queries and TWAP calculations

​
Curator Vault Management

The curator role is central to vault operations. Curators are trusted operators who execute strategies on behalf of depositors: Capital Deployment: Deploy idle vault assets to Vesu lending pools: 
fn deploy_to_vesu(ref self: ContractState, amount: u256)
Leverage Execution: Execute leverage loops (deposit → borrow → swap → re-deposit): 
fn execute_leverage_loop(
    ref self: ContractState,
    collateral_amount: u256,
    borrow_amount: u256,
    min_swap_out: u256,
    routes: Array<Route>,
)
Position Unwinding: Atomically close leveraged positions using flash loans: 
fn flash_unwind(
    ref self: ContractState,
    wbtc_to_sell: u256,
    min_usdc_out: u256,
    routes: Array<Route>,
)
Yield Harvesting: Update vault accounting to reflect accrued interest: 
fn harvest(ref self: ContractState)
Curators cannot withdraw user funds directly—they only manage strategy execution. Users maintain full custody through their vault share tokens.

​
Security Features

  • Pausable: Vaults can be paused by curator in emergencies
  • 2-Step Ownership Transfer: Prevents accidental ownership loss
  • Slippage Protection: All swaps require minimum output amounts
  • Dust Threshold Validation: Vesu positions must meet minimum value requirements
  • Flash Loan Security: Callbacks verify sender is the vault itself
  • Atomic Operations: Leverage loops and unwinds execute atomically to prevent partial state

​
Next Steps

Deployment Guide

Learn how to build and deploy Cairo contracts to StarkNet

API Reference

Explore contract interfaces and function signatures

Build docs developers (and LLMs) love

Get started for freeTalk to us