Lumma Protocol Docs

System documentation for a quest-native stablecoin utility protocol.

Contracts, data rails, reward logic, and operational controls for Lumma on Arc testnet.

Open CockpitLandingArc Docs

Overview

Lumma is a loop-based DeFi system: vault actions + stable swaps + validated incentive scoring.

  • Arc-native gas model (USDC as native gas).
  • Offchain anti-sybil scoring engine with settlement gates.
  • Onchain milestone NFTs for durable reward states.

Architecture

Frontend

Next.js host-routed surfaces:
`lumma.xyz` landing
`testnet.lumma.xyz` cockpit
`docs.lumma.xyz` docs

Execution Layer

Vault manager + milestones contracts on Arc testnet and StableFX router integration.

Reward Layer

Points, referrals, quests, and leaderboard snapshots in API + Supabase.

Control Layer

Admin pause controls, anti-abuse flags, and scheduled settlement windows.

Contract Registry

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

USDC: 0x3600000000000000000000000000000000000000
EURC: 0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a
StableFX Router: 0x1f91886C7028986aD885ffCee0e40b75C9cd5aC1
LummaVaultManager: 0xe40675fe67868d7c646110ca65c09a7f47f0cf54
LummaMilestones: 0x75f162947ed90906e5d0dbdac8ac10b97434bc99

Core Functions

Vault Manager

configureVault(bytes32 vaultId, uint8 risk, uint256 txCap)
setGlobalPause(bool paused)
setVaultPause(bytes32 vaultId, bool paused)
deposit(bytes32 vaultId, uint256 amount)
withdraw(bytes32 vaultId, uint256 amount)
getUserPosition(address user, bytes32 vaultId)

Milestones NFT

claimMilestone(address account, string tier, string tokenUri)
setContractMetadataURI(string uri)
contractURI()
tokenURI(uint256 tokenId)

Estimated APY Model (Testnet)

APY is modeled offchain for iteration speed and displayed explicitly as estimated.

estimated_apy = clamp(
  center + wave_drift + time_bucket_noise,
  vault.apy_min,
  vault.apy_max
)

Conservative: 5-8%, Balanced: 8-12%, Aggressive: 12-20%.

Security Model

  • Per-vault tx cap enforcement onchain.
  • Global + per-vault pause switches for emergency controls.
  • Anti-sybil scoring before social/referral settlement.
  • Delayed social reward windows with block rules.

Integration Quickstart

  1. Set Arc chain/RPC/explorer env vars.
  2. Configure Privy + Supabase keys.
  3. Set deployed contract addresses in env.
  4. Use Circle StableFX quotes with `CIRCLE_API_KEY`.
  5. Use `/api/*` routes for app flows and scoring events.

Ops Runbook

  • Pause rails with `POST /api/admin/vaults/pause` + admin token.
  • Deploy contracts via `npm run deploy:arc`.
  • Rotate compromised secrets before production activation.
  • Verify DNS + TLS before launch messaging.