LearnWeb3DAO · austinLorenzMccoy · Oct 8, 2025 · Oct 16, 2025 · Oct 16, 2025 · Oct 17, 2025
diff --git a/.gitignore b/.gitignore
@@ -1,13 +1,44 @@
+# OS
+.DS_Store
 
-**/settings/Mainnet.toml
-**/settings/Testnet.toml
-.cache/**
-history.txt
-
-logs
-*.log
+# Node
+node_modules/
+frontend/node_modules/
 npm-debug.log*
-coverage
-*.info
-costs-reports.json
-node_modules
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+
+# Envs
+.env
+.env.*
+frontend/.env
+frontend/.env.*
+
+# Build outputs
+dist/
+frontend/dist/
+build/
+
+# Caches
+.cache/
+.vite/
+frontend/.vite/
+node_modules/.vite/
+coverage/
+.nyc_output/
+*.tsbuildinfo
+.eslintcache
+
+# Tooling
+.turbo/
+.vercel/
+.netlify/
+
+# Editors (keep if repo doesn’t track these)
+.idea/
+.vscode/
+
+# Clarinet (local artifacts)
+.clarinet/
diff --git a/README.md b/README.md
@@ -1,5 +1,270 @@
-# Token Streaming
+# sBTC-Streamr 🚀
 
-A token streaming DeFi protocol built using Clarity for Stacks. Inspired by Superfluid.
+**The first multi-token streaming protocol on Stacks**
 
-This project was done as part of the "Introduction to Stacks" course for the "Stacks Developer Degree" on LearnWeb3.
+A decentralized streaming protocol that enables continuous payments with STX, sBTC, and other SIP-010 tokens. Built for the Stacks Ascent Trailblazer Program as an original feature enhancement.
+
+## 🌐 Live Demo
+
+**Try it now:** [https://stacks-token-streaming-liart.vercel.app](https://stacks-token-streaming-liart.vercel.app)
+
+**Deployed Contract:** `ST1QXWAQZCKF0X9YJDEY3EWCA7ABHKFJ0AN9AGCTC.stream-v3` on Stacks Testnet
+
+The application is fully deployed with multi-token streaming support! Connect your wallet and start streaming STX, sBTC, or custom SIP-010 tokens.
+
+## 🌟 Features
+
+### Multi-Token Support (Original Feature)
+- **STX Streaming**: Native Stacks token streaming
+- **sBTC Streaming**: Bitcoin-backed token streaming  
+- **Custom Token Support**: Any SIP-010 compliant token
+- **Unified Interface**: Single protocol for all token types
+
+### Core Functionality
+- **Continuous Payments**: Stream tokens over time instead of lump sums
+- **Flexible Timing**: Start immediately or schedule for future blocks
+- **Real-time Withdrawals**: Recipients can withdraw accumulated tokens anytime
+- **Stream Refueling**: Add more tokens to existing streams
+- **Excess Refunds**: Reclaim unused tokens after stream completion
+- **Cryptographic Updates**: Secure stream parameter modifications
+
+### Frontend Features
+- **Modern UI**: Beautiful, responsive React interface
+- **Wallet Integration**: Connect with Leather, Xverse, or any Stacks wallet
+- **Analytics Dashboard**: Track performance and insights
+- **Stream Management**: Create, monitor, and manage streams
+- **Real-time Updates**: Live balance and status updates
+
+## 🏗️ Architecture
+
+### Project Structure
+```
+sBTC-Streamr/
+├── contract/            # Smart contract (Clarity)
+│   ├── contracts/      # Contract source files
+│   ├── tests/          # Contract tests
+│   ├── deployments/    # Deployment plans
+│   └── settings/       # Network configurations
+├── frontend/           # Web application (React + Next.js)
+│   ├── src/
+│   │   ├── app/        # Next.js pages
+│   │   ├── components/ # UI components
+│   │   ├── hooks/      # Custom hooks
+│   │   └── lib/        # Utilities
+│   └── public/         # Static assets
+├── .gitignore
+└── README.md
+```
+
+### Smart Contract (Clarity)
+Located in `contract/` folder.
+
+**Key Functions:**
+- `stream-to`: Create STX streams
+- `stream-token-to`: Create SIP-010 token streams ✨ NEW
+- `withdraw`: Withdraw STX from streams
+- `withdraw-token`: Withdraw SIP-010 tokens from streams ✨ NEW
+- `refuel`: Add funds to streams
+- `refund`: Withdraw excess STX
+- `refund-token`: Withdraw excess SIP-010 tokens ✨ NEW
+- `update-details`: Modify stream parameters
+- `is-stx-stream`: Check if stream uses STX or tokens ✨ NEW
+- `get-token-contract`: Get token contract for a stream ✨ NEW
+
+### Frontend (React + TypeScript)
+Located in `frontend/` folder.
+
+**Features:**
+- Liquid Mercury theme (unique, non-generic)
+- Multi-token support (STX, sBTC, custom)
+- Real-time balance updates
+- Wallet integration (Stacks Connect)
+- Responsive design
+
+## 🚀 Quick Start
+
+### Prerequisites
+- [Clarinet](https://docs.hiro.so/clarinet/getting-started) - Stacks development toolkit
+- [Node.js](https://nodejs.org/) 16+ 
+- A Stacks-compatible wallet
+
+### Smart Contract Setup
+
+1. **Navigate to contract folder:**
+```bash
+cd contract
+```
+
+2. **Install dependencies:**
+```bash
+npm install
+```
+
+3. **Run tests:**
+```bash
+npm test
+```
+
+4. **Deploy to testnet:**
+```bash
+# Get testnet STX from faucet first
+clarinet deployment apply -p deployments/default.testnet-plan.yaml
+```
+
+See `TESTNET_DEPLOYMENT.md` for detailed deployment instructions.
+
+### Frontend Setup
+
+1. **Navigate to frontend folder:**
+```bash
+cd frontend
+```
+
+2. **Install dependencies:**
+```bash
+npm install
+```
+
+3. **Start development server:**
+```bash
+npm run dev
+```
+
+4. **Open [http://localhost:3000](http://localhost:3000)**
+
+## 📊 Test Results
+
+All tests passing ✅
+
+```
+✓ 19 tests passed
+- STX stream creation and management
+- SIP-010 token stream creation ✨ NEW
+- Multi-token detection and helpers ✨ NEW
+- STX withdrawal and refund functionality
+- Token withdrawal and refund functionality ✨ NEW
+- Signature verification
+- Authorization and access control
+- Error handling and edge cases
+```
+
+## 🎯 Use Cases
+
+### Freelance Payments
+- **Client → Freelancer**: Continuous payment streams for ongoing work
+- **Flexible Withdrawals**: Freelancers withdraw as needed
+- **Multi-token Support**: Pay in STX, sBTC, or custom tokens
+
+### Grant Distribution
+- **Organization → Project**: Structured funding over time
+- **Transparent Tracking**: Public stream visibility
+- **Automated Payments**: No manual intervention required
+
+### Subscription Services
+- **User → Service**: Recurring payments for services
+- **Token Flexibility**: Pay with preferred tokens
+- **Real-time Updates**: Live balance tracking
+
+## 🔧 Development
+
+### Smart Contract Development
+```bash
+# Create new contract
+clarinet contract new my-contract
+
+# Run tests
+npm run test
+
+# Deploy to testnet
+clarinet deployment apply -p deployments/default.testnet-plan.yaml
+```
+
+### Frontend Development
+```bash
+cd frontend
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run linting
+npm run lint
+```
+
+## 🧪 Testing
+
+The project includes comprehensive tests covering:
+
+- **Stream Creation**: STX and token streams
+- **Multi-token Support**: Different token types
+- **Withdrawal Logic**: Balance calculations
+- **Refund System**: Excess token recovery
+- **Signature Verification**: Cryptographic updates
+- **Error Handling**: Edge cases and failures
+
+Run tests:
+```bash
+npm run test
+```
+
+## 📈 Analytics
+
+The frontend includes analytics features:
+
+- **Stream Performance**: Volume, duration, success rates
+- **Token Usage**: Popular tokens and trends
+- **User Behavior**: Withdrawal patterns and preferences
+- **Growth Metrics**: Adoption and usage statistics
+
+## 🔐 Security
+
+- **Clarity Smart Contracts**: Formally verifiable
+- **Cryptographic Signatures**: Secure parameter updates
+- **Access Controls**: Proper authorization checks
+- **Error Handling**: Comprehensive error management
+
+## 🌐 Deployment
+
+### Testnet Deployment
+1. Set up wallet with testnet STX
+2. Configure `settings/Testnet.toml`
+3. Generate deployment plan
+4. Deploy contract
+
+### Frontend Deployment
+1. Build production bundle
+2. Deploy to hosting service
+3. Configure environment variables
+4. Update contract addresses
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## 🙏 Acknowledgments
+
+- **Stacks Foundation** for the Ascent Trailblazer Program
+- **LearnWeb3** for the foundational streaming protocol tutorial
+- **Clarity Community** for development tools and support
+
+## 📞 Support
+
+- **GitHub Issues**: Bug reports and feature requests
+- **Stacks Discord**: Community support
+- **Documentation**: [Stacks Docs](https://docs.stacks.co)
+
+---
+
+**Built with ❤️ for the Stacks Ascent Trailblazer Program**
+
+*This project demonstrates advanced Clarity development, multi-token support, and modern frontend integration as an original feature enhancement to the LearnWeb3 streaming protocol tutorial.*
diff --git a/Clarinet.toml → contract/Clarinet.toml b/Clarinet.toml → contract/Clarinet.toml
@@ -1,12 +1,12 @@
 [project]
-name = 'stacks-token-streaming'
-description = ''
+name = "sBTC-Streamr"
+description = ""
 authors = []
-telemetry = false
-cache_dir = './.cache'
+telemetry = true
+cache_dir = "./.cache"
 requirements = []
-[contracts.stream]
-path = 'contracts/stream.clar'
+[contracts.stream-v3]
+path = "contracts/stream.clar"
 clarity_version = 2
 epoch = 2.4