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

git clone <repository-url>
cd c-relay
git submodule update --init --recursive
make

2. Start the Relay

./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:

{
  "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

# Build the relay
make

# Run directly
./build/c_relay_x86

SystemD Service (Recommended)

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

const relay = new WebSocket('ws://localhost:8888');
relay.send(JSON.stringify(["REQ", "sub1", {"kinds": [1], "limit": 10}]));

Update Configuration (using nostrtool or similar)

# 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

# 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

# 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

# Comprehensive test suite
tests/event_config_tests.sh

# Quick validation tests
tests/quick_error_tests.sh

Manual Testing

# Test WebSocket connection
wscat -c ws://localhost:8888

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

🔧 Development

Build from Source

git clone <repository-url>
cd c-relay
git submodule update --init --recursive
make clean && make

Debug Build

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

• 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

🆘 Troubleshooting

Common Issues

Relay won't start

# 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

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