super_ball_thrower/tests/README.md

Superball Protocol Test Suite

Comprehensive test suite for verifying SUP-01 through SUP-06 compliance in the Superball Thrower daemon.

Overview

This test suite validates all aspects of the Superball protocol implementation:

• SUP-01: Basic single-hop routing
• SUP-02: Multi-hop routing (2-5 hops)
• SUP-03: Padding payload handling (Type 2 payloads)
• SUP-04: Delay and jitter verification
• SUP-05: Relay authentication testing
• SUP-06: Thrower information publishing

Prerequisites

Required Tools

1. nak (Nostr Army Knife)

   go install github.com/fiatjaf/nak@latest
   

2. jq (JSON processor)

   sudo apt-get install jq  # Debian/Ubuntu
   brew install jq          # macOS
   

3. Superball Thrower daemon

   cd ..
   make
   

Running Throwers

For multi-hop tests, you need multiple thrower instances running. Create separate config files for each:

# Thrower A
cp config.example.json config_thrower_a.json
# Edit config_thrower_a.json with thrower_a private key

# Thrower B
cp config.example.json config_thrower_b.json
# Edit config_thrower_b.json with thrower_b private key

# Thrower C
cp config.example.json config_thrower_c.json
# Edit config_thrower_c.json with thrower_c private key

Start each thrower in a separate terminal:

./superball_thrower config_thrower_a.json
./superball_thrower config_thrower_b.json
./superball_thrower config_thrower_c.json

Test Structure

tests/
├── test_framework.sh          # Main test orchestrator
├── test_single_hop.sh         # SUP-01: Single-hop routing
├── test_multi_hop.sh          # SUP-02: Multi-hop routing
├── test_padding.sh            # SUP-03: Padding payloads
├── test_delays.sh             # SUP-04: Delay verification
├── test_relay_auth.sh         # SUP-05: AUTH relay handling
├── test_thrower_info.sh       # SUP-06: Thrower info publishing
├── test_end_to_end.sh         # Complete workflow test
├── helpers/
│   ├── timing_utils.sh        # Timing and delay utilities
│   └── event_utils.sh         # Event creation utilities
├── fixtures/
│   ├── test_keys.json         # Test keypairs
│   └── test_relays.json       # Test relay configurations
├── logs/                      # Test execution logs
└── results/                   # Test results

Running Tests

Run All Tests

cd tests
./test_framework.sh

or

cd tests
./test_framework.sh all

Run Specific Test

cd tests
./test_framework.sh test_single_hop
./test_framework.sh test_multi_hop
./test_framework.sh test_padding

List Available Tests

cd tests
./test_framework.sh list

View Help

cd tests
./test_framework.sh help

Test Descriptions

test_single_hop.sh (SUP-01)

Tests basic single-hop routing:

• Builder creates encrypted event
• Thrower receives and decrypts
• Thrower waits for delay
• Thrower posts to final relay
• Verifies timing and content

Duration: ~10-15 seconds
Requirements: 1 thrower running

test_multi_hop.sh (SUP-02)

Tests multi-hop routing with 3 hops:

• Creates onion-routed event (3 layers)
• Each thrower unwraps one layer
• Verifies complete routing chain
• Checks cumulative delays

Duration: ~30-45 seconds
Requirements: 3 throwers running (A, B, C)

test_padding.sh (SUP-03)

Tests padding payload handling:

• Thrower A adds padding bytes
• Creates Type 2 payload
• Thrower B performs double decryption
• Verifies padding is discarded
• Confirms content integrity

Duration: ~15-20 seconds
Requirements: 2 throwers running (A, B)

test_delays.sh (SUP-04)

Tests delay constraints with multiple values:

• Tests delays: 0s, 5s, 10s, 30s, 60s
• Verifies minimum delay respected
• Checks jitter application
• Validates timing accuracy

Duration: ~2-3 minutes
Requirements: 1 thrower running

test_relay_auth.sh (SUP-05)

Tests AUTH-required relay handling:

• Detects AUTH requirement
• Verifies relay marked as "auth-required"
• Confirms events skip AUTH relay
• Checks appropriate logging

Duration: ~5 seconds
Requirements: AUTH-required relay (optional)

test_thrower_info.sh (SUP-06)

Tests thrower information publishing:

• Queries for kind 12222 events
• Verifies all required fields
• Checks relay configurations
• Validates event structure

Duration: ~10-15 seconds
Requirements: 1 thrower running with auto-publish

test_end_to_end.sh

Complete workflow test combining all features:

• 3-hop routing chain
• Padding at first hop
• Delays at each hop
• Full protocol compliance
• Performance metrics

Duration: ~30-45 seconds
Requirements: 3 throwers running (A, B, C)

Test Configuration

Test Keys

Test keypairs are defined in fixtures/test_keys.json:

• builder: Creates initial Superball events
• thrower_a: First hop
• thrower_b: Second hop
• thrower_c: Third hop
• thrower_d: Fourth hop (for 4-hop tests)
• thrower_e: Fifth hop (for 5-hop tests)

⚠️ WARNING: These are test keys only. NEVER use in production!

Test Relays

Relay configurations are in fixtures/test_relays.json:

• primary: wss://relay.laantungir.net
• secondary: wss://relay.damus.io
• tertiary: wss://nos.lol
• final: wss://relay.nostr.band

You can modify these to use your preferred relays.

Interpreting Results

Success Output

=== Superball Protocol Test Suite ===
Starting at Mon Dec 10 14:00:00 UTC 2025

Running: test_single_hop
✓ PASSED: test_single_hop (12s)

Running: test_multi_hop
✓ PASSED: test_multi_hop (38s)

...

=== Test Summary ===
Passed:  7
Failed:  0
Skipped: 0
Total:   7

Failure Output

When a test fails, the last 20 lines of the log are displayed:

Running: test_single_hop
✗ FAILED: test_single_hop (15s)
  See log: logs/test_single_hop.log
  Last 20 lines of log:
    ERROR: Inner event not found on final relay within 30s
    This could indicate:
      - Thrower is not running
      - Network connectivity issues

Logs

Detailed logs for each test are saved in logs/:

• logs/test_single_hop.log
• logs/test_multi_hop.log
• etc.

Results summary is saved in results/summary.txt.

Troubleshooting

Test Fails: "nak command not found"

Install nak:

go install github.com/fiatjaf/nak@latest

Test Fails: "superball_thrower binary not found"

Build the daemon:

cd ..
make

Test Fails: "Event not found on relay"

Possible causes:

1. Thrower not running
2. Wrong private key in config
3. Relay connectivity issues
4. Firewall blocking WebSocket connections

Check thrower logs:

tail -f /tmp/superball_thrower.log

Test Fails: "Event arrived too early"

The thrower may not be respecting delay constraints. Check:

1. Queue processing is working
2. Delays are being applied
3. System time is correct

Multi-hop Tests Fail

Ensure all required throwers are running:

ps aux | grep superball_thrower

Each thrower needs its own config file with the correct private key.

CI/CD Integration

GitHub Actions

Example workflow:

name: Superball Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: recursive
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y jq libsecp256k1-dev libsodium-dev
          go install github.com/fiatjaf/nak@latest
      
      - name: Build
        run: make
      
      - name: Run tests
        run: |
          cd tests
          ./test_framework.sh all
      
      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v2
        with:
          name: test-results
          path: tests/results/

Contributing

When adding new tests:

1. Create test script in tests/
2. Follow naming convention: test_<feature>.sh
3. Add to TESTS array in test_framework.sh
4. Include clear documentation
5. Add expected duration and requirements
6. Provide troubleshooting guidance

License

Same as parent project.