super_ball/SUPs.md

# SUPs - Superball Upgrade Possibilities

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

## SUP Types

- **Standards Track**: SUPs that affect protocol compatibility
- **Informational**: General guidelines and information  
- **Process**: Procedures and governance for the SUP process

## SUP Status

- **Draft**: Initial specification under development
- **Proposed**: Ready for community review
- **Final**: Accepted and implemented
- **Replaced**: Superseded by newer SUP
- **Withdrawn**: No longer pursued

---

## SUP-1: Core Protocol Specification

**Type**: Standards Track  
**Status**: Final  
**Author**: Alice & Contributors  
**Created**: 2024-01-17  

### Abstract

This SUP defines the core Superball protocol for providing location privacy in Nostr through encrypted event routing via daemon 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
```json
{
  "kind": 22222,
  "pubkey": "<ephemeral_key>",
  "content": "<nip44_encrypted_payload>",
  "tags": [
    ["p", "<superball_pubkey>"],
    ["p", "<audit_pubkey>"],
    ["padding", "<random_data>"]
  ],
  "created_at": "<timestamp>",
  "id": "<event_id>",
  "sig": "<ephemeral_signature>"
}
```

#### Encrypted Payload Format
```json
{
  "event": { /* Original signed event or next routing event */ },
  "routing": {
    "relays": ["wss://relay1.com", "wss://relay2.com"],
    "delay": 30,
    "padding": "+150",
    "p": "next_superball_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

### 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

**Type**: Standards Track  
**Status**: Final  
**Author**: Alice & Contributors  
**Created**: 2024-01-17  

### Abstract

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

### Motivation

Users need the ability to verify that Superballs are honestly forwarding events 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 Superballs 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

```javascript
// 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;
      
      recordSuperballReputation(event.pubkey, delayCompliant && sizeCompliant);
    }
  });
};
```

---

## SUP-3: Daemon Operational Rules  

**Type**: Informational  
**Status**: Final  
**Author**: Superball Operators  
**Created**: 2024-01-17  

### Abstract

This SUP provides operational guidelines for Superball daemon 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

**Type**: Standards Track  
**Status**: Draft  
**Author**: Security Researchers  
**Created**: 2024-01-17  

### Abstract

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

### Motivation

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

### Specification

#### Multi-Path Event Structure
```json
{
  "paths": [
    {
      "chain_id": "random_identifier_1",
      "routing": { /* Standard routing instructions */ }
    },
    {
      "chain_id": "random_identifier_2", 
      "routing": { /* Different Superballs and relays */ }
    }
  ],
  "threshold": 1 // Minimum successful deliveries required
}
```

#### Implementation Requirements
- Generate independent routing chains with no overlapping Superballs
- 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

**Type**: Standards Track  
**Status**: Proposed  
**Author**: Economic Protocol Designers  
**Created**: 2024-01-17  

### Abstract

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

### Specification

#### Payment Field Format
```json
{
  "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

---

## Future SUP Topics

### Proposed Enhancements
- **SUP-6**: Zero-Knowledge Proof Integration for Verifiable Delays
- **SUP-7**: Decentralized Superball Discovery Protocol  
- **SUP-8**: Quantum-Resistant Encryption Migration
- **SUP-9**: Mobile Client Optimizations
- **SUP-10**: 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.