BitYield Protocol - Bitcoin Native Yield Aggregator on Starknet

BitYield Protocol enables Bitcoin holders to earn DeFi yields on Starknet without complex bridging or wrapping processes. Single Query for Bitcoin to Starknet yield farming with automated optimization across multiple protocols.

🎯 Problem & Solution

Problem

Bitcoin holders cannot easily access DeFi yields without:

Understanding complex bridging mechanisms
Manually wrapping BTC to WBTC
Navigating multiple DeFi protocols
Managing rebalancing strategies As a result ,Billions of Bitcoin capital remains unused and untapped in Defi.

Solution

BitYield provides:

AI Powered Bitcoin deposits via Atomiq integration
Automatic WBTC conversion on Starknet
Yield optimization across Vesu lending markets and Troves strategies
Automated rebalancing via Cairo smart contracts
Xverse wallet integration for seamless UX

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   Frontend (React + Starknet.js)         │
│            Xverse Wallet + Atomiq SDK Integration        │
└────────────────┬────────────────────────────────────────┘
                 │AI Agent (LangGraph AGENT)
                 ▼
┌─────────────────────────────────────────────────────────┐
│              Atomiq Bridge Layer (BTC → WBTC)           │
│  ┌────────────────┐         ┌──────────────────┐       │
│  │ AtomiqBridge   │◄────────► MockAtomiqGateway│       │
│  │ (Cairo)        │         │ (Testing)        │       │
│  └────────────────┘         └──────────────────┘       │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│           BitYield Core (Cairo 2.12.0 Contracts)        │
│  ┌──────────────────────────────────────────────────┐  │
│  │         BitYieldVault.cairo (ERC-4626)           │  │
│  │  • Deposit/Withdraw with share calculations      │  │
│  │  • Fee collection (performance + management)     │  │
│  │  • Emergency pause mechanism                     │  │
│  └────────────┬─────────────────────────────────────┘  │
│               │                                          │
│  ┌────────────▼─────────────────────────────────────┐  │
│  │         StrategyManager.cairo                     │  │
│  │  • Yield optimization algorithm                   │  │
│  │  • Rebalancing with threshold triggers            │  │
│  │  • APY calculation: Σ(w_i × r_i)                 │  │
│  └────────────┬─────────────────────────────────────┘  │
│               │                                          │
│  ┌────────────▼──────────────┬──────────────────────┐  │
│  │  VesuAdapter.cairo        │ TrovesAdapter.cairo  │  │
│  │  • Multi-pool management  │ • Strategy framework │  │
│  │  • ERC-4626 vToken calls  │ • Reward harvesting  │  │
│  └───────────────────────────┴──────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│          Protocol Integration Layer (Starknet)           │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │   Vesu   │  │  Troves  │  │  Future Protocols    │  │
│  │ (Lending)│  │(Staking) │  │  (Expandable)        │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────┘

📍 Deployed Contracts (Sepolia Testnet)

Contract	Address	Starkscan
BitYieldVault	`0x06552bc669d3a53c7223ae7d0d5f47613f5da4fb318f21e5f596cc8a791a3f90`	View
VesuAdapter	`0x0096b181aba9febca459591efdf27b885b3f8096b42f5f1f805fbd9bee65b75b`	View
TrovesAdapter	`0x0722c6917ff0ac4e298bfdeb409001d3bac6df3b72f338d63d075a6f614a4910`	View
StrategyManager	`0x06154fad2a07742aed27af28c80c1259377bdffd1ffabee5aca9b1b7690b6a57`	View
AtomiqBridge	`0x030cb9c97a7bb3f4e160382ce233ffdbc623b65776ce2e08ee9806e7f9d808ff`	View

📝 Project Structure

BitYield-Protocol/
├── packages/
│   ├── nextjs/              # Frontend application
│   │   ├── app/             # Next.js app router pages
│   │   ├── components/      # React components
│   │   ├── contracts/       # Contract ABIs and addresses
│   │   └── public/          # Static assets
│   │
│   └── snfoundry/           # Smart contracts
│       ├── contracts/       # Cairo contracts
│       │   ├── src/         # Contract source code
│       │   └── tests/       # Contract tests
│       └── scripts-ts/      # Deployment scripts
│
├── .tool-versions           # asdf version specifications
├── package.json             # Root package config
└── README.md               # This file

