mnr — Protocol & Development Architecture

an RPC network for Monero

The protocol and component design behind Stage 2, the permissionless operator network. Rendered from the architecture document in the code repository with the build plan and internal decisions left out. See the roadmap for the principles in brief.

1. What is being built

A permissionless network in which independent operators run monerod behind a small agent, relayers aggregate many operators into one verified, cached, metered endpoint, and clients (wallets, swap backends, autonomous agents) pay in XMR — either to a relayer for one URL, or, later, directly to operators. The protocol, operator agent, relayer, and client library are open source (AGPL-3.0 for binaries, CC-BY for the spec). The founders participate as the first operators and the reference relayer; they do not own the network.

Design principles, in priority order:

1. Verify, don't trust. Wherever Monero data is self-authenticating (block hashes, tx hashes, header chains), the relayer or client checks it. Trust is used only where verification is impossible (mempool, node info), and there it is replaced by agreement across independent operators.
2. No token, no stake, no slashing. Operators are paid in XMR for verified work; bad work is recorded in a public, cryptographically verifiable fault log that anyone can weigh. Nothing is locked, nothing is confiscated.
3. Stock wallets must work. A wallet must be able to use the network with nothing more than --daemon-address. Direct multi-operator verification is a client-library feature, not a requirement.
4. Hobbyist operators must be able to join in ten minutes with a one-line install, no view key, no public IP if they use Tor.
5. The reference relayer must be replaceable. Everything a relayer knows that others would need (operator directory, fault log, settlement statements) is published in a form another relayer can consume.
6. Both sides of the market are paid from day one. Operators through the pool with a probation lane for newcomers; distributors (wallets, agents, interfaces) through an affiliate share. These are the two THORChain mechanisms that demonstrably bootstrapped an anonymous-operator network, and they are protocol features here, not marketing programmes.

Out of scope, permanently: monero-wallet-rpc methods, mixnets / decoy traffic, any on-chain protocol changes to Monero. Out of scope for the first 18 months: I2P ingress (planned, not built), payment channels of any kind, cross-relayer traffic sharing.

2. Roles, identities and trust boundaries

2.1 Roles

2.2 Identity and keys

• Every operator and relayer has a long-lived Ed25519 identity key. The public key is the identity (op1… / rl1… bech32m encoded). Keys are generated by the binary on first run and stored in the config directory; loss of key = new identity with zero history, which is the only "penalty" the network has, and it is enough.
• Operators sign their directory record. Relayers sign session challenges, settlement statements and fault records. Directory signers sign the directory snapshot.
• Transport identity is separate: clearnet endpoints use TLS with either a public CA cert or a self-signed cert whose SPKI hash is in the directory record (pinning); .onion endpoints get identity from Tor. Both are acceptable; pinning is preferred because it does not depend on the CA system.

2.3 Trust boundaries (who can hurt whom)

3. Protocol specification (v0 — what the spec document will contain)

The spec is a separate, versioned document (mnr-spec). This section fixes the decisions so engineering can start; wire formats are finalised in the spec.

3.1 Directory

Operator record (CBOR, signed by operator key):

{ v: 1, id: <op pubkey>, endpoints: [{kind: "https"|"onion"|"i2p", url, spki?}],
  node: {pruned: bool, restricted: true, version: "0.18.x", chain: "mainnet"|"stagenet"},
  capacity: {rps_light: u32, mbps_stream: u32},         // self-declared, verified by relayers
  payout: [{addr: <monero subaddress or integrated addr>, bps: u16}, …],   // splits must sum to 10000; see "pooled operators" below
  min_payout_xmr: f64,
  accepts_direct: bool,                                  // phase 3
  votes: {param_name: value, …},                         // optional; §3.7
  contact: <optional onion/simplex/matrix string>, ts: unix, sig }

