RUNNER — run to earn

Whitepaper (v1.0).

A simple GPS running app with a run-to-earn layer: own a RUNNER Genesis sneaker NFT, run inside its pace zone, and earn the RUNNER token.

Try it: https://runearn.fun

Live on Robinhood Chain (25 October 2026). RUNNER trades against IMD in its Uniswap v4 pool (liquidity locked forever); RUNNER Genesis sneakers are on sale with real ETH. Run rewards are on: emission started 25 October 2026 (10,000,000 RUNNER/day, halving every 30 days); verified runs can be claimed.

Contract	Address
RUNNER token	0x52cE7fC26a4Bb4B8aFef02C1b00486FDF4Bb804e
RunnerHook (RUNNER/IMD pool, 4% fee)	0x962c745D5feC4BC0Fd6dE15D47fc17C40C4c68EC
RunnerRouter (IMD)	0x55866De8BD1e5Fbf79433Ee2526D3405F64692Ba
RunnerEthRouter (ETH)	0xcAc6938E8309Dc9687C82DFb745B21950Fe0F6A1
RUNNER Genesis NFT	0x7ded256c6646630dFcf15317aeB7cF40027932CC
IMD	0x5F7Bb59365ce557C26dbcAa4EE9d39A4b95B7127

Each deployed contract was checked byte for byte against the audited build.

Install on your phone

Android app: download it from https://runearn.fun/download (an APK, no Play Store needed). It keeps recording with the screen locked. Building and publishing it: see NATIVE.md.

Or add the website to your home screen:

1. Open the link above on your phone.
2. Add it to your home screen:
   • iPhone (Safari): Share → Add to Home Screen
   • Android (Chrome): ⋮ menu → Install app / Add to Home screen
3. Open RUNNER from the home screen and go through the short setup.

How to use it

1. Onboarding — sign in (or continue as a guest) and enter your name.
2. Record a real outdoor run — tap Record → Start. Check the GPS line, distance and pace look right (compare with your watch if you have one).
3. Earning — with a sneaker NFT equipped, the bar says Earning, Too fast or Too slow for its pace zone. RUNNER appears when you finish.
4. Heart rate — You → Settings → Heart-rate sensor → pair a Bluetooth chest strap or a watch that broadcasts heart rate (+10% while earning).
5. Get a sneaker — sign in, open Earn → Browse sneakers, pick one and buy it with ETH on Robinhood Chain (Common 0.005 · Uncommon 0.015 · Rare 0.04 · Epic 0.1).
6. Earn tab — level up, assign attribute points (Efficiency / Resilience) and repair with RUNNER.
7. Rewards tab — for RUNNER holders: check whether you qualify, see each day's IMD share and claim it.

Known limitations

• iPhone: Safari pauses GPS when the screen locks — keep the screen on while running (the app asks it to stay awake). On Android, the app keeps recording with the screen off.
• Bluetooth heart-rate sensors work in Chrome on Android / desktop, not on iPhone.
• Runs are stored on each device (earnings and claims live on the server and the chain) — no friends or leaderboards yet.
• Only runs recorded live with GPS in the app earn RUNNER.
• You need at least one RUNNER Genesis sneaker NFT to earn.

Send feedback

Found a bug or have an idea? Open an issue — include your phone model, browser and what happened. You can also reach it from Settings → Send feedback in the app.

Run locally

It's a static web app — no build step:

python3 -m http.server 5190

Then open http://localhost:5190.

RUNNER Genesis NFT contract

contracts/RunnerGenesis.sol — 9,999 sneaker NFTs (ERC-721) on Robinhood Chain. Open sale, no reveal: buyers pick any token id and pay its price (Common 0.005 / Uncommon 0.015 / Rare 0.04 / Epic 0.1 ETH). Rarity and price come from the token id with the same formula the app uses, so app and chain always agree.

• Dev wallet 0x0f397E46e4e810313dBC782CDb0236347157f1B4 is set at deployment as owner, treasury (mint payments) and royalty receiver. Whoever sends the deployment gets no control.
• 5% royalty: ERC-2981 plus ERC-721C transfer-validator support (setTransferValidator), which marketplaces use to enforce creator earnings.
• OpenSea: contractURI() → /nft/collection.json (name, images, website, fee). OpenSea gives the contract owner() edit rights, so the dev wallet can sign in to OpenSea and add socials, website and banner. After a mainnet launch, turn on enforced creator earnings in OpenSea Studio → Creator earnings. The required OpenSea contracts only exist on mainnet, not on testnet.
• Metadata: /nft/:id (JSON) and /nft/image/:id (SVG) are served by api/nft.js and api/nft-image.js from the same trait and art code as the app. The owner can change them with setBaseURI and setContractURI.
• Build: Solidity 0.8.24, optimizer 200 runs, EVM paris — creation-code keccak 0x270c71d725f5555873c1391b02799879056d7d4923759ab75fe6cd3d9c32ed9e.
• Deploy (mainnet): open /admin.html, sign in with any wallet holding a little ETH, compile (the page checks the fingerprint) and deploy. Then set NFT_CONTRACT in js/config.js.

