v0.0.1 - Up and running

2025-12-10 10:17:24 -04:00
parent d436a4927d
commit 60543cf7c4
11 changed files with 2552 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,4 +1,308 @@
-Thrower
+# Superball Thrower - C Implementation

-This is an implementaion of a superball thower written in C99
+A high-performance, privacy-focused Superball Thrower daemon implemented in C using the nostr_core_lib.

+## Overview
+
+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:
+
+1. **Includes & Constants** - System headers and configuration
+2. **Data Structures** - All structs and type definitions
+3. **Utility Functions** - Logging, time, padding generation
+4. **Configuration Functions** - JSON config loading and parsing
+5. **Crypto Functions** - NIP-44 encryption/decryption wrappers
+6. **Queue Functions** - Thread-safe event queue management
+7. **Relay Functions** - Relay authentication and management
+8. **Event Processing Functions** - Core protocol logic
+9. **Thrower Info Functions** - SUP-06 publishing with auto-refresh
+10. **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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# Copy example configuration
+cp config.example.json config.json
+
+# Edit with your settings
+nano config.json
+```
+
+### Configuration Format
+
+```json
+{
+  "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
+
+```bash
+# 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`:
+
+```ini
+[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:
+
+```bash
+sudo systemctl enable superball-thrower
+sudo systemctl start superball-thrower
+sudo systemctl status superball-thrower
+```
+
+View logs:
+
+```bash
+sudo journalctl -u superball-thrower -f
+```
+
+## Protocol Flow
+
+### Single Unwrapping (Routing Payload)
+1. **Receive**: Kind 22222 event with thrower's pubkey in p tag
+2. **Decrypt**: Get payload with routing instructions from builder
+3. **Process**: Routing instructions were created specifically for this thrower
+4. **Forward or Post**: Based on presence of `routing.p` field
+
+### Double Unwrapping (Padding Payload)
+1. **Receive**: Kind 22222 event with thrower's pubkey in p tag
+2. **First Decrypt**: Get padding payload - discard padding data
+3. **Second Decrypt**: Decrypt inner event to get routing instructions
+4. **Process**: Routing instructions were created specifically for this thrower
+5. **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
+
+1. **Private Key Protection**: Store private key securely, never commit to version control
+2. **Relay Authentication**: Only writes to relays that don't require AUTH
+3. **Memory Safety**: All decrypted data cleared after processing
+4. **No Logging**: Sensitive routing information never logged
+5. **Fresh Keys**: Uses ephemeral keys for each forwarding operation
+
+## Troubleshooting
+
+### Build Issues
+
+```bash
+# If nostr_core_lib fails to build
+cd nostr_core_lib
+./build.sh lib
+cd ..
+make
+```
+
+### Runtime Issues
+
+```bash
+# 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:
+
+1. Running both implementations simultaneously
+2. Sending test events through the routing chain
+3. Verifying events are properly forwarded and posted
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Follow the existing code style
+2. Add tests for new features
+3. Update documentation
+4. Submit pull requests to the main repository
+
+## License
+
+MIT License - See LICENSE file for details
+
+## References
+
+- [Superball Protocol Documentation](super_ball/SUPs.md)
+- [Thrower Rules](super_ball/THROWER.md)
+- [nostr_core_lib](https://git.laantungir.net/laantungir/nostr_core_lib)
+- [NOSTR Protocol](https://github.com/nostr-protocol/nostr)
+
+## 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