relay

module

v0.6.1 Latest Latest Go to latest Published: Apr 13, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/zapstore/relay

Links

Open Source Insights

README ¶

Zapstore Relay

A Nostr relay and Blossom server for the Zapstore app ecosystem.

Features

Nostr Relay

Full Nostr relay implementation using rely
NIP-11 relay information document
NIP-42 authentication support
Configurable allowed event kinds with structure validation
Filter specificity scoring to reject overly vague queries
SQLite-based event storage

Blossom Server

Full Blossom server implementation using blossy
Bunny CDN integration for scalable blob delivery
Configurable allowed media types (APKs, images)
Deduplication: blobs are checked before upload to save bandwidth
Local SQLite metadata store with CDN redirect for downloads

Access Control (ACL)

Hot-reloadable CSV-based allow/block lists for:
- Pubkeys (allowed and blocked)
- Event IDs (blocked)
- Blob hashes (blocked)
Configurable unknown pubkey policy:
- ALLOW - allow all unknown pubkeys
- BLOCK - block all unknown pubkeys
- VERTEX - use Vertex DVM reputation filtering

Vertex DVM Integration

Reputation-based access control for unknown pubkeys
Supports multiple ranking algorithms:
- Global PageRank
- Personalized PageRank
- Follower count
Configurable reputation threshold
In-memory LRU cache for rank lookups

Analytics

Privacy-preserving usage statistics for app impressions and blob downloads
Counts impressions derived from Nostr REQs
Counts downloads from blossom downloads
Batched, non-blocking writes: events are queued in memory and flushed to SQLite periodically or when the batch size threshold is reached

Rate Limiting

Token bucket rate limiting per IP group
Configurable initial tokens, max tokens, and refill rate
Different costs for different operations (connections, events, queries, uploads)
Penalty system for misbehaving clients

Running

Prerequisites

Go 1.25 or later
A BunnyCDN account with a storage zone configured
A Nostr secret key loaded with Vertex DVM credits

Build and Run

# Clone the repository
git clone https://github.com/zapstore/relay.git
cd relay

# Build with default parameters:
# - TAG = <latest_tag>
# - BUILD_DIR = /build
make build

# Or build with specific tag and build directory
make build TAG=v1.2.3 BUILD_DIR=path/to/build

# Create and configure .env file
cp .env.example build/.env

# Edit build/.env with your configuration

# Run (use the tag that was built)
./build/relay-v1.2.3

Data Directory Structure

On first run, the server creates the following structure:

$SYSTEM_DIRECTORY_PATH/
├── acl/
│   ├── pubkeys_allowed.csv
│   ├── pubkeys_blocked.csv
│   ├── events_blocked.csv
│   └── blobs_blocked.csv
│
├── analytics/
│   ├── analytics.db  # SQLite database for analytics
│   └── geo.mmdb      # MaxMind database for ip geolocation
│ 
└── data/
    ├── relay.db      # SQLite database for relay events
    └── blossom.db    # SQLite database for blob metadata

ACL File Format

ACL files are CSV with two columns: identifier and reason. Lines starting with # are comments.

# Allowed pubkeys
# pubkey,reason
npub1abc...,Trusted developer
abc123...,Another trusted user

Files are hot-reloaded when modified - no server restart required.

Endpoints

Relay: ws://localhost:3334 (or your configured port)
Blossom: http://localhost:3335 (or your configured port)

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
pkg
acl The acl package is responsible for managing the access control list for the relay and blossom servers.	The acl package is responsible for managing the access control list for the relay and blossom servers.
acl/repo Package repo provides platform-agnostic repository verification for the ACL.	Package repo provides platform-agnostic repository verification for the ACL.
acl/vertex The vertex package exposes a configurable Filter struct that allows or rejects a pubkey based on its reputation.	The vertex package exposes a configurable Filter struct that allows or rejects a pubkey based on its reputation.
analytics Package analytics provides an analytics Engine for collecting privacy-preserving statistics useful for Zapstore developers to keep track of app usage.	Package analytics provides an analytics Engine for collecting privacy-preserving statistics useful for Zapstore developers to keep track of app usage.
analytics/geo
analytics/store Package store provides a SQLite-backed storage layer for analytics data.	Package store provides a SQLite-backed storage layer for analytics data.
blossom The blossom package is responsible for setting up the blossom server.	The blossom package is responsible for setting up the blossom server.
blossom/bunny The bunny package is responsible for interacting with the Bunny Storage Zone and CDN.	The bunny package is responsible for interacting with the Bunny Storage Zone and CDN.
blossom/store The store package is responsible for storing blobs metadata in sqlite.	The store package is responsible for storing blobs metadata in sqlite.
config The package config is responsible for loading package specific configs from the environment variables, and validating them.	The package config is responsible for loading package specific configs from the environment variables, and validating them.
events Package events provides functions for validating events structures.	Package events provides functions for validating events structures.
events/legacy
indexing Package indexing provides a non-blocking engine for recording demand signals from the relay into the shared indexing.db database.	Package indexing provides a non-blocking engine for recording demand signals from the relay into the shared indexing.db database.
indexing/store Package store provides SQLite access to the shared indexing.db database.	Package store provides SQLite access to the shared indexing.db database.
rate The rate is a wrapper around the github.com/pippellia-btc/rate package, exposing a Config struct for configuring the limiter, and a NewLimiter function to create a new ip-rate limiter.	The rate is a wrapper around the github.com/pippellia-btc/rate package, exposing a Config struct for configuring the limiter, and a NewLimiter function to create a new ip-rate limiter.
relay The relay package is responsible for setting up the relay.	The relay package is responsible for setting up the relay.
relay/linkverify Package linkverify implements NIP-C1 certificate link verification as a relay save hook.	Package linkverify implements NIP-C1 certificate link verification as a relay save hook.
relay/store The store package is responsible for storing nostr events in a sqlite database.	The store package is responsible for storing nostr events in a sqlite database.
repourl Package repourl identifies and normalises repository URLs from free-text search terms.	Package repourl identifies and normalises repository URLs from free-text search terms.