Mekhala - เมขลา ⚡️

A private, stateless Nostr relay optimized for Nostr Wallet Connect (NIP-47) on Cloudflare Workers.

According to legend, the phenomena of lightning and thunder are produced by the flashing of Manimekhala's crystal ball.

---

📖 Overview

Mekhala is a specialized, ephemeral Nostr relay built in Rust and compiled to WebAssembly. It acts as a private, zero-persistence communication bridge between Lightning wallet applications (e.g. Alby, Amethyst) and your wallet node:

• 100% Stateless: No event history or database storage. All events are routed instantly in-memory.
• WebSocket Hibernation: Uses Cloudflare Durable Objects to hibernate idle connections, waking up seamlessly when new events arrive to save resources.
• Strictly Specialized: Only routes NWC-related event kinds (13194, 23194-23197). Social and generic Nostr events are rejected.

---

📦 Quick Setup

1. Fork & Deploy:
   • Fork this repository to your GitHub account.
   • Connect it to your Cloudflare Dashboard via Workers & Pages -> Create application -> Connect to Git and deploy.
2. Configure Private Path:
   • Under your Worker's Settings -> Variables and Secrets, add a Secret named RELAY_SECRET.
   • Set it to a long, secure, unique path identifier.
3. Connect Your Wallet:
   • Your Relay URL: wss://your-worker.workers.dev/<your-secret-path>

Warning

Lightning Address Bridge (Experimental): The feature to bridge Lightning Addresses (e.g., you@domain.com) to NWC is highly experimental, under development, and not yet ready for production or general use.

---

⚙️ Configuration & Limits

Configurable via wrangler.toml or environment variables:

Variable	Default	Description
RELAY_SECRET	None	Optional secret path parameter for private routing.
WALLET_REGION	apac	Physical DO location (apac, weur, wnam).
MAX_CONNECTIONS	100	Max concurrent WebSocket connections per DO.
MAX_CONTENT_LENGTH	65536	Max Nostr event size in bytes (16KB to 64KB recommended).

---

🛠 For Developers

Common Commands

• Build WASM: ./scripts/build.sh (Requires Rust + wasm32 target + worker-build)
• Local Dev: npx wrangler dev (Runs locally on port 8787)
• Unit Tests: cargo test
• Integration Tests: ./scripts/test.sh (Runs E2E compilation, DO setup, and Node.js checks)

Coding Standards

Mekhala compiles with panic = "abort". To prevent isolates from crashing:

• No panics: Never use unwrap() or expect(). Handle errors with ? or match.
• Safe indexing: Use .get() for slice/array access instead of bracket notation.
• Storage state: Every subscription update must call sync() to ensure active filters survive DO hibernation.

---

📄 License

Mekhala is open-source software under the MIT License.