[Tutorial] Building an sBTC DeFi Lending Protocol

Overview

Complete tutorial for building a production-ready sBTC lending protocol with collateralized borrowing, health factor tracking, and liquidation mechanics.

Gap in Current Documentation

What's Missing:

1. No sBTC DeFi lending tutorial - DeFi use case page shows Hermetica and StackingDAO but no step-by-step lending protocol tutorial
2. Existing DeFi lending example has issues:
   • Uses STX instead of sBTC (misses emerging use case)
   • Contract has bugs (borrow function doesn't accumulate existing loans properly)
   • No tutorial or tests - just contract code
   • Uses outdated Clarity syntax (block-height instead of stacks-block-height)
3. sBTC Builder Quickstart is entry-level only - No advanced DeFi patterns

Where Users Look:

• docs.stacks.co/get-started/use-cases/defi - Shows protocols but no tutorials
• docs.stacks.co/sbtc - Basics only, no DeFi tutorials
• docs.stacks.co/cookbook/clarity/example-contracts/defi-lending - Broken example

Proposed Solution

Add comprehensive sBTC DeFi lending tutorial to the cookbook or use cases section.

Tutorial Covers:

• Protocol design (collateral ratios, health factors, liquidations)
• Complete Clarity smart contract implementation
• Supply/withdraw for lenders
• Borrow/repay with position accumulation
• Health factor calculation
• Liquidation mechanics with incentives
• 24 comprehensive Clarinet SDK tests
• Production integration patterns
• Common pitfalls and solutions

Working Code & Tutorial

Repository: https://github.com/bastiatai/sbtc-lending

Key Features:

• ✅ Complete smart contract (253 lines)
• ✅ 24 Clarinet SDK tests (all passing)
• ✅ Comprehensive README with usage examples
• ✅ Step-by-step TUTORIAL.md
• ✅ Fixes bugs in existing cookbook example
• ✅ Uses Clarity 3+ syntax (stacks-block-height)
• ✅ Production integration guidance

Tutorial Outline

1. Core Concepts - Collateralization, health factors, liquidation economics
2. Project Setup - Clarinet project structure
3. Smart Contract - Step-by-step contract development
   • Constants and error codes
   • Data storage design
   • Supply/withdraw functions
   • Borrow with position accumulation (fixes cookbook bug!)
   • Repayment with proportional collateral return
   • Health factor calculation
   • Liquidation function
4. Testing - Comprehensive Clarinet SDK tests
5. Production Integration - Real sBTC token integration
6. Common Pitfalls - What to avoid

Why This Matters

1. Emerging Use Case - Bitcoin-backed lending is a killer DeFi app for sBTC
2. Fixes Ecosystem Gap - Current lending example is broken and incomplete
3. Educational Value - Teaches core DeFi patterns developers can adapt
4. Production-Ready - Includes health factors, partial repayments, liquidations

Suggested Location

Add to either:

• docs/get-started/use-cases/defi.md - Add "Building a Lending Protocol" section
• docs/cookbook/clarity/tutorials/ - Create sbtc-lending-protocol.md

Additional Context

This tutorial demonstrates the pattern requested in the DeFi use case page - showing developers how to build DeFi protocols, not just use existing ones.

The example fixes critical bugs in the existing cookbook lending example while using sBTC (the emerging asset on Stacks) instead of STX.

---

Ready for review and merge. All code tested and documented. Happy to address feedback or adjust structure to fit docs style guide.

Start by reviewing docs/get-started/use-cases/defi.md, docs/cookbook/clarity/example-contracts/defi-lending, and the proposed sbtc-lending repository and TUTORIAL.md. Check the documentation style and decide whether the tutorial belongs in the use-cases section or docs/cookbook/clarity/tutorials/. Done means a complete sBTC lending tutorial covers the listed concepts, implementation, tests, integration guidance, and pitfalls.