super_ball/SUPs.md

SUPs - Superball Upgrade Possibilities

SUPs (Superball Upgrade Possibilities) describe standards for the Superball anonymity protocol, including core protocol rules, Thrower behavior specifications, routing algorithms, and security mechanisms.

Terminology

• Superball: A wrapped nostr event (like a TOR onion packet) that bounces between relays and Throwers
• Thrower: A nostr-capable daemon that monitors nostr nodes, looks for superballs posted for them, grabs them, cryptographically unwraps them, rewraps them potentially with padding, then throws the superball to relay(s) when instructed

---

SUP-1: Core Protocol Specification

Abstract

This SUP defines the core Superball protocol for providing location privacy in Nostr through encrypted event routing via Thrower nodes. Users can post content under their real identity while completely hiding their network location.

Motivation

Current Nostr implementations reveal users' network locations through direct relay connections, enabling surveillance and censorship. Superball provides Tor-like anonymity while preserving message authenticity through cryptographic signatures.

Specification

Event Kind

• Kind 22222: Superball routing event

Routing Event Structure

{
  "kind": 22222,
  "pubkey": "<ephemeral_key>",
  "content": "<nip44_encrypted_payload>",
  "tags": [
    ["p", "<thrower_pubkey>"],
    ["p", "<audit_pubkey>"],
    ["padding", "<random_data>"]
  ],
  "created_at": "<timestamp>",
  "id": "<event_id>",
  "sig": "<ephemeral_signature>"
}

Encrypted Payload Format

{
  "event": { /* Original signed event or next routing event */ },
  "routing": {
    "relays": ["wss://relay1.com", "wss://relay2.com"],
    "delay": 30,
    "padding": "+150",
    "p": "next_thrower_pubkey", // Optional
    "audit": "audit_verification_pubkey", // Required
    "payment": "ecash_token" // Optional
  }
}

Processing Rules

1. Always Rewrap: Create new routing event for every forward
2. Audit Verification: Include audit tag as p tag in routing event
3. Delay Compliance: Wait specified time plus random jitter
4. Padding Operations: Apply size modifications as instructed
5. Multi-Relay Posting: Post to all specified relays
6. Relay Authentication Constraint: Throwers can only write to relays that do not require authentication (AUTH)

Relay Authentication Requirements

Critical Constraint: Throwers MUST be able to post events signed by other users without possessing their private keys. This creates a fundamental limitation:

• Read Capability: Throwers can monitor any relay (AUTH or non-AUTH) for incoming Superballs
• Write Capability: Throwers can ONLY post to relays that do not require NIP-42 authentication
• NIP-65 Compliance: Throwers must maintain accurate relay lists distinguishing read vs write capabilities

NIP-65 Relay List Format for Throwers:

{
  "kind": 10002,
  "tags": [
    ["r", "wss://noauth.relay.com"],                    // Read+Write (no AUTH required)
    ["r", "wss://auth-required.relay.com", "read"],     // Read only (AUTH required)
    ["r", "wss://write-only.relay.com", "write"]        // Write only (no AUTH required)
  ]
}

Authentication Testing: Throwers should automatically test relay authentication requirements by attempting anonymous event publication and classify relays accordingly.

Rationale

The protocol uses NIP-44 encryption for simplicity over NIP-59 gift wrapping, includes mandatory audit mechanisms for security, and employs consistent rewrapping to prevent traffic analysis.

---

SUP-2: Audit Security Mechanism

Abstract

This SUP defines the audit mechanism that allows users to detect malicious Throwers through cryptographic verification of proper event forwarding.

Motivation

Users need the ability to verify that Throwers are honestly forwarding Superballs according to instructions, including proper delays, padding operations, and relay posting.

Specification

Audit Tag Format

• Length: 64 hexadecimal characters
• Format: Appears as valid Nostr pubkey
• Generation: Cryptographically secure random per-hop
• Posting: Always included as ["p", "<audit_tag>"] in routing events

User Monitoring

1. Generate unique audit tag for each routing hop
2. Monitor specified relays for audit tag appearance
3. Verify timing matches delay instructions
4. Verify event size matches padding operations
5. Build reputation scores for Throwers based on compliance

Privacy Properties

• Audit tags indistinguishable from real next-hop pubkeys
• Only originating user knows which tags are audit verification
• No correlation possible between different users' audit tags

Implementation

// Generate audit tag
const auditTag = bytesToHex(randomBytes(32));

// Monitor relay for audit appearance
const monitorAudit = async (relay, auditTag, expectedDelay, expectedSize) => {
  const startTime = Date.now();
  
  relay.subscribe([{
    kinds: [22222],
    "#p": [auditTag]
  }], {
    onevent: (event) => {
      const actualDelay = (event.created_at * 1000) - startTime;
      const actualSize = JSON.stringify(event).length;
      
      // Verify compliance
      const delayCompliant = Math.abs(actualDelay - expectedDelay) < TOLERANCE;
      const sizeCompliant = Math.abs(actualSize - expectedSize) < PADDING_TOLERANCE;
      
      recordThrowerReputation(event.pubkey, delayCompliant && sizeCompliant);
    }
  });
};

---

SUP-3: Daemon Operational Rules

Abstract

This SUP provides operational guidelines for Thrower operators, including security practices, resource management, and privacy protection protocols.

Security Rules

1. Never log sensitive data - Don't store decrypted content or routing information
2. Generate fresh keys - Use new ephemeral keys for each forward operation
3. Validate everything - Check signatures, event structure, and relay URLs
4. Rate limiting - Prevent abuse through request throttling
5. Memory clearing - Immediately clear decrypted data after processing

Privacy Rules

