Skip to content
BranchesTags

Latest commit

 

History

31 Commits

Folders and files

Repository files navigation

BTCFi Strategy Vault

Your BTC capital never sleeps. Auto-switches between Ekubo LP and Vesu Lending based on oracle price — zero idle capital.

Cairo 2.14 Starknet Sepolia ERC-4626 Ekubo + Vesu + Pragma

Table of Contents

Problem & Solution

strkBTC is bringing native BTC to Starknet — unlocking real BTC-denominated DeFi for the first time. But without smart yield infrastructure, BTC holders face a familiar problem: concentrated LP positions on Ekubo earn 0% yield the moment price drifts out of range. Existing solutions (like Re7) re-range the LP — crystallizing impermanent loss. Capital sits idle, and holders lose out.

BTCFi Strategy Vault solves this. It detects out-of-range conditions via Pragma oracle and escapes to Vesu lending (3-5% APY). When price returns to range, it returns to Ekubo LP automatically. All on-chain, all verifiable.

The current MVP uses wBTC on Sepolia testnet. Phase 2 will integrate strkBTC natively — making this vault a core yield layer for BTC on Starknet.

Scenario Re7 / Others Manual LP Our Vault
In Range LP fee earning LP fee earning LP fee earning
Out of Range Re-range (IL crystallized) 0% yield (idle) Auto Vesu lending (90%)
High Volatility Repeated re-range = cumulative IL 0% yield Stay in Vesu until stable
Return to Range Already re-ranged Manual re-entry Auto LP re-entry

Architecture

Escape Flow (Out of Range)

sequenceDiagram
    participant U as User
    participant V as BTCFiVault<br/>(ERC-4626)
    participant E as EkuboLPStrategy
    participant Ve as VesuLendingStrategy
    participant M as BTCFiManager
    participant P as Pragma Oracle

    Note over U,P: 1. User Deposit
    U->>V: deposit(wBTC)
    V-->>U: mint shares

    Note over U,P: 2. Initial Rebalance (In Range)
    M->>P: get_data_median(BTC/USD)
    P-->>M: $100,000
    M->>M: is_in_range() = true
    M->>V: execute_rebalance()
    V->>E: deposit_liquidity(90%)
    Note over V: 10% buffer retained

    Note over U,P: 3. Price Exits Range → ESCAPE
    P-->>M: $105,000 (out of range)
    M->>M: is_in_range() = false
    M->>V: execute_rebalance()
    V->>E: withdraw_liquidity(100%)
    E-->>V: wBTC returned
    V->>E: collect_fees()
    V->>Ve: supply(withdrawn wBTC, 90%)
    Note over V: 10% buffer retained
    Note over Ve: Now earning 3-5% APY
Loading

Return Flow (Back in Range)

sequenceDiagram
    participant M as BTCFiManager
    participant P as Pragma Oracle
    participant V as BTCFiVault
    participant Ve as VesuLendingStrategy
    participant E as EkuboLPStrategy

    Note over M,E: 4. Price Returns to Range → RETURN
    M->>P: get_data_median(BTC/USD)
    P-->>M: $100,000 (back in range)
    M->>M: is_in_range() = true
    M->>V: execute_rebalance()
    V->>Ve: withdraw(all)
    Ve-->>V: wBTC returned
    V->>E: deposit_liquidity(amount0, amount1)
    Note over E: Back to earning LP fees
Loading

State Machine

stateDiagram-v2
    [*] --> EKUBO_LP_ACTIVE: Initial Deposit + Rebalance

    EKUBO_LP_ACTIVE --> VESU_LENDING: Price exits range<br/>(ESCAPE)
    VESU_LENDING --> EKUBO_LP_ACTIVE: Price returns to range<br/>(RETURN)

    EKUBO_LP_ACTIVE --> EMERGENCY: Owner calls<br/>emergency_withdraw()
    VESU_LENDING --> EMERGENCY: Owner calls<br/>emergency_withdraw()

    EMERGENCY --> [*]: All assets in buffer

    state EKUBO_LP_ACTIVE {
        [*] --> Earning_LP_Fees
        Earning_LP_Fees --> Collecting_Fees: harvest_and_compound()
        Collecting_Fees --> Earning_LP_Fees
    }

    state VESU_LENDING {
        [*] --> Earning_Lend_Yield
        Earning_Lend_Yield: 3-5% APY
    }
