Skip to content
KyraLabsPublic

About

nostr relay wip

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

easyrelay

A Nostr relay written in Zig.

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.

What it is

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.

Quick start

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:

easyrelay

That 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 -d

This 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 in

Every 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.

Documentation

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.

Requirements

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.

Contributing

Start with CONTRIBUTING.md. In short:

mise install     # pinned Zig 0.16.0
zig build test

License

MIT. See LICENSE.

About

nostr relay wip

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages