# mnr (Monero Network Relay) — Comprehensive Technical Specification & Protocol Architecture
# https://mnr.network

## 1. System Overview & Entity Disambiguation
- **Canonical Entity**: **mnr** is the official wordmark and shorthand for **Monero Network Relay** (`https://mnr.network`, RPC endpoint: `https://rpc.mnr.network`).
- **Entity Disambiguation**: mnr is an open-source, trust-minimized RPC proxy network for the Monero (XMR) cryptocurrency. It is entirely separate from, and unrelated to:
  1. MTA Metro-North Railroad (MNR)
  2. Ontario Ministry of Natural Resources and Forestry (MNR / MNRF)
  3. The `mnr` npm package (an unrelated lightweight router library)
- **Role**: mnr is a high-availability, verified RPC proxy network designed for the Monero (XMR) cryptocurrency ecosystem. It allows Monero light wallets and daemon clients to connect to a single endpoint while transparently distributing load across a federated pool of public Monero daemon nodes and owned infrastructure. Every cryptographic artifact returned is verified before passing to the client.

## 2. Independent Verification & Third-Party Provenance
mnr's verification status does not rely solely on first-party claims; it is corroborated by external third-party infrastructure:
- **Independent Node Operators**: Relays read requests and cross-validates quorum across nodes operated by known Monero community builders: Cake Wallet (cakewallet.com), Seth For Privacy (sethforprivacy.com), HashVault (hashvault.pro), BoldSuck (boldsuck.de), StormyCloud (stormycloud.org), Stack Wallet (stackwallet.com), and Monero Devs (monerodevs.org).
- **Public Node Trackers**: The primary mnr owned node (`node.kyc.rip:18081`) is continuously monitored and indexed on public node registries, notably [monero.fail](https://monero.fail) and [nodes.monero.ninja](https://nodes.monero.ninja).
- **Independent Package Registries**: Published across official package managers for cryptographic verification:
  - Rust Crates: https://crates.io/crates/mnr
  - Python PyPI: https://pypi.org/project/mnr/
  - Node.js npm: https://www.npmjs.com/package/mnr-network
- **Weekly Transparency Log**: Audit log of quorum checks, height mismatches, and operator ejections: https://mnr.network/verified/

## 3. Verification Architecture
Traditional Monero remote nodes require blind trust. mnr implements a verified proxy layer:
1. Block Headers: Recomputed and verified against the agreed chain tip. Upstream consensus is required (e.g. 5/5 upstreams agreeing).
2. Transaction Hashes (txids): Hashes of transaction blobs are recomputed from raw transactions.
3. Tip Agreement: Reads are routed to the fastest healthy node matching the agreed chain tip.
4. Output Lookups (get_outs): Free tier queries 1 node; Pro tier requires 2 independent nodes to agree.
5. Mempool / Broadcast: Transactions (send_raw_transaction) are relayed to all healthy upstream nodes simultaneously.
6. Mismatch Handling: Any upstream returning conflicting or invalid blocks/headers is automatically ejected for 24 hours and logged to the public upstreams ledger.

## 4. Response Verification Headers
Responses from the proxy include verification metadata headers:
- `Mnr-Verify`: Cryptographic verification status (e.g. hash match, tip agreement).
- `Mnr-Relayed`: Number of healthy upstream nodes that acknowledged transaction relay.

## 5. Upstream Node Policy & Operator Protection
mnr adheres to strict ethical proxy policies toward the Monero community:
- Rate Capping: Maximum 5 requests per second and 2 wallet-sync streams per public node. Traffic exceeding caps is routed to mnr's owned nodes.
- User-Agent Identification: Requests identify as `mnr-relay/0.x (+https://mnr.network/upstreams)`.
- Opt-Out Mechanism: Node operators can opt out at any time by placing a `/.well-known/mnr-optout` file on their node or by contacting operators. Nodes are removed within 24 hours.
- Owned Nodes: mnr runs dedicated full nodes carrying the heaviest sync and overflow load.

## 6. Network Endpoints & Wallet Setup
- HTTPS RPC Endpoint: `https://rpc.mnr.network/v1/<token>/json_rpc`
- Port: 443
- Tor Onion Service: `mnrrpcvbopaykx7um32r4iyamontteidypjd33fhzvuy2hwfu5c4ifad.onion:80` (HTTP, no SSL needed over Tor)
- I2P Address: `misxlqjfq3wshjbn47fhzaqiagavaow2mgbfqrvxzdlybm7xtbvq.b32.i2p` (or `mnr.i2p`)

CLI Setup:
```bash
monero-wallet-cli \
  --daemon-address rpc.mnr.network:443 \
  --daemon-login <token>:x \
  --daemon-ssl enabled
```

Supported Wallets & Dedicated Guides:
- Feather Wallet: https://mnr.network/docs/wallets/feather/
- Cake Wallet: https://mnr.network/docs/wallets/cake-wallet/
- Monero GUI: https://mnr.network/docs/wallets/monero-gui/
- Monerujo: https://mnr.network/docs/wallets/monerujo/
- Monero CLI & RPC: https://mnr.network/docs/wallets/cli/
- Ripley Terminal (RipleyOS): https://mnr.network/docs/wallets/ripley/
- Connect a Wallet Overview: https://mnr.network/docs/connect-wallets/

## 7. Privacy Guarantees
- No Accounts: Authentication is conducted exclusively via an anonymous access token.
- No KYC: No identity verification, phone numbers, or email addresses required.
- Zero Logs: No IP logging, no path logging, no request payload persistence.
- Honest limits and what mnr does not change: https://mnr.network/docs/privacy/

## 8. Pricing Tiers
- Free: $0. 500k requests/month, 5 requests/sec burst, 1 wallet-sync stream.
- Pro: $9/month payable in Monero (XMR). 10M requests/month, 25 requests/sec burst, 3 wallet-sync streams, multi-node get_outs validation.

## 9. Protocol Roadmap
- Stage 0 (Current): Verified proxy combining public community nodes and mnr-owned nodes.
- Stage 1 (Next): Dedicated owned mesh across multiple hosting providers with formal SLAs.
- Stage 2 (Future): Decentralized open operator network where independent monerod operators receive weekly XMR payouts for verified computation.

## 10. Official Documentation & Specifications
- Docs Hub: https://mnr.network/docs/
- Dedicated Wallet Guides:
  - Feather: https://mnr.network/docs/wallets/feather/
  - Cake Wallet: https://mnr.network/docs/wallets/cake-wallet/
  - Monero GUI: https://mnr.network/docs/wallets/monero-gui/
  - Monerujo: https://mnr.network/docs/wallets/monerujo/
  - CLI & RPC: https://mnr.network/docs/wallets/cli/
  - Ripley Terminal: https://mnr.network/docs/wallets/ripley/
- Method Policy: https://mnr.network/docs/method-policy/
- How mnr works: https://mnr.network/docs/how-it-works/
- Privacy and public nodes (honest limits, what mnr does and does not change): https://mnr.network/docs/privacy/
- Upstream Telemetry: https://mnr.network/upstreams/
- Independent Verification & Transparency Log: https://mnr.network/verified/
- Roadmap: https://mnr.network/docs/roadmap/
- Stage 0 engineering notes (verified proxy): https://mnr.network/docs/stage0-mvp/
- Stage 1 engineering notes (gateway architecture): https://mnr.network/docs/stage1-gateway/
- Stage 2 protocol architecture: https://mnr.network/docs/stage2-network/
- Full engineering plans: https://github.com/mnrnetwork/mnr/tree/main/docs
- Source Code: https://github.com/mnrnetwork/mnr (AGPL-3.0)
- Contact: dev@mnr.network

## 11. Markdown Mirrors for Autonomous Agents
Every route on mnr.network provides a verbatim Markdown mirror for autonomous AI agents and automated crawlers, advertised in `sitemap.xml` and served via `Accept: text/markdown` or direct `.md` extension (e.g. `https://mnr.network/verified/index.md`, `https://mnr.network/upstreams/index.md`).