Files
wikideck/docs/night2/MOBILE_MINING.md
claudeanderic dbb89ce9c5 Night 2: 40-card Magic-style duel, PvP with owned decks, polite Wikimedia client, Android mining (#23)
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).

## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
  - The server checks ownership, and 40-card eligibility is enforced.
  - Modes: Classic (ranked), Draft and Trending.
  - Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).

PR numbers refer to `claude/wikideck`.

## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
  - The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
  - Bot matches aren't reachable from Play.
  - Card identity pre-bake hasn't been done.
  - The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.

This PR is for Eric to merge.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: WikiDeck/wikideck#23

Co-authored-by: Claude <claude@eom.dev>
2026-11-18 18:12:24 +00:00

9.3 KiB
Raw Permalink Blame History

Mobile mining (Android, sideload build)

Status (Night 2, 2026-11-17): it works. The emulator mined and got testnet block #92 accepted with the in-app native RandomX engine (see "Results tonight"). Issue: claude/wikideck#59.

BRIEF decision 4: the mobile app must be able to mine, because otherwise mobile players can never earn the 40 owned cards a deck needs. Night 1's isNativeApp() hid the mining panel and the app had no miner at all.

App stores: why this is a sideloaded APK

Google Play and the Apple App Store both prohibit on-device cryptocurrency mining, so the mining build cannot ship through either store. It is distributed as a sideloaded APK only.

  • Google Play, Developer Program Policy, Device and Network Abuse: "We don't allow apps that mine cryptocurrency on devices." Apps that remotely manage mining that happens elsewhere are allowed.
  • Apple, App Review Guidelines 3.1.5(b)(ii) Cryptocurrencies, Mining: "Apps may not mine for cryptocurrencies unless the processing is performed off device (e.g. cloud-based mining)." Guideline 2.4.2 also bans unrelated background processes such as mining.

A WikiDeck block is a RandomX proof-of-work that mints an NFT on WikiDeck's own chain. That is cryptocurrency mining under both policies, whatever the reward looks like. Re-check the policy wording before any store submission; these quotes are from memory, not verified tonight (tests and agents make no web calls).

How it works

WebView (React)                                Native (Java, Capacitor plugin "WikiDeckMiner")
src/MobileMiningPanel.tsx  consent, intensity, stats
src/mobile-miner.ts        same loop as server/testnet/miner.ts
  POST /api/mining/template {owner, publicKey}  ──►  node (picks the article and stats; the phone never calls Wikipedia)
  build blob = sha256(headerMessage) || nonceLE8
  WikiDeckMiner.mine(lane, key, blob, target, 32, 16) ──►  MinerPlugin.java ──stdin/stdout──► libwikideck_randomx.so
                                                         (the pinned native/ engine, LIGHT mode, line protocol)
  found → hash, tokenId (mintId), sign(blockClaimMessage) with the web wallet
  POST /api/blocks                              ──►  node validates as usual
  • Same engine as desktop. native/ (RandomX v1.2.1, pinned SHA 102f8acf…) is cross-compiled with the Android NDK by scripts/build-randomx-android.sh for arm64-v8a and x86_64 (the emulator). It is packaged as jniLibs/<abi>/libwikideck_randomx.so: an executable named like a library, so Android extracts it to nativeLibraryDir, the one place an app may exec from (useLegacyPackaging true in android/app/build.gradle). The binaries are build outputs, so they're gitignored, and android/build-debug.sh builds them when they're missing.
  • Light mode only (256 MiB cache per engine process). Fast mode (about 2 GiB) is never started on a phone: the plugin runs the binary with no arguments.
  • Known-vector check on the device. Before the first start in each session, the app runs libwikideck_randomx.so --self-test (upstream Hash test 1a/2a). If the hash doesn't match, mining is disabled. A wrong hash would get every block rejected.
  • Keys never leave the web wallet. The plugin only receives the public work (key, blob, target). The WebView builds and signs the block with the existing wallet code (src/wallet.ts sign). The private key and backup password are never passed to native code or to the node.
  • No protocol, consensus or server changes. src/mobile-miner.ts rebuilds miningBlob and mintId with Web Crypto. tests/mobile-mining-miner.test.ts checks that they're byte-identical to server/testnet/consensus.ts and that the consensus validator accepts the assembled block.
  • Testnet only tonight. In a mainnet build (IS_MAINNET), the panel only says mainnet mining isn't enabled. The debug build points at the private testnet http://192.168.1.32:3101.

Safeguards

