Skip to content

collat-labs/collat

BranchesTags

Repository files navigation

Collat

Bank on Bitcoin. Spend your Bitcoin without selling it.

Deposit BTC once. Shop normally. Collat does the rest.

Collat is a Bitcoin-collateralized spending protocol built on Mezo (EVM). Deposit BTC as collateral and auto-borrow MUSD at checkout. No manual steps. No selling your Bitcoin. Your BTC stays on-chain in your vault.

Test Solidity Foundry React TypeScript Vite License

How It Works

01. Deposit BTC
    Lock BTC as collateral in your Collat vault. One-time setup.

02. Shop Normally
    Pay online with a virtual Collat card. The protocol auto-borrows
    the exact MUSD needed against your BTC collateral.

03. Repay and Unlock
    Repay MUSD at any time. BTC is released proportionally back to you.

Architecture

 ┌─────────────────────────────────────────┐
 │            Collat Dashboard             │
 │          (React + Vite + wagmi)         │
 └────────────────┬────────────────────────┘
                  │
 ┌────────────────┴────────────────────────┐
 │            Auth Relay                   │
 │         (Off-chain service)             │
 │  Checks on-chain LTV → approves card    │
 │  then borrows MUSD on-chain             │
 └────────┬───────────────────┬────────────┘
          │                   │
 ┌────────┴────────┐  ┌───────┴──────────┐
 │ Mezo Blockchain │  │ Card Issuing API │
 │   (EVM)        │  │ (Stripe/Marqeta)  │
 │                │  │                   │
 │ CollatVault.sol│  │ Virtual Cards     │
 │ PriceFeed.sol  │  │ Merchant Settlement│
 │ MUSD (ERC-20)  │  │                   │
 └────────────────┘  └───────────────────┘

Smart Contracts (Solidity + Foundry)

Contract Purpose
CollatVault.sol Vault: deposit/withdraw BTC, borrow/repay MUSD, liquidate, interest accrual
PriceFeed.sol BTC/USD oracle with multi-oracle support and staleness checks
MockBTCToken.sol Test BTC ERC-20 token (for testnet)

Instructions

Function Description
depositCollateral(amount) Deposit BTC as collateral
withdrawCollateral(amount) Withdraw BTC (requires no outstanding loan)
borrow(amount) Borrow MUSD against BTC (max 60% LTV)
repay(amount) Repay MUSD to reduce debt
liquidate(owner, debtToCover) Liquidate underwater positions (>75% LTV, +5% penalty)
accrueInterest(owner) Accrue time-based interest on outstanding debt
getMaxBorrow(owner) View max available borrowing power
getHealthFactor(owner) View position health factor

Parameters

Parameter Value
Max LTV 60% (6000 bps)
Liquidation LTV 75% (7500 bps)
Liquidation Penalty 5% (500 bps)
Collateral Token BTC (ERC-20, 8 decimals)
Borrow Token MUSD (ERC-20, 6 decimals)
Interest Rate 5% APR (configurable)
Fee Rate 0.5% (configurable)

Bugs Fixed from Anchor Version

Bug Fix
LTV divided by LAMPORTS_PER_SOL incorrectly Proper decimal normalization (BTC 8dp, MUSD 6dp)
Liquidation seized BTC without repaying MUSD Liquidator must transfer MUSD to vault first
No interest accrual model Per-second interest with configurable APR
Single centralized oracle Multi-oracle with staleness threshold

Getting Started

Prerequisites

Smart Contracts

cd solidity

# Install dependencies
forge install

# Build
forge build

# Run tests (26 tests)
forge test

# Run with verbose output
forge test -vvv

# Run with gas report
forge test --gas-report

Deploy to Mezo Testnet (matsnet)

cd solidity

# Set your private key
export PRIVATE_KEY=your_private_key_here

# Deploy to Mezo testnet
forge script script/DeployCollat.s.sol \
  --rpc-url https://rpc.test.mezo.org \
  --broadcast \
  --verify \
  -vvvv

# Or use the configured profile
forge script script/DeployCollat.s.sol --rpc-url matsnet --broadcast -vvvv

Get testnet BTC from the Mezo Faucet.

Frontend

cd frontend

# Install dependencies
npm install

# Start dev server (http://localhost:5173)
npm run dev

# Build for production
npm run build

