# Protocol and events

What is actually on the wire. Useful if you are auditing the client, writing another one, or just want to know that the description above is the truth.

## Nostr underneath

Nymbot is built on Nostr. Messages are events, identities are keypairs, and delivery is a set of relays rather than a server you have to trust. That is why an identity from any other Nostr app works here unchanged.

The events involved:

| Kind | What it is |
| --- | --- |
| 1059 | The gift wrap carrying a message, in either direction. |
| 14 | The rumor inside it — unsigned, so it is deniable. |
| 13 | The seal, signed by the sender, encrypted to the recipient. |
| 30078 | The post-quantum capability announcement carrying a KEM key. |
| 27235 | The short-lived auth event that proves a request is yours. |

## One turn, end to end

1. Your app seals the message to Nymbot's announced keys — classical and ML-KEM — wraps it under a single-use key and publishes the wrap to the relays. A copy wrapped to your own key goes out too, so the conversation restores on any device.
2. It calls the worker with the wrap's event id and a fresh auth event signed for that one action and endpoint, so a captured signature cannot be replayed against a different request. The message itself never travels as plaintext.
3. The worker claims the turn before it fetches, generates or charges anything. Resending the same message replays the first attempt's answer rather than buying a second one — and two wraps of one rumor count as one question.
4. It fetches the wrap from the relays, opens it, checks the seal's signer matches the authenticated key, reconstructs the thread from the previous wraps, and generates.
5. The reply is sealed back to your announced keys, published, and handed to your app in the response so it appears without waiting on relay propagation.

The classification, routing, search and tool calls all happen inside step 4, on the server. What comes back is one message.

## The credit ledger

Balances live in a single-writer ledger rather than in ordinary rows, so concurrent spends from two devices cannot both succeed against the same credit. Every money operation is idempotent and keyed: a claim for a paid invoice credits once no matter how many times it is retried, and a voucher redemption resumed after a crash credits once too.

A spend is authorised by a fresh signature bound to that action, and the amount is reserved before generation and settled after, which is how a Pro reply can budget for its maximum and charge you only what it used.

The [voucher tables](https://nymbot.ai/docs/anonymous/#vouchers) record issuance and spending without recording who, which is the whole point of them.