NIP-22

Event Publication Onion-routing

draft optional

This NIP defines a way to do onion-based routing for event publishing, optionally compensated with cashu where pubkeys (not necessarily relays) provide routing services.

Announcement

A pubkey announces itself as willing to route by publishing an ephemeral event kind:20690 in their outbox relays. Announcers should republish a new ephemeral event every few minutes to indicate they are still willing to route and online. The refresh rate depends on the relays where they are publishing (usually ~5 minutes).

{
    "kind": 20690,
    "tags": [
        [ "relay", "wss://example1.com" ],
        [ "relay", "wss://example2.com" ],
        [ "fee", "1", "sat" ]
    ],
    "content": "",
    "pubkey": <pubkey-of-router>
}

Tags: relay -- relay(s) where the pubkey will be listening for requests. fee -- an optional fee indicating how much money the pubkey demands to be paid.

Routing request

A sender publishes a series of kind:2444 or kind:20444 where the payload is the event that should be published by the pubkey of the current hop in the relays specified by the envelope. An optional proof can be included, this cashu proof is for the hop processing this route.

{
    "kind": 20444,
    "content": nip44_encrypt("{
        'relays': [ 'wss://example1.com' ],
        'event': { 'id': ...., sig: ...,  }, // event the current routing pubkey should publish
        'proof': <optional-unencoded-cashu-proof>,
        'mint': 'https://mint.com',
        'unit': 'sat'
    }")
    "tags": [
        [ "p", "pubkey-of-next-hop" ]
    ]
}

Event kind:2444 has the exact same format as the kind:20444, the only difference being that it's not ephemeral, so it can be used to route events that are expected to take longer to route. kind:2444 events SHOULD include an NIP-40 expiration tag.

Routing pubkeys MUST look at the created_at of the event they need to publish and wait until at least that time before publishing. Using future created_ats allows the sender to increase their privacy by preventing timing analysis by mixing different time delays at each hop.

When a routing pubkey receives a routing request event it should decrypt the content, redeem the cashu and publish the event in the event field. If the cashu cannot be redeemed the routing pubkey MUST NOT publish the event. This is useful as a way to cancel a routing event where the sender uses a future created_at timestamps and chooses to cancel the publication.

Constructing a route

The sender:

looks for kind:20400 announcements and assembles a path
creates the event they want to publish and sign it with their normal pubkey
walks the path backwards (finish -> start), putting the event signed in the previous step in the event field of the content and the other fileds of the envelope
encrypts to the current hop and signs -- both operations with a new disposable key and p-tags the current hop.
repeat step #3 and #4 for the rest of the route until the first hop
sender publishes the resulting event to one of the relays the first hop indicated it's active on

Pseudocode implementation

// event to be published
event = { "kind": 1, content: "This is an onion-routed event" }
sign_event(event, my_private_key)
outer_layer = assemble_onion_route(event, [ "pubkey-A", "pubkey-B", "pubkey-C" ])
publish_event(outer_layer)

function assemble_onion_route(final_event, path) {
    current_event = final_event  // Start with the event to be published by the final hop

    // Walk the path backwards from "C" to "A"
    for hop_pubkey in reverse(path):  // path = ["A", "B", "C"], reversed to ["C", "B", "A"]
        // Generate a new disposable key for this hop
        disposable_key = generate_disposable_key()

        // Create the payload for this hop
        payload = {
            "event": current_event  // The event for the hop to publish
            // ...
        }
        
        // Encrypt the payload for the current hop
        encrypted_payload = nip44_encrypt(payload, hop_pubkey)  // Encrypt with the hop's pubkey
        
        // Create the routing event for this hop
        routing_event = {
            "kind": 20444,  // Ephemeral routing request
            "content": encrypted_payload,  // The encrypted payload for this hop
            "tags": [["p", hop_pubkey]]  // Tag indicating the pubkey of the next hop
        }
        
        // Sign the event with the disposable key for this hop
        sign_event(routing_event, disposable_key)
        
        // Prepare for the next hop (wrap another layer)
        current_event = routing_event
    }

    return current_event  // Return the fully wrapped outermost event ready to be published
}

Example anatomy of a sequence of routing events

{
    kind: 20444,
    content: nip44_encrypt({
        relays: [...],
        event: {
            "id": ...,
            "kind": 20444,
            "pubkey": "ephemeral-key-1",
            "sig": ...,
            content: nip44_encrypt({
                relays: [....],
                event: {
                    "id": ....,
                    "kind": 20444,
                    "pubkey": "ephemeral-key-2",
                    "sig": ...,
                    "content": nip44_encrypt({
                        relays: [ "wss://target-relay.com" ],
                        event: {
                            id: ...,
                            "kind": 1,
                            content: "This is an onion-routed event",
                            "pubkey": "real-pubkey",
                            "sig": ...,
                        }
                    })
                }
            })
        }
    }
}

5.7 KiB Raw Blame History