Landing Page (/)

  • Full-viewport hero with video background + smooth crossfade loop
  • Liquid-glass UI across all sections (backdrop-blur, gradient borders)
  • Animated SVG backgrounds — Bitcoin node mesh, hex grid, vault shield
  • Scroll-triggered framer-motion animations (useInView)
  • Instrument Serif display typeface, Mezo-inspired red palette (#E53935)
  • 5 sections: Hero, About, How it Works, Security × Freedom, Core Features
  • Comprehensive footer with product links, docs, legal, social icons

Dashboard (/dashboard)

  • RainbowKit wallet integration — connect MetaMask, WalletConnect, etc.
  • Live on-chain data via viem — reads CollatVault contract on Mezo matsnet
  • Protocol stats: TVL, MUSD borrowed, Max LTV, interest rate
  • Deposit BTC panel — balance display, approve + deposit with wagmi writeContract
  • Position table — BTC deposited, MUSD borrowed, LTV%, health factor
  • Virtual card preview — mock Collat Card with spending limits
  • Contract addresses and protocol parameters displayed
  • Graceful fallback to defaults when contracts aren't deployed

Stack

React 19 · TypeScript · Vite · Tailwind CSS 4 · framer-motion · wagmi · RainbowKit · viem · lucide-react

Deployed Addresses

Mezo Matsnet (Testnet)

Contract Address
MUSD (official) 0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

After deployment, run forge script to populate the remaining addresses in solidity/broadcast/deployed-addresses.json.

⚠️ Credit Card: What Works and What Doesn't

See docs/CREDIT_CARD_ARCHITECTURE.md for the full analysis.

TL;DR: A blockchain cannot replace Visa/Mastercard. But Collat provides the on-chain collateral infrastructure, and the virtual card MVP works through a card issuing API (Stripe Issuing, Marqeta, Lithic) with an off-chain auth relay.

Feature Collat MVP Production
BTC collateral vault ✅ On-chain ✅
MUSD borrowing ✅ 60% LTV max ✅
Interest accrual ✅ 5% APR ✅
Liquidation ✅ +5% penalty ✅
Virtual card numbers ✅ Via API partner ✅
Physical NFC card ❌ Phase 4 ✅ Tangem-style
Auto-borrow at checkout ✅ Auth relay ✅
KYC-free ✅ Protocol level ✅ Issuer handles KYC

Mezo Testnet Details

Parameter Value
Network Name Mezo Matsnet
Chain ID 31611
RPC URL https://rpc.test.mezo.org
Explorer https://explorer.test.mezo.org
Faucet https://faucet.test.mezo.org
Native Currency BTC (18 decimals)
MUSD Token 0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

Mezo Mainnet

Parameter Value
Chain ID 31612
MUSD Token 0xdD468A1DDc392dcdbEf6db6e34E89AA338F9F186
Explorer https://explorer.mezo.org

Project Structure

collat-mezo/
├── solidity/                  # Foundry project
│   ├── src/                   # Solidity contracts
│   │   ├── CollatVault.sol
│   │   ├── PriceFeed.sol
│   │   ├── MockBTCToken.sol
│   │   └── interfaces/IERC20.sol
│   ├── test/CollatVault.t.sol # 26 tests
│   ├── script/DeployCollat.s.sol
│   └── foundry.toml
├── frontend/                  # React + Vite + Tailwind
│   ├── src/
│   │   ├── components/        # 11 components
│   │   │   ├── HeroSection.tsx
│   │   │   ├── AboutSection.tsx
│   │   │   ├── FeaturedVideoSection.tsx (How it Works)
│   │   │   ├── PhilosophySection.tsx
│   │   │   ├── ServicesSection.tsx
│   │   │   ├── DepositPanel.tsx
│   │   │   ├── CardPreview.tsx
│   │   │   ├── PositionTable.tsx
│   │   │   ├── Navbar.tsx
│   │   │   ├── FooterSection.tsx
│   │   │   └── AnimatedSection.tsx
│   │   ├── pages/
│   │   │   ├── Landing.tsx
│   │   │   └── Dashboard.tsx
│   │   ├── hooks/useCollatData.ts
│   │   ├── lib/               # chain.ts, contracts.ts, wagmi.ts
│   │   ├── App.tsx
│   │   └── index.css
│   └── vite.config.ts
├── docs/CREDIT_CARD_ARCHITECTURE.md
├── PRD.md
├── COMPETITOR_ANALYSIS.md
└── README.md

About

collat-mezo.vercel.app

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages