# 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**