c-relay/README.md

# C Nostr Relay - Event-Based Configuration System

A high-performance Nostr relay implemented in C with SQLite backend, featuring a revolutionary **zero-configuration** approach using event-based configuration management.

## 🌟 Key Features

- **🔧 Zero Configuration**: No config files or command line arguments needed
- **🔑 Event-Based Config**: All settings stored as kind 33334 Nostr events
- **🚀 Real-Time Updates**: Configuration changes applied instantly via WebSocket
- **🛡️ Cryptographic Security**: Configuration events cryptographically signed and validated
- **📊 SQLite Backend**: High-performance event storage with optimized schema
- **🔄 Auto Key Generation**: Secure admin and relay keypairs generated on first startup
- **💾 Database Per Relay**: Each relay instance uses `<relay_pubkey>.nrdb` database naming

## 🚀 Quick Start

### 1. Build the Relay
```bash
git clone <repository-url>
cd c-relay
git submodule update --init --recursive
make
```

### 2. Start the Relay
```bash
./build/c_relay_x86
```

**That's it!** No configuration files, no command line arguments needed.

### 3. Save Your Admin Keys (IMPORTANT!)
On first startup, the relay will display:

```
=================================================================
IMPORTANT: SAVE THIS ADMIN PRIVATE KEY SECURELY!
=================================================================
Admin Private Key: f8491814ea288260dad2ab52c09b3b037e75e83e8b24feb9bdc328423922be44
Admin Public Key:  07fc2cdd8bdc0c60eefcc9e37e67fef88206bc84fadb894c283b006554ac687b

Relay Private Key: a1b2c3d4e5f6...
Relay Public Key:  1a2b3c4d5e6f...

Database: dc9a93fd0ffba7041f6df0602e5021913a42fcaf6dbf40f43ecdc011177b4d94.nrdb
=================================================================
```

⚠️ **Save the admin private key securely** - it's needed to update relay configuration and is only displayed once!

## 📋 System Requirements

- **OS**: Linux, macOS, or Windows (WSL)
- **Dependencies**: 
  - SQLite 3
  - libwebsockets
  - OpenSSL/LibreSSL
  - libsecp256k1
  - libcurl
  - zlib

## 🏗️ Event-Based Configuration System

### How It Works

Traditional Nostr relays require configuration files, environment variables, or command line arguments. This relay uses a **revolutionary approach**:

1. **First-Time Startup**: Generates cryptographically secure admin and relay keypairs
2. **Database Creation**: Creates `<relay_pubkey>.nrdb` database file
3. **Default Configuration**: Creates initial kind 33334 configuration event with sensible defaults
4. **Real-Time Updates**: Administrators send new kind 33334 events to update configuration
5. **Instant Application**: Changes are applied immediately without restart

### Configuration Updates

To update relay configuration, send a signed kind 33334 event:

```json
{
  "kind": 33334,
  "content": "C Nostr Relay Configuration",
  "tags": [
    ["d", "<relay_pubkey>"],
    ["relay_description", "My awesome Nostr relay"],
    ["max_subscriptions_per_client", "25"],
    ["pow_min_difficulty", "16"],
    ["nip40_expiration_enabled", "true"]
  ],
  "created_at": 1234567890,
  "pubkey": "<admin_pubkey>",
  "id": "...",
  "sig": "..."
}
```

Send this event to your relay via WebSocket, and changes are applied instantly.

### Configurable Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `relay_description` | Relay description (NIP-11) | "C Nostr Relay" |
| `relay_contact` | Admin contact info | "" |
| `max_subscriptions_per_client` | Max subscriptions per client | "25" |
| `max_total_subscriptions` | Total subscription limit | "5000" |
| `pow_min_difficulty` | NIP-13 PoW difficulty | "0" |
| `pow_mode` | PoW validation mode | "optional" |
| `nip40_expiration_enabled` | Enable NIP-40 expiration | "true" |
| `nip40_expiration_strict` | Strict expiration mode | "false" |
| `max_message_length` | Max message size | "65536" |
| `max_event_tags` | Max tags per event | "2000" |
| `max_content_length` | Max content length | "65536" |

## 🔧 Deployment

### Manual Installation
```bash
# Build the relay
make

# Run directly
./build/c_relay_x86
```

### SystemD Service (Recommended)
```bash
# Install as system service
sudo systemd/install-service.sh

# Start the service
sudo systemctl start c-relay

# Enable auto-start on boot
sudo systemctl enable c-relay

# View logs
sudo journalctl -u c-relay -f
```

See [`systemd/README.md`](systemd/README.md) for detailed deployment documentation.

### Docker (Coming Soon)
Docker support is planned for future releases.

## 📊 Database Schema

The relay uses an optimized SQLite schema (version 4) with these key features:

- **Event-based storage**: All Nostr events in single `events` table
- **JSON tags support**: Native JSON storage for event tags
- **Performance optimized**: Multiple indexes for fast queries
- **Subscription logging**: Optional detailed subscription analytics
- **Auto-cleanup**: Automatic ephemeral event cleanup
- **Replaceable events**: Proper handling of replaceable/addressable events

## 🛡️ Security Features

- **Cryptographic validation**: All configuration events cryptographically verified
- **Admin-only config**: Only authorized admin pubkey can update configuration
- **Signature verification**: Uses `nostr_verify_event_signature()` for validation
- **Event structure validation**: Complete event structure validation
- **Secure key generation**: Uses `/dev/urandom` for cryptographically secure keys
- **No secrets storage**: Admin private key never stored on disk

## 🔌 Network Configuration

- **Default Port**: 8888 (WebSocket)
- **Protocol**: WebSocket with Nostr message format
- **Endpoints**: 
  - `ws://localhost:8888` - WebSocket relay
  - `http://localhost:8888` - NIP-11 relay information (HTTP GET)

## 🏃‍♂️ Usage Examples

### Connect with a Nostr Client
```javascript
const relay = new WebSocket('ws://localhost:8888');
relay.send(JSON.stringify(["REQ", "sub1", {"kinds": [1], "limit": 10}]));
```

### Update Configuration (using `nostrtool` or similar)
```bash
# Create configuration event with nostrtool
nostrtool event --kind 33334 --content "Updated config" \
  --tag d <relay_pubkey> \
  --tag relay_description "My updated relay" \
  --private-key <admin_private_key>

# Send to relay
nostrtool send ws://localhost:8888 <event_json>
```

## 📈 Monitoring and Analytics

### View Relay Status
```bash
# Check if relay is running
ps aux | grep c_relay

# Check network port
netstat -tln | grep 8888

# View recent logs
tail -f relay.log
```

### Database Analytics
```bash
# Connect to relay database
sqlite3 <relay_pubkey>.nrdb

# View relay statistics
SELECT * FROM event_stats;

# View configuration events
SELECT * FROM configuration_events;

# View recent events
SELECT * FROM recent_events LIMIT 10;
```

## 🧪 Testing

### Run Error Handling Tests
```bash
# Comprehensive test suite
tests/event_config_tests.sh

# Quick validation tests
tests/quick_error_tests.sh
```

### Manual Testing
```bash
# Test WebSocket connection
wscat -c ws://localhost:8888

# Test NIP-11 information
curl http://localhost:8888
```

## 🔧 Development

### Build from Source
```bash
git clone <repository-url>
cd c-relay
git submodule update --init --recursive
make clean && make
```

### Debug Build
```bash
make debug
gdb ./build/c_relay_x86
```

### Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

## 📜 Supported NIPs

<!--
NOTE FOR ASSISTANTS: When updating the NIPs checklist below, ONLY change [ ] to [x] to mark as complete.
Do NOT modify the formatting, add emojis, or change the text. Keep the simple format consistent.
-->

- [x] NIP-01: Basic protocol flow implementation
- [x] NIP-09: Event deletion
- [x] NIP-11: Relay information document
- [x] NIP-13: Proof of Work
- [x] NIP-15: End of Stored Events Notice
- [x] NIP-20: Command Results
- [x] NIP-33: Parameterized Replaceable Events
- [x] NIP-40: Expiration Timestamp
- [ ] NIP-42: Authentication of clients to relays
- [ ] NIP-45: Counting results
- [ ] NIP-50: Keywords filter
- [ ] NIP-70: Protected Events

## 🆘 Troubleshooting

### Common Issues

**Relay won't start**
```bash
# Check for port conflicts
netstat -tln | grep 8888

# Check permissions
ls -la build/c_relay_x86

# Check dependencies
ldd build/c_relay_x86
```

**Lost admin private key**
- If you lose the admin private key, you cannot update configuration
- You must delete the database file and restart (loses all events)
- The relay will generate new keys on first startup

**Database corruption**
```bash
# Check database integrity
sqlite3 <relay_pubkey>.nrdb "PRAGMA integrity_check;"

# If corrupted, remove database (loses all events)
rm <relay_pubkey>.nrdb*
./build/c_relay_x86  # Will create fresh database
```

**Configuration not updating**
- Ensure configuration events are properly signed
- Check that admin pubkey matches the one from first startup
- Verify WebSocket connection is active
- Check relay logs for validation errors

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🤝 Support

- **Issues**: Report bugs and feature requests on GitHub
- **Documentation**: See `docs/` directory for technical details
- **Deployment**: See `systemd/README.md` for production deployment
- **Community**: Join the Nostr development community

## 🚀 Future Roadmap

- [ ] Docker containerization
- [ ] NIP-42 authentication support
- [ ] Advanced analytics dashboard
- [ ] Clustering support for high availability
- [ ] Performance optimizations
- [ ] Additional NIP implementations

---

**The C Nostr Relay represents the future of Nostr infrastructure - zero configuration, event-based management, and cryptographically secure administration.**