diff --git a/.gitignore b/.gitignore index 76c2842..3d01b3b 100644 --- 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 index 593ee6b..524dfe5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,244 @@ -# 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://s-btc-streamr.vercel.app](https://s-btc-streamr.vercel.app) + +The application is deployed and ready to use! Connect your wallet and start streaming 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 + +### Smart Contract (Clarity) +``` +contracts/ +└── sBTC-Streamr.clar # Main streaming protocol +``` + +**Key Functions:** +- `stream-to`: Create STX streams +- `stream-token-to`: Create token streams +- `withdraw`: Withdraw available funds +- `refuel`: Add funds to streams +- `refund`: Withdraw excess funds +- `update-details`: Modify stream parameters + +### Frontend (React + TypeScript) +``` +frontend/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ components/ # UI components +β”‚ β”œβ”€β”€ hooks/ # Custom hooks +β”‚ └── utils/ # Utilities +└── public/ # Static assets +``` + +### Testing +``` +tests/ +└── sBTC-Streamr.test.ts # Comprehensive test suite +``` + +## πŸš€ 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. **Install dependencies:** +```bash +npm install +``` + +2. **Run tests:** +```bash +npm run test +``` + +3. **Deploy to testnet:** +```bash +clarinet deployments generate --testnet --low-cost +clarinet deployment apply -p deployments/default.testnet-plan.yaml +``` + +### Frontend Setup + +1. **Navigate to frontend:** +```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 βœ… + +``` +βœ“ 12 tests passed +- Stream creation and management +- Multi-token support +- Withdrawal and refund functionality +- Signature verification +- Error handling +``` + +## 🎯 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/settings/Mainnet.toml b/settings/Mainnet.toml new file mode 100644 index 0000000..b39892e --- /dev/null +++ b/settings/Mainnet.toml @@ -0,0 +1,7 @@ +[network] +name = "mainnet" +stacks_node_rpc_address = "https://api.hiro.so" +deployment_fee_rate = 10 + +[accounts.deployer] +mnemonic = "" diff --git a/settings/Testnet.toml b/settings/Testnet.toml new file mode 100644 index 0000000..9cd6aae --- /dev/null +++ b/settings/Testnet.toml @@ -0,0 +1,7 @@ +[network] +name = "testnet" +stacks_node_rpc_address = "https://api.testnet.hiro.so" +deployment_fee_rate = 10 + +[accounts.deployer] +mnemonic = "ready giraffe river census point resource reduce caught burst possible round soft unique system output mother life shaft claw physical blast stumble toy hurt"