= realy.lol
:toc:
:note-caption: note 👉

image:https://img.shields.io/badge/godoc-documentation-blue.svg[Documentation,link=https://pkg.go.dev/realy.lol]
image:https://img.shields.io/badge/donate-geyser_crowdfunding_project_page-orange.svg[Support this project,link=https://geyser.fund/project/realy]
zap me: ⚡️mleku@getalby.com

image:./realy.png[realy.png]

nostr relay built from a heavily modified fork of https://github.com/nbd-wtf/go-nostr[nbd-wtf/go-nostr]
and https://github.com/fiatjaf/relayer[fiatjaf/relayer] aimed at maximum performance, simplicity and memory efficiency.

== Features

* new HTTP REST API available in addition to standard websocket access, simplifying writing applications and tools, and building a standard API method set for future extensions for more flexible features
* a lot of other bits and pieces accumulated from nearly 8 years of working with Go, logging and run control, XDG user data directories (windows, mac, linux, android)
* a cleaned up and unified fork of the btcd/dcred BIP-340 signatures, including the use of bitcoin core's BIP-340 implementation (more than 4x faster than btcd) (todo: ECDH from the C library tbd)
* AVX/AVX2 optimized SHA256 and SIMD hex encoder
* https://github.com/bitcoin/secp256k1[libsecp256k1]-enabled signature and signature verification (see link:p256k/README.md[here])
* efficient, mutable byte slice based hash/pubkey/signature encoding in memory (zero allocation decode from wire, can tolerate whitespace, at a speed penalty)
* custom badger based event store with an optional garbage collector that deletes least recent once the store exceeds a specified size access, and data encoded using a more space efficient format based on the nostr canonical json array event form
* link:cmd/vainstr[vainstr] vanity npub generator that can mine a 5 letter suffix in around 15 minutes on a 6 core Ryzen 5 processor using the CGO bitcoin core signature library
* reverse proxy tool link:cmd/lerproxy[lerproxy] with support for Go vanity imports and https://github.com/nostr-protocol/nips/blob/master/05.md[nip-05] npub DNS verification and own TLS certificates
* link:https://github.com/nostr-protocol/nips/blob/master/98.md[nip-98] implementation with new expiring variant for vanilla HTTP tools and browsers.

== Configuration

=== Authentication for Admin

Authentication is required to read and write to the endpoints tagged "admin" in the `/api` endpoint that you must use some other tool that can do `cURL` style requests, or you can use the ones i created that are very bare minimal:

- `cmd/nauth` contains a tool that requires the environment variable `NOSTR_SECRET_KEY` to have your nsec or hex secret key, and

- `cmd/nurl` is a simple `cURL` like tool limited to only printing responses from GET, or if you put a filename after the URL, it pushes it with a POST. This can be used to read and write from the API for all endpoints you can see when you go to `/api` on a running instance. It is not featureful because there is a planned web UI that replaces what is currently available with one that can do nostr `NIP-98` http authentication which will be the preferred way (and only advanced way) to access the configuration.

=== Configuration API

There is very minimal configuration in the main runtime, because it has been deliberately minimized  to make it less work to administer.

The HTTP endpoint at `/api` has documentation that you can see and every item in it is explained briefly.

Everything that can and should be dynamically configured is part of the `/api/configuration` data, which you set with `/api/configuration/set` and read with the `/api/configuration/get`

This currently includes the following settings:

    admins
    Type:[ "array", "null" ] string[]
    required
    list of npubs that have admin access

    allow_list
    Type:[ "array", "null" ] string[]
    required
    List of allowed IP addresses

    app_name
    Type:string
    default:
    realy
    required
    application name

    auth_required
    Type:boolean
    default:
    false
    required
    authentication is required for read and write

    block_list
    Type:[ "array", "null" ] string[]
    required
    list of IP addresses that will be ignored

    db_log_level
    Type:string
    default:
    info
    required
    database log level

    log_level
    Type:string
    required
    Log level

    log_timestamp
    Type:boolean
    default:
    false
    required
    print log timestamp

    owners
    Type:[ "array", "null" ] string[]
    required
    list of owner npubs whose follow lists set the whitelisted users and enables auth implicitly for all writes

    public_readable
    Type:boolean
    default:
    false
    required
    authentication is relaxed for read except privileged events

