C-Relay: High-Performance Nostr Relay
A blazingly fast, production-ready Nostr relay implemented in C with an innovative event-based configuration system. Built for performance, security, and ease of deployment.
🚀 Why C-Relay?
Event-Based Configuration
Unlike traditional relays that require config files, C-Relay uses cryptographically signed Nostr events for all configuration. This means:
- Zero config files - Everything stored in the database
- Real-time updates - Changes applied instantly without restart
- Cryptographic security - All changes must be signed by admin
- Complete audit trail - Every configuration change is timestamped and signed
- Version control built-in - Configuration history is part of the event stream
Built-in Web Admin Interface
Access a full-featured web dashboard at http://localhost:8888/api/ with:
- Real-time configuration management
- Database statistics and analytics
- Auth rules management (whitelist/blacklist)
- NIP-42 authentication for secure access
- No external dependencies - all files embedded in the binary
Direct Message Admin System
Control your relay by sending direct messages from any Nostr client:
- Send "stats" to get relay statistics
- Send "config" to view current configuration
- Full Nostr citizen with its own keypair
- Works with any NIP-17 compatible client
Performance & Efficiency
- Written in C - Maximum performance and minimal resource usage
- SQLite backend - Reliable, fast, and self-contained
- Static binary available - Single file deployment with zero dependencies
- Efficient memory management - Optimized for long-running operation
- WebSocket native - Built on libwebsockets for optimal protocol support
📋 Supported NIPs
C-Relay implements a comprehensive set of Nostr Improvement Proposals:
- ✅ NIP-01: Basic protocol flow implementation
- ✅ NIP-09: Event deletion
- ✅ NIP-11: Relay information document
- ✅ NIP-13: Proof of Work
- ✅ NIP-15: End of Stored Events Notice
- ✅ NIP-20: Command Results
- ✅ NIP-33: Parameterized Replaceable Events
- ✅ NIP-40: Expiration Timestamp
- ✅ NIP-42: Authentication of clients to relays
- ✅ NIP-45: Counting results
- ✅ NIP-50: Keywords filter
- ✅ NIP-70: Protected Events
🎯 Key Features
Security
- NIP-42 Authentication - Cryptographic client authentication
- Proof of Work - Configurable PoW requirements (NIP-13)
- Protected Events - Support for encrypted/protected content (NIP-70)
- Whitelist/Blacklist - Flexible access control by pubkey
- Admin key security - Private key shown only once, never stored
Flexibility
- Dynamic configuration - Most settings update without restart
- Subscription management - Configurable limits per client and globally
- Event expiration - Automatic cleanup of expired events (NIP-40)
- Parameterized events - Full support for replaceable events (NIP-33)
- Keyword search - Built-in full-text search (NIP-50)
Monitoring
- Real-time statistics - Live event distribution and metrics
- Subscription-based monitoring - Ephemeral events (kind 24567) for dashboards
- SQL query API - Direct database queries for advanced analytics
- Resource tracking - CPU, memory, and database size monitoring
- Event broadcast logging - Complete audit trail of all operations
Developer-Friendly
- Comprehensive test suite - Automated tests for all NIPs
- Clear documentation - Detailed guides for deployment and configuration
- SystemD integration - Production-ready service files included
- Docker support - Container deployment with Alpine Linux
- Cross-platform - Builds on Linux, macOS, and Windows (WSL)
🚀 Quick Start
Option 1: Static Binary (Recommended)
Download and run - no dependencies required:
# Download the latest static release
wget https://git.laantungir.net/laantungir/c-relay/releases/download/v0.6.0/c-relay-v0.6.0-linux-x86_64-static
chmod +x c-relay-v0.6.0-linux-x86_64-static
mv c-relay-v0.6.0-linux-x86_64-static c-relay
# Run the relay
./c-relay
Important: On first startup, save the Admin Private Key displayed in the console. You'll need it for all administrative operations.
Option 2: Build from Source
# Install dependencies (Ubuntu/Debian)
sudo apt install -y build-essential git sqlite3 libsqlite3-dev \
libwebsockets-dev libssl-dev libsecp256k1-dev libcurl4-openssl-dev zlib1g-dev
# Clone and build
git clone https://github.com/your-org/c-relay.git
cd c-relay
git submodule update --init --recursive
./make_and_restart_relay.sh
The relay will start on port 8888 (or the next available port).
🌐 Access the Web Interface
Once running, open your browser to:
http://localhost:8888/api/
The web interface provides:
- Configuration management with live updates
- Database statistics and event distribution charts
- Auth rules management (whitelist/blacklist)
- SQL query interface for advanced analytics
- Real-time monitoring dashboard
📦 Installation Options
Production Deployment (SystemD)
# Clone repository
git clone https://github.com/your-org/c-relay.git
cd c-relay
git submodule update --init --recursive
# Build
make clean && make
# Install as system service
sudo systemd/install-service.sh
# Start and enable
sudo systemctl start c-relay
sudo systemctl enable c-relay
# Capture admin keys from logs
sudo journalctl -u c-relay | grep "Admin Private Key"
Docker Deployment
# Build Docker image
docker build -f Dockerfile.alpine-musl -t c-relay .
# Run container
docker run -d \
--name c-relay \
-p 8888:8888 \
-v /path/to/data:/data \
c-relay
Cloud Deployment
Quick deployment scripts for popular cloud providers:
# AWS, GCP, DigitalOcean, etc.
sudo examples/deployment/simple-vps/deploy.sh
See docs/deployment_guide.md for detailed deployment instructions.
🔧 Configuration
C-Relay uses an innovative event-based configuration system. All settings are managed through signed Nostr events.
Basic Configuration
Use the web interface at http://localhost:8888/api/ or send admin commands via the API.
Common Settings
- Relay Information: Name, description, contact info
- Connection Limits: Max subscriptions per client, total subscriptions
- Authentication: Enable/disable NIP-42, whitelist/blacklist rules
- Proof of Work: Minimum difficulty, enforcement mode
- Event Validation: Max tags, content length, message size
- Expiration: Enable/disable NIP-40 event expiration
Dynamic Updates
Most configuration changes take effect immediately without restart:
- Relay information (NIP-11)
- Authentication settings
- Subscription limits
- Event validation rules
- Proof of Work settings
See docs/configuration_guide.md for complete configuration reference.
📚 Documentation
- API Documentation - Complete API reference and advanced features
- Configuration Guide - Detailed configuration options
- Deployment Guide - Production deployment instructions
- User Guide - End-user documentation
- NIP-42 Authentication - Authentication setup guide
🧪 Testing
Run the comprehensive test suite:
# Run all tests
./tests/run_all_tests.sh
# Run NIP-specific tests
./tests/run_nip_tests.sh
# Test specific NIPs
./tests/42_nip_test.sh # NIP-42 authentication
./tests/13_nip_test.sh # NIP-13 proof of work
🔒 Security
Admin Key Management
The admin private key is displayed only once during first startup. Store it securely:
# Save to secure location
echo "ADMIN_PRIVKEY=your_admin_private_key" > ~/.c-relay-admin
chmod 600 ~/.c-relay-admin
Production Security
- Use HTTPS/WSS with reverse proxy (nginx/Apache)
- Enable NIP-42 authentication for client verification
- Configure whitelist/blacklist for access control
- Set up firewall rules to restrict access
- Enable Proof of Work to prevent spam
- Regular database backups
See docs/deployment_guide.md for security hardening guide.
🤝 Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
📄 License
[Add your license here]
🔗 Links
- Repository: https://github.com/your-org/c-relay
- Releases: https://git.laantungir.net/laantungir/c-relay/releases
- Issues: https://github.com/your-org/c-relay/issues
- Nostr Protocol: https://github.com/nostr-protocol/nostr
💬 Support
- Open an issue on GitHub
- Join the Nostr community
- Contact via Nostr DM (relay pubkey shown on startup)
Built with ❤️ for the Nostr protocol