Monero RPC Gateway — Development Plan (v1)

0. How this plan was derived

The three reviews disagree on tone but agree on substance. Every item below was raised by at least two reviewers and is treated as a binding decision for v1:

Where reviewers offered different specifics (e.g. tip safety margin of 10 vs "10+"), this plan picks one value and states it.

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.

6. Repository layout

monero-rpc-gateway/
├── apps/edge/                 Hono Worker (TypeScript, wrangler)
│   ├── src/index.ts           router: /v1/:token/*, /v1/* (basic-auth)
│   ├── src/auth.ts            token parse, hash, KV/DO lookup, isolate cache
│   ├── src/ratelimit.ts       local token bucket + batched DO sync
│   ├── src/methods.ts         THE method policy table (§3.3)
│   ├── src/cache.ts           immutable + SWR helpers, epoch keys, single-flight
│   ├── src/dispatch.ts        ranking, retry-once, header allow-list, streaming
│   ├── src/broadcast.ts       send_raw_transaction fan-out
│   ├── src/do/TenantDO.ts     quota, token hashes, validity
│   ├── src/do/HealthProber.ts alarm loop, quorum, reorg detection
│   ├── src/do/GatewayState.ts latest health snapshot (strongly consistent read)
│   ├── src/metrics.ts         Analytics Engine writes
│   ├── test/                  vitest + miniflare; fixtures of real monerod responses
│   └── wrangler.toml
├── services/billing/          invoice API, wallet-rpc watcher, XMR402 endpoints, provisioning client
├── services/node-agent/       /healthz, disk/sync checks (runs on each node)
├── infra/ansible/             node provisioning, hardening, cloudflared, systemd units
├── infra/cloudflare/          terraform: zone, WAF rules, tunnel, access policies, KV/DO/R2 bindings
├── docs/                      this plan, ops doc, API reference (generated from methods.ts)
└── tools/loadtest/            k6 scripts: wallet-sync replay, get_info storm, tx broadcast

7. Milestones and schedule

Assumes one senior full-stack engineer plus one part-time infra/Monero engineer. Weeks are calendar weeks starting the week of 2026-09-07.

Phase 2 (post-launch, sequenced by customer pull, not by the diagram):

1. Tor bridge: tor + haproxy on a fourth box behind a tunnel; Tor upstream pool as Tier 3 failover with 8 s timeouts; optional .onion ingress for the gateway itself (separate from Cloudflare).
2. Public status page: static site (Cloudflare Pages or GitHub Pages) fed by the prober snapshot; 30/90-day uptime; webhooks for Business tenants. No 99.999% SLO claim.
3. R2 cold-range accelerator for get_blocks.bin: only if node bandwidth or IOPS becomes the bottleneck; requires an epee response assembler and a finality rule (export at tip − 720). Treat as its own design doc.
4. Sovereign tier: dedicated node pair per tenant, sharded quota DOs, custom SLA.
5. Stripe / fiat: only when a specific enterprise customer requires an invoice in fiat.
6. Rust or Wasm hot path: only if Worker CPU time becomes a measured cost driver.

8. Testing and acceptance

Definition of done for v1: all M0–M6 exit criteria met; the tier table in the Ops doc matches wrangler.toml tier config byte-for-byte (checked by a CI test); measured cost per 1M requests recorded; two dogfood tenants live for 14 days.

9. Cost model (line items, not a rounded total)

Prices from Cloudflare's published Workers/DO/KV/R2 rates (September 2026) and current Hetzner pricing after the June-2026 adjustment. Scenario: 100 M edge requests/month, 60% cache-hit, 3 ms average CPU per request, quota sync every 100 miss-requests, 20 paying tenants.

Sensitivity: every additional 100 M edge requests adds ≈ $35 (requests + CPU). A fourth node adds ≈ $50–75. The old "$77 / 98% margin" figure is retired; margin is computed in the Ops doc from these lines against the reconciled tier table.

Capacity ceiling for the 3-node mesh (to be replaced by measured numbers at M6): light JSON-RPC ≈ 300–500 rps sustained per full node before p99 degrades; get_blocks.bin ≈ 20–30 concurrent syncing wallets per node before disk IOPS is the limit. That is the input to the quota table in the Ops doc, not the other way round.

10. Risks and mitigations

11. Open decisions (need an owner, not a reviewer)

1. Domain and brand name confirmation ("Monero RPC Gateway" as product; domain TBD).
2. Provider choice for node-b and node-c (OVH vs Vultr vs Latitude) — decide by NVMe IOPS and ASN diversity, not price alone.
3. Whether Free tier survives launch or becomes a zero-amount 7-day trial.
4. Business SLA number: this plan proposes 99.9% (see Ops doc) instead of the original 99.95%; confirm.
5. Language for the Basic-auth tenant id (random id vs derived from token hash prefix).

Sources for pricing facts used in §4 and §9: Cloudflare Workers pricing, Monero blockchain size 2026 (Monerica), Hetzner price adjustment June 2026.