📦 Contract Architecture

Core Contracts

1. BitYieldVault.cairo

The main ERC4626-compliant vault contract managing user deposits and withdrawals.

Key Features:

ERC20 share tokens (byWBTC) representing vault ownership
Deposit WBTC, receive byWBTC shares
Withdraw by burning byWBTC shares
Automated fee collection (performance + management)
Emergency pause/unpause functionality
Owner-controlled rebalancing

State Variables:

asset: ContractAddress              // WBTC token
total_assets_deposited: u256        // Total WBTC deposited
strategy_manager: ContractAddress   // Strategy orchestration
vesu_adapter: ContractAddress       // Vesu integration
troves_adapter: ContractAddress     // Troves integration
performance_fee_bps: u32            // Performance fee (basis points)
management_fee_bps: u32             // Management fee (basis points)
fee_recipient: ContractAddress      // Fee collection address

Key Functions:

deposit(assets: u256) -> u256: Deposit WBTC, receive byWBTC shares
withdraw(shares: u256) -> u256: Burn shares, receive WBTC
total_assets() -> u256: Total value locked (TVL)
rebalance(vesu_bps: u32, troves_bps: u32): Rebalance allocations
collect_fees(): Collect accrued fees
emergency_withdraw(): Pull all funds from strategies

2. VesuAdapter.cairo

Manages deposits/withdrawals to Vesu lending pools.

Key Features:

Multi-pool support (different Vesu markets)
ERC4626 vToken integration
Pool weight management
Emergency withdrawal per pool

Key Functions:

add_pool(pool_id: felt252, v_token: ContractAddress): Add Vesu pool
deposit(pool_id: felt252, assets: u256) -> u256: Deposit to pool
withdraw(pool_id: felt252, assets: u256) -> u256: Withdraw from pool
get_total_assets() -> u256: Total deposited across pools
get_pool_balance(pool_id: felt252) -> u256: Balance in specific pool

3. TrovesAdapter.cairo

Integration with Troves/Endurfi for liquid staking strategies.

Features:

Liquid staking deposit/withdrawal
Reward claiming and compounding
Strategy optimization

4. StrategyManager.cairo

Orchestrates yield optimization across protocols.

Features:

APY calculation and optimization
Automated rebalancing with threshold triggers
Multi-protocol allocation management

👤 User Flow

For Bitcoin Holders

1. Connect Xverse Wallet
   ↓
2. Initiate Bitcoin Deposit
   ↓
3. Atomiq Bridges BTC → WBTC (Starknet)
   ↓
4. User Approves WBTC to BitYield Vault
   ↓
5. Vault Deposits WBTC, Mints byWBTC Shares
   ↓
6. Vault Automatically Deploys to Vesu/Troves
   ↓
7. Yield Accrues (Lending Interest + Staking Rewards)
   ↓
8. User Withdraws: Burn byWBTC → Receive WBTC
   ↓
9. Optional: Bridge WBTC → BTC via Atomiq

For Vault Operators

1. Monitor Pool Yields (Vesu vs Troves)
   ↓
2. Call rebalance() to Optimize Returns
   ↓
3. Collect Performance + Management Fees
   ↓
4. Emergency: Pause vault or emergency_withdraw()

🚀 Getting Started

Prerequisites

This project is built using Scaffold-Stark 2, a modern development stack for Starknet dApps.

System Requirements:

Node.js v18+ and Yarn package manager

node --version  # Should be v18 or higher
yarn --version

Starknet Development Tools (managed via asdf):
- Scarb v2.12.0 (Cairo package manager)
- Starknet Foundry v0.49.0 (Testing framework)
- Starknet Devnet v0.4.3 (Local node)

Installation

Step 1: Clone the Repository

git clone https://github.com/CodeBlocker52/BitYield-Protocol
cd BitYield-Protocol

Step 2: Install asdf Version Manager (if not already installed)

The project uses asdf to manage Starknet toolchain versions. This ensures everyone uses the same versions.

# Install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

# Add to shell profile (choose your shell)
# For bash:
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc

# For zsh:
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc
source ~/.zshrc

Step 3: Install asdf Plugins

# Add Starknet toolchain plugins
asdf plugin add scarb
asdf plugin add starknet-foundry
asdf plugin add starknet-devnet

Step 4: Install Project Dependencies

