A full-stack decentralized application (dApp) on the Stacks blockchain that empowers fans to directly tip creators using STX. This project demonstrates a production-ready architecture combining a React frontend, a Node.js/Express backend, and a Clarity smart contract.
- Direct Tipping: Send STX tips directly to creators via the Stacks blockchain.
- Wallet Integration: Seamless connection with Stacks wallets (e.g., Leather, Xverse) using WalletConnect v2 (via Reown AppKit) and
@stacks/connect. - Real-time Stats: View live data including total tips, recent transactions, and top tippers.
- Responsive Design: A modern, mobile-friendly UI with a premium aesthetic.
- Creator Profiles: Manage creator information and portfolios.
- Works Gallery: Showcase creators' work (music, art, etc.).
- Transaction Monitoring: Track and index tips for enhanced data persistence.
- API: RESTful endpoints for fetching creator and tip data.
- On-chain Logic: Securely handles tip transfers.
- Minimum Tip: Enforces a minimum tip amount (e.g., 0.1 STX) to prevent spam.
- History: Stores total tips and a ring buffer of the last 5 tips on-chain.
The project is structured as a monorepo with three main components:
contracts/: Clarity smart contracts.frontend/: React application (Vite + TypeScript).backend/: Node.js API (Express + MongoDB).
- Blockchain: Stacks (Clarity)
- Frontend: React, TypeScript, Vite, Stacks.js, WalletConnect (Reown AppKit)
- Backend: Node.js, Express, MongoDB (Mongoose)
- Monitoring: Sentry (optional)
- Node.js: v18 or higher recommended.
- MongoDB: A running MongoDB instance (local or cloud like Atlas).
- Stacks Wallet: A browser extension wallet (e.g., Leather) or mobile wallet.
- WalletConnect Project ID: (Optional) Get one from Reown Cloud for WalletConnect support.
The contract is located in contracts/tip-jar.clar.
- Mainnet Deployment: The frontend is currently configured to point to a deployed mainnet contract.
- Local Development: You can use Clarinet to test and deploy the contract locally.
The backend handles creator data and off-chain indexing.
-
Navigate to the backend directory:
cd tip-jar/backend -
Install dependencies:
npm install
-
Create a
.envfile intip-jar/backend/with the following variables:PORT=5001 MONGODB_URI=mongodb://localhost:27017/tipjar CORS_ORIGIN=http://localhost:5173 # Optional SENTRY_DSN=your_sentry_dsn NODE_ENV=development
-
Start the server:
npm run dev
The API will run on
http://localhost:5001.
The frontend is the user interface for tipping and viewing stats.
-
Navigate to the frontend directory:
cd tip-jar/frontend -
Install dependencies:
npm install
-
Create a
.envfile intip-jar/frontend/(or use existing defaults):# The Stacks contract address (Mainnet default provided in config) VITE_CONTRACT_ID=SP2A8V93XXB43Q8JXQNCS9EBFHZJ6A2HVXHC4F4ZB.tip-jar # Your WalletConnect Project ID (Required for WalletConnect) VITE_WALLETCONNECT_PROJECT_ID=YOUR_WC_PROJECT_ID
-
Start the development server:
npm run dev
Open
http://localhost:5173in your browser.
The backend provides the following main endpoints (prefixed with /api):
/creators:GET /: List all creators.POST /: Create a new creator profile.GET /:id: Get specific creator details.
/works:GET /: List works.POST /: Add a new work.
/tips:GET /: Get tip history (off-chain indexed).
/monitor:- Endpoints for monitoring blockchain events.
The tip-jar contract exposes:
tip(amount uint): Public function to send STX to the creator.get-total-tips: Read-only function returning the total amount tipped.get-recent-tip(index uint): Read-only function to get details of a recent tip by index.
- 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.
This project is licensed under the MIT License.