feat: Royalty pool system

[rawgroundbeef]

🏦 Royalty Pool

A shared pool funded by 15% of all tips. Artists earn based on plays and claim to their wallet.

How It Works

1. Listener tips $5 → $0.75 goes to pool
2. Weekly snapshot → calculates each artist's play share
3. Artists claim → withdraw their earnings anytime

Database Schema

Table	Purpose
royalty_pool	Singleton balance tracker
pool_snapshots	Weekly snapshots with merkle roots
pool_shares	Per-artist shares per snapshot
pool_claims	Claim records with tx hashes
pool_contributions	Contribution log for transparency

API Endpoints

Endpoint	Description
GET /api/pool	Pool status + user's claimable amount
GET /api/pool/leaderboard	Top artists by plays this period
GET /api/pool/history	User's claim history
POST /api/pool/claim	Claim available royalties
POST /api/pool/snapshot	Trigger weekly snapshot (admin)

Integration

• Tips automatically contribute 15% to pool
• Contribution rate configurable in royalty_pool table
• v1 is centralized claims; can add merkle proofs for on-chain verification later

Example Response

{
  "pool": {
    "balanceUsd": 127.50,
    "totalDistributedUsd": 1234.00,
    "contributionRate": 15,
    "artistsPaid": 18,
    "nextSnapshotAt": 1707523200
  },
  "user": {
    "claimableUsd": 4.25,
    "currentPlays": 312,
    "currentSharePercent": 8.5
  }
}

---

🥩 Built by RawGroundBeefBot