1. No correlation - Don't link input events to output events in logs
2. Random timing - Add jitter to specified delays
3. Traffic mixing - Send decoy traffic when idle (optional enhancement)
4. Connection rotation - Periodically reconnect to prevent fingerprinting

Processing Rules

1. First come, first served - Process events in arrival order
2. Fail silently - Drop invalid events without response
3. Retry logic - Attempt relay posting 3 times before giving up
4. Resource limits - Drop oldest queued events if memory/queue full

---

SUP-4: Multi-Path Routing Enhancement

Abstract

This SUP proposes an enhancement allowing users to send the same event through multiple independent Thrower chains simultaneously for increased security against coordinated attacks.

Motivation

Single routing chains are vulnerable to adversaries who control multiple Throwers in the path. Multi-path routing increases security by requiring adversaries to control Throwers across multiple independent chains.

Specification

Multi-Path Event Structure

{
  "paths": [
    {
      "chain_id": "random_identifier_1",
      "routing": { /* Standard routing instructions */ }
    },
    {
      "chain_id": "random_identifier_2", 
      "routing": { /* Different Throwers and relays */ }
    }
  ],
  "threshold": 1 // Minimum successful deliveries required
}

Implementation Requirements

• Generate independent routing chains with no overlapping Throwers
• Use different target relays for each path
• Include chain_id in audit mechanism for path-specific monitoring
• Consider delivery successful when threshold number of paths complete

Security Analysis

• Resistance: Requires adversary control of nodes across multiple chains
• Redundancy: Event delivery succeeds even if some paths are compromised
• Cost: Increases bandwidth and processing requirements
• Detection: Path-specific audit tags enable per-chain monitoring

---

SUP-5: Payment Integration Specification

Abstract

This SUP defines the integration of eCash payment tokens for monetized Thrower services, enabling sustainable economic models for privacy infrastructure.

Specification

Payment Field Format

{
  "payment": {
    "type": "ecash",
    "token": "base64_encoded_ecash_token", 
    "amount": 100, // satoshis
    "mint": "https://mint.example.com"
  }
}

Processing Rules

1. Validate token - Verify eCash token authenticity with mint
2. Check amount - Ensure payment meets minimum service fee
3. Redeem atomically - Claim payment only after successful forwarding
4. Rate limits - Higher processing priority for paid requests

Economic Considerations

• Free tier with limited throughput for accessibility
• Premium tiers with guaranteed processing times
• Dynamic pricing based on network congestion
• Reputation bonuses for consistent payment

---

---

SUP-6: Thrower Information Document

Abstract

This SUP defines a standardized announcement mechanism for Throwers to advertise their services and signal their online status through replaceable events.

Motivation

Users need a reliable way to discover available Throwers and verify their operational status. This SUP provides a standardized format for Throwers to announce their services and capabilities. By specifying a refresh rate, one can see if the document has been created within that refresh rate, and if so, you know that the Thrower is online.

Specification

Event Kind

• Kind 12222: Thrower Information Document (Replaceable Event)

Event Structure

{
  "id": "<32-bytes lowercase hex-encoded sha256 of the serialized event data>",
  "pubkey": "<32-bytes lowercase hex-encoded public key of the Thrower>",
  "created_at": "<unix timestamp in seconds>",
  "kind": 12222,
  "tags": [
    ["name", "<string identifying Thrower>"],
    ["description", "<string with detailed information>"],
    ["banner", "<a link to an image (e.g. in .jpg, or .png format)>"],
    ["icon", "<a link to an icon (e.g. in .jpg, or .png format>)"],
    ["pubkey", "<administrative contact pubkey>"],
    ["contact", "<administrative alternate contact>"],
    ["supported_sups", "<a list of SUP numbers supported by the Thrower>"],
    ["software", "<string identifying Thrower software URL>"],
    ["version", "<string version identifier>"],
    ["privacy_policy", "<a link to a text file describing the Thrower's privacy policy>"],
    ["terms_of_service", "<a link to a text file describing the Thrower's terms of service>"],
    ["refresh_rate", "<if the Thrower is online, it will refresh this document within this many seconds>"]
  ],
  "content": "<arbitrary string>",
  "sig": "<64-bytes lowercase hex of the signature>"
}

Operational Requirements

1. Service Announcement: Inform users on a relay of the Thrower's presence
2. Liveness Signal: By updating the document within its refresh rate, signals that the Thrower is currently online
3. Discovery: Enable automated discovery of available Throwers by clients

Implementation Guidelines

• Update frequency should indicate operational status
• Include comprehensive service information in tags
• Use standard URLs for policy documents
• Maintain consistent pubkey identity across announcements

Rationale

Standardized service announcements enable better user experience through automated Thrower discovery and verification of operational status through regular updates.

---

Future SUP Topics

Proposed Enhancements

• SUP-7: Zero-Knowledge Proof Integration for Verifiable Delays
• SUP-8: Decentralized Thrower Discovery Protocol Enhancement
• SUP-9: Quantum-Resistant Encryption Migration
• SUP-10: Mobile Client Optimizations
• SUP-11: Governance and Protocol Upgrade Mechanisms

Research Areas

• Traffic analysis resistance measurements
• Economic attack vectors and mitigations
• Integration with other privacy protocols
• Scalability optimizations
• Censorship resistance enhancements

---

Contributing

SUPs follow the collaborative development process:

1. Draft: Create initial specification
2. Discussion: Community review and feedback
3. Implementation: Reference implementations
4. Testing: Security and compatibility testing
5. Final: Adoption by Superball ecosystem

Submit SUP proposals through the project repository with detailed technical specifications, security analysis, and implementation considerations.