Status: pre-alpha. It speaks NIP-01 over WebSocket — publishing, subscriptions, live
delivery, full event validation, kind semantics — with NIP-09 deletion, NIP-11, NIP-40
expiration, NIP-42 authentication, NIP-65 relay lists and NIP-70 protected events, and keeps its
events in LMDB under ./data. Rate limits, backpressure, admission policy, metrics and graceful
shutdown are in place; the first release, which publishes the binaries and the container image,
has not been cut. See the roadmap for what is being built and in which order.
easyrelay has three goals, in this order. Where they conflict, the earlier one wins.
It works. Full NIP-01 conformance, correct handling of every kind class, and the NIPs a serious relay is expected to speak — up to and including NIP-77 set reconciliation. A relay that computes event ids from a non-canonical serialization is silently unusable no matter how fast it is.
It is fast. An embedded LMDB store with hand-built indexes, zero-copy reads, and query cost bounded by the requested page size rather than by how much history the relay holds. No garbage collector, no unbounded queues, and limits on everything a client can grow.
It is trivial to run. Running easyrelay with no arguments and no configuration file gives
you a working relay. There is no database to create, no system package to install, no runtime
to provision. Getting a public relay onto the internet with TLS is one command. This is the
goal the name refers to, and it is treated as a feature with its own tests, not as a side
effect of shipping a static binary.
It is built on top of zig-nostr/nostr, which supplies
the protocol primitives (event model, canonical serialization, BIP-340 Schnorr verification via
a vendored libsecp256k1, filter matching) and a zero-copy LMDB event store. easyrelay adds
what a relay needs on top of a protocol library: the WebSocket server, the subscription engine,
the admission policy layer, and the operational surface.
Partly available. Running the relay built from source works today, and so does the compose file below once its image is published. Neither the binaries nor the image exist until the first release is cut; the roadmap says what that release still has to prove.
Run it:
easyrelayThat is the whole setup. The relay listens on ws://127.0.0.1:7777, creates its data directory
on first start, prints the URL it is serving, and is ready for a client. No configuration file
is required, and no argument is mandatory.
Put it on the internet with TLS:
curl -LO https://github.com/KyraLabs/easyrelay/raw/main/deploy/docker-compose.yml
RELAY_DOMAIN=relay.example.com docker compose up -dThis runs easyrelay behind Caddy, which obtains and renews the certificate on its own. See operations.md for the systemd equivalent and for tuning.
Change something:
easyrelay init > easyrelay.zon # a commented file with every default filled inEvery setting has a working default, so the file only needs the lines you actually want to change. Configuration is validated at startup: an unknown key or an impossible value stops the relay with a message naming the key, never a silently ignored line.
Start here:
| Document | Contents |
|---|---|
| Overview | Vision, goals, non-goals, who this is for |
| Roadmap | Implementation phases with exit criteria |
| Architecture | Layers, threading model, data flow, repository layout |
Reference:
| Document | Contents |
|---|---|
| Protocol | Wire behaviour: messages, filters, kind semantics, error prefixes |
| Storage | Data model, indexes, retention, deletion, expiration |
| NIP coverage | Per-NIP status and the phase that delivers it |
| Configuration | Configuration reference |
| Operations | Deployment, TLS, backup, metrics, tuning |
| Testing | Test strategy, conformance, fuzzing, benchmarks |
| Development | Toolchain setup and build commands |
| Decisions | Architecture Decision Records |
docs/research/ holds background research written before the project started. It is dated,
written in Spanish, and is not maintained as project documentation.
To run it: nothing. A prebuilt binary has no dependencies — no database server, no runtime,
no system packages. LMDB and libsecp256k1 are compiled into it. The compose path additionally
needs a container runtime.
To build it: Zig 0.16.0, pinned in .zigversion and installable with
mise. Still no system packages: the dependencies are vendored and
compiled from source, and Zig ships its own C compiler. See
development.md.
Start with CONTRIBUTING.md. In short:
mise install # pinned Zig 0.16.0
zig build test- Development guide — commands, layout, code conventions
- Code of Conduct
- Security policy — report vulnerabilities privately, never as an issue
- Changelog
MIT. See LICENSE.