Compare commits

..
Author SHA1 Message Date
claudeandClaude Opus 5.5 15470d5130 MOBILE_MINING.md: record the wallet keep-alive trade-off (review on #78)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:51:57 -05:00
claudeandClaude Opus 5.5 8694239d7c MOBILE_MINING.md: emulator mined accepted testnet block #92
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:37:35 -05:00
claudeandClaude Opus 5.5 2e4836f5e8 Android app can mine: native RandomX engine, WikiDeckMiner plugin, mobile panel
- scripts/build-randomx-android.sh: NDK cross-build of the pinned native/ engine
  (light mode) for arm64-v8a and x86_64, packaged as jniLibs/<abi>/libwikideck_randomx.so
- MinerPlugin.java (Capacitor "WikiDeckMiner"): runs engine processes over the
  line protocol, on-device self-test, and halts on background, battery saver,
  thermal, hot or low battery. Never receives wallet keys.
- src/mobile-miner.ts: template -> mine -> sign -> submit loop in the WebView,
  byte-identical to consensus miningBlob/mintId (tests/mobile-mining-miner.test.ts)
- src/MobileMiningPanel.tsx: consent, intensity (1 thread default; Max = 4 only
  while charging), live hashrate/status; testnet-only (disabled on mainnet builds)
- docs/night2/MOBILE_MINING.md: how it works, safeguards, measured hashrate,
  store policies (sideload APK only), options for Eric

No protocol, consensus or server changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:32:51 -05:00
18 changed files with 854 additions and 640 deletions
+4
View File
@@ -28,3 +28,7 @@ dist-ssr
*.njsproj
*.sln
*.sw?
# Native RandomX engine for the app (scripts/build-randomx-android.sh)
native/build-android-*/
android/app/src/main/jniLibs/
+7
View File
@@ -16,6 +16,13 @@ android {
ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
}
}
packagingOptions {
jniLibs {
// The RandomX engine (jniLibs/<abi>/libwikideck_randomx.so) is an executable, not a JNI library.
// Android may exec it only from the extracted nativeLibraryDir, so keep legacy extraction.
useLegacyPackaging true
}
}
buildTypes {
release {
minifyEnabled false
@@ -1,5 +1,14 @@
package dev.eom.wikideck;
import android.os.Bundle;
import com.getcapacitor.BridgeActivity;
public class MainActivity extends BridgeActivity {}
public class MainActivity extends BridgeActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
// Local plugins must be registered before the bridge starts.
registerPlugin(MinerPlugin.class);
super.onCreate(savedInstanceState);
}
}
@@ -0,0 +1,264 @@
package dev.eom.wikideck;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.BatteryManager;
import android.os.Build;
import android.os.PowerManager;
import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;
import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.regex.Pattern;
/**
* Native RandomX engine for the WikiDeck app (sideload build only, see docs/night2/MOBILE_MINING.md).
*
* The plugin only runs the pinned `wikideck-randomx` executable (shipped as jniLibs/<abi>/libwikideck_randomx.so)
* in LIGHT mode and speaks its line protocol (docs/randomx-native.md). It never sees wallet keys: the WebView builds
* the work blob, signs the block claim with the web wallet, and submits it to the node. This class also enforces the
* device safeguards: engines are killed when the app goes to the background, on battery saver, when the device is
* hot, or when the battery is low and not charging. Each stop is reported to the WebView as a `halted` event.
*/
@CapacitorPlugin(name = "WikiDeckMiner")
public class MinerPlugin extends Plugin {
private static final String BINARY = "libwikideck_randomx.so";
private static final int MAX_THREADS = 4;
/** At or above Android's THERMAL_STATUS_MODERATE we stop. */
private static final int THERMAL_LIMIT = 2;
/** Battery temperature limit in tenths of a degree Celsius. */
private static final int BATTERY_TEMP_LIMIT = 400;
private static final int LOW_BATTERY_PERCENT = 20;
private static final Pattern HEX = Pattern.compile("^[0-9a-f]+$");
private final List<Engine> engines = new ArrayList<>();
private BroadcastReceiver receiver;
private Object thermalListener;
/** One long-lived engine process with exactly one outstanding command (it is strictly request/response). */
private static final class Engine {
final Process process;
final OutputStream in;
final BufferedReader out;
final ExecutorService worker = Executors.newSingleThreadExecutor();
Engine(Process process) {
this.process = process;
this.in = process.getOutputStream();
this.out = new BufferedReader(new InputStreamReader(process.getInputStream(), StandardCharsets.US_ASCII));
}
String command(String line) throws Exception {
in.write((line + "\n").getBytes(StandardCharsets.US_ASCII));
in.flush();
String reply = out.readLine();
if (reply == null) throw new Exception("RandomX engine exited");
return reply;
}
void kill() {
worker.shutdownNow();
try { in.close(); } catch (Exception ignored) { }
process.destroy();
try { if (!process.waitFor(1, TimeUnit.SECONDS)) process.destroyForcibly(); } catch (InterruptedException ignored) { }
}
}
private File binary() {
return new File(getContext().getApplicationInfo().nativeLibraryDir, BINARY);
}
@Override
public void load() {
receiver = new BroadcastReceiver() {
@Override public void onReceive(Context context, Intent intent) { checkAndHalt(); }
};
IntentFilter filter = new IntentFilter();
filter.addAction(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED);
filter.addAction(Intent.ACTION_BATTERY_CHANGED);
getContext().registerReceiver(receiver, filter);
if (Build.VERSION.SDK_INT >= 29) {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
PowerManager.OnThermalStatusChangedListener l = status -> checkAndHalt();
pm.addThermalStatusListener(l);
thermalListener = l;
}
}
@Override
protected void handleOnPause() {
halt("background");
super.handleOnPause();
}
@Override
protected void handleOnDestroy() {
halt("closed");
try { getContext().unregisterReceiver(receiver); } catch (Exception ignored) { }
if (Build.VERSION.SDK_INT >= 29 && thermalListener != null) {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
pm.removeThermalStatusListener((PowerManager.OnThermalStatusChangedListener) thermalListener);
}
super.handleOnDestroy();
}
/** Current device state and, if mining must not run, the reason. */
private JSObject conditionsObject() {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
Intent battery = getContext().registerReceiver(null, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
int temp = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_TEMPERATURE, -1);
int level = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
int scale = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
int plugged = battery == null ? 0 : battery.getIntExtra(BatteryManager.EXTRA_PLUGGED, 0);
int percent = level >= 0 && scale > 0 ? Math.round(100f * level / scale) : -1;
int thermal = Build.VERSION.SDK_INT >= 29 ? pm.getCurrentThermalStatus() : 0;
boolean powerSave = pm.isPowerSaveMode();
String block = null;
if (powerSave) block = "battery-saver";
else if (thermal >= THERMAL_LIMIT) block = "thermal";
else if (temp >= BATTERY_TEMP_LIMIT) block = "battery-hot";
else if (plugged == 0 && percent >= 0 && percent < LOW_BATTERY_PERCENT) block = "battery-low";
JSObject o = new JSObject();
o.put("powerSave", powerSave);
o.put("thermalStatus", thermal);
o.put("batteryTempC", temp < 0 ? null : temp / 10.0);
o.put("batteryPercent", percent);
o.put("charging", plugged != 0);
o.put("cores", Runtime.getRuntime().availableProcessors());
o.put("abi", Build.SUPPORTED_ABIS.length > 0 ? Build.SUPPORTED_ABIS[0] : "unknown");
o.put("engineInstalled", binary().canExecute());
o.put("blocked", block);
return o;
}
private void checkAndHalt() {
String block = conditionsObject().getString("blocked");
if (block != null) halt(block);
}
private synchronized void halt(String reason) {
if (engines.isEmpty()) return;
for (Engine e : engines) e.kill();
engines.clear();
JSObject event = new JSObject();
event.put("reason", reason);
notifyListeners("halted", event);
}
@PluginMethod
public void conditions(PluginCall call) {
call.resolve(conditionsObject());
}
/** Runs upstream's known-vector test (Hash test 1a/2a) on this device. */
@PluginMethod
public void selfTest(PluginCall call) {
new Thread(() -> {
try {
Process p = new ProcessBuilder(binary().getAbsolutePath(), "--self-test").redirectErrorStream(true).start();
p.getOutputStream().close();
StringBuilder text = new StringBuilder();
BufferedReader r = new BufferedReader(new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8));
for (String line; (line = r.readLine()) != null && text.length() < 2000; ) text.append(line).append('\n');
boolean done = p.waitFor(120, TimeUnit.SECONDS);
if (!done) p.destroyForcibly();
JSObject o = new JSObject();
o.put("ok", done && p.exitValue() == 0);
o.put("output", text.toString().trim());
call.resolve(o);
} catch (Exception e) {
call.reject("Self-test failed to run: " + e.getMessage());
}
}).start();
}
/** Starts 1..4 light-mode engines (more than 2 only while charging) (each needs about 256 MiB). Refuses if a safeguard is active. */
@PluginMethod
public synchronized void start(PluginCall call) {
int threads = call.getInt("threads", 1);
if (threads < 1 || threads > MAX_THREADS || threads > Runtime.getRuntime().availableProcessors()) { call.reject("threads must be 1 to " + MAX_THREADS + " and at most the core count"); return; }
String block = conditionsObject().getString("blocked");
if (block == null && threads > 2 && !conditionsObject().getBool("charging")) block = "max-needs-charging";
if (block != null) { call.reject("Mining is paused: " + block, block); return; }
if (!engines.isEmpty()) { for (Engine e : engines) e.kill(); engines.clear(); }
try {
for (int i = 0; i < threads; i++) {
// No arguments = LIGHT mode. `--fast` (about 2 GiB) is never used on phones.
Process p = new ProcessBuilder(binary().getAbsolutePath()).redirectError(ProcessBuilder.Redirect.to(new File("/dev/null"))).start();
engines.add(new Engine(p));
}
} catch (Exception e) {
for (Engine en : engines) en.kill();
engines.clear();
call.reject("Could not start the RandomX engine: " + e.getMessage());
return;
}
JSObject o = new JSObject();
o.put("threads", threads);
call.resolve(o);
}
@PluginMethod
public synchronized void stop(PluginCall call) {
for (Engine e : engines) e.kill();
engines.clear();
call.resolve();
}
/**
* One bounded batch on engine `lane`: `mine <key> <blob> <target> <nonceOffset> <maxAttempts>`.
* Resolves {found:false} on exhaustion or {found:true, hash, nonce} (nonce as a decimal string).
*/
@PluginMethod
public void mine(PluginCall call) {
String key = call.getString("key", ""), blob = call.getString("blob", ""), target = call.getString("target", "");
int lane = call.getInt("lane", 0), offset = call.getInt("nonceOffset", -1), attempts = call.getInt("maxAttempts", 0);
if (key.length() != 64 || target.length() != 64 || blob.length() < 2 || blob.length() > 16384 || blob.length() % 2 != 0
|| !HEX.matcher(key).matches() || !HEX.matcher(target).matches() || !HEX.matcher(blob).matches()
|| offset < 0 || offset + 8 > blob.length() / 2 || attempts < 1 || attempts > 10000) {
call.reject("Invalid mining request");
return;
}
final Engine engine;
synchronized (this) {
if (lane < 0 || lane >= engines.size()) { call.reject("Miner is not running", "stopped"); return; }
engine = engines.get(lane);
}
String line = "mine " + key + " " + blob + " " + target + " " + offset + " " + attempts;
try {
engine.worker.execute(() -> {
try {
String reply = engine.command(line);
JSObject o = new JSObject();
if (reply.equals("exhausted")) {
o.put("found", false);
} else {
String[] parts = reply.split(" ");
if (parts.length != 3 || !parts[0].equals("found") || parts[1].length() != 64 || !HEX.matcher(parts[1]).matches()
|| !parts[2].matches("^[0-9]{1,20}$")) throw new Exception("Malformed engine reply");
o.put("found", true);
o.put("hash", parts[1]);
o.put("nonce", parts[2]);
}
call.resolve(o);
} catch (Exception e) {
call.reject("Miner stopped: " + e.getMessage(), "stopped");
}
});
} catch (Exception e) {
call.reject("Miner is not running", "stopped");
}
}
}
+5 -1
View File
@@ -1,11 +1,15 @@
#!/bin/sh
# Build the WikiDeck debug APK against the private Night-1 testnet.
# Needs ANDROID_HOME and a JDK 21 (JAVA_HOME). Output: android/app/build/outputs/apk/debug/app-debug.apk
# Needs ANDROID_HOME (with an NDK and CMake for the RandomX engine) and a JDK 21 (JAVA_HOME). Output: android/app/build/outputs/apk/debug/app-debug.apk
set -eu
cd "$(dirname "$0")/.."
export VITE_WIKIDECK_NETWORK="${VITE_WIKIDECK_NETWORK:-testnet}"
export VITE_WIKIDECK_GENESIS_TIME="${VITE_WIKIDECK_GENESIS_TIME:-1792411200}"
export VITE_NODE_URL="${VITE_NODE_URL:-http://192.168.1.32:3101}"
# Native RandomX engine (jniLibs/<abi>/libwikideck_randomx.so); built once, reused after (scripts/build-randomx-android.sh).
for abi in ${ABIS:-arm64-v8a x86_64}; do
[ -x "android/app/src/main/jniLibs/$abi/libwikideck_randomx.so" ] || ABIS="$abi" sh scripts/build-randomx-android.sh
done
npm run build
npx cap sync android
cd android && ./gradlew --no-daemon -q assembleDebug
-89
View File
@@ -1,89 +0,0 @@
# WikiDeck Duel: engine API (v1, Night 2)
Owner: **duel-core** (claude/wikideck#55). Rules: `docs/game/DUEL_DESIGN.md` (duel-design). This file: how code talks to the engine.
- Types: `shared/duel/types.ts`. Ruleset: `shared/duel/ruleset.ts`. Function surface: `DuelEngineApi` in `shared/duel/index.ts`, implemented by `shared/duel/engine.ts` (engine-alpha PR).
- `shared/game/` (Edit War) is untouched. Change requests: comment on #55 with `[from <agent>]`.
## Principles
- **Pure and deterministic.** `(rules, decks, seed, actions)` → identical state and log. RNG: `shared/game/rng.ts` (mulberry32); its uint32 state lives in `DuelState.rng`.
- **Plain JSON.** `DuelState` round-trips through `JSON.stringify`/`parse`; `serialize`/`deserialize` are thin wrappers.
- **Clone-on-apply.** `applyAction` never mutates its input and throws on an illegal action.
- **Atomic actions.** `legalActions(state, seat)` is small, and `[]` for the seat that is not to act. The host checks an action by deep-equal against that list (`concede` and `timeout` excepted).
- **Off-chain.** Matches never move or burn cards. Cards arrive derived and frozen; the engine does no I/O.
## Cards (`DuelCard`)
Built by duel-cards (`derive()`), frozen by the host at match start. Shape agreed with duel-cards on #55.
| Field | Notes |
|---|---|
| `cardId` | unique in a deck (NFT tokenId; sample id in sims; `token:` for tokens) |
| `pageId`, `revisionId?`, `title`, `description?` | `pageId` matches Linked pairs; `revisionId` for recap references |
| `type`, `subtype?` | `Figure` · `Location` · `Event` · `Institution` · `Doctrine` |
| `portal` | `Arts, Earth, History, Science, Society, Neutral`; no deckbuilding restriction |
| `cost` | 1–6 (Locations 1–3) |
| `power`, `toughness` | Figures: body. Locations: 0 / Garrison (0 = can't block). Others: `null` or 0 |
| `keywords` | ≤ `maxKeywords` (2). Figures only |
| `territory?` | Location: +N max Citations while controlled (total from all sources ≤ `territoryCap`) |
| `effects` | `EffectSpec[]` (below), ≤ 4 |
| `rulesText`, `flavor` | display only |
| `connect?` | `{countries, centuries, links, p31}` frozen claims; the engine computes Connected |
| `rarity?`, `deriveVersion?`, `token?` | |
### Keywords (DUEL_DESIGN §4), as the engine applies them
- **Protected**: can't be the target of Events or Doctrines an opponent controls (abilities of other permanents and combat still apply).
- **Featured**: can be blocked only by Featured, Translated or Multilingual Figures.
- **Multilingual**: can block Featured; can't be blocked by Local Figures.
- **Translated**: can block Featured.
- **Legacy**: when destroyed, its controller draws a card.
- **Well-sourced**: prevent the first 1 damage dealt to it each turn.
- **Stub**: at the start of your turn, a +1/+1 counter, up to `stubMax` (2).
- **Local**: +1/+1 while you control a Location sharing a `connect.countries` value.
- **Trending** (Trending mode, set by the host via `applyLive`): no Pending review, +`trendingPower`/+0.
### Effects (`EffectSpec`)
`{ trigger, op, target?, amount?, power?, toughness?, duration?, token?, condition?, grant?, template? }`
- **Triggers:** `onPlay` (Event resolves; on a permanent same as `onEnter`), `onEnter`, `onAttack`, `onDestroyed`, `startOfTurn`, `onCombatDamageToPlayer` (on a Figure, or on a Doctrine for its attached Figure), `static`.
- **Ops:** `damage`, `damageEach`, `createToken`, `pump`, `fight`, `draw`, `attach`, `gainLife`, `drain`, `destroy`, `bounce`, `tap`.
- **Targets:** chosen: `figure`, `figureOrLocation`, `ownFigure`, `opponentFigure`, `anyTarget`; automatic: `each`, `self`, `attached`, `ownFigures`, `opponentFigures`, `opponent`, `controller`. Defaults: damage → `anyTarget`, pump → `self`, draw/gainLife/createToken → `controller`, drain → `opponent`.
- **Chosen targets:** each `onPlay`/`onEnter` effect with a chosen target consumes the next entry of `play.targets`, in effect order; `legalActions` enumerates the combinations. An Event or Doctrine with no legal target can't be played; a Figure/Location/Institution enters and its targeted effect fizzles (`targets` omitted).
- **fight:** the previous chosen target in the same card (else the source permanent) and this target deal damage equal to their power to each other. T6 = `[{op:'pump', target:'ownFigure', power:k, toughness:0}, {op:'fight', target:'opponentFigure'}]`.
- **Doctrine:** its `attach` effect's target is the Figure it attaches to (`ownFigure` for T11, `figure` for T12). Its `static` effects with `target: 'attached'` apply to that Figure; `condition.samePortal` on a Doctrine means "other Figures you control of the attached Figure's Portal". When the Figure leaves, the Doctrine is Deleted.
- **static pump** applies while the source is in play; conditions use **printed** power (no feedback loops). `condition.connected` = the affected Figure is Connected to the source (T9).
- **createToken:** `amount` tokens of `token` (a fresh `DuelCard` with `token: true`, uid `t:<n>`); `condition.maxTokens` = only if you control fewer tokens than that. Tokens leaving play cease to exist.
- Triggers resolve immediately: the active player's first, then in entry order.
## Rules (defaults: `DEFAULT_DUEL_RULESET`; details in DUEL_DESIGN §2)
- 40-card decks (`deckSize`), ≤ 4 per `pageId`, unique `cardId`s, no tokens. 20 Notability. Drawing from an empty library loses (`libraryEmpty: 'lose'`; `'reshuffle'` and `'fatigue'` exist as data).
- Opening hand 7. Up to `mulligans` (1): shuffle in, draw 7, then on `keep` put one card per mulligan on the bottom (the last in hand order). Seat 0 decides first, then seat 1.
- First player (from the seed) skips their first draw.
- **Turn:** refresh (base max +1 to 10, plus Territory ≤ 2; refill; untap; Pending review ends; Stub and `startOfTurn` triggers) → draw → **main** → **attack** → **block** → damage → end (damage and "until end of turn" clear; discard down to `handSize` 7, **highest cost first**, automatically).
- Locations: `locationsPerTurn` (1), can't attack. Garrison Locations (toughness > 0) block as 0-power.
- Combat: attack the opponent only; each blocker blocks one attacker, at most one blocker per attacker; simultaneous damage; destroy triggers after all combat damage. No trample, first strike, stack or instants.
- **Connected** (engine, from `connect`, tiers in `connectedTiers`): Linked (either `links` contains the other's `pageId`, or either `cites` contains the other's `qid`), Compatriot (shared country), Contemporary (shared century, different types), Kin (shared P31, not Q5/Q16521). A Figure gets the single best bonus among other permanents its controller controls: `+linkedBonus` (2) if Linked, else `+connectedBonus` (1). Logged once (`connected`). Opposing Connected pairs are logged once as `rivalry`.
- **Timeouts:** `timeout` passes (mulligan: keep; main/attack: end the turn without attacking; block: confirm current blocks). `timeoutsToConcede` (3) consecutive timeouts by one seat lose (`reason: 'timeout'`).
- `turnCap` (null by default): after that many total turns, higher Notability wins, then higher total power in play, then the second player.
## Phases and actions
| Phase | Who acts | Listed actions |
|---|---|---|
| `mulligan` | seat 0 until ready, then seat 1 | `keep`, `mulligan` |
| `main` | active | `play {uid, targets?}`, `endPhase` |
| `attack` | active | `toggleAttacker {uid}` (untapped, not Pending review, not yet declared), `confirmAttack` |
| `block` | defender | `block {blocker, attacker}` (unassigned blocker, unblocked attacker, evasion allowing), `confirmBlocks` |
| any | either seat | `concede` (not listed) |
| any | host, for the seat to act | `timeout` (not listed) |
Declarations are **monotonic** (no un-declare), so every turn has a bounded number of actions; UIs stage choices locally and send them on confirm. If the defender has no legal block, damage resolves at `confirmAttack` with no block phase. `confirmAttack` with no attackers ends the turn.
## Views and log
- `viewFor(state, seat): PlayerView`: your hand; the opponent's hand and library **sizes** only; both graveyards; the battlefield with current power/toughness, keywords and Connected badge; combat; `toAct`; `version`; `result`. Never the RNG or library order.
- **The seed is secret until the match ends.** `seed` plus the deck lists reproduce every shuffle, so the host never sends `seed` or `rng` (or the raw `DuelState`) to clients before `gameOver`. Live log rendering picks template variants from a derived `storySeed = sha256(seed + ':story')`.
- `state.log` is omniscient (server, and the recap after the match). Clients get **`logFor(state, seat)`**: the opponent's `draw` events have no `card`. Every other event is public information.
- Every event has `seq` and `turn`. `CardRef` carries `uid, cardId, title, pageId, type` plus `power`/`toughness` right after the event.
- Kinds (DUEL_DESIGN §10 names): `start, mulligan, keep, turnStart, draw, deploy, cast, adopt, tokenCreated, connected, rivalry, effect, attack, block, effectDamage, combatDamage, playerDamage, lifeGain, destroyed, bounced, discard, fatigue, concede, timeout, gameOver`. `destroyed` = the recap's casualties. Prose templates live with duel-design / ui-pvp, not in the engine.
## Host binding
`duelEnginePort` (engine.ts) is structurally an `EnginePort<DuelRuleset, DuelCard, DuelState, DuelAction>` (`server/game/engine-port.ts`; `shared/` doesn't import `server/`, so host-pvp types it there). `concedeAction`, `timeoutAction`, `turnSeconds`, `turnOf`, `applyLive` included. `starterDeck` and `previewPool` throw: there are no starters (BRIEF decision 2); draft pools come from both players' collections.
## Stability
These types are the contract for duel-cards, host-pvp, ui-duel, ui-pvp and sim-balance. Additive changes (optional fields, new log kinds) can land with the engine; breaking ones get a `[duel-core] contract change` comment on #55 first.
+78
View File
@@ -0,0 +1,78 @@
# 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](mobile-mining-accepted.jpg)
## 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.
Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

+35
View File
@@ -0,0 +1,35 @@
#!/bin/sh
# Cross-compile the pinned native RandomX engine (native/, RandomX v1.2.1) for the Android app.
# Output: android/app/src/main/jniLibs/<abi>/libwikideck_randomx.so, an executable named like a
# library so Android extracts it to nativeLibraryDir, where an app may exec it (docs/night2/MOBILE_MINING.md).
#
# Needs ANDROID_HOME with an NDK (ndk;<version>) and CMake 3.24+ (cmake;<version>, or cmake on PATH).
# ABIS="x86_64 arm64-v8a" JOBS=2 sh scripts/build-randomx-android.sh
set -eu
cd "$(dirname "$0")/.."
: "${ANDROID_HOME:?set ANDROID_HOME}"
ABIS="${ABIS:-arm64-v8a x86_64}"
JOBS="${JOBS:-2}"
API="${ANDROID_API:-24}"
NDK="${ANDROID_NDK_HOME:-$(ls -d "$ANDROID_HOME"/ndk/* 2>/dev/null | sort -V | tail -n1)}"
[ -f "$NDK/build/cmake/android.toolchain.cmake" ] || { echo "No NDK under $ANDROID_HOME/ndk" >&2; exit 1; }
CMAKE_DIR="$(ls -d "$ANDROID_HOME"/cmake/* 2>/dev/null | sort -V | tail -n1 || true)"
[ -n "$CMAKE_DIR" ] && PATH="$CMAKE_DIR/bin:$PATH"
command -v cmake >/dev/null || { echo "cmake not found" >&2; exit 1; }
GEN=""
command -v ninja >/dev/null && GEN="-G Ninja"
for abi in $ABIS; do
build="native/build-android-$abi"
# shellcheck disable=SC2086
cmake -S native -B "$build" $GEN \
-DCMAKE_TOOLCHAIN_FILE="$NDK/build/cmake/android.toolchain.cmake" \
-DANDROID_ABI="$abi" -DANDROID_PLATFORM="android-$API" \
-DCMAKE_BUILD_TYPE=Release -DWIKIDECK_RANDOMX_TESTS=OFF
cmake --build "$build" --config Release --target wikideck-randomx --parallel "$JOBS"
out="android/app/src/main/jniLibs/$abi"
mkdir -p "$out"
cp "$build/wikideck-randomx" "$out/libwikideck_randomx.so"
"$NDK"/toolchains/llvm/prebuilt/*/bin/llvm-strip "$out/libwikideck_randomx.so"
ls -l "$out/libwikideck_randomx.so"
done
-35
View File
@@ -1,35 +0,0 @@
/**
* WikiDeck Duel public API. Spec: docs/game/DUEL_API.md.
* Contracts PR: types and ruleset only. engine.ts (createDuel, legalActions,
* applyAction, viewFor, logFor, replay, ...) lands in the engine alpha PR and
* implements DuelEngineApi below; build against that interface until then.
*/
export * from './types.ts';
export * from './ruleset.ts';
import type { DuelAction, DuelCard, DuelResult, DuelRuleset, DuelState, LogEvent, PlayerView, Seat } from './types.ts';
/** The engine's function surface (implemented by shared/duel/engine.ts). All pure; inputs are never mutated. */
export interface DuelEngineApi {
/** Throws if the deck is illegal: size ≠ deckSize, duplicate cardId, > maxCopiesPerPage of one pageId, bad stats, > maxKeywords. */
validateDeck(rules: DuelRuleset, cards: DuelCard[]): void;
/** Shuffle both decks from `seed`, deal opening hands, phase 'mulligan'. */
createDuel(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string): DuelState;
/** Atomic legal actions for `seat`; [] if `seat` is not the one to act (concede is always accepted by applyAction but not listed). */
legalActions(state: DuelState, seat: Seat): DuelAction[];
/** Returns a new state. Throws on an illegal action. */
applyAction(state: DuelState, seat: Seat, action: DuelAction): DuelState;
/** Seat that must act now, or null when over. Mulligan: the lowest seat not yet ready. */
toAct(state: DuelState): Seat | null;
isOver(state: DuelState): boolean;
result(state: DuelState): DuelResult | null;
viewFor(state: DuelState, seat: Seat): PlayerView;
/** Per-seat log: the opponent's draws (and other hidden-zone cards) are masked. */
logFor(state: DuelState, seat: Seat): LogEvent[];
/** Deterministic: same inputs → identical state (and log). */
replay(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string, actions: { seat: Seat; action: DuelAction }[]): DuelState;
serialize(state: DuelState): string;
deserialize(text: string): DuelState;
/** Current power/toughness of a permanent after counters, buffs, statics and Connected. */
statsOf(state: DuelState, uid: string): { power: number; toughness: number };
}
-76
View File
@@ -1,76 +0,0 @@
/**
* Duel ruleset: every rule number as data (BRIEF "Game rules core").
* parseDuelRuleset() is the only way untrusted JSON (mode files, peer hosts)
* becomes a DuelRuleset. Night 1 Edit War rulesets are rejected cleanly.
*/
import { z } from 'zod';
import type { DuelRuleset } from './types.ts';
const int = (min: number, max: number) => z.number().int().min(min).max(max);
export const DuelRulesetSchema = z.object({
engine: z.literal('duel'),
version: z.string().min(1).max(16),
deckSize: int(1, 60),
maxCopiesPerPage: int(1, 60),
startingLife: int(1, 100),
openingHand: int(0, 10),
handSize: int(1, 15),
mulligans: int(0, 3),
firstPlayerDraws: z.boolean(),
maxCitations: int(1, 20),
citationsPerTurn: int(1, 5),
territoryCap: int(0, 10),
locationsPerTurn: int(0, 10),
libraryEmpty: z.enum(['lose', 'reshuffle', 'fatigue']),
maxKeywords: int(0, 4),
stubMax: int(0, 10),
trendingPower: int(0, 5),
connectedTiers: z.array(z.enum(['Linked', 'Compatriot', 'Contemporary', 'Kin'])).max(4)
.refine(v => new Set(v).size === v.length, 'Duplicate tier'),
connectedBonus: int(0, 5),
linkedBonus: int(0, 5),
turnSeconds: int(5, 600),
bankSeconds: int(0, 3600),
timeoutsToConcede: int(1, 20),
turnCap: int(2, 200).nullable(),
}).strict();
export const DEFAULT_DUEL_RULESET: DuelRuleset = Object.freeze({
engine: 'duel',
version: 'duel-1',
deckSize: 40,
maxCopiesPerPage: 4,
startingLife: 20,
openingHand: 7,
handSize: 7,
mulligans: 1,
firstPlayerDraws: false,
maxCitations: 10,
citationsPerTurn: 1,
territoryCap: 2,
locationsPerTurn: 1,
libraryEmpty: 'lose',
maxKeywords: 2,
stubMax: 2,
trendingPower: 1,
connectedTiers: ['Linked', 'Compatriot', 'Contemporary', 'Kin'],
connectedBonus: 1,
linkedBonus: 2,
turnSeconds: 60,
bankSeconds: 300,
timeoutsToConcede: 3,
turnCap: null,
}) as DuelRuleset;
/** Validate a full ruleset. Throws (ZodError) on anything invalid or unknown. */
export function parseDuelRuleset(value: unknown): DuelRuleset {
return DuelRulesetSchema.parse(value) as DuelRuleset;
}
/** Merge a partial override (a mode file's `rules`) onto the defaults, then validate. */
export function mergeDuelRuleset(overrides: unknown, base: DuelRuleset = DEFAULT_DUEL_RULESET): DuelRuleset {
if (overrides === undefined || overrides === null) return parseDuelRuleset(structuredClone(base));
if (typeof overrides !== 'object' || Array.isArray(overrides)) throw new TypeError('Ruleset overrides must be an object');
return parseDuelRuleset({ ...structuredClone(base), ...(overrides as Record<string, unknown>) });
}
-397
View File
@@ -1,397 +0,0 @@
/**
* WikiDeck Duel: the Magic-style 40-card engine (off-chain). Contract types.
* Spec: docs/game/DUEL_API.md (rules: docs/game/DUEL_DESIGN.md). Owner: duel-core (claude/wikideck#55).
*
* Everything here is plain JSON data: DuelState round-trips through
* JSON.stringify/parse with no loss (no Maps, classes or functions).
* shared/game/ (Edit War) is a separate engine and is not affected.
*/
import type { RngState } from '../game/rng.ts';
export type Seat = 0 | 1;
export const SEATS: readonly Seat[] = [0, 1];
// ---------------------------------------------------------------------------
// Cards (derived by duel-cards in shared/duel/derive.ts; the engine never re-derives)
// ---------------------------------------------------------------------------
export type CardType = 'Figure' | 'Location' | 'Event' | 'Institution' | 'Doctrine';
export const CARD_TYPES: readonly CardType[] = ['Figure', 'Location', 'Event', 'Institution', 'Doctrine'];
export type Portal = 'Arts' | 'Earth' | 'History' | 'Science' | 'Society' | 'Neutral';
export const PORTALS: readonly Portal[] = ['Arts', 'Earth', 'History', 'Science', 'Society', 'Neutral'];
/** Card keywords (DUEL_DESIGN §4), ≤ ruleset.maxKeywords per card. 'Trending' is granted by Trending mode only. */
export type Keyword = 'Protected' | 'Featured' | 'Legacy' | 'Multilingual' | 'Translated' | 'Well-sourced' | 'Stub' | 'Local' | 'Trending';
export const KEYWORDS: readonly Keyword[] = ['Protected', 'Featured', 'Legacy', 'Multilingual', 'Translated', 'Well-sourced', 'Stub', 'Local', 'Trending'];
/** Connected tiers (DUEL_DESIGN §6). The engine computes them from `connect`. */
export type ConnectedTier = 'Linked' | 'Compatriot' | 'Contemporary' | 'Kin';
export const CONNECTED_TIERS: readonly ConnectedTier[] = ['Linked', 'Compatriot', 'Contemporary', 'Kin'];
/** Frozen claims used for Connected (no I/O during a match). */
export interface ConnectKeys {
/** P17/P27 values (Q-ids or labels; compared as strings). */
countries: string[];
/** From P569/P570/P571/P580/P585, e.g. 19 for the 1800s. */
centuries: number[];
/** Outlink pageIds (cached), plus pageIds the card's claims cite. */
links: number[];
/** P31 Q-ids. Q5 (human) and Q16521 (taxon) never count for Kin. */
p31: string[];
/** The card's own Q-id, and the Q-ids its claims cite: Linked if either cites the other (DUEL_DESIGN §6). */
qid?: string;
cites?: string[];
}
/** When an effect runs. Sorcery speed only: there is no stack and no response window. */
export type EffectTrigger =
| 'onPlay' // an Event resolves (on a permanent: same as onEnter)
| 'onEnter' // this permanent enters the battlefield
| 'onAttack' // this Figure is declared as an attacker (resolves at confirmAttack)
| 'onDestroyed' // this permanent is destroyed (after all combat damage)
| 'startOfTurn' // its controller's refresh step, in entry order
| 'onCombatDamageToPlayer' // this Figure (or the Figure this Doctrine is attached to) deals combat damage to a player
| 'static'; // continuous while on the battlefield
/** Effect ops the interpreter knows. duel-cards builds the 12 templates (DUEL_DESIGN §5) from these. */
export type EffectOp =
| 'damage' // `amount` to each target (Figure, Location or player)
| 'damageEach' // `amount` to every Figure and Location (target narrows: 'ownFigures' / 'opponentFigures')
| 'createToken' // `amount` (default 1) copies of `token` under the controller; condition.maxTokens limits
| 'pump' // +power/+toughness (negative allowed); duration 'turn' | 'permanent'; as static: while the source is in play
| 'fight' // the previous chosen target (else this permanent) and this target deal damage equal to their power to each other
| 'draw' // controller draws `amount`
| 'attach' // Doctrine: attach to the target Figure (defines the Doctrine's target)
| 'gainLife' // controller gains `amount` Notability
| 'drain' // opponent loses `amount`, controller gains `amount`
| 'destroy' // destroy target permanent
| 'bounce' // return target permanent to its owner's hand
| 'tap'; // tap target permanent
export type TargetSpec =
// chosen (each consumes one entry of play.targets, in effect order)
| 'figure' // any Figure
| 'figureOrLocation' // any Figure or Location
| 'ownFigure' // a Figure you control
| 'opponentFigure' // a Figure you don't control
| 'anyTarget' // any Figure, Location or player
// automatic
| 'each' // every Figure and Location
| 'self' // this permanent
| 'attached' // the Figure this Doctrine is attached to
| 'ownFigures' // every Figure you control
| 'opponentFigures' // every Figure you don't control
| 'opponent' // the opposing player
| 'controller'; // you
export interface TokenSpec { name: string; power: number; toughness: number; portal: Portal }
export interface EffectSpec {
trigger: EffectTrigger;
op: EffectOp;
/** Default per op: damage → 'anyTarget'; pump → 'self'; draw/gainLife/createToken → 'controller'; drain → 'opponent'. */
target?: TargetSpec;
amount?: number;
/** pump: +power/+toughness (default: amount/amount). */
power?: number;
toughness?: number;
/** pump/grant outside static: 'turn' (default) or 'permanent'. */
duration?: 'turn' | 'permanent';
token?: TokenSpec;
condition?: {
/** Only affects Figures with printed power ≤ maxPower. */
maxPower?: number;
/** Only Figures of the source's Portal (for a Doctrine: the attached Figure's Portal), excluding that card itself. */
samePortal?: boolean;
/** Only Figures Connected to the source. */
connected?: boolean;
/** createToken: only if the controller controls fewer than this many tokens. */
maxTokens?: number;
};
/** Keywords granted to the affected Figures (static: while in play; otherwise for `duration`). */
grant?: Keyword[];
/** Template id (T1–T12) for rules text and log wording. */
template?: string;
}
/**
* A card as the engine sees it, frozen at match start. The host builds these
* from the chain via duel-cards' derive(); the engine trusts them.
*/
export interface DuelCard {
/** Unique within one deck: the NFT tokenId (or a sample id in sims; `token:` ids for tokens). */
cardId: string;
pageId: number | null;
revisionId?: number;
title: string;
/** Wikidata description ("American actor (1909–1994)"), for log first mentions. */
description?: string;
type: CardType;
/** e.g. 'conflict', 'election', 'organisation', 'pathology'. */
subtype?: string | null;
portal: Portal;
cost: number;
/** Figures: the body. Locations: power 0, toughness = Garrison (0 = can't block). Others: null or 0. */
power: number | null;
toughness: number | null;
keywords: Keyword[];
/** Locations: +N max Citations while controlled (all sources together ≤ territoryCap). */
territory?: number;
effects: EffectSpec[];
/** Deterministic rules text (shared/duel/text.ts). Display only. */
rulesText: string;
/** First sentence of article.extract (else description). Display only. */
flavor: string;
connect?: ConnectKeys;
rarity?: 'Common' | 'Rare' | 'Epic' | 'Legendary';
deriveVersion?: string;
/** Tokens are created in play and never in decks. */
token?: boolean;
}
// ---------------------------------------------------------------------------
// Ruleset (all numbers are data; parseDuelRuleset in ruleset.ts validates)
// ---------------------------------------------------------------------------
export type LibraryEmpty = 'lose' | 'reshuffle' | 'fatigue';
export interface DuelRuleset {
engine: 'duel';
version: string;
deckSize: number; // 40
maxCopiesPerPage: number; // 4
startingLife: number; // 20 Notability
openingHand: number; // 7
handSize: number; // 7: hand limit at end of turn (DUEL_DESIGN `handLimit`); excess discarded highest cost first
mulligans: number; // 1: shuffle, draw openingHand, bottom one per mulligan taken
firstPlayerDraws: boolean; // false
maxCitations: number; // 10
citationsPerTurn: number; // 1
territoryCap: number; // 2
locationsPerTurn: number; // 1
libraryEmpty: LibraryEmpty; // 'lose'
maxKeywords: number; // 2
stubMax: number; // 2: max Stub counters
trendingPower: number; // 1: Trending gets +N/+0
connectedTiers: ConnectedTier[]; // all four; cut tiers by removing them
connectedBonus: number; // 1
linkedBonus: number; // 2
turnSeconds: number; // 60
bankSeconds: number; // 300
timeoutsToConcede: number; // 3 consecutive timeouts lose
/** Optional: after this many turns in total, higher Notability wins, then higher power in play, then the second player. */
turnCap: number | null;
}
// ---------------------------------------------------------------------------
// State
// ---------------------------------------------------------------------------
/** 'mulligan' → 'main' → 'attack' → ('block' if attackers can be blocked) → next turn. Refresh, draw, damage and end are automatic. */
export type Phase = 'mulligan' | 'main' | 'attack' | 'block' | 'over';
/** One physical card in a match. `uid` is unique per match ("0:12" = seat 0, deck index 12; "t:3" = token); actions use uids. */
export interface CardInstance {
uid: string;
owner: Seat;
card: DuelCard;
}
export interface Permanent extends CardInstance {
controller: Seat;
tapped: boolean;
/** "Pending review": entered this turn, can't attack. */
sick: boolean;
damage: number;
/** Stub +1/+1 counters. */
counters: number;
/** Permanent pump modifiers. */
permPower: number;
permToughness: number;
/** Until-end-of-turn modifiers. */
tempPower: number;
tempToughness: number;
/** Keywords granted until end of turn / permanently by non-static effects. */
tempKeywords: Keyword[];
permKeywords: Keyword[];
/** Doctrines: uid of the Figure they're attached to. */
attachedTo?: string;
/** Well-sourced: prevention already used this turn. */
shielded: boolean;
/** Entry order (trigger order). */
entered: number;
/** Connected bonus already logged. */
connectedLogged: boolean;
}
export interface PlayerState {
life: number;
/** Citations available this turn. */
citations: number;
/** Base max (rises by citationsPerTurn to maxCitations). */
baseCitations: number;
library: CardInstance[]; // top = index 0. Hidden.
hand: CardInstance[]; // hidden from the opponent
graveyard: CardInstance[]; // "Deleted", public
mulligansTaken: number;
ready: boolean;
locationsThisTurn: number;
/** Remaining time bank in seconds (the host decrements it). */
bankSeconds: number;
/** Consecutive timeouts. */
timeouts: number;
/** libraryEmpty 'fatigue': damage of the last empty draw. */
fatigue: number;
}
export interface CombatState {
attackers: string[];
/** blocker uid → attacker uid. */
blocks: Record<string, string>;
}
export type EndReason = 'life' | 'library' | 'concede' | 'timeout' | 'turnCap';
export interface DuelResult {
winner: Seat | null; // null = draw
reason: EndReason;
}
export interface DuelState {
engine: 'duel';
rules: DuelRuleset;
seed: string;
rng: RngState;
/** 1-based, counts both players' turns. 0 during mulligans. */
turn: number;
active: Seat;
firstSeat: Seat;
phase: Phase;
players: [PlayerState, PlayerState];
battlefield: Permanent[];
combat: CombatState;
log: LogEvent[];
result: DuelResult | null;
/** Increments on every applied action (host polling: unchanged → 204). */
version: number;
/** Counters for token uids and entry order. */
nextToken: number;
nextEntry: number;
}
// ---------------------------------------------------------------------------
// Actions (atomic; legalActions enumerates them; [] for the seat not to act)
// ---------------------------------------------------------------------------
export type TargetRef = { kind: 'card'; uid: string } | { kind: 'player'; seat: Seat };
export type DuelAction =
| { type: 'keep' }
| { type: 'mulligan' }
/** targets: one per chosen-target effect, in effect order (Doctrine: its 'attach' target). Omitted when none. */
| { type: 'play'; uid: string; targets?: TargetRef[] }
| { type: 'endPhase' } // main → attack
| { type: 'toggleAttacker'; uid: string } // declare one more attacker (monotonic)
| { type: 'confirmAttack' } // no attackers → end turn
| { type: 'block'; blocker: string; attacker: string } // defender, monotonic
| { type: 'confirmBlocks' } // damage, then end of turn
| { type: 'concede' } // any time, either seat (not listed)
| { type: 'timeout' }; // host-only, for the seat that must act (not listed)
// ---------------------------------------------------------------------------
// Log (encyclopedic; clients get logFor(state, seat); state.log is omniscient)
// ---------------------------------------------------------------------------
/** A card in the log. power/toughness: current values right after the event (Figures and Garrisons on the battlefield). */
export interface CardRef { uid: string; cardId: string; title: string; pageId: number | null; type: CardType; power?: number; toughness?: number }
export type LogEvent = { seq: number; turn: number } & (
| { kind: 'start'; firstSeat: Seat }
| { kind: 'mulligan'; seat: Seat }
| { kind: 'keep'; seat: Seat; handSize: number }
| { kind: 'turnStart'; seat: Seat; citations: number; life: [number, number] }
/** card is omitted in the opponent's logFor (hidden draw). */
| { kind: 'draw'; seat: Seat; card?: CardRef }
/** A Figure, Location or Institution entered. */
| { kind: 'deploy'; seat: Seat; card: CardRef }
/** An Event resolved. */
| { kind: 'cast'; seat: Seat; card: CardRef; targets: TargetRef[] }
/** A Doctrine was attached. */
| { kind: 'adopt'; seat: Seat; card: CardRef; to: CardRef }
| { kind: 'tokenCreated'; seat: Seat; card: CardRef; source: CardRef }
| { kind: 'connected'; seat: Seat; card: CardRef; with: CardRef; tier: ConnectedTier; via: string; bonus: number }
/** Rivalry (log only): two opposing permanents are Connected. */
| { kind: 'rivalry'; card: CardRef; with: CardRef; tier: ConnectedTier; via: string }
/** Any resolved effect (wording key: template). Damage and life changes follow as their own events. */
| { kind: 'effect'; seat: Seat; source: CardRef; op: EffectOp; template?: string; targets: TargetRef[] }
| { kind: 'attack'; seat: Seat; attackers: CardRef[] }
| { kind: 'block'; seat: Seat; blocks: { blocker: CardRef; attacker: CardRef }[] }
/** Damage to a permanent from an effect / from combat. */
| { kind: 'effectDamage'; source: CardRef; target: CardRef; amount: number }
| { kind: 'combatDamage'; source: CardRef; target: CardRef; amount: number }
/** Damage or life loss to a player. source null = fatigue. */
| { kind: 'playerDamage'; source: CardRef | null; seat: Seat; amount: number; life: number; combat: boolean }
| { kind: 'lifeGain'; source: CardRef; seat: Seat; amount: number; life: number }
| { kind: 'destroyed'; card: CardRef; owner: Seat }
| { kind: 'bounced'; card: CardRef; owner: Seat }
| { kind: 'discard'; seat: Seat; card: CardRef }
| { kind: 'fatigue'; seat: Seat; amount: number }
| { kind: 'concede'; seat: Seat }
| { kind: 'timeout'; seat: Seat }
| { kind: 'gameOver'; winner: Seat | null; reason: EndReason; life: [number, number] }
);
export type LogKind = LogEvent['kind'];
// ---------------------------------------------------------------------------
// Views (what one seat may see; bots and UI get only this)
// ---------------------------------------------------------------------------
export interface PermanentView {
uid: string;
owner: Seat;
controller: Seat;
card: DuelCard;
tapped: boolean;
sick: boolean;
damage: number;
counters: number;
attachedTo?: string;
/** Current values after counters, pumps, statics, Connected and Trending. */
power: number;
toughness: number;
keywords: Keyword[];
/** Active Connected bonus, if any (for the card face). */
connected?: { with: string; tier: ConnectedTier; via: string; bonus: number };
}
export interface SideView {
seat: Seat;
life: number;
citations: number;
maxCitations: number;
handSize: number;
librarySize: number;
graveyard: CardInstance[];
bankSeconds: number;
ready: boolean;
mulligansTaken: number;
}
export interface PlayerView {
engine: 'duel';
seat: Seat;
turn: number;
active: Seat;
phase: Phase;
/** Seat that must act now (null when over). */
toAct: Seat | null;
you: SideView & { hand: CardInstance[] };
opponent: SideView;
battlefield: PermanentView[];
combat: CombatState;
result: DuelResult | null;
version: number;
rules: DuelRuleset;
}
+3 -1
View File
@@ -16,6 +16,7 @@ import { IS_MAINNET, NETWORK_GENESIS_TIME, NETWORK_LABEL } from '../shared/netwo
import { StateClient } from '../shared/rpc-client.ts';
import { PlaySection } from './game/PlaySection.tsx';
import { isNativeApp } from './native.ts';
import { MobileMiningPanel } from './MobileMiningPanel.tsx';
import { Landing } from './Landing.tsx';
import './App.css';
import './testnet.css';
@@ -190,7 +191,8 @@ export default function App() {
<div><span className="metric-icon"><WalletIcon size={19} /></span><div><span>Confirmed ownership</span><strong>{wallet && snapshot ? owned.length : '—'}<small>in your wallet</small></strong></div></div>
<div><span className="metric-icon"><Cpu size={19} /></span><div><span>Proof of work</span><strong className="algorithm">{snapshot?.algorithm ?? 'RandomX'}<small>native CPU mining</small></strong></div></div>
</section>
<section className="mining-panel native-mining" ref={minerPanel} hidden={isNativeApp()}>
{isNativeApp() && <MobileMiningPanel ref={minerPanel} wallet={wallet} onAccepted={() => { void refresh().catch(() => {}); }} />}
<section className="mining-panel native-mining" ref={isNativeApp() ? undefined : minerPanel} hidden={isNativeApp()}>
<div className="mining-description"><div className="section-eyebrow"><span className="idle-dot" /> RANDOMX · DESIGNED FOR GENERAL-PURPOSE CPUS</div><h2>Mining should be for more people.</h2><p>Wikideck and Monero use RandomX, an algorithm designed to resist specialized ASICs and keep general-purpose CPUs competitive. That can make mining more accessible—not make every machine equally powerful or promise rewards. Each accepted Wikideck block earns its miner a distinct illustrated Wikipedia card. Wikideck is its own independent network.</p><div className="mining-meta"><span><Cpu size={13} /> Mine with a CPU</span><span><Shield size={13} /> Independently validating peers</span></div><details className="mining-details"><summary>Hardware, rewards &amp; network details</summary><div className="native-memory"><strong>Light · default</strong><span>256 MiB cache plus scratchpad and process overhead.</span><strong>Fast · --fast</strong><span>About 2 GiB dataset plus cache; budget over 2.3 GiB per process. Mining uses CPU, memory, electricity and time. ASIC resistance is a design goal, not a guarantee; results depend on hardware and network difficulty. Wikideck does not share Monero’s network, hashpower or security.</span></div></details></div>
<div className="miner-controls"><div className="miner-display"><div><span>NEXT WIKIPEDIA ARTICLE</span><strong>{snapshot ? 'Chosen when the miner requests work' : `Waiting for ${NETWORK_LABEL} RPC…`}</strong></div></div><p className="muted">The miner selects a random illustrated English Wikipedia article. The same article can appear again; each card keeps its own mint-time statistics.</p><details className="mining-details"><summary>Want to run a miner? Setup &amp; safety details</summary><ol className="native-steps"><li>Build <code>wikideck-randomx</code> using the repository’s native build instructions.</li><li>Save your encrypted backup and keep its password separate.</li><li>Replace <code>&lt;backup.json&gt;</code> with your local file path (quote paths with spaces), then run:</li></ol><pre className="native-command"><code>{nativeCommand}</code></pre><p className="miner-footnote">Node: {window.location.origin}. The command connects to this node; use HTTPS for remote nodes. Password entry stays local—never put it in the command. It defaults to one worker and at most one block. Ctrl+C stops the native miner; closing this page does not.</p></details><button className="button dark full" onClick={openWallet}><Download size={16} /> Download wallet backup</button><button className="text-button" onClick={() => setDialog('guide')}>Read the {NETWORK_LABEL.toLowerCase()} field guide <ArrowRight size={14} /></button></div>
</section>
+144
View File
@@ -0,0 +1,144 @@
// Android (sideload build) mining panel. Rendered only inside the native app; see docs/night2/MOBILE_MINING.md.
import { forwardRef, useEffect, useRef, useState } from 'react';
import { registerPlugin, type PluginListenerHandle } from '@capacitor/core';
import { Cpu, Pickaxe, Square } from 'lucide-react';
import { IS_MAINNET, NETWORK_LABEL } from '../shared/network.ts';
import { expectedChainIdentity } from '../shared/chain-identity.ts';
import { sign, touchWallet, type Wallet } from './wallet.ts';
import { nodeHref } from './native.ts';
import { MobileMiner, type MinerEngine, type MinerStatus, type MineResult } from './mobile-miner.ts';
import './mobile-mining.css';
type Conditions = { powerSave: boolean; thermalStatus: number; batteryTempC: number | null; batteryPercent: number;
charging: boolean; cores: number; abi: string; engineInstalled: boolean; blocked: string | null };
interface MinerPlugin {
conditions(): Promise<Conditions>;
selfTest(): Promise<{ ok: boolean; output: string }>;
start(o: { threads: number }): Promise<{ threads: number }>;
stop(): Promise<void>;
mine(o: { lane: number; key: string; blob: string; target: string; nonceOffset: number; maxAttempts: number }): Promise<MineResult>;
addListener(event: 'halted', fn: (e: { reason: string }) => void): Promise<PluginListenerHandle>;
}
const Native = registerPlugin<MinerPlugin>('WikiDeckMiner');
const engine: MinerEngine = {
start: async threads => { await Native.start({ threads }); },
stop: () => Native.stop(),
mine: (lane, key, blob, target, nonceOffset, maxAttempts) => Native.mine({ lane, key, blob, target, nonceOffset, maxAttempts }),
};
const CONSENT_KEY = 'wikideck.mobileMining.consent.v1';
const INTENSITY_KEY = 'wikideck.mobileMining.intensity';
const INTENSITIES = {
low: { label: 'Low: 1 thread, rests between batches', threads: 1, idleMs: 400 },
normal: { label: 'Normal: 1 thread', threads: 1, idleMs: 0 },
high: { label: 'High: 2 threads (about 512 MiB)', threads: 2, idleMs: 0 },
max: { label: 'Max: 4 threads (about 1 GiB), only while charging', threads: 4, idleMs: 0 },
} as const;
type Intensity = keyof typeof INTENSITIES;
const REASONS: Record<string, string> = {
background: 'the app went to the background', 'battery-saver': 'battery saver is on', thermal: 'the device is warm',
'battery-hot': 'the battery is hot', 'battery-low': 'the battery is below 20% and not charging', 'max-needs-charging': 'Max intensity needs the charger', closed: 'the app closed',
};
const explain = (reason: string) => REASONS[reason] ?? reason;
async function api(path: string, body?: unknown): Promise<unknown> {
const url = path.startsWith('/p2p/') ? nodeHref(path) : path; // /api/... is routed to the node by native.ts
const res = await fetch(url, { method: body ? 'POST' : 'GET', cache: 'no-store', signal: AbortSignal.timeout(30000),
headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify(body) : undefined });
const text = await res.text();
if (text.length > 262144) throw new Error('Node response too large');
const data = text ? JSON.parse(text) : {};
if (!res.ok) throw new Error(data.error ?? `Node rejected request (${res.status})`);
return data;
}
export const MobileMiningPanel = forwardRef<HTMLElement, { wallet?: Wallet; onAccepted?: () => void }>(function MobileMiningPanel({ wallet, onAccepted }, ref) {
const [consent, setConsent] = useState(() => localStorage.getItem(CONSENT_KEY) === 'yes');
const [intensity, setIntensity] = useState<Intensity>(() => (localStorage.getItem(INTENSITY_KEY) as Intensity) in INTENSITIES ? localStorage.getItem(INTENSITY_KEY) as Intensity : 'normal');
const [conditions, setConditions] = useState<Conditions>();
const [status, setStatus] = useState<MinerStatus>();
const [check, setCheck] = useState<{ ok: boolean; output: string }>();
const [error, setError] = useState('');
const miner = useRef<MobileMiner | undefined>(undefined);
const accepted = useRef(0);
const active = !!status && ['starting', 'requesting', 'mining', 'submitting'].includes(status.phase);
useEffect(() => {
let live = true;
const poll = () => Native.conditions().then(c => { if (live) setConditions(c); }).catch(() => {});
void poll();
const timer = setInterval(poll, 5000);
const halted = Native.addListener('halted', e => { void miner.current?.stop(`Paused: ${explain(e.reason)}`); });
const hide = () => { if (document.visibilityState !== 'visible') void miner.current?.stop(`Paused: ${explain('background')}`); };
document.addEventListener('visibilitychange', hide);
return () => { live = false; clearInterval(timer); void halted.then(h => h.remove()); document.removeEventListener('visibilitychange', hide); void miner.current?.stop(); };
}, []);
// A different (or locked) wallet must never keep mining to the previous address.
useEffect(() => { if (miner.current?.active) void miner.current.stop('Stopped: the wallet changed or locked.'); }, [wallet]);
const start = async () => {
setError('');
if (!wallet) { setError('Unlock your wallet first: cards are mined to its address.'); return; }
try {
let result = check;
if (!result?.ok) { result = await Native.selfTest(); setCheck(result); }
if (!result.ok) { setError('The RandomX engine failed its known-vector self-test on this device, so mining is disabled.'); return; }
const { chainId } = await expectedChainIdentity();
const preset = INTENSITIES[intensity];
const current = new MobileMiner({
engine, api, chainId, idleMs: preset.idleMs,
sign: message => sign(wallet, message),
blocked: async () => {
const c = await Native.conditions(); setConditions(c);
if (c.blocked) return explain(c.blocked);
if (preset.threads > 2 && !c.charging) return explain('max-needs-charging');
return document.visibilityState !== 'visible' ? explain('background') : undefined;
},
onStatus: s => {
// Mining runs only in the foreground with consent; keep the unlocked session alive so a found block can be signed.
touchWallet();
setStatus(s);
if (s.accepted > accepted.current) { accepted.current = s.accepted; onAccepted?.(); }
},
}, wallet);
miner.current = current;
void current.start(preset.threads);
} catch (e) { setError((e as Error).message); }
};
const stop = () => { void miner.current?.stop('Stopped.'); };
if (IS_MAINNET) return <section className="mining-panel mobile-mining" ref={ref}><h2>Mining</h2>
<p className="muted">This build mines on the private testnet only. Mainnet mining from the app is not enabled.</p></section>;
const blockedNow = conditions?.blocked;
return <section className="mining-panel mobile-mining" ref={ref} aria-label="Mine on this phone">
<div className="section-eyebrow"><Cpu size={14} /> RANDOMX LIGHT · {NETWORK_LABEL.toUpperCase()} · SIDELOAD BUILD</div>
<h2>Mine cards on this phone</h2>
<p>Each accepted block mints one Wikipedia card to your wallet. The phone runs the same pinned RandomX engine as the desktop miner, in light mode (about 256 MiB per thread). Mining runs only while this screen is open, and it stops by itself on battery saver, when the phone is warm, or below 20% battery when not charging.</p>
<label className="mobile-mining-consent"><input type="checkbox" checked={consent} disabled={active}
onChange={e => { setConsent(e.target.checked); localStorage.setItem(CONSENT_KEY, e.target.checked ? 'yes' : 'no'); }} />
<span>I understand that mining uses this phone's CPU and battery and can make it warm, and I want to mine to my wallet.</span></label>
<label className="mobile-mining-intensity">Intensity
<select value={intensity} disabled={active} onChange={e => { setIntensity(e.target.value as Intensity); localStorage.setItem(INTENSITY_KEY, e.target.value); }}>
{Object.entries(INTENSITIES).map(([k, v]) => <option key={k} value={k} disabled={(k === 'high' && (conditions?.cores ?? 0) < 4) || (k === 'max' && ((conditions?.cores ?? 0) < 4 || !conditions?.charging))}>{v.label}</option>)}
</select></label>
<div className="mobile-mining-actions">
{active ? <button className="button outline" onClick={stop}><Square size={15} /> Stop mining</button>
: <button className="button" onClick={() => void start()} disabled={!consent || !wallet || !!blockedNow || conditions?.engineInstalled === false}><Pickaxe size={15} /> Start mining</button>}
</div>
{!wallet && <p className="muted">Unlock or create your wallet to mine.</p>}
{conditions?.engineInstalled === false && <p className="error-text">This APK has no RandomX engine for {conditions.abi}.</p>}
{blockedNow && !active && <p className="muted">Paused: {explain(blockedNow)}.</p>}
{error && <p className="error-text" role="alert">{error}</p>}
<dl className="mobile-mining-stats" aria-live="polite">
<div><dt>Hashrate</dt><dd>{status ? `${status.hashrate.toFixed(1)} H/s` : '—'}</dd></div>
<div><dt>Status</dt><dd>{status?.phase ?? 'idle'}{status?.height ? ` · block #${status.height}` : ''}</dd></div>
<div><dt>Hashes</dt><dd>{status?.attempts.toLocaleString() ?? 0}</dd></div>
<div><dt>Accepted blocks</dt><dd>{status?.accepted ?? 0}</dd></div>
<div><dt>Battery</dt><dd>{conditions ? `${conditions.batteryPercent}%${conditions.charging ? ' charging' : ''}${conditions.batteryTempC !== null ? ` · ${conditions.batteryTempC.toFixed(1)} °C` : ''}` : '—'}</dd></div>
<div><dt>Engine check</dt><dd>{check ? check.ok ? 'known vector OK' : 'FAILED' : 'runs before first start'}</dd></div>
</dl>
{status?.article && active && <p className="muted">Mining for: {status.article}</p>}
{status?.message && <p className="muted">{status.message}</p>}
</section>;
});
+173
View File
@@ -0,0 +1,173 @@
// Mobile (Android sideload) mining: the same loop as server/testnet/miner.ts, run in the WebView.
// The native WikiDeckMiner plugin (android/.../MinerPlugin.java) only runs the pinned RandomX engine in
// LIGHT mode; this module builds work from the node's template, signs the block claim with the local web
// wallet and submits it. The plugin never sees a private key or backup password.
// Browser-safe: Web Crypto only, no node: imports. See docs/night2/MOBILE_MINING.md.
import { CONSENSUS, NETWORK, blockClaimMessage, headerMessage, statsSnapshotTuple,
type BlockHeader, type MiningTemplate, type TestnetBlock } from '../shared/testnet.ts';
export type MineResult = { found: false } | { found: true; hash: string; nonce: string };
/** The RandomX engine as seen from the WebView (the Capacitor plugin, or a fake in tests). */
export interface MinerEngine {
start(threads: number): Promise<void>;
stop(): Promise<void>;
mine(lane: number, key: string, blobHex: string, target: string, nonceOffset: number, maxAttempts: number): Promise<MineResult>;
}
export interface MinerIdentity { address: string; publicKey: string }
export interface MinerDeps {
engine: MinerEngine;
/** POST/GET JSON against the node (relative paths such as /api/mining/template). */
api: (path: string, body?: unknown) => Promise<unknown>;
/** Sign a message with the unlocked web wallet. */
sign: (message: string) => Promise<string>;
chainId: string;
/** Checked before every batch; return a reason to stop (battery saver, thermal, background...). */
blocked?: () => string | undefined | Promise<string | undefined>;
onStatus?: (status: MinerStatus) => void;
now?: () => number;
/** Pause between batches per lane (ms): intensity control. */
idleMs?: number;
random?: () => number;
}
export type MinerPhase = 'idle' | 'starting' | 'requesting' | 'mining' | 'submitting' | 'stopped' | 'error';
export interface MinerStatus {
phase: MinerPhase; hashrate: number; attempts: number; height?: number; article?: string;
accepted: number; rejected: number; lastBlock?: { height: number; tokenId: string; title: string };
message?: string;
}
export const BATCH = 16;
const hex = (bytes: Uint8Array) => Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
export function hexToBytes(value: string): Uint8Array {
if (!/^([0-9a-f]{2})*$/i.test(value)) throw new Error('Invalid hex');
const out = new Uint8Array(value.length / 2);
for (let i = 0; i < out.length; i++) out[i] = parseInt(value.slice(2 * i, 2 * i + 2), 16);
return out;
}
export async function sha256Hex(data: string | Uint8Array): Promise<string> {
const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes as BufferSource)));
}
/** Same bytes as consensus `miningBlob`: sha256(headerMessage) || nonce as uint64 little-endian. */
export async function miningBlobHex(header: BlockHeader): Promise<string> {
const nonce = new Uint8Array(8);
new DataView(nonce.buffer).setBigUint64(0, BigInt(header.nonce), true);
return await sha256Hex(headerMessage(header)) + hex(nonce);
}
/** Same value as consensus `mintId`, with the chain id taken from the (verified) header. */
export function mintIdOf(h: BlockHeader): Promise<string> {
return sha256Hex(JSON.stringify([NETWORK, h.chainId, 'mint', h.previousHash, h.height, h.owner,
h.article.pageId, statsSnapshotTuple(h.statsSnapshot)]));
}
export function meetsTarget(hash: string, target: string): boolean {
return BigInt(`0x${hash}`) <= BigInt(`0x${target}`);
}
/** Check a node template before spending CPU on it. */
export async function checkTemplate(t: MiningTemplate, chainId: string, me: MinerIdentity): Promise<void> {
const h = t?.header;
if (!h || h.network !== NETWORK || h.chainId !== chainId || t.nonceOffset !== 32) throw new Error('Node returned work for another network');
if (h.owner !== me.address || h.publicKey !== me.publicKey) throw new Error('Node returned work for another wallet');
if (!/^[0-9a-f]{64}$/.test(h.key) || !/^[0-9a-f]{64}$/.test(h.target)) throw new Error('Node returned malformed work');
if (typeof t.blob === 'string' && t.blob.slice(0, 64) !== (await miningBlobHex({ ...h, nonce: 0 })).slice(0, 64)) {
throw new Error('Node work blob does not match its header');
}
}
/** Assemble the block exactly as server/testnet/miner.ts does. */
export async function buildBlock(t: MiningTemplate, nonce: number, powHash: string, sign: (m: string) => Promise<string>): Promise<TestnetBlock> {
const header: BlockHeader = { ...t.header, nonce };
const blob = await miningBlobHex(header);
const hash = await sha256Hex(hexToBytes(blob));
const signature = await sign(blockClaimMessage(hash));
return { ...header, hash, tokenId: await mintIdOf(header), powHash, signature, transactions: t.transactions };
}
/** Runs until stop() or a safeguard trips. One instance per app. */
export class MobileMiner {
private stopping = false;
private running?: Promise<void>;
status: MinerStatus = { phase: 'idle', hashrate: 0, attempts: 0, accepted: 0, rejected: 0 };
private readonly deps: MinerDeps;
private readonly me: MinerIdentity;
constructor(deps: MinerDeps, me: MinerIdentity) { this.deps = deps; this.me = me; }
private set(patch: Partial<MinerStatus>) { this.status = { ...this.status, ...patch }; this.deps.onStatus?.(this.status); }
get active() { return !!this.running; }
start(threads = 1, maxBlocks = Infinity): Promise<void> {
if (this.running) return this.running;
this.stopping = false;
this.running = this.loop(Math.max(1, Math.min(4, Math.floor(threads))), maxBlocks)
.finally(() => { this.running = undefined; });
return this.running;
}
async stop(reason?: string): Promise<void> {
this.stopping = true;
if (reason) this.set({ message: reason });
await this.deps.engine.stop().catch(() => {});
await this.running?.catch(() => {});
}
private async loop(threads: number, maxBlocks: number) {
const { engine, api } = this.deps;
const now = this.deps.now ?? Date.now, random = this.deps.random ?? Math.random;
this.set({ phase: 'starting', message: undefined, hashrate: 0 });
try {
const reason = await this.deps.blocked?.();
if (reason) throw new Error(`Mining is paused: ${reason}`);
await engine.start(threads);
let accepted = 0;
while (!this.stopping && accepted < maxBlocks) {
this.set({ phase: 'requesting' });
const template = await api('/api/mining/template', { owner: this.me.address, publicKey: this.me.publicKey }) as MiningTemplate;
await checkTemplate(template, this.deps.chainId, this.me);
const h = template.header;
this.set({ phase: 'mining', height: h.height, article: h.article.title });
const started = now();
let attempts = 0, lastCheck = now(), stale = false;
let solution: { nonce: number; hash: string } | undefined;
const lane = async (index: number) => {
let nonce = Math.floor(random() * 2 ** 32);
while (!this.stopping && !solution && !stale) {
const blob = await miningBlobHex({ ...h, nonce });
const result = await engine.mine(index, h.key, blob, h.target, 32, BATCH);
attempts += BATCH;
if (result.found) {
const n = Number(result.nonce);
if (!Number.isSafeInteger(n) || !meetsTarget(result.hash, h.target)) throw new Error('Engine returned an invalid solution');
solution ??= { nonce: n, hash: result.hash };
return;
}
nonce += BATCH;
const elapsed = (now() - started) / 1000;
this.set({ attempts: this.status.attempts + BATCH, hashrate: elapsed > 0 ? attempts / elapsed : 0 });
if (index === 0 && now() - lastCheck >= 2000) {
lastCheck = now();
const reason = await this.deps.blocked?.();
if (reason) { this.stopping = true; this.set({ message: `Paused: ${reason}` }); return; }
const status = await api('/p2p/status') as { tip?: string };
if (status.tip !== h.previousHash || now() / 1000 - h.createdAt > CONSENSUS.targetSeconds * 2) stale = true;
}
if (this.deps.idleMs) await new Promise(r => setTimeout(r, this.deps.idleMs));
}
};
await Promise.all(Array.from({ length: threads }, (_, i) => lane(i)));
if (this.stopping || !solution) continue;
this.set({ phase: 'submitting' });
const block = await buildBlock(template, solution.nonce, solution.hash, this.deps.sign);
try {
const result = await api('/api/blocks', block) as { accepted?: boolean; reason?: string };
if (result.accepted === false) throw new Error(result.reason ?? 'Block not accepted');
accepted++;
this.set({ accepted: this.status.accepted + 1, lastBlock: { height: block.height, tokenId: block.tokenId, title: block.article.title },
message: `Accepted block #${block.height}: ${block.article.title}` });
} catch (error) {
this.set({ rejected: this.status.rejected + 1, message: (error as Error).message });
}
}
this.set({ phase: 'stopped' });
} catch (error) {
this.set({ phase: this.stopping ? 'stopped' : 'error', message: this.stopping ? this.status.message : (error as Error).message });
} finally {
await engine.stop().catch(() => {});
}
}
}
+10
View File
@@ -0,0 +1,10 @@
.mobile-mining { display: grid; gap: 12px; }
.mobile-mining h2 { margin: 0; }
.mobile-mining-consent { display: flex; gap: 10px; align-items: flex-start; }
.mobile-mining-consent input { margin-top: 4px; min-width: 20px; min-height: 20px; }
.mobile-mining-intensity { display: grid; gap: 6px; }
.mobile-mining-intensity select { min-height: 44px; }
.mobile-mining-actions .button { min-height: 44px; display: inline-flex; gap: 8px; align-items: center; }
.mobile-mining-stats { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px 16px; margin: 0; }
.mobile-mining-stats dt { font-size: 0.75rem; opacity: 0.7; }
.mobile-mining-stats dd { margin: 0; font-variant-numeric: tabular-nums; }
-40
View File
@@ -1,40 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { DEFAULT_DUEL_RULESET, mergeDuelRuleset, parseDuelRuleset, CARD_TYPES, KEYWORDS } from '../shared/duel/index.ts';
import { DEFAULT_RULESET } from '../shared/game/index.ts';
test('duel default ruleset matches the BRIEF', () => {
const rules = parseDuelRuleset({ ...DEFAULT_DUEL_RULESET });
assert.equal(rules.deckSize, 40);
assert.equal(rules.startingLife, 20);
assert.equal(rules.maxCitations, 10);
assert.equal(rules.handSize, 7);
assert.equal(rules.openingHand, 7);
assert.equal(rules.mulligans, 1);
assert.equal(rules.libraryEmpty, 'lose');
assert.equal(rules.firstPlayerDraws, false);
assert.equal(rules.turnSeconds, 60);
assert.equal(rules.bankSeconds, 300);
assert.equal(rules.turnCap, null);
assert.equal(rules.territoryCap, 2);
});
test('duel ruleset merges overrides and rejects unknown keys', () => {
assert.equal(mergeDuelRuleset({ deckSize: 20 }).deckSize, 20);
assert.equal(mergeDuelRuleset({ turnCap: 30 }).turnCap, 30);
assert.throws(() => mergeDuelRuleset({ topicCount: 3 }));
assert.throws(() => mergeDuelRuleset({ libraryEmpty: 'shrug' }));
assert.throws(() => mergeDuelRuleset({ deckSize: 0 }));
assert.throws(() => mergeDuelRuleset([1]));
});
test('Night 1 Edit War rulesets are rejected cleanly', () => {
assert.throws(() => parseDuelRuleset(DEFAULT_RULESET));
});
test('card types and keywords are the BRIEF set', () => {
assert.deepEqual([...CARD_TYPES], ['Figure', 'Location', 'Event', 'Institution', 'Doctrine']);
for (const k of ['Protected', 'Featured', 'Translated', 'Legacy', 'Stub', 'Well-sourced', 'Multilingual', 'Local']) {
assert.ok((KEYWORDS as readonly string[]).includes(k), k);
}
});
+121
View File
@@ -0,0 +1,121 @@
// mobile-mining: the WebView mining loop must build blocks byte-identical to server/testnet/miner.ts.
// No network calls: the node API and the RandomX engine are in-process fakes.
import test from 'node:test';
import assert from 'node:assert/strict';
import { createHash, generateKeyPairSync, sign } from 'node:crypto';
import { CHAIN_ID, MAX_TARGET, address, makeTemplate, miningBlob, mintId, sha256, validateBlock } from '../server/testnet/consensus.ts';
import { type MiningTemplate, type TestnetBlock } from '../shared/testnet.ts';
import { deriveStats } from '../shared/enrichment.ts';
import type { PowEngine } from '../server/testnet/randomx.ts';
import { MobileMiner, buildBlock, checkTemplate, meetsTarget, miningBlobHex, mintIdOf, type MinerEngine, type MineResult } from '../src/mobile-miner.ts';
const keys = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
const publicKey = keys.publicKey.export({ format: 'der', type: 'spki' }).toString('base64');
const me = { publicKey, address: address(publicKey) };
const signer = async (message: string) => sign('sha256', Buffer.from(message), { key: keys.privateKey, dsaEncoding: 'ieee-p1363' }).toString('base64');
const fakeHash = (key: string, blob: Uint8Array) => createHash('sha256').update(Buffer.concat([Buffer.from(key, 'hex'), Buffer.from(blob)])).digest('hex');
// Test-only stand-in for RandomX on both sides (production has no fake PoW).
const pow: PowEngine = { hash: async (key, blob) => fakeHash(key, blob), close() {} };
function template(target = MAX_TARGET): MiningTemplate {
const pageBytes = 2048, languageCount = 3;
const stats = { capturedAt: '2026-11-17T00:00:00.000Z', revisionId: 7, pageBytes, languageCount, languagesTruncated: false,
pageviews: { status: 'unavailable' as const, months: [], latestMonth: '2026-10', total: null, dailyAverage: null, trendPercent: null },
stats: deriveStats(pageBytes, languageCount, null) };
const article = { pageId: 4242, title: 'Tetrated dodecahedron', extract: 'A deterministic test article.', image: 'https://upload.wikimedia.org/wikipedia/commons/test.jpg',
url: 'https://en.wikipedia.org/?curid=4242', revisionId: 7, source: 'live' as const, category: 'Science' };
const t = makeTemplate([], {}, me.address, me.publicKey, [], article, stats, Math.floor(Date.now() / 1000));
t.header.target = target;
t.blob = miningBlob(t.header).toString('hex');
return t;
}
/** Fake engine that speaks the plugin's mine contract with the fake hash. */
class FakeEngine implements MinerEngine {
started = 0; stopped = 0; calls = 0;
async start() { this.started++; }
async stop() { this.stopped++; }
async mine(_lane: number, key: string, blobHex: string, target: string, offset: number, max: number): Promise<MineResult> {
this.calls++;
const blob = Buffer.from(blobHex, 'hex');
let nonce = blob.readBigUInt64LE(offset);
for (let i = 0; i < max; i++, nonce++) {
blob.writeBigUInt64LE(nonce, offset);
const hash = fakeHash(key, blob);
if (meetsTarget(hash, target)) return { found: true, hash, nonce: nonce.toString() };
}
return { found: false };
}
}
test('browser blob and mint id match consensus', async () => {
const t = template();
for (const nonce of [0, 1, 2 ** 32 + 5, Number.MAX_SAFE_INTEGER]) {
const header = { ...t.header, nonce };
assert.equal(await miningBlobHex(header), miningBlob(header).toString('hex'));
}
assert.equal(await mintIdOf(t.header), mintId(t.header));
assert.equal(t.header.chainId, CHAIN_ID);
});
test('buildBlock produces a block the consensus validator accepts', async () => {
const t = template();
const header = { ...t.header, nonce: 0 };
while (!meetsTarget(fakeHash(header.key, miningBlob(header)), header.target)) header.nonce++;
const powHash = fakeHash(header.key, miningBlob(header));
const block = await buildBlock(t, header.nonce, powHash, signer);
assert.equal(block.hash, sha256(miningBlob(header)));
assert.equal(block.signature.length > 0, true);
const { block: valid } = await validateBlock(structuredClone(block), [], {}, pow);
assert.equal(valid.tokenId, mintId(header));
});
test('checkTemplate rejects work for another network or wallet', async () => {
const t = template();
await checkTemplate(t, CHAIN_ID, me);
await assert.rejects(checkTemplate(t, 'f'.repeat(64), me), /another network/);
await assert.rejects(checkTemplate(t, CHAIN_ID, { ...me, address: '0'.repeat(64) }), /another wallet/);
await assert.rejects(checkTemplate({ ...t, blob: '00'.repeat(40) }, CHAIN_ID, me), /does not match/);
});
test('MobileMiner mines, signs and submits one accepted block, then stops the engine', async () => {
const engine = new FakeEngine();
const submitted: TestnetBlock[] = [];
const api = async (path: string, body?: unknown) => {
if (path === '/api/mining/template') { assert.deepEqual(body, { owner: me.address, publicKey: me.publicKey }); return template('0' + 'f'.repeat(63)); }
if (path === '/api/blocks') { submitted.push(body as TestnetBlock); await validateBlock(structuredClone(body), [], {}, pow); return { accepted: true }; }
if (path === '/p2p/status') return { tip: 'x' };
throw new Error(`unexpected ${path}`);
};
const miner = new MobileMiner({ engine, api, sign: signer, chainId: CHAIN_ID }, me);
await miner.start(1, 1);
assert.equal(miner.status.phase, 'stopped', miner.status.message);
assert.equal(miner.status.accepted, 1);
assert.equal(submitted.length, 1);
assert.equal(submitted[0].owner, me.address);
assert.ok(engine.stopped >= 1);
});
test('a tripped safeguard stops mining before the engine starts', async () => {
const engine = new FakeEngine();
const miner = new MobileMiner({ engine, api: async () => { throw new Error('no network'); }, sign: signer, chainId: CHAIN_ID,
blocked: () => 'battery saver is on' }, me);
await miner.start(1, 1);
assert.equal(miner.status.phase, 'error');
assert.match(miner.status.message ?? '', /battery saver/);
assert.equal(engine.started, 0);
assert.equal(engine.calls, 0);
});
test('stop() halts an in-progress search', async () => {
const engine = new FakeEngine();
const api = async (path: string) => path === '/api/mining/template' ? template('0'.repeat(64)) : { tip: template().header.previousHash };
const miner = new MobileMiner({ engine, api, sign: signer, chainId: CHAIN_ID }, me);
const run = miner.start(1);
for (let i = 0; engine.calls < 3 && i < 2000; i++) await new Promise(r => setTimeout(r, 1));
assert.ok(engine.calls >= 3, miner.status.message);
await miner.stop('Stopped.');
await run;
assert.equal(miner.status.phase, 'stopped');
assert.equal(miner.status.accepted, 0);
});