POPDOCS
OPEN APP →

// run it in your city · agpl-3.0

FORKING THE PROTOCOL

Proof of Purpose is open-source under AGPL-3.0 so any community can run the same protocol locally. This guide takes you from a fresh fork to a live deployment — ~1 day on testnet and another half day on mainnet.

License & brand

// rebrand before launch

The name "Proof of Purpose", the $PURPOSE wordmark, and the visual identity in src/assets/ are not part of the AGPL grant. Please rebrand before launching publicly. The code, contracts, and architecture are yours to reuse.

Prerequisites

  • A wallet on Base mainnet with a small amount of ETH for gas.
  • A separate treasury wallet (Safe / multisig recommended).
  • A backend signer keypair generated fresh for your fork — never reuse upstream's.
  • A Lovable account (gives you Cloud + edge functions + Postgres) or your own Supabase project.

1. Create your fork

  1. Click Fork on GitHub, or import the repo into a new Lovable project.
  2. Rebrand: package.json → name; index.html → <title>; src/index.css → swap brand color tokens; src/assets/ → replace logos and hero art; README.md → your project name.
  3. Pick a license header — AGPL-3.0 is required for any redistribution.

2. Deploy the contracts

Follow contracts/DEPLOYMENT.md end-to-end. Six contracts in order:

  1. PurposeTokenV2
  2. BountyManagerV2
  3. VendorRedemptionV2
  4. PurposeGovToken (vPURPOSE shadow vote token)
  5. thirdweb Vote governor
  6. (mainnet) OpenZeppelin Timelock

Test on Base Sepolia first. Verify every step in the thirdweb dashboard or Basescan before touching mainnet.

3. Wire the addresses

Edit src/config/contracts.ts:

export const CONTRACTS = {
  PURPOSE_TOKEN: "0xYOUR_PURPOSE_V2",
  VENDOR_REDEMPTION: "0xYOUR_VENDOR_REDEMPTION_V2",
  BOUNTY_MANAGER: "0xYOUR_BOUNTY_MANAGER_V2",
  TREASURY: "0xYOUR_TREASURY",
  USDC_BASE: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  DONATION_SPLIT: "0xYOUR_DONATION_SPLIT",
} as const;

export const ADMIN_ALLOWLIST = [
  "0xYOUR_ADMIN_EOA",
  // optional ENS, e.g. "yourname.eth"
] as const;

4. Set up the backend

  1. Apply every migration in supabase/migrations/ (Lovable Cloud does this on first deploy).
  2. Add runtime secrets: BOUNTY_ADMIN_PRIVATE_KEY, REDEMPTION_SIGNER_PRIVATE_KEY, THIRDWEB_SECRET_KEY, RESEND_API_KEY (optional).
  3. Configure auth providers (Google, Apple, email).
  4. Deploy the edge functions in supabase/functions/.

5. Approve your first vendor & run a test bounty

  1. From your admin EOA, call VendorRedemptionV2.approveVendor(vendorAddr).
  2. Visit /admin/bounties, create a small test bounty.
  3. Sign in as a Champion on a second device, apply, and check in.
  4. End the bounty as admin — $PURPOSE should mint to the Champion.
  5. Have the vendor scan the Champion's redeem QR. Vendor wallet should receive USDC instantly.

6. Going public

  • Read the Security page and complete the hardening checklist for forks.
  • Run the in-app security scan in Lovable Cloud and resolve every finding.
  • Publish your forked repo with your branding and a clear README.md.
  • Tell the upstream community! Open an issue or PR linking to your deployment.