8.6 KiB

Raw Permalink Blame History

Superball Thrower Daemon

A standalone Node.js daemon implementation of the Superball Thrower functionality, extracted from the web-based implementation. This daemon runs as a system service and provides privacy-focused routing for the Superball protocol.

Features

Complete Superball Protocol Support: Implements SUP-01 through SUP-06
NIP-44 Encryption: Secure event routing with NOSTR encryption standards
NIP-65 Relay Management: Automatic relay list publishing and management
Event Queue Processing: Delayed processing with routing instructions
Relay Authentication Testing: Automatic detection of read/write capabilities
Thrower Information Publishing: SUP-06 compliant thrower announcements
Maximum Delay Validation: Security feature to prevent excessive delays (default: 86460 seconds = 1 day + 60s)
Systemd Integration: Runs as a secure system service
Comprehensive Logging: Detailed operation logs for monitoring

Quick Start

Install the daemon:
```
chmod +x install.sh
./install.sh
```
Configure your thrower:
```
sudo nano /etc/superball/config.json
```

Start the service:

sudo systemctl enable superball-thrower
sudo systemctl start superball-thrower

Monitor the service:

sudo systemctl status superball-thrower
sudo journalctl -u superball-thrower -f

Configuration

The daemon uses /etc/superball/config.json for configuration. Key settings include:

Required Settings

privateKey: Your thrower's private key (hex format)
relays: Array of relay configurations with read/write permissions

Optional Settings

throwerInfo: Thrower Information Document settings (SUP-06)
maxDelay: Maximum delay in seconds for routing instructions (default: 86460 = 1 day + 60s)
refreshRate: How often to republish thrower info in seconds (default: 300)

Example Configuration

{
  "thrower": {
    "privateKey": "your-private-key-in-hex",
    "name": "My Superball Thrower",
    "description": "A privacy-focused Superball routing node",
    "maxDelay": 86460,
    "refreshRate": 300
  },
  "relays": [
    {
      "url": "wss://relay.laantungir.net",
      "read": true,
      "write": true
    },
    {
      "url": "wss://relay.damus.io",
      "read": true,
      "write": false
    }
  ],
  "daemon": {
    "logLevel": "info",
    "maxQueueSize": 1000,
    "autoStart": false
  }
}

Architecture

Core Components

Event Monitor: Subscribes to kind 22222 events across configured relays
Decryption Engine: Handles NIP-44 decryption of routing instructions
Queue Processor: Manages delayed event processing
Relay Manager: Tests and manages relay authentication capabilities
Publisher: Handles event forwarding and final posting

Protocol Implementation

SUP-01: Basic routing protocol support
SUP-02: Event queuing and delayed processing
SUP-03: Padding layer handling for privacy
SUP-04: Relay authentication and capability detection
SUP-05: Event validation and security checks
SUP-06: Thrower Information Document publishing

Security Features

Maximum Delay Validation: Prevents excessive routing delays (default: 86460 seconds)
Event Deduplication: Prevents processing the same event multiple times
Relay Authentication: Only uses write-capable relays for publishing
Private Key Security: Configuration file secured with proper permissions

File Structure

thrower_daemon/
├── daemon.js              # Main daemon implementation
├── package.json           # Node.js dependencies
├── config.json           # Example configuration
├── superball-thrower.service  # Systemd service file
├── install.sh            # Installation script
└── README.md             # This documentation

Dependencies

Node.js 16+: Runtime environment
nostr-tools: NOSTR protocol implementation
ws: WebSocket client for relay connections

Installation Details

The installation script (install.sh) performs the following:

System Requirements Check: Verifies Node.js and npm installation
Dependency Installation: Installs required Node.js packages
User Creation: Creates a dedicated superball system user
Directory Setup: Creates log and configuration directories
Service Installation: Installs and configures systemd service
Permission Setup: Secures files with appropriate permissions

Service Management

Start/Stop/Restart

sudo systemctl start superball-thrower
sudo systemctl stop superball-thrower
sudo systemctl restart superball-thrower

Enable/Disable Auto-start

sudo systemctl enable superball-thrower
sudo systemctl disable superball-thrower

View Status and Logs

sudo systemctl status superball-thrower
sudo journalctl -u superball-thrower -f
sudo journalctl -u superball-thrower --since "1 hour ago"

Monitoring

Log Files

System Logs: journalctl -u superball-thrower
Application Logs: /var/log/superball/daemon.log

Key Metrics to Monitor

Events Processed: Number of routing events handled
Queue Length: Current number of queued events
Relay Connections: Number of active relay connections
Authentication Status: Relay read/write capabilities

Health Checks

The daemon logs important events including:

Startup and shutdown
Relay connection status
Event processing statistics
Error conditions and recovery

Troubleshooting

Common Issues

Service Won't Start
- Check configuration file syntax: sudo journalctl -u superball-thrower
- Verify private key format (64-character hex string)
- Ensure relay URLs are valid WebSocket endpoints
No Events Being Processed
- Verify relay connections in logs
- Check if thrower info is being published
- Confirm private key corresponds to expected public key
Permission Errors
- Ensure configuration file is owned by superball user
- Check directory permissions: /var/log/superball, /etc/superball
Relay Connection Issues
- Test relay URLs manually with WebSocket tools
- Check firewall settings for outbound connections
- Verify relay authentication requirements

Debug Mode

Enable verbose logging by editing the service file:

sudo systemctl edit superball-thrower

Add:

[Service]
Environment=DEBUG=1

Security Considerations

Private Key Security

Store private keys securely in the configuration file
Use proper file permissions (600) for configuration
Consider using hardware security modules for production

Network Security

Use TLS-enabled relay connections (wss://)
Monitor relay authentication requirements
Implement firewall rules for outbound connections

System Security

Run daemon as dedicated non-privileged user
Use systemd security features (NoNewPrivileges, etc.)
Regular security updates for Node.js and dependencies

Development

Running in Development Mode

cd thrower_daemon
npm install
node daemon.js

Configuration for Development

Copy config.json to a local file and modify as needed:

cp config.json config-dev.json
# Edit config-dev.json with your settings
node daemon.js config-dev.json

Maximum Delay Feature

The daemon implements a maximum delay security feature:

Default Maximum: 86460 seconds (1 day + 60 seconds)
Purpose: Prevents attackers from creating routing instructions with excessive delays
Validation: All incoming routing instructions are validated against the configured maximum
Configuration: Set via maxDelay field in thrower configuration
Publishing: Maximum delay is published in Thrower Information Documents (SUP-06)

Contributing

This daemon is part of the Superball project. For contributions:

Follow the existing code style and patterns
Test thoroughly with multiple relay configurations
Update documentation for any new features
Ensure backward compatibility with existing configurations

License

This project follows the same license as the main Superball project.

Support

For support and questions:

Check the logs first: sudo journalctl -u superball-thrower
Review this documentation
Check the main Superball project documentation
Report issues with detailed logs and configuration (redact private keys)

⚠️ Security Warning: Always secure your private keys and never share them. The daemon handles sensitive cryptographic operations and should be deployed with appropriate security measures.

8.6 KiB Raw Permalink Blame History