BitFlow Lend V3

A production-grade, decentralized Bitcoin-native fixed-rate lending protocol suite built in Clarity on the Stacks blockchain.

Protocol Suite Architecture

BitFlow Lend V3 consists of three core smart contracts designed to operate collectively:

1. bitflow-oracle-registry-v3: A multi-source decentralized price oracle with whitelisted reporter validation, deviation checks, and automatic staleness protection.
2. bitflow-staking-pool-v3: An incentive-alignment pool distributing STX rewards to protocol participants using a checkpoint-based yield engine.
3. bitflow-vault-core-v3: The core fixed-rate lending engine managing user collateral, deposits, borrow limits, and a robust liquidation liquidator loop.

---

Key Features

• Fixed Interest Rates: Guaranteed and locked at the exact moment of borrowing, eliminating variable rate volatility.
• Robust Collateral Management: Secured by a strict 150% minimum collateralization ratio.
• Automated Liquidations: Automatic position closing triggered at a 110% health factor with a 5% liquidator bonus.
• On-Chain Event Sourcing: Structured event logs emitted with block heights for indexers, substreams, and subgraphs.
• Granular Circuit Breakers: Multi-tier admin toggles allowing per-function pausing (deposits, borrows, withdrawals, liquidations) for emergency risk management.

---

Governance & Trust Model

The BitFlow Lend V3 contracts are immutable once deployed. To handle dynamic network environments, select protocol parameters are admin-governed via the contract-owner (deployer wallet):

• Price feeds and whitelisted oracle reporters.
• Risk parameters (minimum collateral ratio, liquidation threshold, late penalty rates).
• Emergency pause controls for individual protocol functions.

Every privileged operation emits an explicit on-chain admin-action print event logging the executing principal and the action details.

For an exhaustive audit of admin controls, view PRIVILEGED_FUNCTIONS.md.

---

Mainnet Deployments

All three contracts were deployed to the Stacks mainnet on May 21, 2026:

Contract	Mainnet Address	Explorer
Oracle Registry	SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.bitflow-oracle-registry-v3	View on Hiro Explorer
Staking Pool	SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.bitflow-staking-pool-v3	View on Hiro Explorer
Vault Core	SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.bitflow-vault-core-v3	View on Hiro Explorer

Quick Start

git clone https://github.com/Yusufolosun/bitflow-lend
cd bitflow-lend
npm install
npm test

Frontend

cd frontend
npm install
npm run dev

Deploying to Testnet

The deployment orchestration script runs 9 pre-flight safety checks (syntax, tests, wallet balance, secret scans) before publishing:

bash scripts/deploy-v3-suite.sh --network testnet

Or deploy directly via Clarinet:

clarinet deployments apply -p deployments/default.testnet-plan.yaml

Smart Contract Interface Reference

bitflow-vault-core-v3

Function	Type	Description
deposit	Write	Deposit STX as collateral
withdraw	Write	Withdraw unused collateral
borrow	Write	Take a fixed-rate loan
repay	Write	Repay loan principal plus simple interest
liquidate	Write	Liquidate undercollateralized positions (health factor < 1.10)
get-user-deposit	Read	Get current collateral balance for a principal
get-user-loan	Read	Get active loan details, principal, term, and interest rate
calculate-health-factor	Read	Get position health factor (1.50+ is safe, <1.10 is liquidatable)
get-repayment-amount	Read	Get total repayment amount due including simple interest
get-dashboard-snapshot	Read	Get aggregated vault stats, pool utilization, and protocol age

bitflow-staking-pool-v3

Function	Type	Description
stake	Write	Stake STX to earn yield
unstake-request	Write	Initiate a cooldown period to unstake STX
unstake	Write	Withdraw STX after cooldown expires
claim-rewards	Write	Claim accumulated STX rewards
get-staker-summary	Read	View active stake, checkpoints, pending rewards, and cooldowns
get-dashboard-snapshot	Read	View staking pool TVL, reward rates, and yield performance

bitflow-oracle-registry-v3

Function	Type	Description
submit-price	Write	Whitelisted reporter price submission
get-aggregated-price	Read	Get the consensus price aggregated from active reporters
get-dashboard-snapshot	Read	View active reporter list, min reporter threshold, and price age

Technology Stack

Layer	Technology
Smart Contracts	Clarity
Blockchain	Stacks (Bitcoin L2)
Frontend	React 18 + TypeScript + Vite
Styling	Tailwind CSS
Testing	Vitest + Clarinet SDK
CI/CD	GitHub Actions
Deployment	Clarinet (contracts)

Documentation

• Quick Start Guide
• API Reference / Examples
• Architecture
• Contracts Guide
• Privileged Functions and Trust Model
• Deployment Guide
• Full Documentation Index

Security

• Clarity's non-Turing-complete design prevents reentrancy attacks
• Automated collateral ratio enforcement on every transaction
• Health factor monitoring with liquidation threshold
• Comprehensive test coverage across boundary, security, and liquidation scenarios

See SECURITY.md for the security policy and vulnerability reporting.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Run tests: npm test
4. Commit with conventional format: feat: add new feature
5. Open a Pull Request

See CONTRIBUTING.md for full guidelines.

License

MIT — see LICENSE