Bitcoin Collateralized Lending Protocol

A decentralized lending protocol built on Stacks blockchain that enables users to borrow STX tokens against collateral with automatic interest accrual and liquidation mechanisms.

Overview

This smart contract implements a secure, over-collateralized lending system where borrowers deposit STX as collateral to receive loans. The protocol enforces strict collateralization ratios and includes liquidation mechanisms to protect the system's solvency.

Key Features

🏦 Lending Mechanics

• Over-collateralization: Requires 150% collateral ratio (borrow 100 STX with 150 STX collateral)
• Interest Accrual: 5% annual interest rate calculated per block
• Protocol Fees: 0.5% origination fee on all loans
• Flexible Management: Add collateral anytime to improve loan health

⚡ Liquidation System

• Health Monitoring: Real-time loan health ratio calculation
• Liquidation Threshold: Automated liquidation below 120% collateralization
• Liquidator Incentives: Liquidators claim collateral by repaying debt

🛡️ Security

• Comprehensive error handling with 8 distinct error codes
• Input validation on all transactions
• One active loan per borrower limit
• Admin-only protocol parameter controls

Protocol Parameters

Parameter	Default Value	Description
Collateral Ratio	150%	Minimum collateral required for loans
Liquidation Threshold	120%	Health ratio triggering liquidation
Interest Rate	5% APR	Annual interest rate (500 basis points)
Protocol Fee	0.5%	Origination fee on loan creation

Core Functions

For Borrowers

create-loan (collateral uint) (loan-amount uint)

• Creates a new collateralized loan
• Requires collateral ≥ 150% of loan amount
• Charges 0.5% protocol fee
• Returns net loan amount after fees

repay-loan

• Repays full loan amount plus accrued interest
• Returns collateral to borrower
• Marks loan as inactive

add-collateral (amount uint)

• Adds additional collateral to existing loan
• Improves loan health ratio
• Helps avoid liquidation

For Liquidators

liquidate (borrower principal)

• Liquidates unhealthy loans (health ratio < 120%)
• Liquidator pays total debt (principal + interest)
• Liquidator receives all collateral
• Profit = collateral value - debt paid

Utility Functions

deposit (amount uint)

• Deposits STX to user balance (for future features)

withdraw (amount uint)

• Withdraws STX from user balance

Read-Only Functions

get-loan (borrower principal)

• Returns loan details including collateral, amount, interest, and status

get-loan-health (borrower principal)

• Returns current health ratio (collateral/debt × 100)
• Example: 150% means loan is healthy, 110% means at risk

calculate-interest (loan-amount uint) (blocks-elapsed uint)

• Calculates interest for given parameters

get-user-balance (user principal)

• Returns user's deposited balance

Usage Examples

Creating a Loan

;; Borrow 1000 STX with 1500 STX collateral
(contract-call? .lending-protocol create-loan u1500000000 u1000000000)
;; Returns: (ok u995000000) ;; 1000 STX - 0.5% fee = 995 STX

Checking Loan Health

(contract-call? .lending-protocol get-loan-health 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM)
;; Returns: (ok u150) ;; 150% health ratio - healthy loan

Liquidating an Unhealthy Loan

;; If health ratio falls below 120%
(contract-call? .lending-protocol liquidate 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM)
;; Pays debt, receives collateral, earns profit

Repaying a Loan

(contract-call? .lending-protocol repay-loan)
;; Pays principal + interest, receives collateral back

Interest Calculation

Interest is calculated based on blocks elapsed since loan creation or last update:

Interest = (Loan Amount × Interest Rate × Blocks Elapsed) / (Blocks Per Year × 10000)
Blocks Per Year ≈ 52,560 (1 block per ~10 minutes)

Example: 1000 STX loan for 5,256 blocks (≈10% of year)

• Interest = (1000 × 500 × 5,256) / (52,560 × 10,000) = 5 STX

Error Codes

Code	Error	Description
u100	err-owner-only	Function restricted to contract owner
u101	err-insufficient-collateral	Collateral below required ratio
u102	err-loan-not-found	No active loan for borrower
u103	err-insufficient-balance	Insufficient balance for operation
u104	err-loan-already-exists	Borrower has existing active loan
u105	err-invalid-amount	Amount must be greater than zero
u106	err-liquidation-not-allowed	Loan health above liquidation threshold
u107	err-repayment-failed	Loan repayment operation failed
u108	err-transfer-failed	STX transfer operation failed

Admin Functions

set-collateral-ratio (new-ratio uint)

• Updates minimum collateral requirement

set-interest-rate (new-rate uint)

• Updates annual interest rate (in basis points)

withdraw-reserves (amount uint)

• Withdraws accumulated protocol fees

Note: Admin functions can only be called by contract owner

Security Considerations

1. Over-collateralization: Protects protocol from price volatility
2. Liquidation Buffer: 30% buffer between collateral ratio (150%) and liquidation (120%)
3. Single Loan Limit: Prevents loan management complexity
4. Immutable Loans: Loan amounts cannot be increased after creation
5. Automatic Interest: Interest updates on liquidation and repayment

Development & Testing

Prerequisites

• Clarinet CLI
• Stacks blockchain node (for mainnet deployment)

Testing Scenarios

1. Create loan with exact collateral requirement
2. Attempt liquidation on healthy loan (should fail)
3. Simulate price drop triggering liquidation
4. Test interest accrual over multiple blocks
5. Verify repayment returns correct collateral amount

Future Enhancements

• Multi-asset collateral support
• Variable interest rates based on utilization
• Partial loan repayments
• Flash loan functionality
• Oracle integration for price feeds
• Governance token for protocol decisions