git / moonbite-network / docs/ADR-013-miner-distribution-policy.md · raw

# ADR-013 — Miner distribution policy: standalone, never bundled, never in a browser- **Status:** Accepted- **Date:** 2026-10-10- **Related:** ADR-006 (founder-mining disclosure; both miners released  publicly with no hidden speed edge), audit 2026-09-22 finding B2 (checksum drift), audit 2026-10-03  (supply chain is the real risk; `moonbite-wallet.exe` tracked next to the  miner), infra audit 2026-10-09 L5 (release authenticity integrity-only),  `deploy/RELEASE-SIGNING.md`.## ContextMoonBite is a CPU-mined proof-of-work coin. Its miner is the full node(`moonbited`) driven by a small script that calls `generatetoaddress` overloopback RPC. The wallet is a separate program that handles keys and nevermines. Both are distributed as downloads from moonbite.org and GitHub Releases.Three pressures act on how these are packaged:1. **User trust.** A download that quietly installs a miner next to a wallet,   or a wallet that turns out to use the CPU, is indistinguishable from   cryptojacking malware. The project's credibility rests on the miner being   something the user explicitly chose, started and can see running.2. **Antivirus heuristics.** A RandomX miner is, behaviourally, what AV engines   are tuned to catch: a JIT writing and executing memory, several gigabytes   of RAM, every core saturated for hours, from an unsigned binary almost no   one has seen. Every additional suspicious trait (packer, self-extraction to   `%TEMP%`, auto-start, downloading code) compounds the score.3. **Pseudonymity.** The project is run under a pseudonym with no legal   entity. Authenticode OV/EV certificates and Apple Developer ID notarization   require a verified legal identity. That path is closed until an entity   exists, so provenance has to come from somewhere else.Until this ADR, `release/miner/` in the repository held `moonbite-wallet.exe`next to `moonbited.exe`, the PyInstaller spec for the desktop wallet used UPXand the build docs recommended `--onefile`, and the Windows launcher invokedPowerShell with `-ExecutionPolicy Bypass`.### Survey: is there any browser mining?`static/` and `templates/` were searched for `WebAssembly`, `.wasm`,`new Worker`, `importScripts`, `SharedArrayBuffer`, `hashcash`, `cryptonight`and `coinhive`. There are no matches. `static/mining-god.js` draws a particlefield and a sparkline from a synthetic, `Math.random`-jittered "hashrate"; itperforms no hashing and talks to no node. The only `RandomX` strings in`templates/` are prose describing the algorithm. The site-side `/api/mining/*`endpoints and the `/start` page are a demo surface, and `release/miner/README.md`already says so. Conclusion: no browser mining exists anywhere in the web app,and this ADR forbids adding any.## Decision1. **The miner is never bundled with the wallet, and the wallet never carries   a miner.** Two archives per platform, from two source directories:   | Archive | Contents | Source |   |---|---|---|   | `moonbite-miner-<os>-<arch>.{zip,tar.gz}` | `moonbited`, `moonbite-cli`, `mine.ps1`/`Mine-MoonBite.bat` or `mine.sh`, `README.md`, `ANTIVIRUS.md` | `release/miner/` |   | `moonbite-wallet-<os>-<arch>.{zip,tar.gz}` | the wallet app, `README.md` | `release/wallet/` |   `deploy/miner/build-windows-bundle.py` refuses to build an archive whose   member list crosses the line. `moonbite-wallet.exe` moves from   `release/miner/` to `release/wallet/`.2. **The miner never runs in a browser.** No WebAssembly, Web Worker or   server-side mining-on-behalf-of-the-user is ever added to the site. Any   visual on the site that resembles mining is labelled a demo and performs no   proof-of-work. Real mining is a native node process the user starts.3. **Standalone download, started by the user, running only while the user   keeps it running.** No installer, no auto-start entry, scheduled task,   service, cron job or login item is created by anything in a user download.   Operator tooling that does install persistence on seed/explorer hosts   (`install-autostart.sh`) is gated behind an explicit `--i-am-the-operator`   flag and root, and is not shipped to users.4. **No runtime packers and no self-extraction.** `upx=False` in every   PyInstaller spec; one-directory builds, never `--onefile`; no obfuscation,   no bytecode cipher. The node binaries are plain mingw/gcc output, stripped   of debug symbols only.5. **No self-update and no downloading.** The miner scripts and the Python   miner never fetch, write or execute code. Updates are a new release the   user downloads and verifies.6. **No privilege and no security-setting changes.** The scripts never   request administrator or root rights, never add Defender exclusions and   never override the PowerShell execution policy. The `.bat` wrapper calls   `powershell -NoProfile -File mine.ps1` and, if the policy blocks it,   explains the user-scope `Set-ExecutionPolicy -Scope CurrentUser   RemoteSigned` plus `Unblock-File` so the choice is the user's.7. **Every launcher prints the SHA-256 of the binaries it is about to run**   and points at the published `SHA256SUMS.txt`.8. **A full Windows version resource** (CompanyName "MoonBite Labs",   FileDescription, ProductName, FileVersion matching the release tag) is   embedded in PyInstaller builds via `windows-version-info.txt`.9. **Signed where identity allows; attested and reproducible everywhere.**   - `SHA256SUMS.txt` for every archive and every executable inside it,     generated by the build from the artifacts, never hand-typed; verified in     CI by `deploy/verify-release-checksums.py`.   - A minisign signature over the manifest with the key in     `deploy/moonbite-release.pub` (key ceremony per     `deploy/RELEASE-SIGNING.md`).   - GitHub build-provenance attestations (Sigstore) for CI-built archives,     verifiable with `gh attestation verify`.   - Deterministic archives (fixed member order, fixed timestamps, fixed     compression) and documented build inputs so a third party can rebuild     and compare.   - Authenticode and Apple notarization are adopted the day a legal entity     exists to hold the certificate. Until then `codesign_identity=None` and     `skip_notarization=True` are stated in the spec rather than faked with a     self-signed certificate, which buys nothing with SmartScreen and looks     like evasion.10. **AV vendor submissions each release.** Every new executable is submitted    to the major vendors' false-positive portals as part of the release    checklist, and users are given the same list in `release/miner/ANTIVIRUS.md`    together with the reasons a legitimate RandomX miner trips heuristics.### Amendment 2026-10-15: the launcher bypasses the execution policy for itselfItem 6 is changed for `Mine-MoonBite.bat` only, by the owner's decision.Most Windows 11 PCs ship with the `Restricted` execution policy, which blocksevery script, signed or not, and downloaded scripts also carry the"from the internet" mark. In practice the double-click launcher failed fornearly every new miner, who then had to type policy commands first. Signingdoes not solve it (a signed script is still blocked under `Restricted`), andthe signing routes open to a pseudonymous project are uncertain (SignPathFoundation, applied for separately).The launcher now runs `powershell -NoProfile -ExecutionPolicy Bypass -Filemine.ps1`. The bypass is scoped to that one process and that one script nextto the launcher; no policy, registry key or other setting changes, and thescripts still never request administrator rights or touch Defender. The costnamed in the rationale below stands: antivirus engines score this line, sothe launcher may be flagged more often. `ANTIVIRUS.md` and the per-release AVsubmissions remain the mitigation. Running `mine.ps1` directly still obeysthe user's policy.## Rationale- Separation is the only way to make "we did not put a miner on your  machine" provable: a user who downloaded the wallet can open the archive  and see that no node binary is present. Bundling for convenience would  save one download and cost the project its clearest honesty signal.- Browser mining is either theatre (a page cannot run RandomX at a useful  rate) or abuse (using visitors' CPUs). Neither is acceptable for a coin  whose premise is that the user's own machine mines for the user.- Each AV-hygiene item removes a trait that the engines score, so the only  remaining signal is the one the miner cannot avoid: it is a miner. That  residual is addressed by documentation and vendor submissions, not by  asking users to lower their defences.- `-ExecutionPolicy Bypass` is the most common line in malicious batch  droppers. Even though the policy is not a security boundary, shipping the  bypass trains users to accept it and gives engines a reason to flag the  wrapper.- The pseudonymity constraint is real and is stated rather than worked  around. Checksums prove integrity, minisign proves the manifest came from  the project key, attestations prove which commit and workflow produced the  file, and reproducibility lets anyone check that the commit produces the  file. Together they are stronger provenance than an OV certificate bought  by a shell company; what they do not buy is SmartScreen reputation, and the  user-facing documents say so plainly.## Consequences- Two download buttons and two archives per platform; `web_app.py`'s  `_MINER_BUNDLES["wallet"]` currently serves a bare `moonbite-wallet.exe`  and should move to the `moonbite-wallet-windows-x86_64.zip` name when the  web route owner next touches it.- Desktop-wallet builds are larger (no UPX, one directory). Acceptable.- Users on a default Windows execution policy see one explanatory message the  first time instead of a silent bypass; the README documents the two  user-scope commands.- Release checklist grows: build both archives, regenerate and sign  `SHA256SUMS.txt`, confirm attestations, submit executables to AV portals,  bump `windows-version-info.txt` with the tag.- `install-autostart.sh` now exits with an explanation unless invoked with  `--i-am-the-operator` as root.- Any future proposal to embed mining in the wallet, the site or a browser  extension requires superseding this ADR, not amending it.