# Install Starknet toolchain versions (reads from .tool-versions)
asdf install

# Verify installations
scarb --version          # Should show: scarb 2.12.0
snforge --version        # Should show: snforge 0.49.0
starknet-devnet --version # Should show: starknet-devnet 0.4.3

# Install Node.js dependencies for frontend
cd packages/nextjs
yarn install

# Install Node.js dependencies for contracts (if needed)
cd ../snfoundry
yarn install

🔨 Building & Testing Contracts

Build Contracts

cd packages/snfoundry/contracts
scarb build

Run Tests

The project includes comprehensive test coverage (92 tests covering all contracts).

# From contracts directory
cd packages/snfoundry/contracts
snforge test

Run Specific Tests

# Test specific contract
snforge test test_vault

# Test with verbose output
snforge test -vvv

# Test with gas profiling
snforge test --detailed-resources

Test Coverage

snforge test --coverage

🌐 Running the Frontend

Development Mode

cd packages/nextjs

# Start development server
yarn start

Visit http://localhost:3000 to see the application.

Production Build

cd packages/nextjs

# Build for production
yarn build

# Start production server
yarn start

🚢 Deploying Contracts

Deploy to Local Devnet

Terminal 1: Start Local Node

cd packages/snfoundry
yarn chain

Terminal 2: Deploy Contracts

cd packages/snfoundry
yarn deploy --network devnet

Deploy to Sepolia Testnet

cd packages/snfoundry
yarn deploy --network sepolia

Deployment Process:

Deploys VesuAdapter
Deploys TrovesAdapter
Deploys StrategyManager
Deploys BitYieldVault
Deploys AtomiqBridge
Configures all contract addresses
Outputs contract addresses to console

Save the Contract Addresses: After deployment, update packages/nextjs/contracts/deployedContracts.ts with the new addresses.

Deploy to Mainnet

cd packages/snfoundry
yarn deploy --network mainnet

🔧 Development Workflow

Making Changes

Edit Contracts

# Contracts are in packages/snfoundry/contracts/src/
nano packages/snfoundry/contracts/src/vault.cairo

Rebuild

cd packages/snfoundry/contracts
scarb build

Run Tests
```
snforge test
```
Update Frontend (if ABI changed)
```
cd packages/nextjs
yarn contracts:sync
```
Test Frontend
```
yarn dev
```

Common Commands

# Contracts
scarb build              # Build contracts
snforge test            # Run all tests
snforge test -vvv       # Verbose test output
scarb clean             # Clean build artifacts

# Frontend
yarn dev                # Start dev server
yarn build              # Build for production
yarn start              # Start production server
yarn lint               # Run linter
yarn format             # Format code

# Full Stack
yarn chain              # Start local devnet
yarn deploy             # Deploy contracts
yarn contracts:sync     # Sync ABIs to frontend

📡 Interacting with Deployed Contracts

Using the Frontend

