BitLend Protocol Core Implementation

Clarinet.toml

@@ -1,21 +1,19 @@
 [project]
-name = "BitLend"
-description = ""
+name = 'BitLend'
+description = ''
 authors = []
 telemetry = true
-cache_dir = "./.cache"
-
-# [contracts.counter]
-# path = "contracts/counter.clar"
-
+cache_dir = './.cache'
+requirements = []
+[contracts.bitlend]
+path = 'contracts/bitlend.clar'
+clarity_version = 3
+epoch = 3.1
 [repl.analysis]
-passes = ["check_checker"]
-check_checker = { trusted_sender = false, trusted_caller = false, callee_filter = false }
+passes = ['check_checker']
 
-# Check-checker settings:
-# trusted_sender: if true, inputs are trusted after tx_sender has been checked.
-# trusted_caller: if true, inputs are trusted after contract-caller has been checked.
-# callee_filter: if true, untrusted data may be passed into a private function without a
-# warning, if it gets checked inside. This check will also propagate up to the
-# caller.
-# More informations: https://www.hiro.so/blog/new-safety-checks-in-clarinet
+[repl.analysis.check_checker]
+strict = false
+trusted_sender = false
+trusted_caller = false
+callee_filter = false

README.md

@@ -0,0 +1,94 @@
+**BitLend Protocol Documentation**  
+**Version 1.0 | Stacks L2 Smart Contract**
+
+### **Protocol Overview**
+
+BitLend is a non-custodial Bitcoin lending protocol enabling BTC holders to:
+
+1. Lock BTC-collateralized assets as security
+2. Borrow stable-value tokens against collateral
+3. Participate in decentralized liquidations
+4. Govern protocol parameters through DAO-like mechanisms
+
+Built on Stacks L2 for Bitcoin-finalized transactions.
+
+### **Key Technical Components**
+
+#### **1. Collateral Management System**
+
+- **Collateral Types**: Native Bitcoin representations (xBTC)
+- **Dynamic Ratios**:
+  - Minimum Collateral Ratio: 150%
+  - Liquidation Threshold: 130%
+  - Auto-rebalancing via:
+    ```clarity
+    (define-private (update-collateral-ratio user)
+      (let ((loan (unwrap! (get-loan user))))
+        (/ (* (get collateral-amount loan) (var-get btc-price))
+           (get borrowed-amount loan))))
+    ```
+
+#### **2. Debt Position Engine**
+
+- Interest Calculation:
+  ```
+  Interest = (Borrowed Amount × Rate × Blocks) / (Blocks/Year)
+  ```
+- Loan State Machine:  
+  `ACTIVE → UNDERCOLLATERALIZED → LIQUIDATED`
+
+#### **3. Price Oracle Integration**
+
+- Dual Security Model:
+  1. On-Chain: Time-weighted avg from major DEXs
+  2. Off-Chain: Decentralized node network consensus
+- Validity Enforcement:
+  ```clarity
+  (asserts! (<= (- block-height (var-get last-price-update))
+              PRICE-VALIDITY-PERIOD)
+            ERR-PRICE-EXPIRED)
+  ```
+
+### **Core Smart Contract Functions**
+
+#### **User Operations**
+
+| Function             | Parameters       | Security Checks                                |
+| -------------------- | ---------------- | ---------------------------------------------- |
+| `deposit-collateral` | `amount:uint`    | - Non-zero amount<br>- Protocol active status  |
+| `borrow`             | `amount:uint`    | - Collateral ratio >150%<br>- Valid price feed |
+| `repay-loan`         | `amount:uint`    | - Loan existence<br>- STX transfer success     |
+| `liquidate`          | `user:principal` | - Collateral <130%<br>- Penalty application    |
+
+#### **Governance Functions**
+
+```clarity
+(define-public (update-risk-parameters (new-min-ratio uint) (new-liq-threshold uint))
+;; Requires: Contract owner + <10% parameter change/24h
+```
+
+### **Risk Management Framework**
+
+#### **Liquidation Process**
+
+1. Trigger: Collateral ratio <130% for >2 blocks
+2. Execution:
+   - 10% penalty on outstanding debt
+   - Collateral auction:
+     ```
+     Auction Price = Max(OTC Offer, Oracle Price × 95%)
+     ```
+3. Settlement:
+   - Debt clearance
+   - Remaining collateral returned
+
+#### **Circuit Breakers**
+
+- Protocol Pause:
+  ```clarity
+  (define-public (emergency-pause)
+    (asserts! (is-eq tx-sender CONTRACT-OWNER)
+    (var-set protocol-paused true))
+  ```
+- Maximum Exposure:  
+  `Total Borrowed ≤ 70% of Total Collateral Value`