RUNNER token contract

contracts/RunnerToken.sol — ERC-20 on Robinhood Chain mainnet, fixed supply of 1,000,000,000 RUNNER, all created at deployment. There is no mint function, and burning is the only way the supply changes. Not deployed yet. Read AUDIT.md first.

Share	Amount	Goes to
Run rewards	800,000,000 (80%)	Locked in the contract, paid out only by claim()
Liquidity	100,000,000 (10%)	Locked forever in the RUNNER/IMD Uniswap v4 pool by the RunnerHook
Team	100,000,000 (10%)	0x0f4FE718eb8492533E600b30F3287E2f04087332

• No transfer tax; a 4% trading fee paid in IMD. RUNNER itself is a plain ERC-20: every transfer moves exactly the amount sent. It trades against IMD in one Uniswap v4 pool owned by the RunnerHook (contracts/RunnerHook.sol, adapted from PepesFamily's audited PepesEarnIMD). The hook takes 4% of the IMD side of every swap: 2% to the protocol wallet and 2% to RUNNER holders, both in IMD. The fee is fixed in the hook, and a swap that wouldn't fill completely (a price limit, or selling for more IMD than the pool holds) is refused rather than charged on the unfilled part; a swap that would move nothing is refused too, and so are donations to the pool (they would be lost to the locked position). The fee rounds up, so every trade pays. Our routers deliver the holder share in a way that never blocks a trade: if IMD transfers to the token ever fail, the share waits in the hook until anyone calls flush. The hook adds the 100M liquidity allocation as single-sided liquidity at a starting market cap of about 635 IMD and has no way to remove it (locked forever); nobody else can add liquidity to that pool. RunnerRouter (IMD) and RunnerEthRouter (ETH, routed through the IMD/ETH pool) buy and sell in one transaction. Extra RUNNER/ETH pool: the admin page (/admin.html?c=token → RUNNER/ETH pool) creates a Uniswap v4 RUNNER/ETH pool with a 10% LP fee and no hook (like the extra Pepes pools) through Uniswap's own PositionManager (0x58daec31…4fa7), at the price implied by the RUNNER/IMD and IMD/ETH pools, and adds a full-range position from the dev wallet. Trades there pay the 10% to the liquidity provider, not the 4% split. Trades through other pools someone may create are not charged; the owner can exclude such pools from holder rewards (excludePool: only contracts shaped like a v2/v3 pool qualify, and an exclusion can't be undone). Don't send tokens to the hook's address: it has no way to return them.

• Holder rewards, in IMD. The hook delivers the holders' IMD to the token (syncHolderRewards books it as that day's rewards). Each UTC day's IMD is shared by every wallet that held at least 300,000 RUNNER for that whole day, in proportion to its lowest balance that day. It can be claimed (claimHolderRewards) for 7 days in the app's Rewards tab, which shows whether a wallet qualifies today and its share of each of the last 7 days; holders can also Connect wallet there (WalletConnect QR or phone app, MetaMask, Coinbase Wallet, Rainbow, OKX; via Privy, without signing in) to claim from the wallet that holds their RUNNER, and any address can be looked up. The admin page can connect the dev wallet the same way for owner actions. Set in (free at dashboard.reown.com) before launch; empty uses Privy's shared, rate-limited default. The admin page's card shows and claims the protocol's IMD () and sweeps expired holder rewards. After that, sends what's left to the protocol wallet; anyone can call it. The pool (PoolManager), the hook, other excluded pools and the contract get no share; the team wallet does. The threshold is per address: a vault or wrapper holding 300,000+ on behalf of many smaller wallets counts as one holder and could pass rewards on to them. Opening balances count for the deploy day. A pool excluded later stops counting for the days still claimable that nobody has been paid from yet; a day someone was already paid from keeps its total, so every holder of it is paid at the same rate.

Rewards server (claims)

api/rewards.js (Vercel function) is the source of truth for anything worth real RUNNER. The app uploads every finished run's GPS track. The server re-scores it with the same rules the app uses (js/rules.js) and checks the following before crediting it:

• the wallet owns the sneaker on-chain;
• energy is available (1 energy = 30 minutes of earning; 1–2 sneakers give 1 energy, 3–8 give 2, 9–14 give 4, 15–29 give 6, 30+ give 10, refilling over 24 h);
• the run doesn't overlap an earlier one, for this wallet or for this sneaker;
• it's under 72 hours old;
• its speeds are possible on foot.

Level-ups and repairs are paid from the server balance. Levels run 0–30. By default a level-up costs 1,100 × (next level)^1.5 RUNNER (about a month to level 30 for a Common) and gives 1 point (Common, Uncommon) or 2 points (Rare, Epic). Level-up and repair costs follow emission.

