Web3 Hackathon

Web3 bonus distribution app with a Bun/Hono backend, Vite/TanStack frontend, and a Foundry BonusDistributor contract deployed to Base Sepolia.

Prerequisites

• Bun
• Foundry (forge)
• MetaMask
• A Reown/WalletConnect project ID for VITE_WALLETCONNECT_PROJECT_ID
• An OpenAI API key for OPENAI_API_KEY
• A Base Sepolia RPC URL (https://sepolia.base.org works out of the box)
• Base Sepolia ETH for gas
• The dNZD token on Base Sepolia: 0x63ee4b77d3912DC7bCe711c3BE7bF12D532F1853

Project Structure

• backend: API, SQLite/libSQL database, bonus calculations, transaction verification, payout history
• frontend: employer dashboard, wallet connection, contract interaction
• contracts: Foundry project for BonusDistributor source and tests

Environment Files

Create local env files from the examples:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Install

cd frontend && bun install
cd backend && bun install

Configure MetaMask

Configure MetaMask for Base Sepolia.

If you need to add it manually:

• Network name: Base Sepolia
• RPC URL: https://sepolia.base.org
• Chain ID: 84532
• Currency symbol: ETH
• Block explorer URL: https://sepolia.basescan.org

Fund the wallets you plan to use (deployer / employer and any employee wallets you want to test history for) with Base Sepolia ETH before deploying or distributing bonuses.

Run

Frontend:

cd frontend
bun run dev

Backend:

cd backend
bun run db:push
bun run dev

Open http://localhost:3000, connect MetaMask, and switch MetaMask to Base Sepolia.

If the connected wallet is not linked to a company or employee yet, the dashboard shows the company onboarding flow.

Scripts

Frontend:

bun run dev
bun run build
bun run test
bun run lint
bun run format
bun run check

Backend:

bun run dev
bun run typecheck
bun run db:push
bun run db:seed

Contracts:

forge build
forge test
forge fmt