laantungir
/
super_ball
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Created kind 12222

This commit is contained in:
Your Name 2025-09-18 17:18:47 -04:00
parent 6cf5d6c50e
commit e9c8fccc9f
9 changed files with 2574 additions and 2645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
EXAMPLE.md
View File

@ -5,8 +5,8 @@ Alice wants to post a message under her real identity while hiding her location
### Participants ### Participants
- **Alice**: Original sender (pubkey: `alice123...`) - **Alice**: Original sender (pubkey: `alice123...`)
- **Superball A**: First hop (pubkey: `sball_a789...`) - **Thrower A**: First hop (pubkey: `thrower_a789...`)
- **Superball B**: Second hop (pubkey: `sball_b012...`) - **Thrower B**: Second hop (pubkey: `thrower_b012...`)
- **Relay1**: `wss://relay1.com` (where Alice posts) - **Relay1**: `wss://relay1.com` (where Alice posts)
- **Relay2**: `wss://relay2.com` (intermediate relay) - **Relay2**: `wss://relay2.com` (intermediate relay)
- **Relay3**: `wss://relay3.com` (where final message appears) - **Relay3**: `wss://relay3.com` (where final message appears)
@ -26,18 +26,17 @@ Alice wants to post a message under her real identity while hiding her location
} }
``` ```
### 2. Alice Encrypts Instructions for Superball B (Final Hop) ### 2. Alice Encrypts Instructions for Thrower B (Final Hop)
Payload for Superball B (final hop - no `p` field): Payload for Thrower B (final hop - no `p` field):
```json ```json
{ {
"event": { /* Alice's signed event above */ }, "event": { /* Alice's signed event above */ },
"routing": { "routing": {
"relays": ["wss://relay3.com", "wss://relay4.com"], "relays": ["wss://relay3.com", "wss://relay4.com"],
"delay": 15, "delay": 15,
"audit": "audit_tag_b_456def",
"payment": "eCash_ZYX321..." // Optional payment "payment": "eCash_ZYX321..." // Optional payment
// No "p" field - this means final posting // No "p" field - this means final posting
// No "pad" field - can't modify signed event
// No "audit" field - can't audit final signed event - no need
} }
} }
``` ```
@ -47,24 +46,24 @@ Creates routing event:
{ {
"kind": 22222, "kind": 22222,
"pubkey": "ephemeral_key_2", "pubkey": "ephemeral_key_2",
"content": "<encrypted_payload_for_superball_b>", "content": "<encrypted_payload_for_thrower_b>",
"tags": [["p", "sball_b012..."]], "tags": [["p", "thrower_b012..."]],
"created_at": 1703000100, "created_at": 1703000100,
"id": "routing_for_b", "id": "routing_for_b",
"sig": "ephemeral_signature_2" "sig": "ephemeral_signature_2"
} }
``` ```
### 3. Alice Encrypts Instructions for Superball A (First Hop) ### 3. Alice Encrypts Instructions for Thrower A (First Hop)
Payload for Superball A (continuing chain): Payload for Thrower A (continuing chain):
```json ```json
{ {
"event": { /* routing event for Superball B above */ }, "event": { /* routing event for Thrower B above */ },
"routing": { "routing": {
"relays": ["wss://relay2.com"], "relays": ["wss://relay2.com"],
"delay": 45, "delay": 45,
"padding": "+200", "add_padding_bytes": 200,
"p": "sball_b012...", // Next Superball in chain "p": "thrower_b012...", // Next Thrower in chain
"audit": "1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890", "audit": "1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
"payment": "eCash_A1B2C3..." // Optional payment "payment": "eCash_A1B2C3..." // Optional payment
} }
@ -76,11 +75,8 @@ Alice posts this to Relay1:
{ {
"kind": 22222, "kind": 22222,
"pubkey": "ephemeral_key_1", "pubkey": "ephemeral_key_1",
"content": "<encrypted_payload_for_superball_a>", "content": "<encrypted_payload_for_thrower_a>",
"tags": [ "tags": [["p", "thrower_a789..."]],
["p", "sball_a789..."],
["p", "fake audit tag..."],
],
"created_at": 1703000200, "created_at": 1703000200,
"id": "routing_for_a", "id": "routing_for_a",
"sig": "ephemeral_signature_1" "sig": "ephemeral_signature_1"
@ -91,42 +87,46 @@ Alice posts this to Relay1:
**T+0**: Alice posts routing event to Relay1 **T+0**: Alice posts routing event to Relay1
``` ```
Relay1: kind 22222 event (p tag = sball_a789...) Relay1: kind 22222 event (p tag = thrower_a789...)
``` ```
**T+5**: Superball A processes **T+5**: Thrower A processes
- Decrypts payload - Decrypts payload
- Sees: relay2.com, delay 45s, padding +200 - Sees: relay2.com, delay 45s, add_padding_bytes 200, next hop thrower_b012...
- Needs to ADD padding, so creates new wrapper - Creates padding-wrapper payload around the inner encrypted event
- Queues for 45-second delay - Queues for 45-second delay
**T+50**: Superball A always rewraps (consistent behavior) **T+50**: Thrower A forwards with padding wrapper
``` ```
Relay2: NEW routing event (always looks the same) Relay2: NEW routing event with padding wrapper
{ {
"kind": 22222, "kind": 22222,
"pubkey": "superball_a_ephemeral_key", // Fresh key "pubkey": "thrower_a_ephemeral_key", // Fresh key
"content": "<newly_encrypted_payload>", // Re-encrypted "content": "<padding_wrapper_payload>", // Contains inner event + padding
"tags": [ "tags": [
["p", "sball_b012..."], // Real next hop ["p", "thrower_b012..."], // Real next hop
["p", "1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890"], // Audit tag ["p", "1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890"] // Audit tag
["padding", "random_data_1..."], // Adjusted padding
["padding", "random_data_2..."], // (+200 bytes added)
["padding", "random_data_3..."]
] ]
} }
``` ```
Alice monitors relay2.com and sees her audit tag `1a2b3c4d5e6f...` appear at T+50 with correct +200 byte padding, confirming Superball A is honest. Where the padding_wrapper_payload contains:
```json
{
"event": { /* The still-encrypted inner event for Thrower B */ },
"padding": "random_padding_data_200_bytes_worth"
}
```
**T+55**: Superball B processes Alice monitors relay2.com and sees her audit tag `1a2b3c4d5e6f...` appear at T+50, confirming Thrower A is honest.
- Decrypts payload
- Sees: Alice's event + instructions (relays=[relay3.com, relay4.com], delay 15s) **T+55**: Thrower B processes
- First decrypt: Gets padding wrapper payload - discards padding
- Second decrypt: Gets Alice's event + routing instructions (relays=[relay3.com, relay4.com], delay 15s)
- NO `p` field - this means final posting, extract and post Alice's event exactly as-is - NO `p` field - this means final posting, extract and post Alice's event exactly as-is
- Cannot modify padding on signed event
- Queues for 15-second delay - Queues for 15-second delay
**T+70**: Superball B posts Alice's final event (end of chain) **T+70**: Thrower B posts Alice's final event (end of chain)
``` ```
Relay3 AND Relay4: Alice's original signed event appears exactly as she created it Relay3 AND Relay4: Alice's original signed event appears exactly as she created it
{ {
@ -145,16 +145,16 @@ Alice's message now appears on both relay3.com and relay4.com for redundancy.
## Privacy and Security Achieved ## Privacy and Security Achieved
- **Alice's location**: Completely hidden from surveillance - **Alice's location**: Completely hidden from surveillance
- **Message origin**: Appears to come from Superball B's location - **Message origin**: Appears to come from Thrower B's location
- **Traffic analysis**: 65-second delay + size changes prevent correlation - **Traffic analysis**: 65-second delay + size changes prevent correlation
- **Identity preserved**: Alice's real pubkey and signature maintained - **Identity preserved**: Alice's real pubkey and signature maintained
- **Plausible deniability**: No proof Alice initiated the posting - **Plausible deniability**: No proof Alice initiated the posting
- **Malicious node detection**: Audit tags allow Alice to verify proper forwarding - **Malicious node detection**: Audit tags allow Alice to verify proper forwarding
- **Accountability**: Bad Superballs can be identified and avoided - **Accountability**: Bad Throwers can be identified and avoided
### Audit Trail for Alice ### Audit Trail for Alice
- **T+50**: Audit tag `1a2b3c4d5e6f...` appears on relay2.com (✓ Superball A honest) - **T+50**: Audit tag `1a2b3c4d5e6f...` appears on relay2.com (✓ Thrower A honest)
- **T+70**: Final message appears on relay3.com and relay4.com (✓ Superball B honest) - **T+70**: Final message appears on relay3.com and relay4.com (✓ Thrower B honest)
- **Size verification**: Event sizes match expected padding operations - **Size verification**: Event sizes match expected padding operations
- **Timing verification**: Delays match requested timeouts - **Timing verification**: Delays match requested timeouts

20
README.md
View File

@ -1,29 +1,33 @@
# Superball # Superball
![superball](super_ball.jpg) ![superball](super_ball.jpg)
Superball provides Tor-like location privacy for Nostr users. It's a daemon that bounces encrypted events between relays, allowing users to post content under their real identity while completely hiding their network location. Superball provides Tor-like location privacy for Nostr users. A **Superball** is a wrapped nostr event, similar to a TOR onion packet, that bounces between nostr relays and **Throwers**.
A **Thrower** is 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) that it is instructed to, when it is instructed to.
## How It Works ## How It Works
1. **User creates content** - Normal signed Nostr event with their real pubkey 1. **User creates content** - Normal signed Nostr event with their real pubkey
2. **Encrypt with routing** - Bundle event + routing instructions, encrypt to Superball daemon 2. **Wrap as Superball** - Bundle event + routing instructions, encrypt to Thrower daemon
3. **Anonymous forwarding** - Event bounces through multiple daemons with delays and padding 3. **Anonymous bouncing** - Superball bounces through multiple Throwers with delays and padding
4. **Final posting** - Original event appears on target relay with user's identity but from daemon's location 4. **Final posting** - Original event appears on target relay with user's identity but from Thrower's location
## Key Features ## Key Features
- **Location Privacy**: Hide your network location while preserving your identity - **Location Privacy**: Hide your network location while preserving your identity
- **Traffic Analysis Resistance**: Random delays and size padding prevent correlation - **Traffic Analysis Resistance**: Random delays and size padding prevent correlation
- **Simple Protocol**: Uses NIP-44 encryption with new kind 22222 for routing - **Simple Protocol**: Uses NIP-44 encryption with new kind 22222 for routing
- **Flexible Routing**: Support for multi-hop paths through multiple daemons - **Flexible Routing**: Support for multi-hop paths through multiple Throwers
- **Signature Preservation**: Original event signatures maintained for authenticity - **Signature Preservation**: Original event signatures maintained for authenticity
- **Audit Security**: Detect and avoid malicious Superballs through cryptographic verification - **Audit Security**: Detect and avoid malicious Throwers through cryptographic verification
## Documentation ## Documentation
- [`PROTOCOL.md`](PROTOCOL.md) - Technical protocol specification - [`THROWER.md`](THROWER.md) - Rules and behavior for Thrower operators
- [`EXAMPLE.md`](EXAMPLE.md) - Complete walkthrough example - [`EXAMPLE.md`](EXAMPLE.md) - Complete walkthrough example
- [`DAEMON.md`](DAEMON.md) - Rules and behavior for Superball daemon operators - [`SUPs.md`](SUPs.md) - Superball Upgrade Proposals
Perfect for journalists, activists, or anyone who needs to protect their physical location while maintaining accountability for their public statements. Perfect for journalists, activists, or anyone who needs to protect their physical location while maintaining accountability for their public statements.

140
SUPs.md
View File

@ -1,33 +1,19 @@
# SUPs - Superball Upgrade Possibilities # 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. SUPs (Superball Upgrade Possibilities) describe standards for the Superball anonymity protocol, including core protocol rules, Thrower behavior specifications, routing algorithms, and security mechanisms.
## SUP Types ## 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
- **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 ## SUP-1: Core Protocol Specification
**Type**: Standards Track
**Status**: Final
**Author**: Alice & Contributors
**Created**: 2024-01-17
### Abstract ### 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. 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 ### Motivation
@ -45,7 +31,7 @@ Current Nostr implementations reveal users' network locations through direct rel
"pubkey": "<ephemeral_key>", "pubkey": "<ephemeral_key>",
"content": "<nip44_encrypted_payload>", "content": "<nip44_encrypted_payload>",
"tags": [ "tags": [
["p", "<superball_pubkey>"], ["p", "<thrower_pubkey>"],
["p", "<audit_pubkey>"], ["p", "<audit_pubkey>"],
["padding", "<random_data>"] ["padding", "<random_data>"]
], ],
@ -63,7 +49,7 @@ Current Nostr implementations reveal users' network locations through direct rel
"relays": ["wss://relay1.com", "wss://relay2.com"], "relays": ["wss://relay1.com", "wss://relay2.com"],
"delay": 30, "delay": 30,
"padding": "+150", "padding": "+150",
"p": "next_superball_pubkey", // Optional "p": "next_thrower_pubkey", // Optional
"audit": "audit_verification_pubkey", // Required "audit": "audit_verification_pubkey", // Required
"payment": "ecash_token" // Optional "payment": "ecash_token" // Optional
} }
@ -85,18 +71,13 @@ The protocol uses NIP-44 encryption for simplicity over NIP-59 gift wrapping, in
## SUP-2: Audit Security Mechanism ## SUP-2: Audit Security Mechanism
**Type**: Standards Track
**Status**: Final
**Author**: Alice & Contributors
**Created**: 2024-01-17
### Abstract ### Abstract
This SUP defines the audit mechanism that allows users to detect malicious Superballs through cryptographic verification of proper event forwarding. This SUP defines the audit mechanism that allows users to detect malicious Throwers through cryptographic verification of proper event forwarding.
### Motivation ### Motivation
Users need the ability to verify that Superballs are honestly forwarding events according to instructions, including proper delays, padding operations, and relay posting. Users need the ability to verify that Throwers are honestly forwarding Superballs according to instructions, including proper delays, padding operations, and relay posting.
### Specification ### Specification
@ -111,7 +92,7 @@ Users need the ability to verify that Superballs are honestly forwarding events
2. Monitor specified relays for audit tag appearance 2. Monitor specified relays for audit tag appearance
3. Verify timing matches delay instructions 3. Verify timing matches delay instructions
4. Verify event size matches padding operations 4. Verify event size matches padding operations
5. Build reputation scores for Superballs based on compliance 5. Build reputation scores for Throwers based on compliance
#### Privacy Properties #### Privacy Properties
- Audit tags indistinguishable from real next-hop pubkeys - Audit tags indistinguishable from real next-hop pubkeys
@ -140,7 +121,7 @@ const monitorAudit = async (relay, auditTag, expectedDelay, expectedSize) => {
const delayCompliant = Math.abs(actualDelay - expectedDelay) < TOLERANCE; const delayCompliant = Math.abs(actualDelay - expectedDelay) < TOLERANCE;
const sizeCompliant = Math.abs(actualSize - expectedSize) < PADDING_TOLERANCE; const sizeCompliant = Math.abs(actualSize - expectedSize) < PADDING_TOLERANCE;
recordSuperballReputation(event.pubkey, delayCompliant && sizeCompliant); recordThrowerReputation(event.pubkey, delayCompliant && sizeCompliant);
} }
}); });
}; };
@ -150,14 +131,9 @@ const monitorAudit = async (relay, auditTag, expectedDelay, expectedSize) => {
## SUP-3: Daemon Operational Rules ## SUP-3: Daemon Operational Rules
**Type**: Informational
**Status**: Final
**Author**: Superball Operators
**Created**: 2024-01-17
### Abstract ### Abstract
This SUP provides operational guidelines for Superball daemon operators, including security practices, resource management, and privacy protection protocols. This SUP provides operational guidelines for Thrower operators, including security practices, resource management, and privacy protection protocols.
### Security Rules ### Security Rules
1. **Never log sensitive data** - Don't store decrypted content or routing information 1. **Never log sensitive data** - Don't store decrypted content or routing information
@ -182,18 +158,13 @@ This SUP provides operational guidelines for Superball daemon operators, includi
## SUP-4: Multi-Path Routing Enhancement ## SUP-4: Multi-Path Routing Enhancement
**Type**: Standards Track
**Status**: Draft
**Author**: Security Researchers
**Created**: 2024-01-17
### Abstract ### 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. 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 ### 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. 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 ### Specification
@ -207,7 +178,7 @@ Single routing chains are vulnerable to adversaries who control multiple nodes i
}, },
{ {
"chain_id": "random_identifier_2", "chain_id": "random_identifier_2",
"routing": { /* Different Superballs and relays */ } "routing": { /* Different Throwers and relays */ }
} }
], ],
"threshold": 1 // Minimum successful deliveries required "threshold": 1 // Minimum successful deliveries required
@ -215,7 +186,7 @@ Single routing chains are vulnerable to adversaries who control multiple nodes i
``` ```
#### Implementation Requirements #### Implementation Requirements
- Generate independent routing chains with no overlapping Superballs - Generate independent routing chains with no overlapping Throwers
- Use different target relays for each path - Use different target relays for each path
- Include chain_id in audit mechanism for path-specific monitoring - Include chain_id in audit mechanism for path-specific monitoring
- Consider delivery successful when threshold number of paths complete - Consider delivery successful when threshold number of paths complete
@ -231,14 +202,9 @@ Single routing chains are vulnerable to adversaries who control multiple nodes i
## SUP-5: Payment Integration Specification ## SUP-5: Payment Integration Specification
**Type**: Standards Track
**Status**: Proposed
**Author**: Economic Protocol Designers
**Created**: 2024-01-17
### Abstract ### Abstract
This SUP defines the integration of eCash payment tokens for monetized Superball services, enabling sustainable economic models for privacy infrastructure. This SUP defines the integration of eCash payment tokens for monetized Thrower services, enabling sustainable economic models for privacy infrastructure.
### Specification ### Specification
@ -268,14 +234,76 @@ This SUP defines the integration of eCash payment tokens for monetized Superball
--- ---
---
## 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
```json
{
"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 ## Future SUP Topics
### Proposed Enhancements ### Proposed Enhancements
- **SUP-6**: Zero-Knowledge Proof Integration for Verifiable Delays - **SUP-7**: Zero-Knowledge Proof Integration for Verifiable Delays
- **SUP-7**: Decentralized Superball Discovery Protocol - **SUP-8**: Decentralized Thrower Discovery Protocol Enhancement
- **SUP-8**: Quantum-Resistant Encryption Migration - **SUP-9**: Quantum-Resistant Encryption Migration
- **SUP-9**: Mobile Client Optimizations - **SUP-10**: Mobile Client Optimizations
- **SUP-10**: Governance and Protocol Upgrade Mechanisms - **SUP-11**: Governance and Protocol Upgrade Mechanisms
### Research Areas ### Research Areas
- Traffic analysis resistance measurements - Traffic analysis resistance measurements

23
DAEMON.md → THROWER.md
View File

@ -1,7 +1,8 @@
# Superball Daemon Rules # Thrower Rules
## What I Am ## What I Am
I am Superball - an anonymizing node that provides location privacy for Nostr users by forwarding their encrypted events with timing delays and size obfuscation. I am a Thrower - an anonymizing node that provides location privacy for Nostr users by catching, unwrapping, rewrapping and throwing Superballs (wrapped encrypted events) with timing delays and size obfuscation.
## What I Look For ## What I Look For
@ -42,7 +43,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
"routing": { /* My routing instructions from builder */ "routing": { /* My routing instructions from builder */
"relays": ["wss://relay1.com", "wss://relay2.com"], "relays": ["wss://relay1.com", "wss://relay2.com"],
"delay": 30, "delay": 30,
"p": "next_superball_pubkey", // Optional - missing means final posting "p": "next_thrower_pubkey", // Optional - missing means final posting
"audit": "audit_tag", // Required audit tag "audit": "audit_tag", // Required audit tag
"payment": "eCash_token", // Optional "payment": "eCash_token", // Optional
"add_padding_bytes": 256 // Optional "add_padding_bytes": 256 // Optional
@ -50,7 +51,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
} }
``` ```
#### Type 2: Padding Payload (Created by Previous Daemon) #### Type 2: Padding Payload (Created by Previous Thrower)
```json ```json
{ {
"event": { /* Still-encrypted inner event */ }, "event": { /* Still-encrypted inner event */ },
@ -82,7 +83,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
- Provides redundancy and availability - Provides redundancy and availability
#### Next Hop Logic #### Next Hop Logic
- **`p` field present**: Forward to next Superball with padding-only wrapper - **`p` field present**: Forward to next Thrower with padding-only wrapper
- **`p` field missing**: Post inner event directly to relays (end chain) - **`p` field missing**: Post inner event directly to relays (end chain)
#### Audit Tag Processing #### Audit Tag Processing
@ -92,13 +93,13 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
#### Payment Processing #### Payment Processing
- **`payment` field present**: Process eCash token for service payment - **`payment` field present**: Process eCash token for service payment
- **`payment` field missing**: Process for free (if daemon allows) - **`payment` field missing**: Process for free (if thrower allows)
### 5. Forward Event ### 5. Forward Event
#### Two-Path Processing #### Two-Path Processing
**Path 1: Forward to Next Superball (`p` field present)** **Path 1: Forward to Next Thrower (`p` field present)**
- Create padding-only wrapper (never create routing instructions) - Create padding-only wrapper (never create routing instructions)
- Generate fresh ephemeral keypair - Generate fresh ephemeral keypair
- Create padding payload: - Create padding payload:
@ -108,7 +109,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
"padding": "random_padding_data_123456789" "padding": "random_padding_data_123456789"
} }
``` ```
- Encrypt to next Superball's pubkey - Encrypt to next Thrower's pubkey
- Create routing event with next hop's pubkey in p tag - Create routing event with next hop's pubkey in p tag
**Path 2: Final Posting (`p` field missing)** **Path 2: Final Posting (`p` field missing)**
@ -118,7 +119,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
- End of chain - End of chain
#### Critical Rules #### Critical Rules
1. **Daemons NEVER create routing instructions** - Only padding 1. **Throwers NEVER create routing instructions** - Only padding
2. **Routing instructions come ONLY from the builder** - Pre-encrypted for each hop 2. **Routing instructions come ONLY from the builder** - Pre-encrypted for each hop
3. **Always use fresh ephemeral keys** when forwarding 3. **Always use fresh ephemeral keys** when forwarding
4. **Include audit tag** in routing event p tags for camouflage 4. **Include audit tag** in routing event p tags for camouflage
@ -154,7 +155,7 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
1. **Never modify final signatures** - Only remove padding tags, never add to signed events 1. **Never modify final signatures** - Only remove padding tags, never add to signed events
2. **Never store routing paths** - Process and forget 2. **Never store routing paths** - Process and forget
3. **Never respond to clients** - Silent operation only 3. **Never respond to clients** - Silent operation only
4. **Never correlate users** - Each event is independent 4. **Never correlate users** - Each Superball is independent
5. **Never log destinations** - Only log operational metrics 5. **Never log destinations** - Only log operational metrics
## Example Processing Flow ## Example Processing Flow
@ -176,4 +177,4 @@ I am Superball - an anonymizing node that provides location privacy for Nostr us
- **Queue**: Schedule for delayed processing (e.g., 30 seconds + jitter) - **Queue**: Schedule for delayed processing (e.g., 30 seconds + jitter)
- **Clean**: Clear all decrypted data from memory after processing - **Clean**: Clear all decrypted data from memory after processing
I am a privacy-preserving relay that helps users post content while hiding their location. I ask no questions, store no logs, and remember nothing about the events that pass through me. I am a privacy-preserving Thrower that helps users post content while hiding their location. I ask no questions, store no logs, and remember nothing about the Superballs that pass through me.

0
PROTOCOL.md → Trash/PROTOCOL.md
View File

420
debug.md
View File

@ -1,420 +0,0 @@
# Ball Structure
Final Event (What gets posted at the end)
Message Content:
2 bounce
Create Event That Will Be Published Publicly
{
"kind": 1,
"content": "2 bounce",
"tags": [],
"created_at": 1758196136,
"pubkey": "8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e",
"id": "2451f908dba9b2281751ecb91df143b83866795d29bbadde60093dd17cd039dd",
"sig": "31400031068313ba8338faf852ca718ef3495e393a6ef66a925db6e26ef21dd825fe5beca36ad9a2af7ea87ecd1dbc50550112505b7ee30c19125ae89b610b4c"
}
🏀 Bounce 2 (Kind 22222 Routing Event)
Superball Pubkey:
03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25
🎲 Random
Target Relays (comma separated):
wss://relay.laantungir.net
Delay (seconds):
10
Padding (+N or -N bytes):
+150 or -50
Payment (optional):
eCash token or payment info
Audit Tag (auto-generated):
3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3
Create Bounce 2
{
"kind": 22222,
"content": "Aob4...2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
}
🔓 Decrypt Content
🔓 Decrypted Payload:
{
"event": {
"kind": 1,
"content": "2 bounce",
"tags": [],
"created_at": 1758196136,
"pubkey": "8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e",
"id": "2451f908dba9b2281751ecb91df143b83866795d29bbadde60093dd17cd039dd",
"sig": "31400031068313ba8338faf852ca718ef3495e393a6ef66a925db6e26ef21dd825fe5beca36ad9a2af7ea87ecd1dbc50550112505b7ee30c19125ae89b610b4c"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
}
}
🏀 Bounce 1 (Kind 22222 Routing Event)
Superball Pubkey:
e295a831c9a3ae50da2ca3115f8b13b035805a5ebbbd68d95a1e0caf13bff440
🎲 Random
Target Relays (comma separated):
wss://relay.laantungir.net
Delay (seconds):
10
Padding (+N or -N bytes):
+150 or -50
Payment (optional):
eCash token or payment info
Audit Tag (auto-generated):
ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7
Create Bounce 1
{
"kind": 22222,
"content": "AnMH3c...B3LPiw==",
"tags": [
[
"p",
"e295a831c9a3ae50da2ca3115f8b13b035805a5ebbbd68d95a1e0caf13bff440"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
],
"created_at": 1758196166,
"pubkey": "ef4663112f67ab47450605fc33e03f9cf19ddcd4d8ecf83c13bf3ecc9215461d",
"id": "1fa0869733fa11781b9130f8392b672e452e5025d7604182f83551542de21517",
"sig": "9a0a9deee3971e62deb9ff6974251c8599c4e6fd822bca12f28fe3df1646845fa0537ae5c3764e4227ee76874c233813896ee08a1b11e8b9f6e03192577891e6"
}
🔓 Decrypt Content
🔓 Decrypted Payload:
{
"event": {
"kind": 22222,
"content": "Aob44...w2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7",
"p": "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
}
}
# Process at first bounce pubkey:e295a831c9a3ae50da2ca3115f8b13b035805a5ebbbd68d95a1e0caf13bff440
7:49:44 AM Successfully processed event 1fa0869733fa1178...
7:49:44 AM Forwarded event with audit tag ab35d9f342afd954...
7:49:44 AM
Full published event:
{
"kind": 22222,
"content": "AtcPM...GGA==",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
],
"created_at": 1758196183,
"pubkey": "c2ff758233b1099682d99687e096859e4f930ea20e73905756166ffdcab9279c",
"id": "843d662891c497365d514b995c4135fb0cf080531cda4cef842d396cf0d1c1db",
"sig": "765c822b75fe7772e6c10c96e159bc1e64534571d3cd9e6daf25e5276e2a5efdd6dbb3523db75aa1483ca3b1062d8444145b69d0cd0823579980fe5074f8354b"
}
7:49:44 AM Published to relays: wss://relay.laantungir.net
7:49:43 AM
Rewrapped event to publish:
{
"kind": 22222,
"content": "AtcPM...GGA==",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
],
"created_at": 1758196183,
"pubkey": "c2ff758233b1099682d99687e096859e4f930ea20e73905756166ffdcab9279c",
"id": "843d662891c497365d514b995c4135fb0cf080531cda4cef842d396cf0d1c1db",
"sig": "765c822b75fe7772e6c10c96e159bc1e64534571d3cd9e6daf25e5276e2a5efdd6dbb3523db75aa1483ca3b1062d8444145b69d0cd0823579980fe5074f8354b"
}
7:49:43 AM
New payload to encrypt:
{
"event": {
"kind": 22222,
"content": "Aob44...w2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7",
"p": "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
}
}
7:49:43 AM DEBUG Rewrapping: newRouting.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (string)
7:49:43 AM Forwarding to next Superball: 03f857567fc96b47...
7:49:43 AM DEBUG Will FORWARD event
7:49:43 AM DEBUG Decision point - routing.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (string)
7:49:43 AM Processing event 1fa0869733fa1178...
7:49:33 AM Event queued for processing in 10s: 1fa0869733fa1178...
7:49:33 AM DEBUG !routing.p: false
7:49:33 AM DEBUG routing.p === null: false
7:49:33 AM DEBUG routing.p === undefined: false
7:49:33 AM DEBUG routing.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (type: string)
7:49:33 AM
Decrypted payload:
{
"event": {
"kind": 22222,
"content": "Aob44...w2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7",
"p": "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
}
}
7:49:33 AM Successfully decrypted routing event 1fa0869733fa1178...
7:49:33 AM Received routing event: 1fa0869733fa1178...
7:49:33 AM
Full received event:
{
"content": "AnMH3...Piw==",
"created_at": 1758196166,
"id": "1fa0869733fa11781b9130f8392b672e452e5025d7604182f83551542de21517",
"kind": 22222,
"pubkey": "ef4663112f67ab47450605fc33e03f9cf19ddcd4d8ecf83c13bf3ecc9215461d",
"sig": "9a0a9deee3971e62deb9ff6974251c8599c4e6fd822bca12f28fe3df1646845fa0537ae5c3764e4227ee76874c233813896ee08a1b11e8b9f6e03192577891e6",
"tags": [
[
"p",
"e295a831c9a3ae50da2ca3115f8b13b035805a5ebbbd68d95a1e0caf13bff440"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
]
}
7:49:33 AM Received EVENT from wss://relay.laantungir.net: 1fa0869733fa1178...
# Process at second bounce pubkey: 03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25
7:49:54 AM Forwarded event with audit tag ab35d9f342afd954...
7:49:54 AM
Full published event:
{
"kind": 22222,
"content": "ArEYH...cAw==",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
],
"created_at": 1758196194,
"pubkey": "76c213037af4de471d6af7fa996f0b02882ccf2606e871f49ebb6dccef7f7642",
"id": "ddeebcc4091610ec5c7246a06ebfe31f3539492e273c920e9da5e10816b0d0d1",
"sig": "a3845cca91cfa79eb184499350b8f1b2486ee65313371a7b9ca61506cd1abcb684673eefecf9b7b0c17e50a70f4976d750310ef393a77cd69cbe923fa351aa37"
}
7:49:54 AM Published to relays: wss://relay.laantungir.net
7:49:54 AM
Rewrapped event to publish:
{
"kind": 22222,
"content": "ArEYH...cAw==",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
],
"created_at": 1758196194,
"pubkey": "76c213037af4de471d6af7fa996f0b02882ccf2606e871f49ebb6dccef7f7642",
"id": "ddeebcc4091610ec5c7246a06ebfe31f3539492e273c920e9da5e10816b0d0d1",
"sig": "a3845cca91cfa79eb184499350b8f1b2486ee65313371a7b9ca61506cd1abcb684673eefecf9b7b0c17e50a70f4976d750310ef393a77cd69cbe923fa351aa37"
}
7:49:54 AM
New payload to encrypt:
{
"event": {
"kind": 22222,
"content": "Aob44...w2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7",
"p": "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
}
}
7:49:54 AM DEBUG Rewrapping: newRouting.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (string)
7:49:54 AM Forwarding to next Superball: 03f857567fc96b47...
7:49:54 AM DEBUG Will FORWARD event
7:49:54 AM DEBUG Decision point - routing.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (string)
7:49:54 AM Processing event 843d662891c49736...
7:49:44 AM Event queued for processing in 10s: 843d662891c49736...
7:49:44 AM DEBUG !routing.p: false
7:49:44 AM DEBUG routing.p === null: false
7:49:44 AM DEBUG routing.p === undefined: false
7:49:44 AM DEBUG routing.p = "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25" (type: string)
7:49:44 AM
Decrypted payload:
{
"event": {
"kind": 22222,
"content": "Aob44...w2at6",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"3413dc76625f59dc88b4ff4c290643110f21208c9f4f99a678a75730fd35cef3"
]
],
"created_at": 1758196144,
"pubkey": "acb7a5fe35eb69a0f30e58dc790558a86143d5c489749fe9c4db52bdb3f7b310",
"id": "00d7536a425b2d955084f920c45c1d5ddf86b5503374daa02922af60f536b953",
"sig": "a2f9ad4f85bda8fc6ddbce28b2773e8938a747964dc278b2e89553666f777e9d27cbf37d6c69a30223dd8e2e2ace3155d31711ebb9b0b7cd0c5d1c92f8ecefec"
},
"routing": {
"relays": [
"wss://relay.laantungir.net"
],
"delay": 10,
"audit": "ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7",
"p": "03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
}
}
7:49:44 AM Successfully decrypted routing event 843d662891c49736...
7:49:44 AM Received routing event: 843d662891c49736...
7:49:44 AM
Full received event:
{
"content": "AtcPM...GGA==",
"created_at": 1758196183,
"id": "843d662891c497365d514b995c4135fb0cf080531cda4cef842d396cf0d1c1db",
"kind": 22222,
"pubkey": "c2ff758233b1099682d99687e096859e4f930ea20e73905756166ffdcab9279c",
"sig": "765c822b75fe7772e6c10c96e159bc1e64534571d3cd9e6daf25e5276e2a5efdd6dbb3523db75aa1483ca3b1062d8444145b69d0cd0823579980fe5074f8354b",
"tags": [
[
"p",
"03f857567fc96b47b68632457a818563c53e09aaf0028ac1081450afe3352e25"
],
[
"p",
"ab35d9f342afd9541dac9679dae7a68d79eb52d01e35743d108ce0b4c56facd7"
]
]
}
7:49:44 AM Received EVENT from wss://relay.laantungir.net: 843d662891c49736...

1086
web/superball-builder.html
View File

File diff suppressed because it is too large Load Diff

1795
web/superball.html
View File

File diff suppressed because it is too large Load Diff

1653
web/thrower.html Normal file
View File

File diff suppressed because it is too large Load Diff