Fetch Quests Docs

Appearance

FAQ — Technical Questions ​

General ​

How do I run the project locally? ​

bash
# Clone and install
git clone https://github.com/your-org/fetch-quests.git
cd fetch-quests
pnpm install

# Start API server (port 3001)
cd api && node dev-server.mjs &

# Start frontend (port 5173)
cd frontend && pnpm dev

Why does authentication fail in dev mode? ​

Make sure the API server is running on port 3001. The frontend expects /api/* routes to be proxied there.

Common error: "API not running — use vercel dev, not vite dev"

Solution: Run node api/dev-server.mjs before pnpm dev.

Authentication ​

How does SIWE work? ​

Sign-In with Ethereum (SIWE) uses your wallet to cryptographically prove identity:

  1. Frontend requests a random nonce from backend
  2. User signs a standard message containing the nonce
  3. Backend verifies signature → issues JWT token
  4. Token used for subsequent API requests

No username/password needed!

Why do JWTs expire after 24 hours? ​

Security best practice. Short-lived tokens limit damage if compromised. Users simply sign again when prompted.

Can I extend token lifetime? ​

Edit api/_lib/auth.js:

javascript
.setExpirationTime('7d')  // Change from '24h'

Database ​

Where is data stored? ​

  • Production: Vercel KV (Upstash Redis)
  • Development: JSON files in api/seed/ + in-memory cache

How do I inspect KV data? ​

Use the Upstash console at https://console.upstash.com or the Redis CLI:

bash
# With Upstash REST API
curl "https://your-db.upstash.io/get/profile:0x123" \
  -H "Authorization: Bearer YOUR_TOKEN"

How do I reset the database? ​

Development: Delete/edit files in api/seed/

Production: Use Upstash console → FLUSHDB (careful!)

Why isn't my data persisting? ​

Check if you have KV configured:

  • KV_REST_API_URL and KV_REST_API_TOKEN must be set
  • Without these, data only persists in memory (lost on restart)

Quests ​

How does quest acceptance work? ​

  1. User clicks "Accept Quest"
  2. Frontend calls PATCH /api/quests with action: 'accept'
  3. Backend updates quest (activeFarmers++) and user profile (activeQuests)
  4. Both persisted to KV

What happens when max farmers is reached? ​

Quest status changes from open to in-progress. No more farmers can accept.

How do payouts work? ​

(Future) Smart contract escrow:

  1. Giver deposits USDC when creating quest
  2. Farmer completes work, submits PR
  3. GitHub CI verifies PR merged
  4. 48-hour review window
  5. Funds auto-release to farmer

GitHub Integration ​

Check:

  1. VITE_GITHUB_CLIENT_ID is set in frontend env
  2. GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set in backend
  3. OAuth App callback URL matches your domain

How do I set up GitHub OAuth for localhost? ​

  1. Create a separate OAuth App for development
  2. Set callback URL to http://localhost:5173
  3. Use those credentials in .env.local

No, one GitHub account per wallet address. Unlink first to link a different account.

Mail ​

Are messages really encrypted? ​

Yes! Mail content (subject, body) is encrypted with AES-256-GCM before storage. The encryption key is derived from JWT_SECRET.

Can the platform read my messages? ​

The platform operator with access to JWT_SECRET could decrypt messages. For truly private messaging, we'd need end-to-end encryption (E2EE) — a future enhancement.

Why can't I delete platform announcements? ​

Broadcasts (to: '*') are stored separately and shown to all users. They can be marked read but not deleted from your mailbox.

Blockchain ​

Why Base L2? ​

  • Low gas fees (~$0.01 per transaction)
  • Ethereum security (via optimistic rollup)
  • Growing ecosystem and builder community

Can I use another network? ​

Currently no. The codebase is designed for Base. Supporting other chains would require:

  1. Adding chain configs in web3.ts
  2. Deploying contracts to new chain
  3. Updating wagmi config

Where are the smart contracts? ​

contracts/ directory. Currently in development. The MVP uses off-chain storage with plans to migrate critical data on-chain.

Deployment ​

How do I deploy to Vercel? ​

  1. Push code to GitHub
  2. Import project in Vercel dashboard
  3. Set environment variables
  4. Deploy!

Why is there a 12 function limit? ​

Vercel Hobby plan allows max 12 serverless functions. We've consolidated endpoints to stay under this limit. Upgrade to Pro for unlimited.

How do I deploy the wiki? ​

GitHub Pages from /docs:

  1. Go to repo Settings → Pages
  2. Select "Deploy from a branch"
  3. Choose main branch, /docs folder
  4. Save

Wiki will be at https://your-org.github.io/fetch-quests/

Fetch Quests — Decentralized Gig-Work Platform

Built on Base Sepolia