netstr - a nostr relay

Netstr is a modern relay for the nostr protocol written in C#.

Upstream acknowledgment: this repository is forked from bezysoftware/netstr, with gratitude to its original maintainers and contributors.

• Prod instance: https://relay.netstr.io/
• Dev instance: https://relay-dev.netstr.io/ (feel free to play with it / try to break it, just report if you find anything that needs fixing)

Features

NIPs with a relay-specific implementation are listed here.

• NIP-01: Basic protocol flow description
• NIP-02: Follow list
• NIP-04: Encrypted Direct Message (deprecated in favor of NIP-17)
• NIP-05: Mapping Nostr keys to DNS-based internet identifiers
• NIP-09: Event deletion
• NIP-11: Relay information document
• NIP-13: Proof of Work
• NIP-17: Private Direct Messages
• NIP-40: Expiration Timestamp
• NIP-42: Authentication of clients to relays
• NIP-45: Counting results
• NIP-50: Search Capability
• NIP-51: Lists
• NIP-57: Lightning Zaps
• NIP-59: Gift Wrap
• NIP-60: Cashu Wallet and Token
• NIP-62: Request to Vanish
• NIP-64: Chess (Portable Game Notation)
• NIP-65: Relay List Metadata
• NIP-70: Protected events
• NIP-77: Negentropy syncing
• NIP-78: Application-specific Data
• NIP-119: AND operator for filters

Additional Features

• Public Key Whitelist: Restrict which public keys can publish events and/or subscribe to your relay. Learn more

Tests

Supported NIPs are covered by automated tests using Specflow / Gherkin language and xUnit integration/unit tests. The scenarios are described in plain English which lets anyone read them and even contribute with new ones without any programming skills. See sample (simplified):

Scenario: Newly subscribed client receives matching events, EOSE and future events
    Given a relay is running
    And Alice is connected to relay
    And Bob is connected to relay
    When Bob publishes events
    | Id                                                               | Content  | Kind  | CreatedAt  |
    | a6d166e834e78827af0770f31f15b13a772f281ad880f43ce12c24d4e3d0e346 | Hello 1  | 1     | 1722337838 |
    | cb952d0ab727c3fcaf94e6809a64d1a27ff87cae5be583398ee7f0f1381d6b66 | Hello MD | 30023 | 1722337839 |
    And Alice sends a subscription request abcd
    | Kinds |
    | 1     |
    And Bob publishes an event
    | Id                                                               | Content | Kind | CreatedAt  |
    | 8013e4630a69528007355f65e01936c9b761a4bbd9340b60a4bd0222b15b7cf3 | Hello 2 | 1    | 1722337840 |
    Then Alice receives messages
    | Type  | Id   | EventId                                                          |
    | EVENT | abcd | a6d166e834e78827af0770f31f15b13a772f281ad880f43ce12c24d4e3d0e346 |
    | EOSE  | abcd |                                                                  |
    | EVENT | abcd | 8013e4630a69528007355f65e01936c9b761a4bbd9340b60a4bd0222b15b7cf3 |
    And Bob receives messages
    | Type | Id                                                               | Success | 
    | OK   | a6d166e834e78827af0770f31f15b13a772f281ad880f43ce12c24d4e3d0e346 | true    |
    | OK   | cb952d0ab727c3fcaf94e6809a64d1a27ff87cae5be583398ee7f0f1381d6b66 | true    |
    | OK   | 8013e4630a69528007355f65e01936c9b761a4bbd9340b60a4bd0222b15b7cf3 | true    |

Above scenario simulates that Bob publishes events to a relay, Alice creates a subscription and Bob publishes more events. The scenario then asserts that Alice and Bob both received their expected messages in correct order.

Setup

Netstr is c# app backed by a Postgres database. You have several options to get up and running:

• Using dotnet run
• Using docker run
• Using docker compose
• Deploying to Azure

Dotnet run

• Install .NET: https://dotnet.microsoft.com/en-us/download
• Install Postgres: https://www.postgresql.org/download/
• Copy src/Netstr/appsettings.local.json.example to src/Netstr/appsettings.local.json
• Set ConnectionStrings:NetstrDatabase in src/Netstr/appsettings.local.json (or set env var ConnectionStrings__NetstrDatabase)
• Use src/Netstr/appsettings.example.json as a safe baseline if you need a full config template
• Run dotnet run --project .\src\Netstr\Netstr.csproj

Docker run

• Install Docker: https://docs.docker.com/engine/install/
• Install Postgres: https://www.postgresql.org/download/
• Run docker run -e ConnectionStrings__NetstrDatabase=YOUR_CONNECTION_STRING bezysoftware/netstr:latest
  • Set your connection string to point to your Postgres instance
• Note: Docker examples default to the upstream image. You can override with NETSTR_IMAGE (for example, a locally built image) when using Compose.

Docker compose

Docker compose contains a Postgres DB service so no need to install it manually. You will however need to set the following environment variable:

• NETSTR_DB_PASSWORD - password for Postgres DB

Optionally you can also set following variables:

• NETSTR_IMAGE - docker image (default bezysoftware/netstr:latest)
• NETSTR_PORT - port on which the relay will be accessible (default 8080)
• NETSTR_ENVIRONMENT - will be used to name the compose instance (default 'prod')
• NETSTR_ENVIRONMENT_LONG - will be used inside the application to load specific configuration (default 'Production')

Deploying to Azure

The scripts folder contains scripts to setup a VM in Azure with everything you'll need to run a Netstr instance:

• Separate VM with an attached data disk
• Docker with Compose to run the compose.yaml
• Nginx with certbot which generates an SSL certificate for your domain