Loading

Tech Stack

Layer Stack
Smart Contracts Cairo 2.14, Scarb 2.14, snforge 0.52, OpenZeppelin v3.0.0, Alexandria Math
Frontend Next.js 14, TypeScript, TailwindCSS, Starknet.js v6, Privy Auth, Recharts
Protocols Ekubo (concentrated LP), Vesu V2 (lending), Pragma (oracle)
Testing snforge fork tests (Mainnet + Sepolia), Mock contracts

Project Structure

BTCLP/
├── src/
│   ├── vault/
│   │   └── btcfi_vault.cairo          # ERC-4626 vault (deposit/withdraw/share accounting)
│   ├── strategy/
│   │   ├── ekubo_lp.cairo             # Ekubo concentrated LP strategy
│   │   ├── vesu_lending.cairo         # Vesu V2 lending strategy
│   │   └── traits.cairo               # Strategy interface traits
│   ├── oracle/
│   │   └── btcfi_manager.cairo        # Rebalance logic + oracle integration
│   ├── interfaces/
│   │   ├── ekubo.cairo                # Ekubo ACL (vendored)
│   │   ├── vesu.cairo                 # Vesu V2 ACL (vendored)
│   │   ├── pragma.cairo               # Pragma ACL (vendored)
│   │   └── vault.cairo                # Vault interface
│   └── mocks/                         # Mock contracts for testing/demo
├── tests/
│   ├── test_vault.cairo               # Vault unit tests
│   ├── test_ekubo_strategy.cairo      # Ekubo strategy tests
│   ├── test_vesu_strategy.cairo       # Vesu strategy tests
│   ├── test_manager.cairo             # Manager logic tests
│   ├── test_integration.cairo         # Integration tests
│   └── test_fork.cairo                # Mainnet fork tests
├── frontend/                          # Next.js dashboard
├── scripts/
│   ├── deploy_sepolia.sh              # Sepolia deployment script
│   ├── mint_test_wbtc.sh              # Test token minting
│   └── deployed_addresses.txt         # Deployed contract addresses
├── Scarb.toml
└── snfoundry.toml

Getting Started

Prerequisites

Smart Contracts

# Build
scarb build

# Run tests
scarb test

Frontend

cd frontend
npm install
npm run dev

Deployment (Sepolia)

./scripts/deploy_sepolia.sh

Deployed Contracts (Sepolia Testnet)

Deployed: 2026-03-04 | Demo bounds: $99,500 - $103,000

Contract Address Explorer
BTCFiVault 0x2b74b61...2b882 Voyager
BTCFiManager 0x460d2e1...2cbf Voyager
EkuboLPStrategy 0x6c0ba50...2b6f Voyager
VesuLendingStrategy 0x4e849f4...f279 Voyager
MockOracle 0x786ebf8...447d Voyager
wBTC (Mock) 0x14cfad9...6291 Voyager
USDC (Mock) 0x2977b4d...d76b Voyager

Demo Scenario

