super_ball/Trash/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:

{
  "kind": 1,
  "pubkey": "user_pubkey",
  "content": "Message content",
  "tags": [],
  "created_at": 1702222200,
  "id": "event_id",
  "sig": "user_signature"
}

Step 2: Create Routing Instructions

User creates routing instructions:

{
  "relays": [
    "wss://target-relay1.com",
    "wss://target-relay2.com",
    "wss://target-relay3.com"
  ],
  "delay": 30,
  "padding": "+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:

{
  "kind": 22222, // 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:

{
  "event": {
    "kind": 1,
    "pubkey": "user_pubkey",
    "content": "Message content",
    "tags": [],
    "created_at": 1702222200,
    "id": "event_id",
    "sig": "user_signature"
  },
  "routing": {
    "relays": ["wss://target-relay1.com", "wss://target-relay2.com"],
    "delay": 30,
    "padding": "+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 22222 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 22222 event:

{
  "kind": 22222,
  "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

// Alice creates routing with audit tag
{
  "relays": ["wss://relay2.com"],
  "delay": 45,
  "padding": "+200",
  "p": "sball_b_real_pubkey",
  "audit": "a1b2c3...fake_pubkey_for_audit"
}

// Superball A should post this after 45s with +200 bytes:
{
  "kind": 22222,
  "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