Pooled operators (borrowed from THORChain's pooled nodes): payout is a list of splits, so a person with capital can fund a box that a skilled operator runs, with the split (e.g. operator 2,000 bps, funder 8,000 bps) declared in the signed record. Relayers pay each address its share in the same settlement transaction. No protocol state beyond the record; the two parties' agreement is their own business.

Directory snapshot (CBOR, threshold-signed): {v, seq, ts, min_monerod_version, fork_height?, operators: [record…], relayers: [record…], fault_log_urls: [], sigs: []}. Distributed over: HTTPS mirrors (≥3, different hosts), .onion, and a DNS TXT seed carrying the current mirror list and snapshot hash (like Monero's seed nodes). Snapshot size at 500 operators ≈ 250 KB; refreshed hourly; sequence numbers prevent rollback.

Registration: the agent POSTs its signed record to any directory mirror; the record is queued; a relayer (initially ours) probes the endpoint for correctness (height, restricted RPC, version, TLS pin) and the signer includes it in the next snapshot. There is no fee and no bond. Removal is by the operator (signed tombstone) or by the signers (record omitted; reason published in the fault log).

3.2 Relayer ↔ operator session

1. Relayer opens TLS (pinned) or Tor connection to the agent's endpoint and requests /mnr/v1/session with {relayer_id, nonce_r}.
2. Agent replies {nonce_a}; relayer returns sig_relayer(nonce_a || nonce_r || op_id); agent verifies against the relayer's published key (agent fetches the directory too) or, for unknown relayers, its own allow_unknown_relayers setting (default true, so new relayers can bootstrap; operators may restrict).
3. Agent issues a session id (random 128-bit) valid 24 h; all subsequent RPC requests carry Mnr-Session: <id>. Requests without a valid session hit the agent's public policy: by default deny (private operator), optionally free-tier (small unauthenticated allowance — how public nodes join without changing their habits).
4. Both sides count per-session: light_requests, stream_bytes, errors, first_ts, last_ts. Counters are persisted every 10 s (SQLite) so restarts do not lose more than 10 s.

Metering unit: work units (WU) = light_requests × 1 + stream_MB × 20 (one MB of get_blocks.bin costs an operator roughly what 20 light calls do; the coefficient is a directory-snapshot parameter so it can be tuned network-wide without a release).

3.3 Settlement

• Weekly epoch (Monday 00:00 UTC). For each operator with which the relayer had sessions, the relayer publishes a settlement statement: {relayer_id, op_id, epoch, wu_served, wu_faulted, share, pool_xmr, amount_xmr, txid?, sig}.
• The pool: pool_xmr = op_share × relayer_client_revenue_xmr(epoch) where op_share is the relayer's published rate (reference relayer: 0.60). Each operator's share = wu_served_i / Σ wu_served, with wu_faulted (requests whose responses failed verification) excluded and counted against reputation.
• Amounts below the operator's min_payout_xmr roll over. Payouts are batched into one Monero transaction per epoch (up to 16 outputs per tx; more epochs → more txs). Relayer's monero-wallet-rpc (spend-capable hot wallet with a capped float; the storefront's incoming wallet is view-only and swept to cold) sends them.
• Operators compare wu_served in the statement to their own session counters. The agent exposes GET /mnr/v1/statements showing both numbers side by side; discrepancies > 2% are flagged locally and, optionally, published as a signed dispute record to the fault log. Nothing is automatically enforced; the point is visibility.
• Dev fee: the reference relayer's settlement code adds a line {op_id: <maintainers' key>, share: 0.02} to the pool by default, minus any portion of the pool that went to the relayer's own operators (we do not pay ourselves a fee on ourselves). It is a config flag (dev_fee = 0.02), disclosed in the relayer's directory record, and visible in every statement.
• Affiliate share (borrowed from THORChain's interface fee): a client token may carry an affiliate_id (an Ed25519 key registered in the directory like an operator, with a payout address) set at purchase time by the wallet, agent framework, swap interface or integrator that brought the client. The relayer pays the affiliate 15% of that client's revenue (reference default; a relayer config value) out of its own 40%, in the same weekly settlement, with a signed statement. Self-referral is allowed and harmless — it is merely a discount. The op_share pool is unaffected, so operators never subsidise distribution.
• Probation lane (borrowed from THORChain's churn): each epoch the dispatcher reserves 10% of traffic weight for operators with the least verified history in the last 30 days (new joiners and returners), spread evenly among them, subject to the normal on-tip and fault-rate gates. This guarantees that a new operator earns and is audited from its first week instead of being starved by the ranking. The share is a snapshot parameter (probation_weight).
• op_share band (THORChain's incentive pendulum, deferred): op_share is a snapshot parameter with a permitted band of 0.50–0.70. v1 pins it at 0.60; a later version may move it with network utilisation (scarce supply → higher; abundant supply → lower). Declaring it a parameter now means changing it later is not a protocol break.

3.4 Verification rules (the heart of the network)

The relayer maintains its own header chain: for every height, (hash, prev_hash, timestamp, height) — 32 + 32 + 8 + 8 bytes ≈ 80 B × ~3.5 M blocks ≈ 280 MB on disk, built once from operators by majority and then extended at the tip by agreement. RandomX proof-of-work is not verified (too expensive, and irrelevant: an operator that fabricates a PoW-valid alternate chain is a 51% attacker, which is not our threat model); linkage and majority are.

Fault record (CBOR, signed by relayer): {relayer_id, op_id, ts, method, request_hash, response_hash, expected, got, evidence_url?, sig}. The evidence (request + response blobs) is stored by the relayer for 30 days so anyone can reproduce the check. Fault logs are append-only files served over HTTPS/onion; relayers and mnr-client fetch the logs of relayers they choose to believe (initially the reference relayer's; a relayer can mark others' logs as trusted in config). An operator's fault rate = faults / verified requests over 30 days, decayed; ranking multiplies capacity weight by (1 − fault_rate)^8, so 5% faults roughly halves an operator's traffic and 20% removes them from the pool for practical purposes.

3.5 Client access

Relayer mode (v1): exactly the token scheme from the gateway plan §3.1 — path token or Basic auth, 256-bit, hashed at rest, rotation with grace — but issued by the relayer's storefront. Purchases via invoice page or XMR402: the storefront responds 402 with {amount_xmr, address, memo, expires}; the client pays; on 10 confirmations (or a relayer-chosen lower threshold for small credits) the storefront issues the token. Credits are denominated in WU (same unit as settlement) so that a client's balance and an operator's payout are commensurable. Purchase requests may carry affiliate_id (query parameter on the invoice page, header in the XMR402 flow); it is bound to the token for its lifetime and shown on the client's statement.

Direct mode (phase 3): mnr-client fetches the directory, picks k operators by diversity + fault rate + latency, and performs the verification rules itself. Payment: XMR402 credit purchased from an operator whose accepts_direct is true (the agent gets an optional view-only wallet for this; hobbyists stay relayer-only). Stock wallets never use direct mode; it is for backends, agents and wallet developers who embed the library.

3.6 Caching and policy

Identical to the gateway plan §3.3 (tip−10 immutable rule, SWR 1/5/15 for consensus state, per-tx cache, never cache mempool, method allow-list, per-method timeouts) with one change: cache keys include the verification level (full | sampled | agreed) so that a sampled-verified stream never satisfies a request that asked for full verification.

3.7 Network parameters and work-weighted votes (THORChain's "mimir", without a token)

The directory snapshot carries a small set of network parameters: wu_stream_per_mb (20), op_share (0.60, band 0.50–0.70), probation_weight (0.10), affiliate_default (0.15), min_monerod_version, fork_height, tip_safety_depth (10). Until month 15 the directory signers set them. From then on, an operator may include a votes map in its signed record; when the signers build a snapshot they compute, per parameter, the median of votes weighted by each operator's verified WU over the trailing 90 days (from the published settlement statements of all relayers the signers recognise) and adopt it if at least 40% of network-wide verified WU has voted. Voting weight is work actually served and verified, not capital and not identity — the only Sybil-resistant quantity this network has. Relayers are not obliged to follow the snapshot's op_share, but the reference relayer does, and their published value is visible to operators choosing where to serve.

4. Component design

All core components are Rust (tokio, hyper/axum, rustls). Rationale: epee parsing and hashing on streamed data is CPU-bound and must be memory-safe; one language across agent, relayer and client library; existing crates (monero-serai/monero-rs families) for serialization and hashing; arti for Tor as a later option. TypeScript is used only for the storefront UI and the optional wallet-plugin glue.

4.1 mnr-core (library crate)

Modules: wire (epee binary + JSON-RPC types for the daemon API, hand-verified against monerod 0.18.x fixtures), hash (Keccak-256, block hashing blob, tx-tree hash, pruned tx hash), verify (rules of §3.4 as pure functions over bytes), policy (method table; the single source of truth rendered into docs), directory (record/snapshot types, signing, validation), metering (WU accounting), identity (Ed25519 keys, bech32m ids), settlement (statement types, pool math). No I/O in this crate; it must be fuzzable (cargo fuzz targets for every parser).

4.2 mnr-agent (operator binary)

[ clearnet TLS :443 ] ─┐
[ tor hidden svc    ] ─┼─▶ ingress (axum) ─▶ session auth ─▶ local policy (restricted-only) ─▶ proxy ─▶ monerod 127.0.0.1:18081
[ i2p (later)       ] ─┘        │                 │                          │
                               │                 └── unknown-session policy (deny | free-tier bucket)
                               ├── metering (per-session counters → SQLite, 10 s flush)
                               ├── health (self-probe monerod every 5 s: height, sync, peers, disk)
                               ├── directory client (fetch snapshot hourly; enforce min version; refresh own record daily)
                               └── statements viewer (GET /mnr/v1/statements; compares relayer statements to own counters)

Properties: single static binary (musl), ~10 MB; config is one TOML file; mnr-agent init generates keys, detects monerod, writes config, registers with the directory, and prints the operator id; mnr-agent doctor checks restricted RPC, version, disk, port reachability, Tor status. It does not manage monerod (operators keep their setup) but ships a recommended systemd unit and flags. Memory budget < 100 MB; it must run on the same box as a pruned node on a 4 GB VPS. Streaming responses are proxied without buffering. No view key, no wallet, no payments in v1 — the agent is deliberately boring.

4.3 mnr-relay (relayer binary)

client ─▶ ingress (axum; clearnet + onion) ─▶ auth (token hash → SQLite/Postgres; isolate cache) ─▶ rate limit (governor; per-token bucket + WU balance)
      ─▶ policy (mnr-core::policy) ─▶ cache (in-memory LRU + on-disk immutable store, key includes verification level)
      ─▶ dispatcher (operator pool: rank by on_tip, ema_latency, fault_rate, diversity; retry-once; broadcast for writes)
      ─▶ verifier (mnr-core::verify; streaming for .bin; sample-verify under load) ─▶ response (+ Mnr-* headers)

background tasks: header-chain sync (majority extend at tip; reorg detection → epoch bump of cache)
                  operator prober (every 10 s: get_info + last header; EMA; on_tip)
                  directory sync (hourly) + fault-log publisher (append-only, signed)
                  settlement (weekly: pool math, statements, payout via wallet-rpc hot wallet, dev fee line)
                  metrics (Prometheus /metrics, no per-client labels except hashed prefix in error samples)

State: SQLite for a single-node relayer (our v1); Postgres option for larger relayers. Cache: moka in-memory (bounded, e.g. 2 GB) + rocksdb on-disk store for immutable blocks/txs (bounded by size, LRU eviction). The relayer runs on 2 boxes in active/active behind DNS with health-checked failover in v1 (no Cloudflare required; optional Cloudflare in front for those who want it — off by default in the reference deployment). Each box also runs Tor for the .onion ingress; both boxes publish the same onion via OnionBalance.

4.4 mnr-store (storefront + billing, part of the relayer repo)

Axum routes + a small server-rendered UI: tier/credit purchase, invoice page with live confirmations, XMR402 endpoints, token issuance/rotation, statements for clients (WU balance). Watches a view-only monero-wallet-rpc for incoming payments; sweeps to cold on a schedule. A separate spend-capable monero-wallet-rpc with a capped float (refilled manually from cold) performs operator payouts; it is the one hot key in the system and is treated as such (own box, firewalled, cap = one epoch's pool + 10%).

4.5 mnr-client (library) and integrations

Rust library with C ABI, plus thin TypeScript and Python packages generated from it. Provides: directory fetch + selection, relayer-mode helper (token handling, rotation), direct-mode verified calls (phase 3), XMR402 purchase flow. A local proxy mode (mnr-client proxy --listen 127.0.0.1:18089) lets stock wallets use direct mode without embedding the library — the wallet points at localhost and the proxy does selection and verification. This is how Feather/Cake/CLI users get direct mode without those projects changing anything.

4.6 mnr-directory

Signer CLI (mnr-dir sign, mnr-dir add, mnr-dir tombstone) producing snapshots; a static-file publisher for mirrors; a registration intake (small axum service) that queues records for probing. Threshold signing uses FROST (Ed25519) via an existing Rust crate when the signer set expands (month 15); until then a single key with an offline backup.

4.7 mnr-sim (test network harness)

Docker-compose bringing up N stagenet monerod + agents, one relayer, a fault injector (serve wrong block, lag height, drop streams, return alt-chain), synthetic clients (wallet-sync replay, get_info storm, broadcast). Used in CI nightly and for every release. This is not optional; a network protocol without a simulator will ship bugs that only appear with strangers' nodes.

4.8 Repository layout

mnr/
├── spec/                 protocol spec (markdown, versioned; wire formats, verification rules, settlement)
├── crates/core/          mnr-core
├── crates/agent/         mnr-agent
├── crates/relay/         mnr-relay (+ store/ module)
├── crates/client/        mnr-client (+ ffi/, bindings/ts, bindings/py)
├── crates/directory/     mnr-directory
├── sim/                  mnr-sim docker harness, fault injector, k6/replay clients
├── deploy/               ansible for our operators + relayer boxes; systemd units; Tor/OnionBalance config
├── docs/                 operator guide, relayer guide, client guide, wallet how-tos, generated method table
└── .github/              CI: fmt, clippy, tests, fuzz smoke, sim nightly, release builds (musl, arm64)

4.9 Hostnames