This is a C implementation of the Superball protocol (SUP-01 through SUP-06), providing anonymizing relay services for Nostr events. The thrower catches, unwraps, rewraps, and throws Superballs (wrapped encrypted events) with timing delays and size obfuscation to provide location privacy for Nostr users.

Features

Full Protocol Support: Implements SUP-01 through SUP-06
NIP-44 Encryption: Modern ChaCha20-based encryption for payload protection
Dual Payload Handling: Supports both routing payloads (from builder) and padding payloads (from previous thrower)
Double Decryption: Automatically handles padding payloads requiring two decryption steps
Event Queue: Delayed processing with configurable delays and random jitter
Relay Management: Automatic authentication testing and capability detection
Thrower Info Publishing: SUP-06 compliant service announcements with auto-refresh
High Performance: Written in C for minimal resource usage and maximum throughput

Architecture

The implementation uses a simplified single-file architecture in main.c (~1800 lines) with the following organization:

Includes & Constants - System headers and configuration
Data Structures - All structs and type definitions
Utility Functions - Logging, time, padding generation
Configuration Functions - JSON config loading and parsing
Crypto Functions - NIP-44 encryption/decryption wrappers
Queue Functions - Thread-safe event queue management
Relay Functions - Relay authentication and management
Event Processing Functions - Core protocol logic
Thrower Info Functions - SUP-06 publishing with auto-refresh
Main Functions - Initialization and event loop

Dependencies

nostr_core_lib (git submodule) - Provides all NOSTR protocol operations
OpenSSL - Cryptographic operations
libcurl - HTTP/WebSocket communication
libsecp256k1 - Elliptic curve cryptography
pthread - Multi-threading support

Building

Prerequisites

# Ubuntu/Debian
sudo apt-get install build-essential libssl-dev libcurl4-openssl-dev libsecp256k1-dev

# Fedora/RHEL
sudo dnf install gcc make openssl-devel libcurl-devel libsecp256k1-devel

# macOS
brew install openssl curl libsecp256k1

Build Steps

# Clone the repository with submodules
git clone --recursive https://git.laantungir.net/laantungir/super_ball_thrower.git
cd super_ball_thrower

# Build everything (including nostr_core_lib)
make

# The binary will be created as: ./superball_thrower

Build Commands

make              # Build everything
make clean        # Clean build artifacts
make distclean    # Clean everything including nostr_core_lib
sudo make install # Install to /usr/local/bin

Configuration

Create Configuration File

# Copy example configuration
cp config.example.json config.json

# Edit with your settings
nano config.json

Configuration Format

{
  "thrower": {
    "privateKey": "your_64_character_hex_private_key_here",
    "name": "My C Superball Thrower",
    "description": "High-performance C implementation",
    "maxDelay": 86460,
    "refreshRate": 300,
    "supportedSups": "1,2,3,4,5,6",
    "software": "https://git.laantungir.net/laantungir/super_ball_thrower.git",
    "version": "1.0.0"
  },
  "relays": [
    {
      "url": "wss://relay.laantungir.net",
      "read": true,
      "write": true
    }
  ],
  "daemon": {
    "logLevel": "info",
    "maxQueueSize": 1000
  }
}

Configuration Options

Thrower Section

privateKey: Your thrower's private key (64-character hex string)
name: Display name for your thrower
description: Description of your thrower service
maxDelay: Maximum delay in seconds (default: 86460 = ~24 hours)
refreshRate: How often to republish thrower info in seconds (default: 300)
supportedSups: Comma-separated list of supported SUPs (default: "1,2,3,4,5,6")
software: URL to your thrower software
version: Version string

Relays Section

url: WebSocket URL of the relay
read: Enable reading events from this relay
write: Enable writing events to this relay

Daemon Section

logLevel: Logging verbosity: "debug", "info", "warn", "error"
maxQueueSize: Maximum number of events to queue (default: 1000)

Usage

Basic Usage

# Run with default config.json
./superball_thrower

# Run with custom config file
./superball_thrower /path/to/config.json

# Show help
./superball_thrower --help

Running as a Service

systemd Service (Linux)

Create /etc/systemd/system/superball-thrower.service:

[Unit]
Description=Superball Thrower Daemon
After=network.target

[Service]
Type=simple
User=superball
WorkingDirectory=/opt/superball_thrower
ExecStart=/opt/superball_thrower/superball_thrower /opt/superball_thrower/config.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

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

View logs:

sudo journalctl -u superball-thrower -f

Protocol Flow

Single Unwrapping (Routing Payload)

Receive: Kind 22222 event with thrower's pubkey in p tag
Decrypt: Get payload with routing instructions from builder
Process: Routing instructions were created specifically for this thrower
Forward or Post: Based on presence of routing.p field

Double Unwrapping (Padding Payload)

Receive: Kind 22222 event with thrower's pubkey in p tag
First Decrypt: Get padding payload - discard padding data
Second Decrypt: Decrypt inner event to get routing instructions
Process: Routing instructions were created specifically for this thrower
Forward or Post: Based on presence of routing.p field

Forwarding Logic

If routing.p present: Forward to next thrower with padding wrapper
If routing.p missing: Post inner event directly to relays (end of chain)

Performance

Expected performance characteristics:

Throughput: 100+ events/second
Memory Usage: <100MB RAM
Latency: <100ms processing time per event
Reliability: 99.9% uptime in 24-hour operation

Security Considerations

Private Key Protection: Store private key securely, never commit to version control
Relay Authentication: Only writes to relays that don't require AUTH
Memory Safety: All decrypted data cleared after processing
No Logging: Sensitive routing information never logged
Fresh Keys: Uses ephemeral keys for each forwarding operation

Troubleshooting

Build Issues

# If nostr_core_lib fails to build
cd nostr_core_lib
./build.sh lib
cd ..
make

Runtime Issues

# Enable debug logging
# Edit config.json and set "logLevel": "debug"

# Check relay connectivity
# Verify relay URLs are accessible via WebSocket

# Verify private key format
# Must be 64-character hex string (32 bytes)

Development

Project Structure

super_ball_thrower/
├── main.c                       # Complete implementation
├── Makefile                     # Build system
├── config.example.json          # Example configuration
├── config.json                  # User configuration (gitignored)
├── README.md                    # This file
├── nostr_core_lib/              # Git submodule
└── plans/
    └── superball_thrower_c_architecture.md

Testing with Node.js Implementation

The C implementation is fully compatible with the Node.js reference implementation. You can test interoperability by:

Running both implementations simultaneously
Sending test events through the routing chain
Verifying events are properly forwarded and posted

Contributing

Contributions are welcome! Please:

Follow the existing code style
Add tests for new features
Update documentation
Submit pull requests to the main repository

License

MIT License - See LICENSE file for details

References

Support

For issues, questions, or contributions:

Repository: https://git.laantungir.net/laantungir/super_ball_thrower
Issues: Use the repository issue tracker

Version: 1.0.0
Author: Roo (Code Mode)
Last Updated: 2025-12-10