286 lines
9.0 KiB
Markdown
286 lines
9.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# AWS, GCP, DigitalOcean, etc.
|
|
sudo examples/deployment/simple-vps/deploy.sh
|
|
```
|
|
|
|
See [`docs/deployment_guide.md`](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`](docs/configuration_guide.md) for complete configuration reference.
|
|
|
|
## 📚 Documentation
|
|
|
|
- **[API Documentation](API.md)** - Complete API reference and advanced features
|
|
- **[Configuration Guide](docs/configuration_guide.md)** - Detailed configuration options
|
|
- **[Deployment Guide](docs/deployment_guide.md)** - Production deployment instructions
|
|
- **[User Guide](docs/user_guide.md)** - End-user documentation
|
|
- **[NIP-42 Authentication](docs/NIP-42_Authentication.md)** - Authentication setup guide
|
|
|
|
## 🧪 Testing
|
|
|
|
Run the comprehensive test suite:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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`](docs/deployment_guide.md#security-hardening) for security hardening guide.
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes with tests
|
|
4. Submit a pull request
|
|
|
|
## 📄 License
|
|
|
|
[Add your license here]
|
|
|
|
## 🔗 Links
|
|
|
|
- **Repository**: [https://github.com/your-org/c-relay](https://github.com/your-org/c-relay)
|
|
- **Releases**: [https://git.laantungir.net/laantungir/c-relay/releases](https://git.laantungir.net/laantungir/c-relay/releases)
|
|
- **Issues**: [https://github.com/your-org/c-relay/issues](https://github.com/your-org/c-relay/issues)
|
|
- **Nostr Protocol**: [https://github.com/nostr-protocol/nostr](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**
|