GRAIN is a comprehensive Nostr solution that serves primarily as a powerful relay for operators who need fine-grained control, while also providing a complete Go client library for developers building Nostr applications.

Nostr is a simple, open protocol for creating censorship-resistant social networks. Users publish signed events (posts, profiles, reactions) to relays, which store and distribute them. Unlike centralized platforms, users control their identity through cryptographic keys and can freely move between relays.

GRAIN acts as one of these relays - storing events, serving them to clients, and ensuring your relay operates according to your policies. It also provides the building blocks for creating your own Nostr clients.

• Real-time blacklist/whitelist filtering with automatic caching
• Word-based content filtering that escalates temporary bans to permanent ones
• Import blacklists from Nostr mute lists (kind 10000 events)
• Domain-based whitelisting by fetching pubkeys from .well-known/nostr.json

• Hot configuration reloading - change settings without restarting
• Comprehensive structured logging with automatic rotation
• Memory-aware connection management prevents resource exhaustion
• Multi-layer rate limiting (connections, events, queries) with per-kind controls

• Supports all Nostr event categories: regular, replaceable, addressable, ephemeral & deletion events
• Automatic event deletion handling (kind 5 events) with proper cascade cleanup
• Intelligent event purging with category-based retention policies
• nostrdb storage (LMDB-based) optimized for Nostr's event structure

• Unified high-performance database queries for efficient event retrieval
• Zero-dependency embedded storage via nostrdb
• Configurable event size limits to prevent abuse
• Connection pooling and timeout management

GRAIN now includes a full-featured Nostr client library that developers can use to build their own applications:

• Connection pooling with automatic relay management
• Event publishing with multi-relay broadcasting and result aggregation
• Subscription management with filter support and relay hints
• Event signing with private key support and extensible signer interface
• Session management with user authentication and session persistence

• Structured logging integration matching relay standards
• Error handling with proper context and type safety
• Concurrent operations with proper synchronization
• Memory management with buffered channels and cleanup routines

• Standard library first - minimal dependencies
• Clear documentation with examples and best practices
• Go modules support for easy integration
• Consistent API following Go conventions

GRAIN includes a modern web interface that serves as both a relay dashboard and reference client implementation:

• Real-time monitoring of relay status, connections, and event flow
• Configuration management with hot-reload support for all settings
• User management with whitelist/blacklist administration
• Visual analytics showing relay performance and usage patterns

The web interface showcases the client library capabilities with:

• User authentication supporting multiple signing methods
• Event publishing with multi-relay support and status tracking
• Profile management with metadata caching and display
• Session handling demonstrating secure user flows

This reference implementation serves as both a functional interface and documentation for developers using the client library.

• RESTful APIs for client integration and relay management
• NIP-11 compliance for relay discovery and metadata
• Progressive Web App features for mobile-friendly usage

Full documentation lives in docs/ — start at the documentation hub, organized by what you're doing:

• Operators — installation · configuration · Docker
• Library developers — client library guide · HTTP API
• Contributors — development · testing

Development Relay: wss://wheat.oslim.dev

📊 View Detailed Status & Historical Data

My development relay wheat.oslim.dev serves as the testing and demo environment for Grain. This relay helps me validate new features, test performance optimizations, and provide a platform for developers to experiment with grain. This relay routinely runs unreleased versions of grain and may contain bugs.

Wheat is a public nostr relay that anyone can write to and read from. Wheat will delete events from non whitelisted users periodically. You can add your npub to the whitelist by paying for a oslim.dev NIP05.

Status monitoring powered by Upptime

1. Download the latest release for your system from the releases page
2. Run GRAIN - ./grain (Linux) or grain.exe (Windows)

GRAIN is a zero-dependency, single-binary application. All assets (including the web interface) are embedded in the binary. On first run, it will automatically create default configuration files and a local database in the platform-appropriate data directory:

• Linux: ~/.grain/
• macOS: ~/Library/Application Support/grain/
• Windows: %APPDATA%\grain\

You can override the data directory using the --data-dir <path> CLI flag or the GRAIN_DATA_DIR environment variable.

Docker Installation

• Docker Setup Guide

Build from Source

• Requirements: Go 1.23+

Complete Installation Guide

• Full Installation Documentation - includes system service setup for Linux (systemd) and Windows (NSSM)

GRAIN uses four main configuration files with hot-reload support:

• config.yml - Server, database, and rate limiting settings
• whitelist.yml - Allowed users, domains, and event types
• blacklist.yml - Banned content and escalation policies
• relay_metadata.json - Public relay information (NIP-11)

Configuration files are automatically created from embedded examples on first run. Changes to any configuration file are detected and applied automatically without requiring a restart.

📖 For detailed configuration options and examples, see Configuration Documentation

GRAIN can be imported as a Go module for building Nostr clients:

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/0ceanslim/grain/client/core"
	nostr "github.com/0ceanslim/grain/server/types"
)

func main() {
	// The client owns a shared, outbox-routed relay pool.
	client := core.NewClient(core.DefaultConfig())
	ctx := context.Background()

	// Read-only: fetch a user's notes from THEIR outbox relays — no signer needed.
	author := "author-pubkey-hex"
	notes := client.NewUserContext(author).FetchNotes(ctx, author, core.WithLimit(20))
	fmt.Printf("fetched %d notes\n", len(notes))

	// Publishing: attach a signer. The outbox model routes the event to your write
	// relays (and any mentioned recipient's inbox) — no manual relay list needed.
	signer, _ := core.NewEventSigner("your-private-key-hex")
	uc := client.NewUserContext(signer.PublicKey(), core.WithSigner(signer))

	note := &nostr.Event{Kind: 1, Content: "Hello Nostr!", CreatedAt: time.Now().Unix()}
	results, _ := uc.SignAndPublish(ctx, note)
	fmt.Printf("published to %d relays\n", len(results))
}

📖 See the Client Library Guide for complete examples covering connection management, subscriptions, event building/signing, and authentication flows.

This project is Open Source and licensed under the MIT License. See the LICENSE file for details.

I welcome contributions, bug reports, and feature requests via GitHub.

Repository: https://github.com/0ceanslim/grain
Issues: https://github.com/0ceanslim/grain/issues

• 🔧 Development Guide - Development Documentation
• 🧪 Testing Guide - Testing Documentation
• 📚 API Documentation - Every running relay generates its own docs from the OpenAPI spec in the repo and serves Swagger UI at /api/docs (raw spec at /api/docs/openapi.json). Live example on the wheat dev relay: wheat.oslim.dev/api/docs. See docs/api.md for regeneration instructions.

These guides cover setting up your development environment, code standards, testing procedures, client library usage, and contribution workflows.

made with 💦 by OceanSlim

Reliable infrastructure for the decentralized web.