USDU

USDU is a decentralized, Bitcoin-backed stablecoin protocol on Starknet, inspired by Liquity v2.

Overview

USDU enables users to mint stablecoins backed by BTC collateral. Borrowers set their own interest rates, while depositors can earn yield via the Stability Pool. The system uses on-chain price feeds (Pragma by default, with optional Chainlink sources).

Repository Guide

• Contracts: Cairo sources in src/
• Tests: tests/ (snforge)
• Deployment & ops scripts: scripts/ (TypeScript + starknet.js)
• Deployed addresses: deployments/
• ABIs: abis/

Key Features

• BTC-backed collateral
• User-defined interest rates
• Stability Pool yield
• Interest-rate delegation
• Oracle integrations (Pragma + optional Chainlink)

Docs

• Implementation details vs Liquity v2: IMPLEMENTATION_DIFFERENCES.md
• Dev guidelines: GUIDELINES.md

Getting Started

Web app: https://github.com/BBY-Labs/usdu-webapp

Security

This protocol is not production-ready and may be missing important security features. Use for testing only.

Prerequisites

• Scarb (Cairo package manager)
• Starknet Foundry (snforge)
• Node.js 18+ and Yarn

Setup

1. Install dependencies

   yarn install

2. Configure environment

   cp env.example .env

3. Build contracts

   scarb build

Environment Variables

NETWORK controls the active network (sepolia or mainnet). Variables can be provided with a network suffix (e.g., RPC_URL_SEPOLIA) or without a suffix (used as fallback).

Required:

• NETWORK
• PRIVATE_KEY
• DEPLOYER_ADDRESS
• OWNER_ADDRESS
• SPONSOR
• RPC_URL (or RPC_URL_SEPOLIA / RPC_URL_MAINNET)
• PIL_ADDRESS (or network-suffixed)
• PRAGMA_ORACLE_ADDRESS (or network-suffixed)

Optional:

• CHAINLINK_BTC_USD_ADDRESS (or network-suffixed)
• CHAINLINK_WBTC_USD_ADDRESS (or network-suffixed)
• WBTC_ADDRESS, TBTC_ADDRESS, SOLVBTC_ADDRESS (or network-suffixed)
• SALT (default: 0x1)
• FORCE_DEPLOY (true/false)

Common Commands

• Run tests

  snforge test

• Fuzz tests

  snforge test --features fuzz

• Deploy (default: Sepolia)

  yarn deploy

• Deploy explicitly

  yarn deploy:sepolia
  yarn deploy:mainnet

• Operational scripts

  yarn open_positions
  yarn close_positions
  yarn setup_liquidations