A revolutionary Web3 application that combines blockchain-based payments with real-time communication, featuring a unique timer system that can be extended through cryptocurrency payments.
- MetaMask Wallet Connection - Seamless Web3 wallet integration
- Smart Contract Interaction - PaymentSplitter and TestToken contracts
- Sepolia Testnet Support - Full testnet compatibility
- Token-based Payments - THT (TreeHole Token) for timer extensions
- Random Duration Timer - 10-15 minute sessions
- Real-time Countdown - Live updates with visual indicators
- Payment Extensions - Extend timer through blockchain payments
- State Management - Running, paused, warning, and critical states
- Audio Notifications - Sound alerts for state changes
- WebRTC Integration - Peer-to-peer voice communication
- Audio Processing - Real-time audio level monitoring
- Permission Management - Graceful microphone access handling
- P2P Simulation - Testing environment for voice features
- Automatic Token Approval - Streamlined payment process
- Payment Splitting - 50/50 split between listener and treasury
- Transaction Tracking - Complete payment history
- Error Handling - Comprehensive retry logic and user feedback
- Glassmorphism Design - Beautiful modern interface
- Responsive Layout - Works on all devices
- Real-time Updates - Live status indicators
- Toast Notifications - User-friendly feedback system
- Loading States - Professional loading indicators
- Node.js 18+ and npm
- MetaMask browser extension
- Git
- Clone the repository
git clone https://github.com/yourusername/treehole.git
cd treehole- Install dependencies
# Install frontend dependencies
cd frontend
npm install
# Install contract dependencies
cd ../contracts
npm install- Environment Setup
# Copy environment examples
cp .env.example .env
cp contracts/.env.example contracts/.env
cp frontend/.env.example frontend/.env
# Edit .env files with your configuration- Deploy Contracts (Optional)
cd contracts
npm run deploy:sepolia- Start Development Server
cd frontend
npm run dev- Open Application
Navigate to
http://localhost:3000
SEPOLIA_RPC_URL=your_alchemy_or_infura_url
PRIVATE_KEY=your_wallet_private_key
ETHERSCAN_API_KEY=your_etherscan_api_keyVITE_CONTRACT_ADDRESS_PAYMENT_SPLITTER=deployed_contract_address
VITE_CONTRACT_ADDRESS_TEST_TOKEN=deployed_token_address
VITE_NETWORK_CHAIN_ID=11155111The project uses two main contracts:
- PaymentSplitter - Handles payment processing and splitting
- TestToken - ERC20 token for payments (THT)
Contract addresses are configured for Sepolia testnet by default.
- Click "Connect Wallet" button
- Approve MetaMask connection
- Ensure you're on Sepolia testnet
- Click "Claim Tokens" to get THT tokens
- Tokens are required for timer extensions
- Click "Start Timer" to begin session
- Timer runs for 10-15 minutes randomly
- Click "Extend Timer" when running low
- Choose extension duration (1-60 minutes)
- Approve token spending and payment
- Click "Start Voice Chat" to test voice features
- Allow microphone access when prompted
- Framework: Vanilla JavaScript (ES6+)
- Build Tool: Vite
- Styling: Tailwind CSS + Custom CSS
- Web3: Ethers.js v6
- State Management: Custom EventBus + StateManager
- Framework: Foundry
- Language: Solidity ^0.8.19
- Network: Sepolia Testnet
- Standards: ERC20, OpenZeppelin
App.js- Main application controllerTimer.js- Timer logic and state managementPayment.js- Payment processingWalletManager.js- Web3 wallet integrationContractsManager.js- Smart contract interactionsVoiceChat.js- Audio/voice functionalityEventBus.js- Event systemStateManager.js- Application state
PaymentSplitter.sol- Payment processing and splittingTestToken.sol- ERC20 token implementation
cd frontend
npm run testcd contracts
forge test- Connect wallet and claim tokens
- Start timer and let it run
- Extend timer through payment
- Test voice chat functionality
- Verify all error scenarios
cd frontend
npm run build
# Deploy dist/ folder to your hosting servicecd contracts
npm run deploy:mainnet # For production
npm run deploy:sepolia # For testing- Input validation for all user inputs
- Safe contract interactions with proper error handling
- Secure token handling and approval patterns
- Protection against common Web3 vulnerabilities
- Environment variable protection
- Never commit private keys or sensitive data
- Always verify contract addresses before deployment
- Test thoroughly on testnets before mainnet deployment
- Use hardware wallets for production deployments
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow existing code style and patterns
- Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PR
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenZeppelin for secure smart contract libraries
- Ethers.js for Web3 integration
- Vite for fast development experience
- Tailwind CSS for styling system
- Foundry for smart contract development
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@treehole.app
- Mainnet deployment
- Real P2P voice chat implementation
- Mobile app development
- Additional payment tokens support
- Advanced timer customization
- User profiles and history
- Multi-language support
Built with ❤️ by the TreeHole Team
Connecting people through blockchain technology and real-time communication.