nips/22.md

# NIP-22
## Event 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).

```jsonc
{
    "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.

```jsonc
{
    "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.

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:

1. looks for `kind:20400` announcements and assembles a path
2. creates the event they want to publish and sign it with their normal pubkey

3. 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
4. encrypts to the current hop and signs -- both operations with a new disposable key and `p`-tags the current hop.
3. repeat step #3 and #4 for the rest of the route until the first hop
4. sender publishes the resulting event to one of the relays the first hop indicated it's active on

## Pseudocode implementation
```ts
// 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

```jsonc
{
    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": ...,
                        }
                    })
                }
            })
        }
    }
}
```