personal_infra/ansible/roles/xmrblocks/README.md

xmrblocks

The Onion Monero Blockchain Explorer, on monerod-box beside the node, published at exmrplore.contrapeso.xyz.

Why this role installs a binary instead of building one

Every other compiled service in this estate builds on its own host — bitcoin_knots and datum_gateway both do. This one cannot, and the reason is worth recording so nobody "fixes" it later.

xmrblocks is not a client of monerod. Its cmake/FindMonero.cmake imports 21 static libraries out of a compiled monero source tree and its headers, because it opens the LMDB directly rather than going through RPC. Building it therefore means compiling monero first — and the release tarball we install for the daemon contains only executables, no .a files and no headers, so there is nothing on the box to link against.

Measured on Debian 13, building only the libraries xmrblocks needs:

peak RSS, one cc1plus	~3.2 GB
peak RSS, -j4 concurrent	~5.5 GB
wall time, -j4	167 s
build tree	125 MB (source 70 MB)
toolchain	1.6 GB

monerod-box had 2 GB when this was measured (it has since been raised to 6 GB, for monerod's own sake — see below). It was tried at 768 MiB and 1800 MiB, at -j1 and -j2, and every combination was OOM-killed — a single translation unit exceeding 3 GB is not something lower parallelism can work around. Disk was never the constraint; the often-quoted "~10 GB" for a monero build describes upstream's full make, which also produces monerod, both wallets and the test suite, none of which are linked here.

So the binary is built elsewhere by scripts/build-xmrblocks.sh, which runs the whole thing in a debian:13 container. That matters: an artifact only one machine can produce is an artifact nobody can audit. Any host with Docker and ~6 GB of RAM reproduces it, and the script verifies the monero source against binaryFate's GPG signature exactly as roles/monero does for the daemon.

The role refuses to ship anything it has not checked: xmrblocks_sha256 is asserted on the control node, before the copy, against the value the build script prints.

Three upstream problems, and the fixes

None of these are documented anywhere. All three were found by building.

1. libasio-dev is missing from upstream's dependency list. The Dockerfile is Ubuntu-based and installs libboost-all-dev; Crow wants standalone asio.hpp, not boost/asio.hpp. On Debian 13 the build dies with asio.hpp: No such file or directory.

2. The explorer does not compile against monero v0.18.5.1. v0.18.5.0 changed

   crypto::hash get_pruned_transaction_hash(const transaction&, const crypto::hash&);
   bool         get_pruned_transaction_hash(const transaction&, const crypto::hash&, crypto::hash& res);
   

   and src/page.h still calls the old form. Upstream's Dockerfile pins MONERO_BRANCH=v0.18.4.0, which is why nobody has hit it. The build script applies a one-line patch, anchored on the exact source line so that if upstream ever fixes it the build stops loudly instead of silently doing something else.

   We patch rather than build against v0.18.4.0 deliberately: the current signed hashes.txt only covers the current release, so using the older source would mean giving up the provenance chain. The LMDB format is VERSION 5 in both, so either version reads the other's database safely.

3. FindMonero.cmake looks for miniupnpc inside the monero build tree with NO_DEFAULT_PATH, but monero stopped vendoring miniupnp as a submodule. Fixed with a -D Xmr_MINIUPNPC_LIBRARY= cache override pointing at the system library, rather than patching their cmake.

USE_DEVICE_TREZOR=OFF is also passed: an explorer has no use for hardware wallet support, and it drops the generated protobuf units, which are among the heaviest to compile. xmrblocks was verified to link against the resulting libraries.

Two things the unit gets right that look wrong

WorkingDirectory is load-bearing. src/page.h hardcodes #define TMPL_DIR "./templates" — the HTML is resolved relative to the process working directory, at request time. Get it wrong and the service starts happily, listens on 8081, and returns 500 for every page. That is also why the health check fetches a real page and greps it rather than just probing the port.

ReadWritePaths must include the blockchain directory, even though the database is opened read-only. MicroCore::init sets DBF_RDONLY, and monero's db_lmdb.cpp turns that into mdb_flags = MDB_RDONLY without MDB_NOLOCK — so LMDB still registers this process in the reader table inside lock.mdb. With ProtectSystem=strict and nothing writable, the open fails outright. The intuitive "it only reads, grant it nothing" is wrong. data.mdb itself remains read-only to the process, and writing to monerod's lock table is what any second reader does.

Exposure

Published by caddy_site on the edge host at exmrplore.contrapeso.xyz, with TLS terminated there and the upstream reached over the tailnet via MagicDNS.

The explorer listens on 0.0.0.0:8081. Nothing on the LAN or the internet reaches that directly: Tailscale's ts-input chain sits ahead of UFW, so only tailnet peers can, and the Headscale ACL grants tag:prd-vipy exactly tag:monerod-box:8081. A node with no ACL rule is invisible rather than merely unreachable — it never appears in tailscale status, MagicDNS does not resolve it, and the symptom is a Caddy 502 saying "no such host".

There is no authentication, by choice. A block explorer serves public chain data. But note what that includes: --enable-pusher is on (upstream's default), so any visitor can submit a raw transaction and have our node relay it. That is a deliberate decision, not an oversight — drop xmrblocks_enable_pusher to false to close it.

--enable-json-api and --enable-autorefresh-option are likewise upstream's defaults.

Monitoring

Endpoint	Source	Answers
services/monerod-box-local/xmrblocks	infra/401 via monitored_services	is the unit active
probe/xmrblocks	this role + infra/403	does it serve a real page
dns/exmrplore.contrapeso.xyz, public/exmrplore	infra/402	can the internet reach it

public/exmrplore asserts 200, unlike the Monero RPC endpoint next door which asserts 401 — this one genuinely has no auth in front of it.

The timer carries no Requires=xmrblocks.service; see the comment in healthcheck.timer.j2 for why that would be backwards.

Backups: none, deliberately

Everything here is derived or reproducible: the binary comes from scripts/build-xmrblocks.sh, the templates ship with it, and the data it serves is monerod's blockchain, which is itself excluded for the same reason. There is no state on this service worth a backup job. Recorded as a decision so it does not read as an oversight — the same treatment phoenixd and monero get.

Upgrading

1. Edit the pins at the top of scripts/build-xmrblocks.sh (EXPLORER_COMMIT, and MONERO_VERSION + MONERO_SRC_SHA256 together).
2. Run it. It prints the new artifact sha256.
3. Put that in xmrblocks_sha256 and xmrblocks_explorer_commit here.
4. Converge. The role asserts the checksum before copying anything.

If the patch anchor no longer matches, the script stops — read the diff before forcing it.

Runtime cost, and the RAM history

On 2026-09-20 the VM was raised from 2 GB to 6 GB, and that was not for the explorer. monerod alone had outgrown 2 GB once the chain passed ~39%: it was OOM-killed twice in one morning at 1.74 GB anon-rss, restarting every hour. With 6 GB the box sits at ~1.2 GB used of 5.9 GB with both services running (monerod ~1.0 GB, xmrblocks ~96 MB).

The disk is the real performance limit, not memory. proxmox-tank-1 is a spinning-disk mirror, and xmrblocks says so on startup: "The blockchain is on a rotating drive: this will be very slow, use an SSD if possible". Measured consequences, both of which the role accounts for:

• first start takes ~98 seconds to open the LMDB before it binds, so wait_for allows 300s
• a COLD index page took 68 seconds, while the two requests after it took 0.87s and 0.012s — so the health check allows 90s and its unit 180s. A short timeout there does not detect a slow explorer, it manufactures false DOWNs.

Footprint note: xmrblocks mmaps the LMDB, so most of its apparent size is reclaimable page cache rather than anonymous memory, and --concurrency is held at 2 for the same reason.