Game settings (dev wallet, /admin.html?c=token → Controls after launch, applied immediately): the level-price base and curve, an optional per-runner daily max, and NFT boosts. Any future NFT collection can be listed with a boost %, e.g. Season 2 holders earn +10%, up to +100% in total. Claim asks the server to sign, then the wallet sends claim() to the token, paying a tiny ETH gas fee.

Setup, once both contracts are deployed:

1. /admin.html?c=token → Claim server → Generate key (in your browser). Add it in Vercel → Settings → Environment Variables as SIGNER_PRIVATE_KEY.
2. Vercel → Storage → connect Upstash for Redis to the project, which adds the KV_REST_API_URL and KV_REST_API_TOKEN variables. Redeploy.
3. Back on the admin page, the dev wallet presses Set server address on the token (or calls setSigner on Blockscout).
4. On launch day, the dev wallet presses Start emission. The halving clock starts then.

Until all three are done, the app keeps working in local mode.

Fair play.

• Trust score: every run gets a 0–100 score (api/_lib/trust.js). Scripted or spoofed tracks tend to be too clean: perfectly regular timing, constant speed, straight lines, unchanging GPS accuracy, or a copy of someone else's route.

• 24-hour hold: earnings become usable 24 hours after a run.

• Automatic rules (no human review):

  Trust score	Outcome
  70+	Paid in full
  40–69	Paid 50% (no penalty)
  Under 40, a fake-GPS app, or a copied route	Not paid + 1 strike

  3 strikes in 30 days suspend the wallet automatically: 7 days, then 30 days, then permanently. A suspension also forfeits earnings still on hold. Strikes expire after 30 days. All thresholds are game settings on the admin page, which also shows a log of every automatic decision and keeps an optional manual ban.

• Bans: banned wallets can't earn, spend or claim.

• Rate limits: requests are capped per IP and per wallet.

• Step cadence (phone app): the app records the phone's step counter during a run. Running is about 140–190 steps a minute; on a bike, scooter or in a car the counter barely moves. Steps that don't match the GPS pace lower the trust score, so the run goes to review.

• Fake GPS: the app ignores mock-location positions and the server lowers the score of runs where it saw any.

• Phone app only (device attestation): every upload from the app carries a Google Play Integrity token (Android) or an Apple App Attest proof (iPhone), tied to that exact run. With Phone app only switched on in the admin page (setting requireAttestation), only runs from the genuine app on an unmodified phone earn real RUNNER. Website runs still track and count for stats, but earn nothing. Switch it on at launch, after the setup below.

• Limits: attestation proves the app and phone are real, not who carries the phone. Per-wallet energy, the daily emission and the strike rules bound the damage.

Tests (tests/, see AUDIT.md): node rewards-server.test.mjs .. covers sessions, scoring, anti-cheat, spending, claims, halving rates, halving costs, the energy table, level costs, game settings, NFT boosts, the per-runner cap, schedule changes, the daily budget, partial claims, the trust score, the 24-hour hold, the automatic fair-play rules (strikes and suspensions), manual bans, rate limits, step cadence, mock locations and device attestation (108 checks). Google's verdicts are faked in the tests; App Attest runs with real signatures and a test certificate chain. A server-signed claim was also verified against RunnerToken in a local EVM.

Device attestation setup (Google + Apple)

You do these steps yourself: they need your Google and Apple accounts, and the keys must never be pasted into a chat. The step counter needs no setup.

Android: Google Play Integrity

1. Create a Google Play developer account (play.google.com/console, $25 once) and an app named RUNNER with package name fun.runearn.app.
2. Play Console → your app → Test and release → App integrity → Play Integrity API → Link a Cloud project. Choose Create a new project. Write down the project number (digits).
3. console.cloud.google.com → that project → APIs & Services → Library → check Google Play Integrity API is enabled.
4. IAM & Admin → Service accounts → Create service account (name: runner-integrity). No role is needed. Open it → Keys → Add key → Create new key → JSON. A file downloads.
5. Vercel → RUNNER project → Settings → Environment Variables: add PLAY_INTEGRITY_SA (Production) and paste the whole contents of that JSON file. Redeploy. Then delete the file from your Downloads.
6. Put the project number from step 2 in js/config.js → PLAY_CLOUD_PROJECT_NUMBER (it isn't secret, so Claude can do this for you), then rebuild the app.
7. Upload a release build to Play (Internal testing is enough) and install RUNNER from the Play Store. Sideloaded APKs and emulators fail the check on purpose.

iPhone: Apple App Attest

1. Use the Apple Developer account from NATIVE.md (needed for TestFlight anyway).
2. developer.apple.com → Account → Membership details → copy the Team ID (10 characters).
3. Xcode → App target → Signing & Capabilities → + Capability → App Attest. In the new App.entitlements, set App Attest Environment to production.
4. Vercel → Environment Variables: add APPLE_TEAM_ID = your Team ID. Redeploy.
5. Ship through TestFlight. App Attest doesn't work in the iOS Simulator.

Switch it on (launch day): open /admin.html?c=token → Controls after launch. The line under Phone app only should show ✓ for Android and iPhone. Tick Phone app only and press Save game settings.