Monero RPC Gateway — Development Plan (v1)

The engineering notes behind Stage 1, the owned mesh with an SLA. Rendered from the plan in the code repository with milestones, cost model and internal decisions left out. See the roadmap for where this sits.

1. Product definition (one paragraph, one boundary)

Monero RPC Gateway is a paid, authenticated HTTPS endpoint that speaks the monerod daemon JSON-RPC and binary (.bin) API. Behind it sit gateway-owned Monero nodes on separate providers; the edge validates height agreement across them, caches what is safe to cache, broadcasts transactions to all healthy nodes, and fails over automatically. Customers point a stock wallet, a swap backend, or an agent at one URL and stop running monerod.

Scope boundary (state it on the website and in the ToS):

• In scope: monerod daemon RPC (/json_rpc, legacy /get_* endpoints, /get_blocks.bin, /send_raw_transaction, /get_transactions, /get_outs.bin, etc.).
• Out of scope: monero-wallet-rpc. It is stateful, holds view/spend keys, and cannot be multiplexed at an edge. Customers run their own wallet software (CLI/GUI/monero-wallet-rpc/monero-lws) and point it at the gateway as its daemon.

2. Target architecture (v1)

                      ┌──────────────────────────────────────────────────────────┐
 Wallet / agent /     │  Cloudflare edge (Anycast)                               │
 swap backend  ─────▶ │  Hono Worker "gateway-edge"                              │
 https://rpc.<dom>/   │   1. auth: path token /v1/<tok>/…  or Basic-auth         │
   v1/<tok>/json_rpc  │   2. rate limit: isolate-local token bucket              │
                      │      + batched quota sync to tenant DO (miss path only)  │
                      │   3. classify method → cache / swr / passthrough / bcast │
                      │   4. dispatch to node(s) via Cloudflare Tunnel           │
                      │   5. quorum check on response (per-method rule)          │
                      └───────────────┬──────────────────────────────────────────┘
                                      │ Cloudflare Tunnel (cloudflared on each node)
              ┌───────────────────────┼───────────────────────┐
              ▼                       ▼                       ▼
     ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
     │ node-a (full)   │    │ node-b (full)   │    │ node-c (pruned) │
     │ Hetzner, DE     │    │ OVH, FR/CA      │    │ Vultr/other, NL │
     │ monerod --rpc-  │    │ monerod         │    │ monerod --prune │
     │ restricted-rpc  │    │                 │    │                 │
     └─────────────────┘    └─────────────────┘    └─────────────────┘
              ▲                       ▲                       ▲
              └───────────────────────┼───────────────────────┘
                     ┌────────────────┴─────────────────┐
                     │ Durable Object "HealthProber"    │
                     │  alarm() every 10 s               │
                     │  get_info + get_last_block_header │
                     │  EMA latency, tip agreement       │
                     │  writes snapshot → KV + DO state  │
                     └───────────────────────────────────┘

 Billing (separate box, never on the request path):
   monero-wallet-rpc (view-only) ── watches subaddresses ── "billing" service
   ── XMR402 invoice API ── provisions tenant in TenantDO + KV

What is deliberately absent in v1: the Rust routing tier, Tor upstreams, the R2 block archive, the public status-page product, PagerDuty, Stripe, Bot Fight Mode, "speculative execution", any 99.99% SLA.

3. Request path specification

3.1 Authentication

3.2 Rate limiting

Two layers so that the Durable Object is never on the hot path:

1. Burst (req/s): isolate-local token bucket keyed by tenant id, refilled at tier.burst_rps, capacity 2 × burst_rps. Because Cloudflare runs many isolates per colo, the effective global burst is somewhat higher than the nominal number; this is acceptable and stated in the tier table as "nominal".
2. Daily quota: the Worker increments an in-memory counter and flushes it to TenantDO.consume(n) every 100 requests or 1 s, whichever first (ctx.waitUntil). DO returns {remaining, reset_at}; the Worker caches that and locally refuses once remaining ≤ 0. Overshoot is bounded by (isolates × 100) requests, which is far below 1% of any paid quota.
3. Cache hits do not touch the DO at all; they only decrement the local counters. Quota counts all requests, cached or not (that is what the customer buys).
4. Over-limit responses: HTTP 429, Retry-After, JSON-RPC error -32005.
5. Sovereign tier: quota bookkeeping is sharded across N = ceil(burst_rps / 100) DO shards (TenantDO:<id>:<shard>); v1 ships the sharding code path but only Sovereign tenants use it.

3.3 Method classification and per-method policy

This table is the single source of truth. It lives in code as src/methods.ts and is rendered into the docs from there.