Navigate to Yield Dashboard (http://localhost:3000/yield)
Connect Wallet (Argent X, Braavos, or Xverse)
Approve WBTC for vault spending
Deposit WBTC to receive byWBTC shares
Monitor Yield and rebalancing events
Withdraw by burning byWBTC shares

Using Starkli CLI

Read Total Assets

starkli call \
  0x06552bc669d3a53c7223ae7d0d5f47613f5da4fb318f21e5f596cc8a791a3f90 \
  total_assets \
  --rpc https://starknet-sepolia.public.blastapi.io/rpc/v0_9

Deposit WBTC

# 1. Approve WBTC
starkli invoke \
  <WBTC_TOKEN_ADDRESS> \
  approve \
  0x06552bc669d3a53c7223ae7d0d5f47613f5da4fb318f21e5f596cc8a791a3f90 \
  u256:1000000 \
  --rpc https://starknet-sepolia.public.blastapi.io/rpc/v0_9

# 2. Deposit to vault
starkli invoke \
  0x06552bc669d3a53c7223ae7d0d5f47613f5da4fb318f21e5f596cc8a791a3f90 \
  deposit \
  u256:1000000 \
  --rpc https://starknet-sepolia.public.blastapi.io/rpc/v0_9

Using Starkscan UI

Visit contract pages for UI-based interaction:

BitYieldVault on Starkscan

🧪 Test Results

Current Test Coverage: 92 Tests - All Passing ✅

Test Breakdown

Vault Tests (16): Deposit, withdraw, pause, fees, multi-user scenarios
VesuAdapter Tests (24): Pool management, deposits, withdrawals, balances
TrovesAdapter Tests (24): Strategy management, deposits, withdrawals, rewards
StrategyManager Tests (28): Rebalancing, yield calculation, authorization

Key Test Scenarios

✅ Deposit Flow

Zero amount rejection
First deposit share calculation
Multiple user deposits
Share price consistency

✅ Withdrawal Flow

Partial withdrawals
Full withdrawals
Insufficient shares protection

✅ Rebalancing

Owner-only rebalancing
Authorized rebalancer access
Time-based rebalancing constraints
Allocation optimization

✅ Security

Unauthorized access prevention
Zero address validation
Pause mechanism
Emergency withdrawals

🔐 Security Considerations

Implemented

✅ Reentrancy Guards: Prevent reentrancy attacks
✅ Pausable: Emergency stop mechanism
✅ Ownable: Access control for admin functions
✅ Input Validation: Zero amount checks, address validation
✅ Safe Math: Cairo 2.0 overflow protection
✅ Role-Based Access: Separate owner and rebalancer roles

📊 Monitoring & Metrics

On-Chain Metrics

Monitor these key metrics through the frontend dashboard:

TVL (Total Value Locked): Total WBTC deposited in vault
APY: Current annual percentage yield (weighted average)
Allocation: % distribution between Vesu and Troves
User Balance: Your byWBTC shares and WBTC value
Fee Collection: Performance and management fees accrued

Events to Monitor

Deposit(user, assets, shares)
Withdraw(user, assets, shares)
Rebalance(vesu_bps, troves_bps)
FeeCollected(amount, recipient)
StrategyUpdated(strategy_id, new_target)

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# 1. Fork and clone
git clone https://github.com/CodeBlocker52/BitYield-Protocol
cd BitYield-Protocol

# 2. Install dependencies
asdf install
cd packages/nextjs && yarn install

# 3. Create feature branch
git checkout -b feature/amazing-feature

# 4. Make changes and test
cd packages/snfoundry/contracts
scarb build
snforge test

# 5. Test frontend
cd ../../nextjs
yarn dev

# 6. Commit and push
git add .
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature

# 7. Open Pull Request

Coding Standards

Cairo: Follow official Cairo style guide
TypeScript: Use ESLint and Prettier configurations
Testing: Add tests for new features
Documentation: Update README and inline comments

🐛 Troubleshooting

Common Issues

Issue: "No version is set for command scarb"

# Solution: Install asdf and project tools
asdf install

Issue: "Module not found" in frontend

# Solution: Reinstall dependencies
cd packages/nextjs
rm -rf node_modules yarn.lock
yarn install

Issue: Tests failing after contract changes

# Solution: Rebuild contracts
cd packages/snfoundry/contracts
scarb clean
scarb build
snforge test

Issue: Frontend can't connect to contracts

# Solution: Sync ABIs
cd packages/nextjs
yarn contracts:sync

📝 License

MIT License - see LICENSE file for details

🔗 Resources && Links

Starknet: starknet.io
Scaffold-Stark 2: github.com/Scaffold-Stark/scaffold-stark-2
Vesu Protocol: vesu.xyz
Troves Protocol: troves.app
Atomiq Bridge: atomiq.io
Cairo Book: cairo-book.github.io
Starknet Foundry: foundry-rs.github.io/starknet-foundry

🏆 Hackathon Submission

Starknet Re{solve} Hackathon 2025

Innovation Highlights

First Bitcoin-native yield aggregator on Starknet
Seamless UX - No manual bridging/wrapping for users
Automated optimization via Cairo smart contracts
Multi-protocol integration (Vesu, Troves, Atomiq)
ERC4626 compliance for composability
Comprehensive test coverage (92 tests - 100% passing)

Future Roadmap

Integrate additional Troves strategies
Add more Vesu lending pools
Implement auto-compounding
Advanced rebalancing algorithms (ML-based APY prediction)
Governance token for protocol decisions
Cross-chain yield opportunities (Bitcoin L2s)
Mobile app integration (iOS/Android)
Security audit and mainnet launch

Built with ❤️ on Starknet for Starknet Re{Solve} Hackathon 2025

FilesExpand file tree

README.md

Latest commit

History