A fully open-source smart contract system that lets ANY developer add subscription payments to their dApps — like "Stripe Subscriptions for Web3."
This project provides a production-ready, modular subscription payment system for Web3 applications. It supports both native ETH and ERC20 tokens, with features like gasless meta-transactions, L2 optimization, and comprehensive analytics.
- ✅ Core Subscription Management: Create, charge, cancel, and pause subscriptions
- ✅ Multi-Token Support: Native ETH and ERC20 tokens
- ✅ Pull Payment Model: Gas-efficient subscription charging
- ✅ Admin Controls: Pause/resume subscriptions and contract operations
- ✅ Event Logging: Comprehensive events for off-chain tracking
- ✅ Gasless Transactions: Meta-transaction support via EIP-712
- ✅ L2 Optimization: Gas-optimized contract for Layer 2 networks
- ✅ Analytics: On-chain and off-chain analytics tracking
- ✅ Example Frontend: React application with modern UI
- ✅ Example Backend: Bun-based API with event listener
┌─────────────────────────────────────────────────────────────┐
│ Web3 Subscriptions │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Subscription │ │ L2Subscription │ │
│ │ Manager │ │ (Optimized) │ │
│ │ │ │ │ │
│ │ - Create │ │ - Batch Charges │ │
│ │ - Charge │ │ - Packed Storage │ │
│ │ - Cancel │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────────┬───────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ MetaTransactions │ │
│ │ (Gasless) │ │
│ └─────────────────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ SubscriptionAnalytics │ │
│ │ (Metrics) │ │
│ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│ │
│ │
┌────────▼────────┐ ┌────────▼────────┐
│ Frontend │ │ Backend │
│ (React) │ │ (Bun) │
│ │ │ │
│ - UI Components │ │ - REST API │
│ - Web3 Hooks │ │ - Event Listener│
│ - Wallet Connect│ │ - Analytics │
└─────────────────┘ └─────────────────┘
- Node.js 18+ or Bun
- Hardhat
- MetaMask or compatible wallet
- Clone and navigate to the project:
cd web3-subscriptions- Install Hardhat dependencies:
cd hardhat
bun install- Install Frontend dependencies:
cd ../frontend
bun install- Install Backend dependencies:
cd ../backend
bun installCreate a .env file in the project root:
# Network RPC URLs GOERLI_RPC_URL=https://eth-goerli.g.alchemy.com/v2/YOUR_API_KEY POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY # Deployer PRIVATE_KEY=your_private_key_here RECIPIENT_ADDRESS=0x... # Address to receive subscription payments # Contract Addresses (set after deployment) SUBSCRIPTION_MANAGER_ADDRESS= META_TRANSACTIONS_ADDRESS= L2_SUBSCRIPTION_ADDRESS= ANALYTICS_ADDRESS= # Etherscan API Keys ETHERSCAN_API_KEY=your_etherscan_api_key POLYGONSCAN_API_KEY=your_polygonscan_api_key
- Deploy contracts:
cd hardhat
npx hardhat run scripts/deploy.ts --network goerli- Verify contracts:
npx hardhat run scripts/verify.ts --network goerli
Or use the one-click deploy script:
./scripts/deploy-all.sh
// Native ETH subscription subscriptionManager.createSubscription( address(0), // Native ETH 1 ether, // Amount 3600 // Interval (1 hour) ); // ERC20 token subscription subscriptionManager.createSubscription( tokenAddress, // ERC20 token 100 * 10**18, // Amount 86400 // Interval (1 day) );
Anyone can charge a subscription when the interval has elapsed:
subscriptionManager.chargeSubscription(subscriptionId);subscriptionManager.cancelSubscription(subscriptionId);web3-subscriptions/
├── contracts/ # Solidity smart contracts
│ ├── core/ # Core subscription contract
│ ├── extensions/ # Meta-transactions, L2, Analytics
│ └── mocks/ # Mock contracts for testing
├── hardhat/ # Hardhat configuration and scripts
│ ├── scripts/ # Deployment scripts
│ └── test/ # Contract tests
├── frontend/ # React frontend example
│ └── src/
│ ├── components/ # UI components
│ ├── hooks/ # React hooks
│ └── utils/ # Utilities
├── backend/ # Bun backend example
│ └── src/
│ ├── services/ # Business logic
│ └── api/ # REST API
├── docs/ # Documentation
└── scripts/ # Deployment scripts
Run contract tests:
cd hardhat npx hardhat test
See SECURITY.md for security considerations and best practices.
Contributions are welcome! Please read our contributing guidelines and submit pull requests.
MIT License - see LICENSE file for details.
- Open an issue on GitHub
- Check the documentation in
docs/ - Review ARCHITECTURE.md for detailed architecture
- OpenZeppelin for security libraries
- Hardhat team for the development framework
- Bun team for the runtime