Quorum tip = the highest height reported by a majority (≥2 of 3) of nodes whose top_block_hash agrees at that height, as computed by the prober (§3.5). If no majority exists, the gateway enters degraded mode: SWR/IMMUTABLE classes are served from the node with the highest height, cache writes for IMMUTABLE are suspended, and an incident is opened (Ops doc §7).

3.4 Dispatch and failover

• Node ranking = healthy nodes sorted by (on_quorum_tip desc, ema_latency asc). The Worker reads the ranking from the in-isolate copy of the health snapshot (refreshed from KV every 10 s; KV lag is acceptable because the prober also writes the snapshot into a GatewayState DO that the Worker consults if the KV copy is older than 30 s).
• Read requests go to rank 1. On connection error, 5xx, or timeout, retry once on rank 2. No third attempt (bounded latency).
• Connection to nodes: fetch() to https://node-<x>.<internal-domain> fronted by Cloudflare Tunnel, with a Cloudflare Access service token in headers so nodes are unreachable without it. monerod binds RPC to 127.0.0.1:18081 only; cloudflared runs on the same host.
• Requests carry no client IP, no X-Forwarded-For, no CF-Connecting-IP to nodes (headers stripped by allow-list).

3.5 Health prober (Durable Object alarm loop)

class HealthProber extends DurableObject {
  alarm():  for each node in parallel:
              t0; get_info (timeout 2 s); get_last_block_header
              record rtt, height, top_block_hash, synchronized, busy_syncing, status
            compute quorum_tip, per-node on_tip, ema_latency (alpha 0.3)
            detect reorg: if quorum top_block_hash at height h != last snapshot hash at h
              → for depth d = 1..20: if hash(h-d) changed, purge cache for heights > h-d
                (cache purge = bump the `epoch` prefix in IMMUTABLE cache keys; cheap)
            write snapshot → this.state.storage, KV "health:snapshot", GatewayState DO
            setAlarm(now + 10 s)
}

• Runs in one DO; a Cron Trigger (1 min) exists only to re-arm the alarm if it ever dies.
• Snapshot schema is versioned; the Worker refuses snapshots older than 60 s and falls back to "all nodes healthy, round-robin" plus a loud metric.

3.6 Logging policy (replaces "zero-log")

Marketing phrase to use: "No application-level request logging, no accounts, no KYC." Not "zero-log", not "zero-knowledge".

4. Node infrastructure

5. Billing and provisioning service

Runs on a small separate VPS ("billing box"), never on the request path. Ships as services/billing/ (TypeScript/Node or Rust; pick TypeScript to share types with the Worker).

Components: monero-wallet-rpc (view-only wallet, spend key offline), billing-api (HTTP), Postgres or SQLite for invoices and tenants, a Cloudflare API client to write KV and call TenantDO via an internal Worker route protected by a service token.

Provisioning sequence:

Client (web form or XMR402 agent)                Billing API                  wallet-rpc         Edge (KV + TenantDO)
  │  POST /invoices {tier, months}                    │                             │                    │
  │ ────────────────────────────────────────────────▶ │  create_address (subaddr)   │                    │
  │                                                   │ ───────────────────────────▶│                    │
  │ ◀──── {invoice_id, address, amount_xmr,           │ ◀───────────────────────────│                    │
  │        expires_at, xmr402 headers}                │                             │                    │
  │  pays on-chain                                    │  poll get_transfers (10 s)  │                    │
  │                                                   │ ───────────────────────────▶│                    │
  │                                                   │  state: seen(0-conf) → confirmed(10 conf)        │
  │                                                   │  on confirmed: create/extend tenant             │
  │                                                   │  ─────────────── put KV tok:<hash>; DO.provision ─▶
  │  GET /invoices/{id}  (or webhook / XMR402 402→200)│  read-back KV from same colo, then respond       │
  │ ◀──── {status: active, rpc_url, valid_until}      │                             │                    │

Rules: price is quoted in XMR at invoice time, locked for 30 min; underpayment by <2% is accepted, otherwise the invoice stays open and shows the remaining amount; renewals reuse the tenant's persistent subaddress and apply valid_until = max(valid_until, now) + months; Free tier is provisioned instantly without an invoice; no device fingerprinting or per-person cap is attempted (no KYC means Free-tier abuse is limited by quota, not identity — see Ops doc §3.1 for the trial fallback). XMR402: the billing API implements the 402 challenge/receipt flow for agents, backed by the same invoice table, so "XMR402" is a payment rail, not a tier feature. Stripe is out of v1.

0-conf provisioning is not done for paid tiers; 10 confirmations (~20 min) is the activation point, with the invoice page showing live confirmation count. This keeps the gateway's own billing consistent with the 0-conf risk guidance we give customers.

8. Testing and acceptance