Safeguard How
Explicit consent An unchecked consent box ("uses this phone's CPU and battery and can make it warm"). Start stays disabled until it's ticked. The choice is stored locally (wikideck.mobileMining.consent.v1).
Intensity Low (1 thread, rests 400 ms between 16-hash batches), Normal (1 thread, default), High (2 threads, about 512 MiB, offered only on 4+ cores).
Foreground only MinerPlugin.handleOnPause kills the engines as soon as the activity pauses, and the WebView also stops on visibilitychange. There is no foreground service, no wake lock and no background mining. The web wallet also locks when the app is hidden.
Battery saver PowerManager.isPowerSaveMode(), checked before start, every 2 s while mining, and on ACTION_POWER_SAVE_MODE_CHANGED.
Heat PowerManager.getCurrentThermalStatus() >= THERMAL_STATUS_MODERATE (API 29+, with a listener), or a battery temperature of 40 °C or more (ACTION_BATTERY_CHANGED).
Low battery Below 20 % while not charging.
Visible activity Live hashrate, hashes tried, the block height being mined, accepted blocks, battery % and °C, and the self-test result.
Wallet change If the wallet locks or changes, mining stops, so it never keeps mining to an old address.

Each automatic stop shows its reason ("Paused: battery saver is on"). Mining never restarts by itself: the player taps Start again.

Wallet idle lock: a found block must be signed by the unlocked wallet, and the wallet locks after 5 minutes without taps. While mining is active (which means foreground and consented), each status update calls touchWallet() to keep the session alive. The 4-hour absolute limit and lock-on-hide still apply. night-review accepted this trade-off on PR #78. The session can't stay unlocked in the background: hiding the app locks the wallet, and handleOnPause halts mining, so the keep-alive applies only to consented foreground mining. Eric may prefer a stricter rule, such as re-prompting for the password when a block is found.

Measured hashrate (emulator)

Measured on inspiron-3670 (6 cores, shared with ~7 agents), using the AVD wikideck (Android 15, x86_64 google_apis, KVM, -cores 4, 2 GB RAM):

Measurement Result
Known vector (--self-test), x86_64 passed, 1.45 s including the 256 MiB cache init
Known vector, arm64-v8a (through the emulator's ARM translation) passed
Raw engine, 1 process, 2000 hashes about 53 s → ~37 H/s per thread
In the app, Max (4 threads) ~125 H/s shown in the panel, with 4 engine processes at ~260 MB RSS each

Light mode is about 10× slower per thread than desktop fast mode. At tonight's testnet target (00002514…, about 452 K expected hashes), 125 H/s means one block per hour on average, with high variance. On a real phone, expect roughly 20–60 H/s per big core (not measured tonight: no device).

Results tonight

Verified in the emulator with the debug APK (~/worker/jobs/night/mobile-mining/apk/wikideck-mining-testnet-debug.apk on inspiron):

  • The APK contains lib/{arm64-v8a,x86_64}/libwikideck_randomx.so. The app runs the self-test before its first start ("known vector OK"), then mines on the testnet (:3101) with live hashrate and block height.
  • Every safeguard halts the engines (the engine process count drops to 0, and the panel shows the reason):
    • thermal: cmd thermalservice override-status 3 → "Paused: the device is warm"
    • battery saver (unplugged, settings put global low_power 1) → "Paused: battery saver is on"
    • low battery (dumpsys battery set level 15, unplugged) → halted (Android's low-battery dialog paused the activity first)
    • background (HOME) → "Paused: the app went to the background"; the web wallet locks too, so restarting needs an unlock
    • Max intensity is refused while unplugged
  • Accepted block: at 22:37 EST the emulator (Max, ~136 H/s, 4 light threads) mined testnet block #92 ("International FJ"; block edaf8ac3…a8cb0, NFT acf778b1…7ee58) to the in-app wallet 3b2362c7…5e054. All three nodes (:3101–:3103) accepted it as their tip. That one was lucky: about 41 K hashes against ~452 K expected.

Emulator panel after the accepted block

Options for Eric

  1. Keep it sideload-only (what exists now). Publish a signed release APK from a WikiDeck download page with clear battery and heat copy. This needs a release keystore (not in git) and an "unknown sources" install guide. F-Droid is a possible channel, but its anti-features policy would flag it, and its build server needs a reproducible NDK build.
  2. Store builds without mining. Ship the store APK/AAB and the iOS app without the engine (a build flag that drops jniLibs and the panel), with the panel replaced by "Mine on desktop, or with the sideload app", plus a remote-management view of a desktop miner (allowed by Google's policy).
  3. Make mobile mining worthwhile. Phones in light mode are roughly 10× slower per core than desktop fast mode. Options that need consensus changes (out of scope tonight): a lower-difficulty mobile lane, or pooled/shared mining where a phone's partial shares earn a card.
  4. Later engineering: a JNI wrapper instead of exec (needed if a future Android blocks exec from nativeLibraryDir), an arm64 device test on real hardware, and battery-drain measurements.