ReferenceCashu Protocol Cheat Sheet

Compressed reference for the Cashu core protocol (mandatory NUTs 00–06). Source of truth: cashubtc/nuts.

The three operations

Operation	Meaning	Endpoints
Mint (NUT-04)	Pay the mint (Lightning) → receive ecash	`POST /v1/mint/quote/bolt11` `GET /v1/mint/quote/bolt11/{quote_id}` `POST /v1/mint/bolt11`
Swap (NUT-03)	Old proofs in → new proofs out (receive / split / rotate)	`POST /v1/swap`
Melt (NUT-05)	Ecash in → mint pays a Lightning invoice for you	`POST /v1/melt/quote/bolt11` `GET /v1/melt/quote/bolt11/{quote_id}` `POST /v1/melt/bolt11`

Data models (NUT-00)

Model	Direction	JSON
BlindedMessage ("output")	wallet → mint	`{"amount": 8, "id": "<keyset_id>", "B_": "<hex>"}`
BlindSignature ("promise")	mint → wallet	`{"amount": 8, "id": "<keyset_id>", "C_": "<hex>"}`
Proof ("input") — this is the ecash	stored in wallet; wallet → mint to spend	`{"amount": 8, "id": "<keyset_id>", "secret": "<string>", "C": "<hex>"}`

BDHKE — blind signature scheme (NUT-00)

Symbol	Meaning	Held by
`k`, `K = kG`	Mint's private key for one amount; published pubkey	mint / public
`x`	Random secret string (the `secret` field)	wallet
`Y = hash_to_curve(x)`	Secret mapped to a curve point	derivable
`r`	Random blinding factor	wallet only
`B_ = Y + rG`	Blinded message sent to mint	wallet → mint
`C_ = kB_`	Blind signature returned by mint	mint → wallet
`C = C_ − rK = kY`	Unblinded signature (the `C` field)	wallet

Mint verifies a spend by checking C == k·hash_to_curve(secret) and that secret is not in its spent list. The mint never saw x or C at issuance — only B_ and C_ — so it cannot link issuance to spend.

Keysets & fees (NUT-01/02)

A keyset = one keypair per amount (denominations 1, 2, 4, 8, … sats), one unit (e.g. sat), one id.
Every Proof/BlindedMessage carries the keyset id. Wallets should recompute the id from the keys, not trust the mint.
active: true → mint signs new outputs with it; inactive keysets only accept spends (rotation mechanism).
input_fee_ppk: fee per input in parts-per-thousand of the unit. Sum over inputs, round up. E.g. 3 inputs × 100 ppk = 300 ppk → 1 sat.
Balance equation for swap/melt: sum(inputs) == sum(outputs) + fees.

Serialized tokens (NUT-00)

V4 cashuB<base64_urlsafe(CBOR)> — current. Single mint; short keys: m mint URL, u unit, t list of {i: keyset_id, p: [{a, s, c}]} (amount, secret, signature).
V3 cashuA<base64_urlsafe(JSON)> — legacy. JSON with token: [{mint, proofs}], unit, memo.
A serialized token is the money: whoever holds the proofs can spend them. Receiving safely = swapping immediately.

Quote lifecycle (debugging map)

Flow	Progress	Notes
Mint quote	unpaid → paid → issued	NUT-04 tracks `amount_paid` vs `amount_issued`; mintable = paid − issued. The `quote` id is a bearer secret — leak it and tokens can be stolen.
Melt quote	`UNPAID` → `PENDING` → `PAID`	`PENDING` = Lightning payment in flight; proofs are locked. Poll `GET /v1/melt/quote/…`. `fee_reserve` must be covered by inputs.