☕ Buy Me A Coffee (Decentralized App)

📌 Introduction

A complete Web3 dApp enabling anyone to send tips (ETH) along with a short memo to the contract owner. Built with a modern Neo-Brutalist UI and a highly optimized Solidity smart contract. The project focuses on ease of use, clean separation of logic, and professional build automation.

🏗️ Architecture Overview

The project is structurally divided into the backend (Smart Contracts) and frontend (UI).

1. Smart Contracts (src/, test/, script/):
   • Built and tested with Foundry.
   • BuyMeACoffee.sol: Contains the core logic for receiving payments, storing memos on-chain, and allowing the owner to withdraw funds.
   • Scripts handle automatic address synchronization directly to the frontend.
2. Frontend (frontend/):
   • Vanilla JavaScript + ethers.js v6 to interact directly with the blockchain via MetaMask.
   • Neo-brutalist styling powered by TailwindCSS.

⚙️ Prerequisites

To run this project on your local machine, you will need:

• Foundry (Forge, Anvil, Cast) installed.
• Node.js & npm (for running the frontend local server using serve).
• Python 3 (alternative for serving the frontend).
• A browser wallet like MetaMask.

🚀 How to Run Locally (Beginner's Guide)

Follow these steps to deploy your local testnet and connect your frontend!

1. Start the Local Blockchain

We use anvil to run a fast, local Ethereum node. Open a new terminal and run:

make anvil

(Leave this terminal running. It provides 10 test accounts seeded with 10,000 ETH each.)

2. Deploy the Smart Contract

In a separate terminal, deploy the smart contract to your local Anvil node:

make deploy-anvil

Magic trick: This script automatically syncs the newly generated contract address directly into frontend/constants/contractAddress.js and copies over the ABI, so your frontend knows exactly where to look!

3. Start the Frontend Application

You can serve the frontend using either Node.js or Python. Run ONE of the following commands:

# Using Node.js (via the 'serve' npm package)
make serve-node

# OR using Python 3
make serve-python

The application will be available at http://localhost:3000 (Node) or http://localhost:8000 (Python).

4. Connect Your Wallet

• Open MetaMask, click the network dropdown, and select Localhost 8545.
• Import one of the private keys provided by your anvil terminal (from step 1). This is crucial because your regular accounts won't have any local ETH!
• Click "Connect Wallet" on the dApp.
• If you imported Account #0 (the deployer account), you will see the Admin Zone appear, allowing you to withdraw all tipped coffee funds.

🛠️ Makefile Commands Cheat Sheet

This project utilizes a Makefile to simplify complex commands into single keywords:

• make build: Compiles the Solidity contracts.
• make test: Runs the automated test suite natively in Foundry.
• make anvil: Starts the local Ethereum testnet.
• make deploy-anvil: Deploys the contract to Anvil and syncs addresses/ABIs.
• make deploy-sepolia: Deploys to the Sepolia testnet (Requires SEPOLIA_RPC_URL and PRIVATE_KEY environment variables).
• make serve-node: Starts the frontend on localhost:3000 via npm serve.
• make serve-python: Starts the frontend on localhost:8000 via Python's HTTP server.

🐛 Troubleshooting Common Errors

• could not decode result data (BAD_DATA): This means your frontend is looking at a contract address that has no code. Did you restart anvil? If so, you must redeploy by running make deploy-anvil again while anvil is active.
• insufficient funds for gas * price + value: The MetaMask account you are using has 0 ETH on the local network. Make sure you import one of the accounts generated by the make anvil command.
• RPC Error / Wallet won't connect: Ensure MetaMask is set to Localhost 8545 and your anvil node is currently running in your terminal.