This list may get out of sync with this documentation because simply running the relay you can access these endpoints. They are the original "source of truth" for how you can configure the relay, other than that, there is the environment variables, which you can get by running the relay and using the command `env` and get a result like this:

    #!/usr/bin/env bash
    export APP_NAME=realy
    export BINARY=false
    export LISTEN=0.0.0.0
    export PORT=3334
    export PPROF=false
    export SUPERUSER=npub1fjqqy4a93z5zsjwsfxqhc2764kvykfdyttvldkkkdera8dr78vhsmmleku

This output is configured as a shell script, because that is the simplest way to use it. This is standardised and if you run this script, and then run the relay in a normal shell environment, you will get it running the configuration you want.

The Binary option is highly recommended to be set to true, because the binary database encoding is about 3x faster than the already fast JSON encoding that is default as with the setting shown above.

The rest should be self-explanatory, except for `SUPERUSER` which sets a static npub that you can't change with the `/api/configuration/*` endpoints, and that configuration refuses to allow no `admins` to be set, anyway.

== Building

If you just want to make it run from source, you should check out a tagged version.

The commits on these tags will explain what state the commit is at.

In general, the most stable versions are new minor tags, eg v1.2.0 or v1.23.0, and minor patch versions may not be stable and occasionally may not compile (not very often).

Go 1.24 or better is recommended.
Go 1.23.1 is minimum required.

== Repository Policy

In general, the main `dev` branch will build, but occasionally may not.
It is where new commits are added once they are working, mostly, and allows people to easily see ongoing activity.

WARNING: IT IS NOT GUARANTEED TO BE STABLE... but it is getting there.

Use tags to pin to a specific version.
Tags are in standard Go semver pattern `vX.X.X`

== CGO and secp256k1 signatures library

By default, Go will usually be configured with `CGO_ENABLED=1`.
This selects the use of the C library from bitcoin core, which does signatures and verifications much faster (4x and better) but complicates the build process as you have to install the library beforehand.
There is instructions in link:p256k/README.md[p256k/README.md] for doing this.

=== Disabling CGO

In order to disable the use of this, you must set the environment variable `CGO_ENABLED=0` and it the Go compiler will automatically revert to using the btcec based secp256k1 signatures library.

----
export CGO_ENABLED=0
cd cmd/realy
go build .
----

This will build the binary and place it in cmd/realy and then you can move it where you like.

=== Static build

To produce a static binary, whether you use the CGO secp256k1 or disable CGO as above:

----
go build --ldflags '-extldflags "-static"' -o ~/bin/realy ./cmd/realy/.
----

will place it into your `~/bin/` directory, and it will work on any system of the same architecture with the same glibc major version (has been 2 for a long time).

== Configuration

The default will run the relay with default settings, which will not be what you want.

=== Show Current Configuration

To see the current active configuration:

----
realy env
----

=== Create Persistent Configuration

This output can be directed to the profile location to make the settings editable without manually setting them on the commandline:

----
realy env > $HOME/.config/realy/.env
----

You can now edit this file to alter the configuration.

Regarding the configuration system, this is an element of many servers that is absurdly complex, and for which reason Realy does not use a complicated scheme, a simple library that allows automatic configuration of a series of options, added a simple info print:

----
realy help
----

will show you the instructions, and the one simple extension of being able to use a standard formated .env file to configure all the options for an instance.

=== Database Storage Location

The database is stored in `$HOME/.local/share/realy` and if need be you can stop `realy` delete everything in this directory and restart to "nuke" the database. Note that this is now available through the link:#_simplified_nostr[Simplified Nostr] HTTP OpenAPI endpoint on `/nuke`

== API support

=== Standard Nostr NIPs

`realy` already accepts all the standard NIPs mainly nip-01 and many other types are recognised such an NIP-42 auth messages and it uses and parses relay lists, and all that other stuff.
It has maybe the most faithful implementation of NIP-42 but most clients don't correctly implement it, or at all.
Which is sad, but what can you do with stupid people?

[#_simplified_nostr]
=== Simplified Nostr

Rather than write a text that will likely fall out of date very quickly, simply run `realy` and visit its listener address (eg link:http://localhost:3334/api[http://localhost:3334/api]) to see the full documentation.

By default this presents you with a Scalar Docs page that lets you browse the available API methods and shows examples in many forms including cURL and most languages how to call and what data needs to go in headers, body, and parameters and what results will come back.

There is even a subscription endpoint, also, which uses SSE format and does not require a websocket upgrade to work with.