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.

📜 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

🔧 Administrator API

C-Relay uses an innovative event-based administration system where all configuration and management commands are sent as signed Nostr events using the admin private key generated during first startup. All admin commands use tag-based parameters for simplicity and compatibility.

Authentication

All admin commands require signing with the admin private key displayed during first-time startup. Save this key securely - it cannot be recovered and is needed for all administrative operations.

Event Structure

All admin commands use the same unified event structure with tag-based parameters:

Admin Command Event:

{
  "id": "event_id",
  "pubkey": "admin_public_key",
  "created_at": 1234567890,
  "kind": 23456,
  "content": "<nip44 encrypted command>",
  "tags": [
    ["p", "relay_public_key"],
  ],
  "sig": "event_signature"
}

Admin Response Event:

["EVENT", "temp_sub_id", {
  "id": "response_event_id",
  "pubkey": "relay_public_key",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "<nip44 encrypted response>",
  "tags": [
    ["p", "admin_public_key"]
  ],
  "sig": "response_event_signature"
}]

Admin Commands

All commands are sent as nip44 encrypted content. The following table lists all available commands:

Command Type	Tag Format	Description
Configuration Management
`config_update`	`["relay_description", "My Relay"]`	Update relay configuration parameters
`config_query`	`["config_query", "list_all_keys"]`	List all available configuration keys
Auth Rules Management
`auth_add_blacklist`	`["blacklist", "pubkey", "abc123..."]`	Add pubkey to blacklist
`auth_add_whitelist`	`["whitelist", "pubkey", "def456..."]`	Add pubkey to whitelist
`auth_query_all`	`["auth_query", "all"]`	Query all auth rules
`auth_query_type`	`["auth_query", "whitelist"]`	Query specific rule type
`auth_query_pattern`	`["auth_query", "pattern", "abc123..."]`	Query specific pattern
System Commands
`system_clear_auth`	`["system_command", "clear_all_auth_rules"]`	Clear all auth rules
`system_status`	`["system_command", "system_status"]`	Get system status

Available Configuration Keys

Basic Relay Settings:

relay_description: Relay description text
relay_contact: Contact information
max_connections: Maximum concurrent connections
max_subscriptions_per_client: Max subscriptions per client
max_event_tags: Maximum tags per event
max_content_length: Maximum event content length

Authentication & Access Control:

auth_enabled: Enable whitelist/blacklist auth rules (true/false)
nip42_auth_required: Enable NIP-42 cryptographic authentication (true/false)
nip42_auth_required_kinds: Event kinds requiring NIP-42 auth (comma-separated)
nip42_challenge_timeout: NIP-42 challenge expiration seconds

Proof of Work & Validation:

pow_min_difficulty: Minimum proof-of-work difficulty
nip40_expiration_enabled: Enable event expiration (true/false)

Response Format

All admin commands return signed EVENT responses via WebSocket following standard Nostr protocol. Responses use JSON content with structured data.

Response Examples

Success Response:

["EVENT", "temp_sub_id", {
  "id": "response_event_id",
  "pubkey": "relay_public_key",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "nip44 encrypted:{\"status\": \"success\", \"message\": \"Operation completed successfully\"}",
  "tags": [
    ["p", "admin_public_key"]
  ],
  "sig": "response_event_signature"
}]

Error Response:

["EVENT", "temp_sub_id", {
  "id": "response_event_id",
  "pubkey": "relay_public_key",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "nip44 encrypted:{\"status\": \"error\", \"message\": \"Error: invalid configuration value\"}",
  "tags": [
    ["p", "admin_public_key"]
  ],
  "sig": "response_event_signature"
}]

Auth Rules Query Response:

["EVENT", "temp_sub_id", {
  "id": "response_event_id",
  "pubkey": "relay_public_key",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "nip44 encrypted:{\"query_type\": \"auth_rules\", \"total_results\": 2, \"data\": [{\"rule_type\": \"blacklist\", \"pattern_type\": \"pubkey\", \"pattern_value\": \"abc123...\", \"action\": \"deny\"}]}",
  "tags": [
    ["p", "admin_public_key"]
  ],
  "sig": "response_event_signature"
}]

Configuration Query Response:

["EVENT", "temp_sub_id", {
  "id": "response_event_id",
  "pubkey": "relay_public_key",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "nip44 encrypted:{\"query_type\": \"config_keys\", \"config_keys\": [\"auth_enabled\", \"max_connections\"], \"descriptions\": {\"auth_enabled\": \"Enable whitelist/blacklist rules\"}}",
  "tags": [
    ["p", "admin_public_key"]
  ],
  "sig": "response_event_signature"
}]

5.8 KiB Raw Blame History