Building a more accountable future on Stacks
🌐 Live Demo • 📖 Documentation • 🚀 Quick Start • 💡 Features • 🤝 Contributing
- Overview
- Key Features
- Why Stacks?
- Tech Stack
- Live Demo
- Getting Started
- Smart Contracts
- Architecture
- Security
- Contributing
- License
Ilenoid is a production-ready decentralized application (dApp) that revolutionizes charity transparency by leveraging blockchain technology on Stacks. Every donation, milestone, and fund release is recorded immutably on-chain, ensuring complete accountability and trust.
Traditional charity platforms lack transparency. Donors lose track of funds once they leave their bank account, leading to:
- ❌ Donor fatigue and distrust
- ❌ Lack of accountability
- ❌ No way to verify fund usage
- ❌ Limited donor engagement
✅ Immutable Tracking: Every STX and SIP-010 token tracked on-chain from donation to expenditure
✅ Milestone Governance: Funds locked in smart contracts, released only after donor approval
✅ Weighted Voting: Donors vote based on contribution amount (vote weight = donation amount)
✅ Radical Transparency: All operations recorded on-chain with full visibility
✅ Low Fees: Built on Stacks for affordable transactions
✅ Bitcoin Security: Leverages Bitcoin's security through Stacks blockchain
- Multi-Asset Donations: Support for STX and SIP-010 fungible tokens
- Milestone-Based Funding: Projects broken into verifiable milestones
- Weighted Voting System: Donors vote on milestone releases based on contribution weight
- NGO Verification: Only verified NGOs can create projects
- Real-Time Updates: TanStack Query for efficient data fetching and caching
- Emergency Controls: Pausable contracts with owner controls
- Stacks Connect: Native wallet integration (Hiro, Xverse, and more)
- Stacks Benefits: Bitcoin security, Clarity language, low fees
- Modern Web3 Stack: @stacks/connect, @stacks/transactions, latest React patterns
- Clarity 4: Built with the latest Clarity language features
- Responsive Design: Works seamlessly on desktop and mobile
- Wallet Integration: Stacks Connect for multi-wallet support
- Network Support: Testnet and Mainnet deployment ready
- Error Handling: Comprehensive error messages and recovery flows
- On-Chain Records: All transactions permanently recorded
- Donation History: Complete donation tracking per project
- Milestone Tracking: Real-time milestone status and voting progress
- Project Analytics: Funding progress, donor counts, and more
We chose Stacks as our platform because:
- Bitcoin Security: Inherits security and finality from Bitcoin
- Clarity Language: Decidable, secure smart contracts by design
- Low Fees: Affordable transactions for micro-donations
- Growing Ecosystem: Active community and strong developer support
- sBTC Integration: Native Bitcoin support through sBTC
- Post-Conditions: Built-in transaction safety features
- Framework: Next.js 16.1 (App Router, React Server Components)
- Web3: @stacks/connect + @stacks/transactions
- Styling: Tailwind CSS v4
- State Management: Zustand v5
- Data Fetching: TanStack Query v5
- UI Components: Custom components with Headless UI
- Notifications: React Hot Toast
- Language: Clarity 4
- Framework: Clarinet
- Security: Clarity's built-in security features (no reentrancy by design)
- Testing: Comprehensive test suite (37 tests) using @stacks/transactions
- Deployment: Stacks Testnet (✅), Mainnet (⏳)
- Frontend Deployment: Netlify
- Contract Deployment: Stacks Testnet
- RPC: Stacks API endpoints (testnet.hiro.so)
- Explorer: Stacks Explorer
- Stacks Connect: Multi-wallet support (Hiro, Xverse, etc.)
- @stacks/transactions: Contract calls and read-only functions
- Stacks Explorer: Contract verification and exploration
- Frontend: https://ilenoid.netlify.app/ ✅ Live
- Stacks Testnet: ✅ Deployed
- Stacks Mainnet: ⏳ Pending final testing
Stacks Testnet:
- Deployer:
ST2W758Q6BS97GWK7STXTAW2ZG26YFXE4V5WMTG3Q - Ilenoid:
ST2W758Q6BS97GWK7STXTAW2ZG26YFXE4V5WMTG3Q.ilenoid - NGO Registry:
ST2W758Q6BS97GWK7STXTAW2ZG26YFXE4V5WMTG3Q.ngo-registry - View on Stacks Explorer
Stacks Mainnet:
- Ilenoid: ⏳ Coming soon after testnet validation
- Node.js 18+ and npm/yarn/pnpm
- Stacks Wallet (Hiro Wallet, Xverse, etc.)
- Stacks Testnet STX (for testing) - Get from Stacks Testnet Faucet
- Git
- Clarinet (for contract development) - Install from Clarinet docs
- Clone the repository:
git clone git@github.com:chain-mint/ilenoid.git
cd ilenoid- Install dependencies:
npm install
# or
yarn install
# or
pnpm install- Set up environment variables:
cp .env.example .env.localEdit .env.local with your configuration:
# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Stacks Network
NEXT_PUBLIC_STACKS_NETWORK=testnet # testnet or mainnet
NEXT_PUBLIC_STACKS_API_URL=https://api.testnet.hiro.so
# Contracts (Testnet)
NEXT_PUBLIC_ILENOID_ADDRESS=ST2W758Q6BS97GWK7STXTAW2ZG26YFXE4V5WMTG3Q.ilenoid
NEXT_PUBLIC_NGO_REGISTRY_ADDRESS=ST2W758Q6BS97GWK7STXTAW2ZG26YFXE4V5WMTG3Q.ngo-registry- Run the development server:
npm run dev
# or
yarn dev
# or
pnpm dev- Open http://localhost:3000 in your browser
See the contract README for detailed instructions on:
- Building and testing contracts
- Deploying to Stacks networks
- Running tests with Clarinet
- Contract architecture and features
- ilenoid.clar: Main contract handling projects, donations, voting, and fund releases (753 lines)
- ngo-registry.clar: Verified NGO management system
- ✅ Clarity 4 language features
- ✅ Pausable for emergency situations
- ✅ Owner-only functions for NGO management
- ✅ Milestone-based fund locking
- ✅ Weighted voting system (>50% quorum)
- ✅ Multi-asset support (STX + SIP-010 tokens)
- ✅ Built-in security (no reentrancy by design in Clarity)
- Comprehensive test coverage (37 tests)
- Clarity's built-in security features
- Access control mechanisms
- Emergency withdrawal capabilities
- Full on-chain transparency
See contract documentation for more details.
- Clarity Language: Decidable, secure smart contracts by design
- No Reentrancy: Clarity prevents reentrancy attacks by design
- Access Control: Owner-only functions for critical operations
- Pausable: Emergency pause functionality
- Input Validation: Comprehensive checks on all inputs
- On-Chain Transparency: All operations are verifiable on-chain
- ✅ Internal security review completed
- ✅ Comprehensive test suite (37 tests)
- ✅ Clarity's built-in security guarantees
- ⏳ External audit planned
If you discover a security vulnerability, please email [security@yourdomain.com] instead of using the issue tracker.
- Smart Contract Documentation
- Deployment Guide
- Implementation Phases
- NGO Registration Flow
- Wallet Connection Setup
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Follow TypeScript best practices
- Write tests for new features
- Update documentation
- Follow the existing code style
- Add comments for complex logic
- Stacks for the amazing Bitcoin L2 platform
- Hiro for excellent developer tools and documentation
- Stacks.js for Web3 integration
- Farcaster for social infrastructure
- The entire Stacks and Web3 community for inspiration and support
This project is licensed under the MIT License - see the LICENSE file for details.
- Live Frontend: https://ilenoid.netlify.app/
- Testnet Contracts: Stacks Explorer
- Smart Contract Docs: contract/README.md
- Stacks Documentation: docs.stacks.co
If you find this project useful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting new features
- 🤝 Contributing code
- 📢 Sharing with others