journey
    title BTCFi Vault — Demo User Journey
    section Deposit
        User approves wBTC: 5: User
        User deposits 1 wBTC: 5: User
        Vault mints shares: 5: Vault
    section In-Range (Earning)
        Manager rebalances: 5: Manager
        90% → Ekubo LP (fees): 5: Ekubo
        10% → buffer (instant withdrawal): 4: Vault
    section Out-of-Range (Escape)
        BTC price moves to $105k: 2: Oracle
        LP earns 0% — capital idle: 1: Ekubo
        Manager triggers ESCAPE: 5: Manager
        90% capital → Vesu (3-5% APY): 4: Vesu
        10% buffer retained in vault: 4: Vault
    section Back-in-Range (Return)
        BTC price returns to $100k: 5: Oracle
        Manager triggers RETURN: 5: Manager
        Capital re-enters Ekubo LP: 5: Ekubo
        Yield maximized again: 5: User
Loading

1. Deposit

User approves and deposits 1 wBTC into the Vault contract. The Vault mints proportional shares representing the user's ownership of the pool.

2. In-Range — Earning Yield

While BTC price stays within the configured band ($99,500 – $103,000), the Manager allocates capital across two DeFi protocols:

  • 90% → Ekubo concentrated LP — earns trading fees from the wBTC/USDC pair
  • 10% → Vault buffer — reserved for instant user withdrawals without unwinding positions

3. Out-of-Range — Escape Mode

When BTC price moves outside the LP range (e.g. spikes to $105k):

  • Ekubo LP stops earning fees — capital sits idle with 0% yield
  • The Manager calls escape() to withdraw all capital from Ekubo
  • 90% of capital moves to Vesu lending, which continues earning 3–5% APY regardless of price
  • 10% buffer remains in the vault for instant withdrawals
  • User funds keep generating yield instead of sitting idle

4. Back-in-Range — Return Mode

When BTC price returns to the LP range:

  • The Manager calls return_to_lp() to move capital back from Vesu to Ekubo
  • Concentrated LP position is re-established, maximizing yield again
  • The cycle repeats automatically as price fluctuates

"When LP yield drops to zero, we automatically move to lending. When LP becomes profitable again, we move back."

Roadmap

gantt
    title BTCFi Strategy Vault Roadmap
    dateFormat YYYY-MM
    axisFormat %b %Y

    section Phase 1 — Hackathon MVP
        Smart Contracts (Cairo)        :done, p1a, 2026-02, 2026-03
        Mock Oracle + Strategies       :done, p1b, 2026-02, 2026-03
        Frontend Dashboard             :done, p1c, 2026-02, 2026-03
        Sepolia Deployment             :done, p1d, 2026-03, 2026-03
        Demo & Submission              :active, p1e, 2026-03, 2026-03

    section Phase 2 — Production Alpha
        strkBTC Native Support         :p2a, 2026-04, 2026-05
        Keeper Automation              :p2b, 2026-04, 2026-05
        Pragma Mainnet Oracle          :p2c, 2026-04, 2026-06
        Fee Structure                  :p2d, 2026-05, 2026-06
        Mainnet Deployment             :milestone, p2m, 2026-06, 0d

    section Phase 3 — Quantitative
        GARCH Volatility Model         :p3a, 2026-07, 2026-09
        EGARCH / GJR-GARCH Upgrade     :p3b, 2026-09, 2026-11
        Curator Vaults                 :p3c, 2026-08, 2026-10
        Tokenized Yield (y-strkBTC)    :p3d, 2026-10, 2026-12
Loading
Phase Timeline Scope
Phase 1: Hackathon MVP March 2026 1 vault (wBTC/USDC), binary LP/Lending switch (90/10 buffer), MockOracle, Sepolia testnet
Phase 2: Production Q2 2026 strkBTC support, keeper automation, Pragma mainnet oracle, fee structure
Phase 3: Quantitative Q3-Q4 2026 GARCH/EGARCH volatility prediction, curator vaults, tokenized yield (y-strkBTC)

License

Apache License 2.0 — see LICENSE for details.

About

BTCFi Strategy Vault — Automated LP/Lending yield optimizer on Starknet. Escapes idle capital when BTC exits LP range, returns when profitable again.

btclp.vercel.app

Topics

btccairodefiekubohackathonnextjsstarknetvaultvesuyield

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages