super_ball/PROTOCOL.md

# Superball Protocol

## Overview

Superball provides location privacy for Nostr by using encrypted routing through daemon nodes. Users can post content under their real identity while completely hiding their network location.

## Protocol Structure

### Step 1: Create Signed Event
User creates and signs their normal Nostr event:
```json
{
  "kind": 1,
  "pubkey": "user_pubkey",
  "content": "Message content",
  "tags": [],
  "created_at": 1703000000,
  "id": "event_id",
  "sig": "user_signature"
}
```

### Step 2: Create Routing Instructions
User creates routing instructions:
```json
{
  "relays": [
    "wss://target-relay1.com",
    "wss://target-relay2.com",
    "wss://target-relay3.com"
  ],
  "delay": 30,
  "pad": "+150",
  "p": "superball_b_pubkey", // Next superball (optional - if missing, final posting)
  "audit": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456", // Audit pubkey (always required)
  "payment": "eCash_token_here" // Optional payment for processing
}
```

### Step 3: Encrypt and Send
User creates a routing event with NIP-44 encryption:
```json
{
  "kind": 30000, // Superball routing event
  "pubkey": "ephemeral_key",
  "content": "<nip44_encrypted_payload>",
  "tags": [
    ["p", "superball_pubkey"]
  ],
  "created_at": 1703000100,
  "id": "routing_event_id",
  "sig": "ephemeral_signature"
}
```

The encrypted payload contains:
```json
{
  "event": {
    "kind": 1,
    "pubkey": "user_pubkey",
    "content": "Message content",
    "tags": [],
    "created_at": 1703000000,
    "id": "event_id",
    "sig": "user_signature"
  },
  "routing": {
    "relays": ["wss://target-relay1.com", "wss://target-relay2.com"],
    "delay": 30,
    "pad": "+150",
    "p": "next_superball_pubkey", // Optional - if missing, final posting
    "audit": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456", // Required audit pubkey
    "payment": "eCash_token" // Optional payment
  }
}
```

## Superball Processing

1. **Receive**: Monitor for kind 30000 events with p tag = own pubkey
2. **Decrypt**: Use NIP-44 to decrypt the content
3. **Parse**: Extract the event and routing instructions
4. **Apply Padding**: Modify padding according to instructions
5. **Delay**: Wait specified time
6. **Always Rewrap**: Create new routing event to hide padding operations
7. **Forward**: Post the new routing event to specified relay

## Always Rewrap Rule

### Privacy Protection
Superballs **ALWAYS** create a new routing wrapper to prevent analysis of padding operations:
- **Consistent behavior**: Every forward looks the same (new routing event)
- **Hide operations**: No way to tell if padding was added, removed, or unchanged
- **Fresh encryption**: New ephemeral key and encryption for each hop
- **Metadata mixing**: Padding levels change unpredictably at each hop

### Routing Event Structure
Every forward creates a new kind 30000 event:
```json
{
  "kind": 30000,
  "pubkey": "<fresh_ephemeral_key>",
  "content": "<newly_encrypted_payload>",
  "tags": [
    ["p", "<next_superball_or_final_user>"],
    ["p", "<audit_pubkey_from_routing>"],
    ["padding", "<adjusted_random_data>"]
  ]
}
```

## Audit Mechanism for Security

### Purpose
The audit mechanism allows users to detect malicious Superballs that drop events, ignore timing delays, or modify padding incorrectly.

### Audit Tag Structure
- **Format**: 64-character hex string (looks like a Nostr pubkey)
- **Generation**: User creates random audit tag for each hop
- **Labeling**: Always labeled as `["p", "<audit_pubkey>"]` in routing events
- **Camouflage**: Indistinguishable from real next-hop pubkeys to observers

### How It Works
1. **User includes audit tag** in routing instructions for each hop
2. **Superball posts audit tag** as additional `p` tag when forwarding
3. **User monitors relays** for audit tag appearances
4. **Timing and size analysis** reveals compliance with instructions

### Example Audit Detection
```json
// Alice creates routing with audit tag
{
  "relays": ["wss://relay2.com"],
  "delay": 45,
  "pad": "+200",
  "p": "sball_b_real_pubkey",
  "audit": "a1b2c3...fake_pubkey_for_audit"
}

// Superball A should post this after 45s with +200 bytes:
{
  "kind": 30000,
  "tags": [
    ["p", "sball_b_real_pubkey"],     // Real next hop
    ["p", "a1b2c3...fake_pubkey"],   // Audit tag (looks identical)
    ["padding", "..."]               // +200 bytes of padding
  ]
}
```

Alice monitors relay2.com and verifies the audit tag appears with correct timing and size.

### Security Properties
- **Misbehavior Detection**: Dropped, delayed, or incorrectly padded events
- **Reputation Building**: Users can rate Superball reliability over time
- **Privacy Preserved**: Audit tags look like normal routing to observers
- **Always Active**: Every routing event includes audit verification

## Routing Instructions Fields

### Required Fields
- **`relays`**: Array of relay URLs to post to (allows multi-relay posting)
- **`delay`**: Minimum delay in seconds before forwarding

### Required Fields
- **`audit`**: 64-character hex audit tag (format: Nostr pubkey)
  - User-generated random identifier for this hop
  - Always posted as `["p", "<audit_tag>"]` in routing event
  - Enables detection of malicious Superballs

### Optional Fields
- **`pad`**: Padding instruction (`"+N"` to add, `"-N"` to remove N bytes)
  - Only valid when `p` field is present (continuing chain)
  - Ignored when `p` field missing (final hop - can't modify signed event)
- **`p`**: Pubkey of next Superball in chain
  - If present: Create routing event for next Superball (can apply padding)
  - If missing: Post final event directly to relays (end of chain, no padding changes)
- **`payment`**: eCash token for processing payment
  - Allows monetized Superball services
  - Optional - many daemons may operate for free

## Processing Logic

### Multi-Relay Posting
Superballs post to ALL specified relays in the `relays` array for redundancy and availability.

### Chain Termination
- **`p` field present**: Continue routing chain to specified Superball
- **`p` field missing**: Extract and post final event directly, end chain

## Benefits

- **Location Privacy**: User's network location completely hidden
- **Identity Preservation**: Posts appear with user's real pubkey
- **Simple Implementation**: Single NIP-44 encryption layer per hop
- **Purpose-Built**: Designed specifically for anonymous posting
- **Traffic Analysis Resistance**: Timing delays and padding protect against correlation