LUMMA//SYSTEMS
Enter Testnet

Lumma Documentation

Stablecoin utility + game loops on Arc testnet.

Lumma combines yield vaults, USDC/EURC swaps, points, referrals, quests, and milestone NFTs with Privy wallet authentication.

Enter TestnetArc Docs

What Is Lumma

Lumma is a yield app on Arc testnet. Users connect with Privy wallets, deposit to risk-tiered vaults, swap between USDC and EURC, and earn points across activity and social loops.

  • Arc testnet first, with USDC as native gas token.
  • Privy login + embedded wallet + external wallet support.
  • Hybrid rewards: offchain points + onchain milestone NFTs.

Core Feature Loops

Yield Vaults

Conservative (5-8%), Balanced (8-12%), Aggressive (12-20%). Deposit/withdraw with estimated APY labels.

Stable Swaps

USDC ↔ EURC quote + execute flow, history tracking, milestone swap counters.

Points + Tasks

Daily/social/activity tasks with anti-sybil checks and cooldowns.

Referrals + NFTs

Unique referral code, reward sharing activation rules, and Bronze/Silver/Gold/Diamond claims.

Architecture

Surfaces

`lumma.xyz` landing
`docs.lumma.xyz` docs
`testnet.lumma.xyz` app

Auth Layer

Privy access token verification + wallet-based identity mapped to user profile and referral code.

Data Layer

Supabase-backed persistence with in-memory fallback when service role key is missing.

Onchain Layer

LummaVaultManager + LummaMilestones contracts on Arc testnet, plus StableFX routing for swaps.

Contract Registry

Chain ID: 5042002
RPC: https://rpc.testnet.arc.network
Explorer: https://testnet.arcscan.app

USDC: Not configured
EURC: Not configured
StableFX Router: Not configured
LummaVaultManager: 0x15dce2dd5c6cb9508b19d68fea035fd61f521847
LummaMilestones: 0x15872472e3691f52a359b8596bbc7facdb470074

Values are read from `NEXT_PUBLIC_*` env vars with safe fallbacks.

Public API Map

GET  /api/vaults
POST /api/vaults/deposit
POST /api/vaults/withdraw
GET  /api/swap/quote
POST /api/swap/execute
GET  /api/swaps/history
POST /api/points/event
GET  /api/leaderboard
POST /api/referrals/apply
GET  /api/referrals/stats
GET  /api/quests/active
POST /api/quests/complete
POST /api/nft/claim
GET  /api/user/profile
POST /api/user/profile

API calls are user-scoped via `x-user-id`; authenticated sessions resolve to Privy user IDs.

Deploy Runbook (Lumma on Arc Testnet)

  1. Install Foundry (`foundryup`) and set Arc RPC + deployer key in env.
  2. Fund deployer wallet with testnet USDC from Circle faucet (USDC is gas on Arc).
  3. Deploy Lumma contracts using project script: `npm run deploy:arc`.
  4. Copy deployed addresses into env vars and redeploy web app.
  5. Verify contracts and deployment tx on `testnet.arcscan.app`.
NEXT_PUBLIC_ARC_RPC_URL=https://rpc.testnet.arc.network
NEXT_PUBLIC_ARC_CHAIN_ID=5042002
DEPLOYER_PRIVATE_KEY=0x...
NEXT_PUBLIC_USDC_ADDRESS=0x...

npm run deploy:arc

Operations

  • Pause vault rails with `POST /api/admin/vaults/pause` using `ADMIN_API_TOKEN`.
  • Track quote mode warnings (`circle`, `onchain`, `simulation`) in swap responses.
  • Keep Supabase service role key configured to avoid temporary in-memory profile mode.
  • Keep Privy app ID configured on deployed environments for wallet auth visibility.

Troubleshooting

  • Wallet connect missing: set `NEXT_PUBLIC_PRIVY_APP_ID` and redeploy.
  • Username not persisting: set `SUPABASE_SERVICE_ROLE_KEY` and run migrations.
  • Swap fallback warning: check `CIRCLE_API_KEY` and `CIRCLE_API_BASE_URL`.
  • NFT claim fails: confirm `DEPLOYER_PRIVATE_KEY` and milestone contract address.