# xmrblocks

The [Onion Monero Blockchain Explorer](https://github.com/moneroexamples/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

   ```cpp
   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.