This NUT introduces a standardised format for payment requests, that supply a sending wallet with all information necessary to complete the transaction. This enables many use-cases where a transaction is better initiated by the receiver (e.g. point of sale).
Tags are an optional array of [tag, value, value, ...] tuples that can be used to specify additional features about the transport. A single tag can have multiple values.
The n tag specifies the NIPs the receiver supports. At least one tag value MUST be specified. For NIP-17 direct messages, the sender sends a PaymentRequestPayload as the message content.
Here, id is the payment id (corresponding to i in request), memo is an optional memo to be sent to the receiver with the payment, mint is the mint URL from which the ecash is from, unit is the unit of the payment, and proofs is an array of proofs (see NUT-00, can also include DLEQ proofs).
"},{"location":"00/","title":"NUT-00: Notation, Utilization, and Terminology","text":"
mandatory
This document details the notation and models used throughout the specification and lays the groundwork for understanding the basic cryptography used in the Cashu protocol.
Alice picks secret x and computes Y = hash_to_curve(x)
Alice sends to Bob: B_ = Y + rG with r being a random blinding factor (blinding)
Bob sends back to Alice blinded key: C_ = kB_ (these two steps are the DH key exchange) (signing)
Alice can calculate the unblinded key as C_ - rK = kY + krG - krG = kY = C (unblinding)
Alice can take the pair (x, C) as a token and can send it to Carol.
Carol can send (x, C) to Bob who then checks that k*hash_to_curve(x) == C (verification), and if so treats it as a valid spend of a token, adding x to the list of spent secrets.
An encrypted (\"blinded\") secret and an amount is sent from Alice to Bob for minting tokens or for swapping tokens. A BlindedMessage is also called an output.
amount is the value for the requested BlindSignature, id is the requested keyset ID from which we expect a signature, and B_ is the blinded secret message generated by Alice. An array [BlindedMessage] is also referred to as BlindedMessages.
amount is the value of the blinded token, id is the keyset id of the mint keys that signed the token, and C_ is the blinded signature on the secret message B_ sent in the previous step.
A Proof is also called an input and is generated by Alice from a BlindSignature it received. An array [Proof] is called Proofs. Alice sends Proofs to Bob for melting tokens. Serialized Proofs can also be sent from Alice to Carol. Upon receiving the token, Carol deserializes it and requests a swap from Bob to receive new Proofs.
amount is the amount of the Proof, secret is the secret message and is a utf-8 encoded string (the use of a 64 character hex string generated from 32 random bytes is recommended to prevent fingerprinting), C is the unblinded signature on secret (hex string), id is the keyset id of the mint public keys that signed the token (hex string).
In case of an error, mints respond with the HTTP status code 400 and include the following data in their response:
{\n \"detail\": \"oops\",\n \"code\": 1337\n}\n
Here, detail is the error message, and code is the error code. Error codes are to be defined in the documents concerning the use of a certain API endpoint.
"},{"location":"00/#03-methods","title":"0.3 - Methods","text":""},{"location":"00/#serialization-of-tokens","title":"Serialization of tokens","text":"
Tokens can be serialized to send them between users Alice and Carol. Serialized tokens have a Cashu token prefix, a versioning flag, and the token. Optionally, a URI prefix for making tokens clickable on the web.
We use the following format for token serialization:
cashu[version][token]\n
cashu is the Cashu token prefix. [version] is a single base64_urlsafe character to denote the token format version.
V3 tokens are base64-encoded JSON objects. The token format supports tokens from multiple mints. The JSON is serialized with a base64_urlsafe (base64 encoding with / replaced by _ and + by -). base64_urlsafe strings may have padding characters (usually =) at the end which can be omitted. Clients need to be able to decode both cases.
cashuA[base64_token_json]\n
[base64_token_json] is the token JSON serialized in base64_urlsafe. [base64_token_json] should be cleared of any whitespace before serializing.
mint is the mint URL. The mint URL must be stripped of any trailing slashes (/). Proofs is an array of Proof objects. The next two elements are only for displaying the receiving user appropriate information: unit is the currency unit of the token keysets (see Keysets for supported units), and memo is an optional text memo from the sender.
V4 tokens are a space-efficient way of serializing tokens using the CBOR binary format. All field are single characters and hex strings are encoded in binary. V4 tokens can only hold proofs from a single mint.
Wallets serialize tokens in a base64_urlsafe format (base64 encoding with / replaced by _ and + by -). base64_urlsafe strings may have padding characters (usually =) at the end which can be omitted. Clients need to be able to decode both cases.
The deserialized base64_token_cbor is a JSON of the same form as a TokenV4 but with shorter keys and data represented as binary data (bytes) instead of hex strings (hex_str). Note that we have expanded what is called Proofs in TokenV3 (called p here with TokenV4) showing that its values are also different from the TokenV3 serialization.
m is the mint URL. The mint URL must be stripped of any trailing slashes (/). u is the currency unit of the token keysets (see Keysets for supported units), and d is an optional text memo from the sender.
i is the keyset ID of the profs in p, which is an array of Proof objects without the id field. We extracted the keyset ID id from each proof and grouped all proofs by their keyset ID i one level above (in p).
Note that all fields of the bytes type encode hex strings in the original representation of Proof's.
The h'' values are bytes but displayed as hex strings here.
We serialize this JSON using CBOR which can be seen here. The resulting bytes are then serialized to a string using base64_urlsafe and the prefix cashuB is added. This leaves us with the following serialized TokenV4:
"},{"location":"01/","title":"NUT-01: Mint public key exchange","text":"
mandatory
This document outlines the exchange of the public keys of the mint Bob with the wallet user Alice. Alice uses the keys to unblind Bob's blind signatures (see NUT-00).
Wallet user Alice receives public keys from mint Bob via GET /v1/keys. The set of all public keys for a set of amounts is called a keyset.
The mint responds only with its active keysets. Keyset are active if the mint will sign promises with it. The mint will accept tokens from inactive keysets as inputs but will not sign with them for new outputs. The active keysets can change over time, for example due to key rotation. A list of all keysets, active and inactive, can be requested separately (see NUT-02).
Note that a mint can support multiple keysets at the same time but will only respond with the active keysets on the endpoint GET /v1/keys. A wallet can ask for the keys of a specific (active or inactive) keyset via the endpoint GET /v1/keys/{keyset_id} (see NUT-02).
Keysets are generated by the mint. The mint is free to use any key generation method they like. Each keyset is identified by its keyset id which can be computed by anyone from its public keys (see NUT-02).
Keys in Keysets are maps of the form {<amount_1> : <mint_pubkey_1>, <amount_2> : <mint_pubkey_2>, ...} for each <amount_i> of the amounts the mint Bob supports and the corresponding public key <mint_pubkey_1>, that is K_i (see NUT-00). The mint MUST use the compressed Secp256k1 public key format to represent its public keys.
"},{"location":"02/","title":"NUT-02: Keysets and fees","text":"
mandatory
A keyset is a set of public keys that the mint Bob generates and shares with its users. It refers to the set of public keys that each correspond to the amount values that the mint supports (e.g. 1, 2, 4, 8, ...) respectively.
Each keyset indicates its keyset id, the currency unit, whether the keyset is active, and an input_fee_ppk that determines the fees for spending ecash from this keyset.
A mint can have multiple keysets at the same time. For example, it could have one keyset for each currency unit that it supports. Wallets should support multiple keysets. They must respect the active and the input_fee_ppk properties of the keysets they use.
A keyset id is an identifier for a specific keyset. It can be derived by anyone who knows the set of public keys of a mint. Wallets CAN compute the keyset id for a given keyset by themselves to confirm that the mint is supplying the correct keyset ID (see below).
The keyset id is in each Proof so it can be used by wallets to identify which mint and keyset it was generated from. The keyset field id is also present in the BlindedMessages sent to the mint and BlindSignatures returned from the mint (see NUT-00).
Mints can have multiple keysets at the same time but MUST have at least one active keyset (see NUT-01). The active property determines whether the mint allows generating new ecash from this keyset. Proofs from inactive keysets with active=false are still accepted as inputs but new outputs (BlindedMessages and BlindSignatures) MUST be from active keysets only.
To rotate keysets, a mint can generate a new active keyset and inactive an old one. If the active flag of an old keyset is set to false, no new ecash from this keyset can be generated and the outstanding ecash supply of that keyset can be taken out of circulation as wallets rotate their ecash to active keysets.
Wallets SHOULD prioritize swaps with Proofs from inactive keysets (see NUT-03) so they can quickly get rid of them. Wallets CAN swap their entire balance from an inactive keyset to an active one as soon as they detect that the keyset was inactivated. When constructing outputs for a transaction, wallets MUST choose only active keysets (see NUT-00).
"},{"location":"02/#fees","title":"Fees","text":"
Keysets indicate the fee input_fee_ppk that is charged when a Proof of that keyset is spent as an input to a transaction. The fee is given in parts per thousand (ppk) per input measured in the unit of the keyset. The total fee for a transaction is the sum of all fees per input rounded up to the next larger integer (that that can be represented with the keyest).
As an example, we construct a transaction spending 3 inputs (Proofs) from a keyset with unit sat and input_fee_ppk of 100. A fee of 100 ppk means 0.1 sat per input. The sum of the individual fees are 300 ppk for this transaction. Rounded up to the next smallest denomination, the mint charges 1 sat in total fees, i.e. fees = ceil(0.3) == 1. In this case, the fees for spending 1-10 inputs is 1 sat, 11-20 inputs is 2 sat and so on.
When constructing a transaction with ecash inputs (example: /v1/swap or /v1/melt), wallets MUST add fees to the inputs or, vice versa, subtract from the outputs. The mint checks the following equation:
sum(inputs) - fees == sum(outputs)\n
Here, sum(inputs) and sum(outputs) mean the sum of the amounts of the inputs and outputs respectively. fees is calculated from the sum of each input's fee and rounded up to the next larger integer:
Here, the // operator in (sum_fees + 999) // 1000 denotes an integer division operator (aka floor division operator) that rounds down sum_fees + 999 to the next lower integer. Alternatively, we could round up the sum using a floating point division with ceil(sum_fees / 1000) although it is not recommended to do so due to the non-deterministic behavior of floating point division.
Notice that since transactions can spend inputs from different keysets, the sum considers the fee for each Proof indexed by the keyset ID individually.
"},{"location":"02/#deriving-the-keyset-id","title":"Deriving the keyset ID","text":""},{"location":"02/#keyset-id-version","title":"Keyset ID version","text":"
Keyset IDs have a version byte (two hexadecimal characters). The currently used version byte is 00.
The mint and the wallets of its users can derive a keyset ID from the keyset of the mint. The keyset ID is a lower-case hex string. To derive the keyset ID of a keyset, execute the following steps:
1 - sort public keys by their amount in ascending order\n2 - concatenate all public keys to one byte array\n3 - HASH_SHA256 the concatenated public keys\n4 - take the first 14 characters of the hex-encoded hash\n5 - prefix it with a keyset ID version byte\n
An example implementation in Python:
def derive_keyset_id(keys: Dict[int, PublicKey]) -> str:\n sorted_keys = dict(sorted(keys.items()))\n pubkeys_concat = b\"\".join([p.serialize() for p in sorted_keys.values()])\n return \"00\" + hashlib.sha256(pubkeys_concat).hexdigest()[:14]\n
"},{"location":"02/#example-get-mint-keysets","title":"Example: Get mint keysets","text":"
A wallet can ask the mint for a list of all keysets via the GET /v1/keysets endpoint.
Here, id is the keyset ID, unit is the unit string (e.g. \"sat\") of the keyset, active indicates whether new ecash can be minted with this keyset, and input_fee_ppk is the fee (per thousand units) to spend one input spent from this keyset. If input_fee_ppk is not given, we assume it to be 0.
Wallets can request the list of keyset IDs from the mint upon startup and load only tokens from its database that have a keyset ID supported by the mint it interacts with. This also helps wallets to determine whether the mint has added a new current keyset or whether it has changed the active flag of an existing one.
A useful flow is:
If we don't have any keys from this mint yet, get all keys: GET /v1/keys and store them
Get all keysets with GET /v1/keysets
For all new keyset returned here which we don't have yet, get it using GET /v1/keys/{keyset_id} and store it
If any of the keysets has changed its active flag, update it in the db and use the keyset accordingly
The swap operation is the most important component of the Cashu system. A swap operation consists of multiple inputs (Proofs) and outputs (BlindedMessages). Mints verify and invalidate the inputs and issue new promises (BlindSignatures). These are then used by the wallet to generate new Proofs (see NUT-00).
The swap operation can serve multiple use cases. The first use case is that Alice can use it to split her tokens to a target amount she needs to send to Carol, if she does not have the necessary amounts to compose the target amount in her wallet already. The second one is that Carols's wallet can use it to receive tokens from Alice by sending them as inputs to the mint and receive new outputs in return.
"},{"location":"03/#swap-to-send","title":"Swap to send","text":"
To make this more clear, we present an example of a typical case of sending tokens from Alice to Carol.
Alice has 64 sat in her wallet, composed of three Proofs, one worth 32 sat and another two worth 16 sat. She wants to send Carol 40 sat but does not have the necessary Proofs to compose the target amount of 40 sat. For that, Alice requests a swap from the mint and uses Proofs worth [16, 16, 32] as inputs and asks for new outputs worth [8, 32, 8, 16] totalling 64 sat. Notice that the first two tokens can now be combined to 40 sat. The Proofs that Alice sent Bob as inputs of the swap operation are now invalidated.
Note: In order to preserve privacy around the amount that a client might want to send to another user and keep the rest as change, the client SHOULD ensure that the list requested outputs is ordered by amount in ascending order. As an example of what to avoid, a request for outputs expressed like so: [16, 8, 2, 64, 8] might imply the client is preparing a payment for 26 sat; the client should instead order the list like so: [2, 8, 8, 16, 64] to mitigate this privacy leak to the mint.
"},{"location":"03/#swap-to-receive","title":"Swap to receive","text":"
Another useful case for the swap operation follows up the example above where Alice has swapped her Proofs ready to be sent to Carol. Carol can receive these Proofs using the same operation by using them as inputs to invalidate them and request new outputs from Bob. Only if Carol has redeemed new outputs, Alice can't double-spend the Proofs anymore and the transaction is settled. To continue our example, Carol requests a swap with input Proofs worth [32, 8] to receive new outputs (of an arbitrary distribution) with the same total amount.
If successful, Bob will respond with a PostSwapResponse
{\n \"signatures\": <Array[BlindSignature]>\n}\n
"},{"location":"04/","title":"NUT-04: Mint tokens","text":"
mandatory
Minting tokens is a two-step process: requesting a mint quote and minting new tokens. Here, we describe both steps.
In the first request the wallet asks the mint for a quote for a specific amount and unit to mint, and the payment method to pay. The mint responds with a quote that includes a quote id and a payment request. The user pays the request and, if successful, requests minting of new tokens with the mint in a second request. The wallet includes the quote id and new outputs in the second request.
We limit this document to mint quotes of unit=\"sat\" and method=\"bolt11\" which requests a bolt11 Lightning invoice (typically generated by the mint to add Bitcoin to its reserves) to mint ecash denominated in Satoshis.
Where quote is the quote ID and request is the payment request to fulfill. expiry is the Unix timestamp until which the mint quote is valid.
state is an enum string field with possible values \"UNPAID\", \"PAID\", \"ISSUED\":
\"UNPAID\" means that the quote's request has not been paid yet.
\"PAID\" means that the request has been paid.
\"ISSUED\" means that the quote has already been issued.
Note: quote is a unique and random id generated by the mint to internally look up the payment state. quote MUST remain a secret between user and mint and MUST NOT be derivable from the payment request. A third party who knows the quote ID can front-run and steal the tokens that this operation mints.
The wallet MUST store the amount in the request and the quote id in the response in its database so it can later request the tokens after paying the request. After payment, the wallet continues with the next section.
"},{"location":"04/#check-mint-quote-state","title":"Check mint quote state","text":"
To check whether a mint quote has been paid, Alice makes a GET /v1/mint/quote/bolt11/{quote_id}.
GET https://mint.host:3338/v1/mint/quote/bolt11/{quote_id}\n
Like before, the mint Bob responds with a PostMintQuoteBolt11Response.
Example request of Alice with curl:
curl -X GET http://localhost:3338/v1/mint/quote/bolt11/DSGLX9kevM...\n
After requesting a mint quote and paying the request, the wallet proceeds with minting new tokens by calling the POST /v1/mint/{method} endpoint where method is the payment method requested (here bolt11).
POST https://mint.host:3338/v1/mint/bolt11\n
The wallet Alice includes the following PostMintBolt11Request data in its request
with the quote being the quote ID from the previous step and outputs being BlindedMessages (see NUT-00) that the wallet requests signatures on whose sum is amount as requested in the quote.
The mint Bob then responds with a PostMintBolt11Response:
{\n \"signatures\": <Array[BlindSignature]>\n}\n
where signatures is an array of blind signatures on the outputs.
Upon receiving the BlindSignatures from the mint Bob, the wallet of Alice unblinds them to generate Proofs (using the blinding factor r and the mint's public key K, see BDHKE NUT-00). The wallet then stores these Proofs in its database:
The settings for this nut indicate the supported method-unit pairs for minting and whether minting is disabled or not. They are part of the info response of the mint (NUT-06) which in this case reads
Melting tokens is the opposite of minting tokens (see NUT-04). Like minting tokens, melting is a two-step process: requesting a melt quote and melting tokens. Here, we describe both steps.
In the first request the wallet asks the mint for a quote for a request it wants paid by the mint and the unit the wallet would like to spend as inputs. The mint responds with a quote that includes a quote id and an amount the mint demands in the requested unit. For the method bolt11, the mint includes a fee_reserve field indicating the reserve fee for a Lightning payment.
In the second request, the wallet includes the quote id and provides inputs that sum up to amount+fee_reserve in the first response. For the method bolt11, the wallet can also include outputs in order for the mint to return overpaid Lightning fees (see NUT-08). The mint responds with a payment state. If the state is \"PAID\" the response includes a payment_preimage as a proof of payment. If the request included outputs, the mint may respond with change for the overpaid fees (see NUT-08).
We limit this document to mint quotes of unit=\"sat\" and method=\"bolt11\" which requests a bolt11 Lightning payment (typically paid by the mint from its Bitcoin reserves) using ecash denominated in Satoshis.
Where quote is the quote ID, amount the amount that needs to be provided, and fee_reserve the additional fee reserve that is required. The mint expects Alice to include Proofs of at least total_amount = amount + fee_reserve. expiry is the Unix timestamp until which the melt quote is valid. payment_preimage is the bolt11 payment preimage in case of a successful payment.
state is an enum string field with possible values \"UNPAID\", \"PENDING\", \"PAID\":
\"UNPAID\" means that the request has not been paid yet.
\"PENDING\" means that the request is currently being paid.
\"PAID\" means that the request has been paid successfully.
Now that Alice knows what the total amount is (amount + fee_reserve) in her requested unit, she can proceed to melting tokens for which a payment will be executed by the mint. She calls the POST /v1/melt/{method} endpoint where method is the payment method requested (here bolt11).
POST https://mint.host:3338/v1/melt/bolt11\n
\u26a0\ufe0f Attention: This call will block until the Lightning payment either succeeds or fails. This can take quite a long time in case the Lightning payment is slow. Make sure to use no (or a very long) timeout when making this call!
The wallet of Alice includes the following PostMeltBolt11Request data in its request
Here, quote is the melt quote ID to be paid and inputs are the proofs with a total amount of at least amount + fee_reserve (see previous melt quote response).
Like before, the mint Bob then responds with a PostMeltQuoteBolt11Response. If the payment was successful, the state field is set to \"PAID\" and the response includes the payment_preimage field containing the payment secret of the bolt11 payment.
If state==\"PAID\", Alice's wallet can delete the inputs from her database (or move them to a history). If state==\"UNPAID\", Alice can repeat the same request again until the payment is successful.
The mint's settings for this nut indicate the supported method-unit pairs for melting. They are part of the info response of the mint (NUT-06) which in this case reads
(optional) name is the name of the mint and should be recognizable.
(optional) pubkey is the hex pubkey of the mint.
(optional) version is the implementation name and the version of the software running on this mint separated with a slash \"/\".
(optional) description is a short description of the mint that can be shown in the wallet next to the mint's name.
(optional) description_long is a long description that can be shown in an additional field.
(optional) contact is an array of contact objects to reach the mint operator. A contact object consists of two fields. The method field denotes the contact method (like \"email\"), the info field denotes the identifier (like \"contact@me.com\").
(optional) motd is the message of the day that the wallet must display to the user. It should only be used to display important announcements to users, such as scheduled maintenances.
(optional) icon_url is the URL pointing to an image to be used as an icon for the mint. Recommended to be squared in shape.
(optional) time is the current time set on the server. The value is passed as a Unix timestamp integer.
(optional) nuts indicates each NUT specification that the mint supports and its settings. The settings are defined in each NUT separately.
With curl:
curl -X GET https://mint.host:3338/v1/info\n
"},{"location":"07/","title":"NUT-07: Token state check","text":"
optional
used in: NUT-17
With the token state check, wallets can ask the mint whether a specific proof is already spent and whether it is in-flight in a transaction. Wallets can also request the witness data that was used to spend a proof.
A proof is PENDING if it is being processed in a transaction (in an ongoing payment). A PENDING proof cannot be used in another transaction until it is live again.
A proof is SPENT if it has been redeemed and its secret is in the list of spent secrets of the mint.
Note: Before deleting spent proofs from their database, wallets can check if the proof is SPENT to make sure that they don't accidentally delete an unspent proof. Beware that this behavior can make it easier for the mint to correlate the sender to the receiver.
Important: Mints MUST remember which proofs are currently PENDING to avoid reuse of the same token in multiple concurrent transactions. This can be achieved with for example mutex lock whose key is the Proof's Y.
When Alice prepares a token to be sent to Carol, she can mark these tokens in her database as pending. She can then, periodically or upon user input, check with the mint if the token is UNSPENT or whether it has been redeemed by Carol already, i.e., is SPENT. If the proof is not spendable anymore (and, thus, has been redeemed by Carol), she can safely delete the proof from her database.
If Alice's melt operation takes a long time to complete (for example if she requests a very slow Lightning payment) and she closes her wallet in the meantime, the next time she comes online, she can check all proofs marked as pending in her database to determine whether the payment is still in flight (mint returns PENDING), it has succeeded (mint returns SPENT), or it has failed (mint returns UNSPENT).
With the data being of the form PostCheckStateRequest:
{\n \"Ys\": <Array[hex_str]>,\n}\n
Where the elements of the array in Ys are the hexadecimal representation of the compressed point Y = hash_to_curve(secret) of the Proof to check (see NUT-00).
Where Y belongs to the provided Proof to check in the request, state indicates its state, and witness is the witness data that was potentially provided in a previous spend operation (can be empty).
This document describes how the overpaid Lightning fees are handled and extends NUT-05 which describes melting tokens (i.e. paying a Lightning invoice). In short, a wallet includes blank outputs when paying a Lightning invoice which can be assigned a value by the mint if the user has overpaid Lightning fees. This can be the case due to the unpredictability of Lightning network fees. To solve this issue, we introduce so-called blank outputs which are blinded messages with an undetermined value.
Before requesting a Lightning payment as described in NUT-05, Alice produces a number of BlindedMessage which are similar to ordinary blinded messages but their value is yet to be determined by the mint Bob and are thus called blank outputs. The number of necessary blank outputs is max(ceil(log2(fee_reserve)), 1) which ensures that there is at least one output if there is any fee. If the fee_reserve is 0, then the number of blank outputs is 0 as well. The blank outputs will contain the overpaid fees that will be returned by the mint to the wallet.
This code calculates the number of necessary blank outputs in Python:
The wallet wants to pay an invoice with amount := 100 000 sat and determines by asking the mint that fee_reserve is 1000 sats. The wallet then provides 101 000 sat worth of proofs and 10 blank outputs to make the payment (since ceil(log2(1000))=ceil(9.96..)=10). The mint pays the invoice and determines that the actual fee was 100 sat, i.e, the overpaid fee to return is fee_return = 900 sat. The mint splits the amount 900 into summands of 2^n which is 4, 128, 256, 512. The mint inserts these amounts into the blank outputs it received form the wallet and generates 4 new promises. The mint then returns these BlindSignatures to the wallet together with the successful payment status.
The wallet asks the mint for the fee_reserve for paying a specific bolt11 invoice of value amount by calling POST /v1/melt/quote as described in NUT-05. The wallet then provides a PostMeltBolt11Request to POST /v1/melt/bolt11 that has (1) proofs of the value amount+fee_reserve, (2) the bolt11 invoice to be paid, and finally, as a new entry, (3) a field outputs that has n_blank_outputs blinded messages that are generated before the payment attempt to receive potential overpaid fees back to her.
Here we describe how the mint generates BlindSignatures for the overpaid fees. The mint Bob returns in PostMeltQuoteBolt11Response the field change ONLY IF Alice has previously provided outputs for the change AND if the Lightning actual_fees were smaller than the fee_reserve.
If the overpaid_fees = fee_reserve - actual_fees is positive, Bob decomposes it to values of 2^n (as in NUT-00) and then imprints them into the blank_outputs provided by Alice.
Bob then signs these blank outputs (now with the imprinted amounts) and thus generates BlindSignatures. Bob then returns a payment status to the wallet, and, in addition, all blind signatures it generated for the overpaid fees.
Importantly, while Bob does not necessarily return the same number of blind signatures as it received blank outputs from Alice (since some of them may be of value 0), Bob MUST return the all blank signatures with a value greater than 0 in the same order as the blank outputs were received and should omit all blind signatures with value 0. For example, if Bob receives 10 blank outputs but the overpaid fees only occupy 4 blind signatures, Bob will only return these 4 blind signatures with the appropriate imprinted amounts and omit the remaining 6 blind signatures with value 0. Due to the well-defined order of the returned blind signatures, Alice can map the blind signatures returned from Bob to the blank outputs it provided so that she can further apply the correct unblinding operations on them.
Everything here is the same as in NUT-05 except for outputs. The amount field in the BlindedMessages here are ignored by Bob so they can be set to any arbitrary value by Alice (they should be set to a value, like 1 so potential JSON validations do not error).
If the mint has made a successful payment, it will respond the following.
The field change is an array of BlindSignatures that account for the overpaid fees. Notice that the amount has been changed by the mint. Alice must take these and generate Proofs by unblinding them as described in NUT-00 and as she does in NUT-04 when minting new tokens. After generating the Proofs, Alice stores them in her database.
In this document, we describe how wallets can recover blind signatures, and with that their corresponding Proofs, by requesting from the mint to reissue the blind signatures. This can be used for a backup recovery of a lost wallet (see NUT-13) or for recovering the response of an interrupted swap request (see NUT-03).
Mints must store the BlindedMessage and the corresponding BlindSignature in their database every time they issue a BlindSignature. Wallets provide the BlindedMessage for which they request the BlindSignature. Mints only respond with a BlindSignature, if they have previously signed the BlindedMessage. Each returned BlindSignature also contains the amount and the keyset id (see NUT-00) which is all the necessary information for a wallet to recover a Proof.
Request of Alice:
POST https://mint.host:3338/v1/restore\n
With the data being of the form PostRestoreRequest:
{\n \"outputs\": <Array[BlindedMessages]>\n}\n
Response of Bob:
The mint Bob then responds with a PostRestoreResponse.
An ordinary ecash token is a set of Proofs each with a random string secret. To spend such a token in a swap or a melt operation, wallets include proofs in their request each with a unique secret. To autorize a transaction, the mint requires that the secret has not been seen before. This is the most fundamental spending condition in Cashu, which ensures that a token can't be double-spent.
In this NUT, we define a well-known format of secret that can be used to express more complex spending conditions. These conditions need to be met before the mint authorizes a transaction. Note that the specific type of spending condition is not part of this document but will be explained in other documents. Here, we describe the structure of secret which is expressed as a JSON Secret with a specific format.
Spending conditions are enforced by the mint which means that, upon encountering a Proof where Proof.secret can be parsed into the well-known format, the mint can require additional conditions to be met.
Caution: If the mint does not support spending conditions or a specific kind of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
An ecash transaction, i.e., a swap or a melt operation, with a spending condition consists of the following components:
Inputs referring to the Proofs being spent
Secret containing the rules for unlocking a Proof
Additional witness data satisfying the unlock conditions such as signatures
Outputs referring to the BlindMessages with new unlock conditions to which the Proofs are spent to
Spending conditions are defined for each individual Proof and not on a transaction level that can consist of multiple Proofs. Similarly, spending conditions must be satisfied by providing signatures or additional witness data for each Proof separately. For a transaction to be valid, all Proofs in that transaction must be unlocked successfully.
New Secrets of the outputs to which the inputs are spent to are provided as BlindMessages which means that they are blind-signed and not visible to the mint until they are actually spent.
Spending conditions are expressed in a well-known secret format that is revealed to the mint when spending (unlocking) a token, not when the token is minted (locked). The mint parses each Proof's secret. If it can deserialize it into the following format it executes additional spending conditions that are further specified in additional NUTs.
The well-known Secret stored in Proof.secret is a JSON of the format:
"},{"location":"11/","title":"NUT-11: Pay to Public Key (P2PK)","text":"
optional
depends on: NUT-10
This NUT describes Pay-to-Public-Key (P2PK) which is one kind of spending condition based on NUT-10's well-known Secret. Using P2PK, we can lock ecash tokens to a receiver's ECC public key and require a Schnorr signature with the corresponding private key to unlock the ecash. The spending condition is enforced by the mint.
Caution: If the mint does not support this type of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
If for a Proof, Proof.secret is a Secret of kind P2PK, the proof must be unlocked by providing a witness Proof.witness and one or more valid signatures in the array Proof.witness.signatures.
In the basic case, when spending a locked token, the mint requires one valid Schnorr signature in Proof.witness.signatures on Proof.secret by the public key in Proof.Secret.data.
To give a concrete example of the basic case, to mint a locked token we first create a P2PK Secret that reads:
Here, Secret.data is the public key of the recipient of the locked ecash. We serialize this Secret to a string in Proof.secret and get a blind signature by the mint that is stored in Proof.C (see NUT-03]).
The recipient who owns the private key of the public key Secret.data can spend this proof by providing a signature on the serialized Proof.secret string that is then added to Proof.witness.signatures:
To spend a token locked with P2PK, the spender needs to include signatures in the spent proofs. We use libsecp256k1's serialized 64 byte Schnorr signatures on the SHA256 hash of the message to sign. The message to sign is the field Proof.secret in the inputs. If indicated by Secret.tags.sigflag in the inputs, outputs might also require signatures on the message BlindedMessage.B_.
An ecash spending operation like swap and melt can have multiple inputs and outputs. If we have more than one input or output, we provide signatures in each Proof and BlindedMessage individually. The inputs are the Proofs provided in the inputs field and the outputs are the BlindedMessages in the outputs field in the request body (see PostMeltRequest in NUT-05 and PostSwapRequest in NUT-03).
"},{"location":"11/#tags","title":"Tags","text":"
More complex spending conditions can be defined in the tags in Proof.tags. All tags are optional. Tags are arrays with two or more strings being [\"key\", \"value1\", \"value2\", ...].
Supported tags are:
sigflag: <str> determines whether outputs have to be signed as well
n_sigs: <int> specifies the minimum number of valid signatures expected
pubkeys: <hex_str> are additional public keys that can provide signatures (allows multiple entries)
locktime: <int> is the Unix timestamp of when the lock expires
refund: <hex_str> are optional refund public keys that can exclusively spend after locktime (allows multiple entries)
Note: The tag serialization type is [<str>, <str>, ...] but some tag values are int. Wallets and mints must cast types appropriately for de/serialization.
Signatures must be provided in the field Proof.witness.signatures for each Proof which is an input. If the signature flag SIG_ALL is enforced, signatures must also be provided for every output in its field BlindedMessage.witness.signatures.
If the tag n_sigs is a positive integer, the mint will also consider signatures from public keys specified in the pubkeys tag additional to the public key in Secret.data. If the number of valid signatures is greater or equal to the number specified in n_sigs, the transaction is valid.
Expressed as an \"n-of-m\" scheme, n = n_sigs is the number of required signatures and m = 1 (\"data\" field) + len(pubkeys tag) is the number of public keys that could sign.
If the tag locktime is the unix time and the mint's local clock is greater than locktime, the Proof becomes spendable by anyone, except if the following condition is also true. Note: A Proof is considered spendable by anyone if it only requires a secret and a valid signature C to be spent (which is the default case).
"},{"location":"11/#refund-public-keys","title":"Refund public keys","text":"
If the locktime is in the past and a tag refund is present, the Proof is spendable only if a valid signature by one of the the refund pubkeys is provided in Proof.witness.signatures and, depending on the signature flag, in BlindedMessage.witness.signatures.
This is an example secret that locks a Proof with a Pay-to-Pubkey (P2PK) condition that requires 2-of-3 signatures from the public keys in the data field and the pubkeys tag. If the timelock has passed, the Proof becomes spendable with a single signature from the public key in the refund tag. The signature flag sigflag indicates that signatures are necessary on the inputs and the outputs of a transaction.
In this document, we present an extension of Cashu's crypto system to allow a user Alice to verify the mint Bob's signature using only Bob's public keys. We explain how another user Carol who receives ecash from Alice can execute the DLEQ proof as well. This is achieved using a Discrete Log Equality (DLEQ) proof. Previously, Bob's signature could only be checked by himself using his own private keys (NUT-00).
The purpose of this DLEQ is to prove that the mint has used the same private key a for creating its public key A (NUT-01) and for signing the BlindedMessage B'. Bob returns the DLEQ proof additional to the blind signature C' for a mint or swap operation.
The complete DLEQ proof reads
# DLEQ Proof\n\n(These steps occur when Bob returns C')\n\nBob:\nr = random nonce\nR1 = r*G\nR2 = r*B'\ne = hash(R1,R2,A,C')\ns = r + e*a\nreturn e, s\n\nAlice:\nR1 = s*G - e*A\nR2 = s*B' - e*C'\ne == hash(R1,R2,A,C')\n\nIf true, a in A = a*G must be equal to a in C' = a*B'\n
The hash(x) function generates a deterministic Sha256 hash for a given input list of PublicKey. The uncompressed hexadecimal representations of each PublicKey is concatenated before taking the Sha256 hash.
def hash_e(*publickeys: PublicKey) -> bytes:\n e_ = \"\"\n for p in publickeys:\n _p = p.serialize(compressed=False).hex()\n e_ += str(_p)\n e = hashlib.sha256(e_.encode(\"utf-8\")).digest()\n return e\n
"},{"location":"12/#mint-to-user-dleq-in-blindsignature","title":"Mint to user: DLEQ in BlindSignature","text":"
The mint produces these DLEQ proofs when returning BlindSignature's in the responses for minting (NUT-04) and swapping (NUT-03) tokens. The BlindSignature object is extended in the following way to include the DLEQ proof:
"},{"location":"12/#user-to-user-dleq-in-proof","title":"User to user: DLEQ in Proof","text":"
In order for Alice to communicate the DLEQ to another user Carol, we extend the Proof (see NUT-00) object and include the DLEQ proof. As explained below, we also need to include the blinding factor r for the proof to be convincing to another user Carol.
e and s are the challenge and response of the DLEQ proof returned by Bob, r is the blinding factor of Alice that was used to generate the Proof. Alice serializes these proofs like any other in a token (see NUT-00) to send it to another user Carol.
When minting or swapping tokens, Alice receives DLEQ proofs in the BlindSignature response from the mint Bob. Alice checks the validity of the DLEQ proofs for each ecash token she receives via the equations:
R1 = s*G - e*A\nR2 = s*B' - e*C'\ne == hash(R1,R2,A,C') # must be True\n
Here, the variables are
A \u2013\u00a0the public key Bob used to sign this Proof
(e, s) \u2013\u00a0the DLEQ proof returned by Bob
B' \u2013 Alice's BlindedMessage
C' \u2013 Bob's BlindSignature on B'
In order to execute the proof, Alice needs e, s that are returned in the BlindSignature by Bob. Alice further needs B' (the BlindedMessageAlice created and Bob signed) and C' (the blind signature in the BlindSignature response) from Bob, and A (the public key of Bob with which he signed the BlindedMessage). All these values are available to Alice during or after calling the mint and swap operations.
If a DLEQ proof is included in the mint's BlindSignature response, wallets MUST verify the DLEQ proof.
Carol is a user that receives Proofs in a token from another user Alice. When Alice sends Proofs with DLEQ proofs to Carol or when Alice posts the Proofs publicly, Carol can validate the DLEQ proof herself and verify Bob's signature without having to talk to Bob. Alice includes the following information in the Proof (see above):
(x, C) \u2013\u00a0the ecash Proof
(e, s) \u2013\u00a0the DLEQ proof revealed by Alice
r \u2013 Alice's blinding factor
Here, x is the Proof's secret, and C is the mint's signature on it. To execute the DLEQ proof like Alice did above, Carol needs (B', C') which she can compute herself using the blinding factor r that she receives from Alice.
To verify the DLEQ proof of a received token, Carol needs to reconstruct B' and C' using the blinding factor r that Alice has included in the Proof she sent to Carol. Since Carol now has all the necessary information, she can execute the same equations to verify the DLEQ proof as Alice did:
Y = hash_to_curve(x)\nC' = C + r*A\nB' = Y + r*G\n\nR1 = ... (same as Alice)\n
If a DLEQ proof is included in a received token, wallets MUST verify the proof.
In this document, we describe the process that allows wallets to recover their ecash balance with the help of the mint using a familiar 12 word seed phrase (mnemonic). This allows us to restore the wallet's previous state in case of a device loss or other loss of access to the wallet. The basic idea is that wallets that generate the ecash deterministically can regenerate the same tokens during a recovery process. For this, they ask the mint to reissue previously generated signatures using NUT-09.
An ecash token, or a Proof, consists of a secret generated by the wallet, and a signature C generated by the wallet and the mint in collaboration. Here, we describe how wallets can deterministically generate the secrets and blinding factors r necessary to generate the signatures C.
The wallet generates a private_key derived from a 12-word BIP39 mnemonic seed phrase that the user stores in a secure place. The wallet uses the private_key, to derive deterministic values for the secret and the blinding factors r for every new ecash token that it generates.
In order to do this, the wallet keeps track of a counter_k for each keyset_k it uses. The index k indicates that the wallet needs to keep track of a separate counter for each keyset k it uses. Typically, the wallet will need to keep track of multiple keysets for every mint it interacts with. counter_k is used to generate a BIP32 derivation path which can then be used to derive secret and r.
The following BIP32 derivation path is used. The derivation path depends on the keyset ID of keyset_k, and the counter_k of that keyset.
Purpose' = 129372' (UTF-8 for \ud83e\udd5c)
Coin type' = Always 0'
Keyset id' = Keyset ID represented as an integer (keyset_k_int)
Coin counter' = counter' (this value is incremented)
Here, {keyset_k_int} and {counter_k} are the only variables that can change. keyset_id_k_int is an integer representation (see below) of the keyset ID the token is generated with. This means that the derivation path is unique for each keyset. Note that the coin type is always 0', independent of the unit of the ecash.
The wallet starts with counter_k := 0 upon encountering a new keyset and increments it by 1 every time it has successfully minted new ecash with this keyset. The wallet stores the latest counter_k in its database for all keysets it uses. Note that we have a counter (and therefore a derivation path) for each keyset k. We omit the keyset index k in the following of this document.
The integer representation keyset_id_int of a keyset is calculated from its hexadecimal ID which has a length of 8 bytes or 16 hex characters. First, we convert the hex string to a big-endian sequence of bytes. This value is then modulo reduced by 2^31 - 1 to arrive at an integer that is a unique identifier keyset_id_int.
"},{"location":"13/#restore-from-seed-phrase","title":"Restore from seed phrase","text":"
Using deterministic secret derivation, a user's wallet can regenerate the same BlindedMessages in case of loss of a previous wallet state. To also restore the corresponding BlindSignatures to fully recover the ecash, the wallet can either requests the mint to re-issue past BlindSignatures on the regenerated BlindedMessages (see NUT-09) or by downloading the entire database of the mint (TBD).
The wallet takes the following steps during recovery:
To generate the BlindedMessages, the wallet starts with a counter := 0 and , for each increment of the counter, generates a secret using the BIP32 private key derived from secret_derivation_path and converts it to a hex string.
The wallet similarly generates a blinding factor r from the r_derivation_path:
r = self.bip32.get_privkey_from_path(r_derivation_path)\n
Note: For examples, see the test vectors.
Using the secret string and the private key r, the wallet generates a BlindedMessage. The wallet then increases the counter by 1 and repeats the same process for a given batch size. It is recommended to use a batch size of 100.
The user's wallet can now request the corresponding BlindSignatures for theses BlindedMessages from the mint using the NUT-09 restore endpoint or by downloading the entire mint's database.
Using the restored BlindSignatures and the r generated in the previous step, the wallet can unblind the signature to C. The triple (secret, C, amount) is a restored Proof.
If the wallet used the restore endpoint NUT-09 for regenerating the Proofs, it additionally needs to check for the Proofs spent state using NUT-07. The wallet deletes all Proofs which are already spent and keeps the unspent ones in its database.
Generally, the user won't remember the last state of counter when starting the recovery process. Therefore, wallets need to know how far they need to increment the counter during the restore process to be confident to have reached the most recent state.
In short, following approach is recommended:
Restore Proofs in batches of 100 and increment counter
Repeat until three consecutive batches are returned empty
Reset counter to the value at the last successful restore + 1
Wallets restore Proofs in batches of 100. The wallet starts with a counter=0 and increments it for every Proof it generated during one batch. When the wallet begins restoring the first Proofs, it is likely that the first few batches will only contain spent Proofs. Eventually, the wallet will reach a counter that will result in unspent Proofs which it stores in its database. The wallet then continues to restore until three successive batches are returned empty by the mint. This is to be confident that the restore process did not miss any Proofs that might have been generated with larger gaps in the counter by the previous wallet that we are restoring.
This NUT describes the use of Hashed Timelock Contracts (HTLCs) which defines a spending condition based on NUT-10's well-known Secret format. Using HTLCs, ecash tokens can be locked to the hash of a preimage or a timelock. This enables use cases such as atomic swaps of ecash between users, and atomic coupling of an ecash spending condition to a Lightning HTLC.
HTLC spending conditions can be thought of as an extension of P2PK locks NUT-11 but with a hash lock in Secret.data and a new Proof.witness.preimage witness in the locked inputs to be spent. The preimage that was used to spend a locked token can be retrieved using NUT-07. Caution: applications that rely on being able to retrieve the witness independent from the spender must check via the mint's info endpoint that NUT-07 is supported.
Caution: If the mint does not support this type of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
"},{"location":"14/#htlc","title":"HTLC","text":"
NUT-10 Secret kind: HTLC
If for a Proof, Proof.secret is a Secret of kind HTLC, the hash of the lock is in Proof.secret.data. The preimage for unlocking the HTLC is in the witness Proof.witness.preimage. All additional tags from P2PK locks are used here as well, allowing us to add a locktime, signature flag, and use multisig (see NUT-11).
Here is a concrete example of a Secret of kind HTLC:
A Proof with this Secret can be spent in two ways. To spend the hash lock, the witness in Proof.witness includes the preimage to Secret.data and a signature from the key in Secret.tag.pubkeys. Additionally, if the current system time is later than Secret.tag.locktime, the Proof can be spent if Proof.witness includes a signature from the key in Secret.tags.refund.
The hash lock in Secret.data and the preimage in Proof.witness.preimage is treated as 32 byte data encoded as 64 character hex strings.
See NUT-11 for a description of the signature scheme, the additional use of signature flags, and how to require signature from multiple public keys (multisig).
In this document, we describe how wallets can instruct multiple mints to each pay a partial amount of a bolt11 Lightning invoice. The full payment is composed of partial payments (MPP) from multiple multi-path payments from different Lightning nodes. This way, wallets can pay a larger Lightning invoice combined from multiple smaller balances on different mints. Due to the atomic nature of MPP, either all payments will be successful or all of them will fail.
The Lightning backend of the mint must support paying a partial amount of an Invoice and multi-path payments (MPP, see BOLT 4). For example, the mint's Lightning node must be able to pay 50 sats of a 100 sat bolt11 invoice. The receiving Lightning node must support receiving multi-path payments as well.
Alice's wallet coordinates multiple MPPs on different mints that support the feature (see below for the indicated setting). For a given Lightning invoice of amount_total, Alice splits the total amount into several partial amounts amount_total = amount_1 + amount_2 + ... that each must be covered by her individual balances on the mints she wants to use for the payment. She constructs multiple PostMeltQuoteBolt11Request's that each include the corresponding partial amount in the payment option (see below) that she sends to all mints she wants to use for the payment. The mints then respond with a normal PostMeltQuoteBolt11Response (see NUT-05). Alice proceeds to pay the melt requests at each mint simultaneously. When all mints have sent out the partial Lightning payment, she receives a successful response from all mints individually.
To request a melt quote with a partial amount, the wallet of Alice makes a POST /v1/melt/quote/bolt11 similar to NUT-05.
POST https://mint.host:3338/v1/melt/quote/bolt11\n
The wallet Alice includes the following PostMeltQuoteBolt11Request data in its request which includes an additional (and optional) options object compared to the standard request in NUT-05:
Here, request is the bolt11 Lightning invoice to be paid, unit is the unit the wallet would like to pay with, and amount is the amount for the requested payment. The wallet then pays the returned melt quote the same way as in NUT-05.
The settings returned in the info endpoint (NUT-06) indicate that a mint supports this NUT. The mint MUST indicate each method and unit that supports mpp. It can indicate this in an array of objects for multiple method and unit pairs and the boolean flag mpp set to true.
QR codes are a great way to send and receive Cashu tokens. Before a token can be shared as a QR code, it needs to be serialized (see NUT-00).
"},{"location":"16/#static-qr-codes","title":"Static QR codes","text":"
If the serialized token is not too large (i.e. includes less than or equal to 2 proofs) it can usually be shared as a static QR code. This might not be the case if the secret includes long scripts or the token has a long memo or mint URL.
"},{"location":"16/#animated-qr-codes","title":"Animated QR codes","text":"
If a token is too large to be displayed as a single QR code, we use animated QR codes are based on the UR protocol. The sender produces an animated QR code from a serialized Cashu token. The receiver scans the animated QR code until the UR decoder is able to decode the token.
The websocket enables real-time subscriptions that wallets can use to receive notifications for a state change of a MintQuoteResponse (NUT-04), MeltQuoteResponse (NUT-05), CheckStateResponse (NUT-07).
A summary of the subscription flow is the following:
A wallet connects to the websocket endpoint and sends a WsRequest with the subscribe command.
The mint responds with a WsResponse containing an ok or an error.
If the subscription was accepted, the mint sends a WsNotification of the current state of the subscribed objects and whenever there is an update for the wallet's subscriptions.
To close a subscription, the wallet sends WsRequest with the unsubscribe command.
Note that id and subId are unrelated. The subId is the ID for each subscription, whereas id is part of the JSON-RPC spec and is an integer counter that must be incremented for every request sent over the websocket.
Important: If the subscription is accepted by the mint, the mint MUST first respond with the current state of the subscribed object and continue sending any further updates to it.
For example, if the wallet subscribes to a Proof.Y of a Proof that has not been spent yet, the mint will first respond with a ProofState with state == \"UNSPENT\". If the wallet then spends this Proof, the mint would send a ProofState with state == \"PENDING\" and then one with state == \"SPENT\". In total, the mint would send three notifications to the wallet.
The wallet should always unsubscribe any subscriptions that is isn't interested in anymore. The parameters for the \"unsubscribe\" command is only the subscription ID:
subId is the subscription ID (previously generated by the wallet) this notification corresponds to. NotificationPayload carries the subscription data which is a MintQuoteResponse (NUT-04), a MeltQuoteResponse (NUT-05), or a CheckStateResponse (NUT-07), depending on what the corresponding SubscriptionKind was.
To subscribe to the ProofState of a Proof, the wallet establishes a websocket connection to https://mint.com/v1/ws and sends a WsRequest with a filters chosen to be the a Proof.Y value of the Proof (see NUT-00). Note that filters is an array meaning multiple subscriptions of the same kind can be made in the same request.
While leaving the websocket connection open, the wallet then spends the ecash. The mint sends WsNotification updating the wallet about state changes of the ProofState accordingly:
Here, commands is an array of the commands that the mint supports. A mint that supports all commands would return [\"bolt11_mint_quote\", \"bolt11_melt_quote\", \"proof_state\"]. Supported commands are given for each method-unit pair.
"},{"location":"error_codes/","title":"NUT Errors","text":"Code Description Relevant nuts 10002 Blinded message of output already signed NUT-03, NUT-04, NUT-05 10003 Token could not be verified NUT-03, NUT-05 11001 Token is already spent NUT-03, NUT-05 11002 Transaction is not balanced (inputs != outputs) NUT-02, NUT-03, NUT-05 11005 Unit in request is not supported NUT-04, NUT-05 11006 Amount outside of limit range NUT-04, NUT-05 12001 Keyset is not known NUT-02, NUT-04 12002 Keyset is inactive, cannot sign messages NUT-02, NUT-03, NUT-04 20001 Quote request is not paid NUT-04 20002 Tokens have already been issued for quote NUT-04 20003 Minting is disabled NUT-04 20005 Quote is pending NUT-04, NUT-05 20006 Invoice already paid NUT-05 20007 Quote is expired NUT-04, NUT-05"},{"location":"tests/","title":"Test Vectors","text":"
The files in this directory contain test vectors for NUTs that warrant them.
"},{"location":"tests/00-tests/","title":"NUT-00 Test Vectors","text":""},{"location":"tests/00-tests/#hash-to-curve-function","title":"Hash-to-curve function","text":"
The hash to curve function takes a message of any length and outputs a valid point on the secp256k1 curve. Note that unless you are using complex spend conditions (NUT-10), standardized secrets (random 32-bytes-long byte arrays) should be used in order to prevent wallet fingerprinting.
# Test 1 (hex encoded)\nMessage: 0000000000000000000000000000000000000000000000000000000000000000\nPoint: 024cce997d3b518f739663b757deaec95bcd9473c30a14ac2fd04023a739d1a725\n\n# Test 2 (hex encoded)\nMessage: 0000000000000000000000000000000000000000000000000000000000000001\nPoint: 022e7158e11c9506f1aa4248bf531298daa7febd6194f003edcd9b93ade6253acf\n\n# Test 3 (hex encoded)\n# Note that this message will take a few iterations of the loop before finding a valid point\nMessage: 0000000000000000000000000000000000000000000000000000000000000002\nPoint: 026cdbe15362df59cd1dd3c9c11de8aedac2106eca69236ecd9fbe117af897be4f\n
Both of the following v3 tokens are valid, one includes padding characters at the end and the other does not.
# Clients should be able to deserialize both\ncashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vODMzMy5zcGFjZTozMzM4IiwicHJvb2ZzIjpbeyJhbW91bnQiOjIsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6IjQwNzkxNWJjMjEyYmU2MWE3N2UzZTZkMmFlYjRjNzI3OTgwYmRhNTFjZDA2YTZhZmMyOWUyODYxNzY4YTc4MzciLCJDIjoiMDJiYzkwOTc5OTdkODFhZmIyY2M3MzQ2YjVlNDM0NWE5MzQ2YmQyYTUwNmViNzk1ODU5OGE3MmYwY2Y4NTE2M2VhIn0seyJhbW91bnQiOjgsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6ImZlMTUxMDkzMTRlNjFkNzc1NmIwZjhlZTBmMjNhNjI0YWNhYTNmNGUwNDJmNjE0MzNjNzI4YzcwNTdiOTMxYmUiLCJDIjoiMDI5ZThlNTA1MGI4OTBhN2Q2YzA5NjhkYjE2YmMxZDVkNWZhMDQwZWExZGUyODRmNmVjNjlkNjEyOTlmNjcxMDU5In1dfV0sInVuaXQiOiJzYXQiLCJtZW1vIjoiVGhhbmsgeW91IHZlcnkgbXVjaC4ifQ==\ncashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vODMzMy5zcGFjZTozMzM4IiwicHJvb2ZzIjpbeyJhbW91bnQiOjIsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6IjQwNzkxNWJjMjEyYmU2MWE3N2UzZTZkMmFlYjRjNzI3OTgwYmRhNTFjZDA2YTZhZmMyOWUyODYxNzY4YTc4MzciLCJDIjoiMDJiYzkwOTc5OTdkODFhZmIyY2M3MzQ2YjVlNDM0NWE5MzQ2YmQyYTUwNmViNzk1ODU5OGE3MmYwY2Y4NTE2M2VhIn0seyJhbW91bnQiOjgsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6ImZlMTUxMDkzMTRlNjFkNzc1NmIwZjhlZTBmMjNhNjI0YWNhYTNmNGUwNDJmNjE0MzNjNzI4YzcwNTdiOTMxYmUiLCJDIjoiMDI5ZThlNTA1MGI4OTBhN2Q2YzA5NjhkYjE2YmMxZDVkNWZhMDQwZWExZGUyODRmNmVjNjlkNjEyOTlmNjcxMDU5In1dfV0sInVuaXQiOiJzYXQiLCJtZW1vIjoiVGhhbmsgeW91IHZlcnkgbXVjaC4ifQ\n
"},{"location":"tests/00-tests/#serialization-of-tokenv4","title":"Serialization of TokenV4","text":"
The following are JSON-formatted v4 tokens and their serialized counterparts. The h'' values are bytes but displayed as hex strings here.
The following are correct keysets that should be accepted by wallets implementing the NUT-01 specification. Note that the second (bigger) keyset's biggest amount is 9223372036854775808, one unit over what can fit into a 64-bit signed integer (often known as a Long). To handle this you'll need to use either an unsigned 64-bit integer or a 128-bit signed integer (sometimes known as a BigInteger).
"},{"location":"tests/12-tests/","title":"NUT-12 Test vectors","text":""},{"location":"tests/12-tests/#hash_e-function","title":"hash_e function","text":"
"},{"location":"tests/13-tests/","title":"NUT-13 Test vectors","text":""},{"location":"tests/13-tests/#keyset-id-integer-representation","title":"Keyset ID integer representation","text":"
The integer representation of a keyset with an ID 009a1f293253e41e and its corresponding derivation path for a counter of value {counter} are
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Cashu NUTs (Notation, Usage, and Terminology)","text":"
These documents each specify parts of the Cashu protocol. Read the specifications for the legacy API here.
"},{"location":"00/","title":"NUT-00: Notation, Utilization, and Terminology","text":"
mandatory
This document details the notation and models used throughout the specification and lays the groundwork for understanding the basic cryptography used in the Cashu protocol.
Alice picks secret x and computes Y = hash_to_curve(x)
Alice sends to Bob: B_ = Y + rG with r being a random blinding factor (blinding)
Bob sends back to Alice blinded key: C_ = kB_ (these two steps are the DH key exchange) (signing)
Alice can calculate the unblinded key as C_ - rK = kY + krG - krG = kY = C (unblinding)
Alice can take the pair (x, C) as a token and can send it to Carol.
Carol can send (x, C) to Bob who then checks that k*hash_to_curve(x) == C (verification), and if so treats it as a valid spend of a token, adding x to the list of spent secrets.
An encrypted (\"blinded\") secret and an amount is sent from Alice to Bob for minting tokens or for swapping tokens. A BlindedMessage is also called an output.
amount is the value for the requested BlindSignature, id is the requested keyset ID from which we expect a signature, and B_ is the blinded secret message generated by Alice. An array [BlindedMessage] is also referred to as BlindedMessages.
amount is the value of the blinded token, id is the keyset id of the mint keys that signed the token, and C_ is the blinded signature on the secret message B_ sent in the previous step.
A Proof is also called an input and is generated by Alice from a BlindSignature it received. An array [Proof] is called Proofs. Alice sends Proofs to Bob for melting tokens. Serialized Proofs can also be sent from Alice to Carol. Upon receiving the token, Carol deserializes it and requests a swap from Bob to receive new Proofs.
amount is the amount of the Proof, secret is the secret message and is a utf-8 encoded string (the use of a 64 character hex string generated from 32 random bytes is recommended to prevent fingerprinting), C is the unblinded signature on secret (hex string), id is the keyset id of the mint public keys that signed the token (hex string).
In case of an error, mints respond with the HTTP status code 400 and include the following data in their response:
{\n \"detail\": \"oops\",\n \"code\": 1337\n}\n
Here, detail is the error message, and code is the error code. Error codes are to be defined in the documents concerning the use of a certain API endpoint.
"},{"location":"00/#03-methods","title":"0.3 - Methods","text":""},{"location":"00/#serialization-of-tokens","title":"Serialization of tokens","text":"
Tokens can be serialized to send them between users Alice and Carol. Serialized tokens have a Cashu token prefix, a versioning flag, and the token. Optionally, a URI prefix for making tokens clickable on the web.
We use the following format for token serialization:
cashu[version][token]\n
cashu is the Cashu token prefix. [version] is a single base64_urlsafe character to denote the token format version.
V3 tokens are base64-encoded JSON objects. The token format supports tokens from multiple mints. The JSON is serialized with a base64_urlsafe (base64 encoding with / replaced by _ and + by -). base64_urlsafe strings may have padding characters (usually =) at the end which can be omitted. Clients need to be able to decode both cases.
cashuA[base64_token_json]\n
[base64_token_json] is the token JSON serialized in base64_urlsafe. [base64_token_json] should be cleared of any whitespace before serializing.
mint is the mint URL. The mint URL must be stripped of any trailing slashes (/). Proofs is an array of Proof objects. The next two elements are only for displaying the receiving user appropriate information: unit is the currency unit of the token keysets (see Keysets for supported units), and memo is an optional text memo from the sender.
V4 tokens are a space-efficient way of serializing tokens using the CBOR binary format. All field are single characters and hex strings are encoded in binary. V4 tokens can only hold proofs from a single mint.
Wallets serialize tokens in a base64_urlsafe format (base64 encoding with / replaced by _ and + by -). base64_urlsafe strings may have padding characters (usually =) at the end which can be omitted. Clients need to be able to decode both cases.
The deserialized base64_token_cbor is a JSON of the same form as a TokenV4 but with shorter keys and data represented as binary data (bytes) instead of hex strings (hex_str). Note that we have expanded what is called Proofs in TokenV3 (called p here with TokenV4) showing that its values are also different from the TokenV3 serialization.
m is the mint URL. The mint URL must be stripped of any trailing slashes (/). u is the currency unit of the token keysets (see Keysets for supported units), and d is an optional text memo from the sender.
i is the keyset ID of the profs in p, which is an array of Proof objects without the id field. We extracted the keyset ID id from each proof and grouped all proofs by their keyset ID i one level above (in p).
Note that all fields of the bytes type encode hex strings in the original representation of Proof's.
The h'' values are bytes but displayed as hex strings here.
We serialize this JSON using CBOR which can be seen here. The resulting bytes are then serialized to a string using base64_urlsafe and the prefix cashuB is added. This leaves us with the following serialized TokenV4:
"},{"location":"01/","title":"NUT-01: Mint public key exchange","text":"
mandatory
This document outlines the exchange of the public keys of the mint Bob with the wallet user Alice. Alice uses the keys to unblind Bob's blind signatures (see NUT-00).
Wallet user Alice receives public keys from mint Bob via GET /v1/keys. The set of all public keys for a set of amounts is called a keyset.
The mint responds only with its active keysets. Keyset are active if the mint will sign promises with it. The mint will accept tokens from inactive keysets as inputs but will not sign with them for new outputs. The active keysets can change over time, for example due to key rotation. A list of all keysets, active and inactive, can be requested separately (see NUT-02).
Note that a mint can support multiple keysets at the same time but will only respond with the active keysets on the endpoint GET /v1/keys. A wallet can ask for the keys of a specific (active or inactive) keyset via the endpoint GET /v1/keys/{keyset_id} (see NUT-02).
Keysets are generated by the mint. The mint is free to use any key generation method they like. Each keyset is identified by its keyset id which can be computed by anyone from its public keys (see NUT-02).
Keys in Keysets are maps of the form {<amount_1> : <mint_pubkey_1>, <amount_2> : <mint_pubkey_2>, ...} for each <amount_i> of the amounts the mint Bob supports and the corresponding public key <mint_pubkey_1>, that is K_i (see NUT-00). The mint MUST use the compressed Secp256k1 public key format to represent its public keys.
"},{"location":"02/","title":"NUT-02: Keysets and fees","text":"
mandatory
A keyset is a set of public keys that the mint Bob generates and shares with its users. It refers to the set of public keys that each correspond to the amount values that the mint supports (e.g. 1, 2, 4, 8, ...) respectively.
Each keyset indicates its keyset id, the currency unit, whether the keyset is active, and an input_fee_ppk that determines the fees for spending ecash from this keyset.
A mint can have multiple keysets at the same time. For example, it could have one keyset for each currency unit that it supports. Wallets should support multiple keysets. They must respect the active and the input_fee_ppk properties of the keysets they use.
A keyset id is an identifier for a specific keyset. It can be derived by anyone who knows the set of public keys of a mint. Wallets CAN compute the keyset id for a given keyset by themselves to confirm that the mint is supplying the correct keyset ID (see below).
The keyset id is in each Proof so it can be used by wallets to identify which mint and keyset it was generated from. The keyset field id is also present in the BlindedMessages sent to the mint and BlindSignatures returned from the mint (see NUT-00).
Mints can have multiple keysets at the same time but MUST have at least one active keyset (see NUT-01). The active property determines whether the mint allows generating new ecash from this keyset. Proofs from inactive keysets with active=false are still accepted as inputs but new outputs (BlindedMessages and BlindSignatures) MUST be from active keysets only.
To rotate keysets, a mint can generate a new active keyset and inactive an old one. If the active flag of an old keyset is set to false, no new ecash from this keyset can be generated and the outstanding ecash supply of that keyset can be taken out of circulation as wallets rotate their ecash to active keysets.
Wallets SHOULD prioritize swaps with Proofs from inactive keysets (see NUT-03) so they can quickly get rid of them. Wallets CAN swap their entire balance from an inactive keyset to an active one as soon as they detect that the keyset was inactivated. When constructing outputs for a transaction, wallets MUST choose only active keysets (see NUT-00).
"},{"location":"02/#fees","title":"Fees","text":"
Keysets indicate the fee input_fee_ppk that is charged when a Proof of that keyset is spent as an input to a transaction. The fee is given in parts per thousand (ppk) per input measured in the unit of the keyset. The total fee for a transaction is the sum of all fees per input rounded up to the next larger integer (that that can be represented with the keyest).
As an example, we construct a transaction spending 3 inputs (Proofs) from a keyset with unit sat and input_fee_ppk of 100. A fee of 100 ppk means 0.1 sat per input. The sum of the individual fees are 300 ppk for this transaction. Rounded up to the next smallest denomination, the mint charges 1 sat in total fees, i.e. fees = ceil(0.3) == 1. In this case, the fees for spending 1-10 inputs is 1 sat, 11-20 inputs is 2 sat and so on.
When constructing a transaction with ecash inputs (example: /v1/swap or /v1/melt), wallets MUST add fees to the inputs or, vice versa, subtract from the outputs. The mint checks the following equation:
sum(inputs) - fees == sum(outputs)\n
Here, sum(inputs) and sum(outputs) mean the sum of the amounts of the inputs and outputs respectively. fees is calculated from the sum of each input's fee and rounded up to the next larger integer:
Here, the // operator in (sum_fees + 999) // 1000 denotes an integer division operator (aka floor division operator) that rounds down sum_fees + 999 to the next lower integer. Alternatively, we could round up the sum using a floating point division with ceil(sum_fees / 1000) although it is not recommended to do so due to the non-deterministic behavior of floating point division.
Notice that since transactions can spend inputs from different keysets, the sum considers the fee for each Proof indexed by the keyset ID individually.
"},{"location":"02/#deriving-the-keyset-id","title":"Deriving the keyset ID","text":""},{"location":"02/#keyset-id-version","title":"Keyset ID version","text":"
Keyset IDs have a version byte (two hexadecimal characters). The currently used version byte is 00.
The mint and the wallets of its users can derive a keyset ID from the keyset of the mint. The keyset ID is a lower-case hex string. To derive the keyset ID of a keyset, execute the following steps:
1 - sort public keys by their amount in ascending order\n2 - concatenate all public keys to one byte array\n3 - HASH_SHA256 the concatenated public keys\n4 - take the first 14 characters of the hex-encoded hash\n5 - prefix it with a keyset ID version byte\n
An example implementation in Python:
def derive_keyset_id(keys: Dict[int, PublicKey]) -> str:\n sorted_keys = dict(sorted(keys.items()))\n pubkeys_concat = b\"\".join([p.serialize() for p in sorted_keys.values()])\n return \"00\" + hashlib.sha256(pubkeys_concat).hexdigest()[:14]\n
"},{"location":"02/#example-get-mint-keysets","title":"Example: Get mint keysets","text":"
A wallet can ask the mint for a list of all keysets via the GET /v1/keysets endpoint.
Here, id is the keyset ID, unit is the unit string (e.g. \"sat\") of the keyset, active indicates whether new ecash can be minted with this keyset, and input_fee_ppk is the fee (per thousand units) to spend one input spent from this keyset. If input_fee_ppk is not given, we assume it to be 0.
Wallets can request the list of keyset IDs from the mint upon startup and load only tokens from its database that have a keyset ID supported by the mint it interacts with. This also helps wallets to determine whether the mint has added a new current keyset or whether it has changed the active flag of an existing one.
A useful flow is:
If we don't have any keys from this mint yet, get all keys: GET /v1/keys and store them
Get all keysets with GET /v1/keysets
For all new keyset returned here which we don't have yet, get it using GET /v1/keys/{keyset_id} and store it
If any of the keysets has changed its active flag, update it in the db and use the keyset accordingly
The swap operation is the most important component of the Cashu system. A swap operation consists of multiple inputs (Proofs) and outputs (BlindedMessages). Mints verify and invalidate the inputs and issue new promises (BlindSignatures). These are then used by the wallet to generate new Proofs (see NUT-00).
The swap operation can serve multiple use cases. The first use case is that Alice can use it to split her tokens to a target amount she needs to send to Carol, if she does not have the necessary amounts to compose the target amount in her wallet already. The second one is that Carols's wallet can use it to receive tokens from Alice by sending them as inputs to the mint and receive new outputs in return.
"},{"location":"03/#swap-to-send","title":"Swap to send","text":"
To make this more clear, we present an example of a typical case of sending tokens from Alice to Carol.
Alice has 64 sat in her wallet, composed of three Proofs, one worth 32 sat and another two worth 16 sat. She wants to send Carol 40 sat but does not have the necessary Proofs to compose the target amount of 40 sat. For that, Alice requests a swap from the mint and uses Proofs worth [16, 16, 32] as inputs and asks for new outputs worth [8, 32, 8, 16] totalling 64 sat. Notice that the first two tokens can now be combined to 40 sat. The Proofs that Alice sent Bob as inputs of the swap operation are now invalidated.
Note: In order to preserve privacy around the amount that a client might want to send to another user and keep the rest as change, the client SHOULD ensure that the list requested outputs is ordered by amount in ascending order. As an example of what to avoid, a request for outputs expressed like so: [16, 8, 2, 64, 8] might imply the client is preparing a payment for 26 sat; the client should instead order the list like so: [2, 8, 8, 16, 64] to mitigate this privacy leak to the mint.
"},{"location":"03/#swap-to-receive","title":"Swap to receive","text":"
Another useful case for the swap operation follows up the example above where Alice has swapped her Proofs ready to be sent to Carol. Carol can receive these Proofs using the same operation by using them as inputs to invalidate them and request new outputs from Bob. Only if Carol has redeemed new outputs, Alice can't double-spend the Proofs anymore and the transaction is settled. To continue our example, Carol requests a swap with input Proofs worth [32, 8] to receive new outputs (of an arbitrary distribution) with the same total amount.
If successful, Bob will respond with a PostSwapResponse
{\n \"signatures\": <Array[BlindSignature]>\n}\n
"},{"location":"04/","title":"NUT-04: Mint tokens","text":"
mandatory
Minting tokens is a two-step process: requesting a mint quote and minting new tokens. Here, we describe both steps.
In the first request the wallet asks the mint for a quote for a specific amount and unit to mint, and the payment method to pay. The mint responds with a quote that includes a quote id and a payment request. The user pays the request and, if successful, requests minting of new tokens with the mint in a second request. The wallet includes the quote id and new outputs in the second request.
We limit this document to mint quotes of unit=\"sat\" and method=\"bolt11\" which requests a bolt11 Lightning invoice (typically generated by the mint to add Bitcoin to its reserves) to mint ecash denominated in Satoshis.
Where quote is the quote ID and request is the payment request to fulfill. expiry is the Unix timestamp until which the mint quote is valid.
state is an enum string field with possible values \"UNPAID\", \"PAID\", \"ISSUED\":
\"UNPAID\" means that the quote's request has not been paid yet.
\"PAID\" means that the request has been paid.
\"ISSUED\" means that the quote has already been issued.
Note: quote is a unique and random id generated by the mint to internally look up the payment state. quote MUST remain a secret between user and mint and MUST NOT be derivable from the payment request. A third party who knows the quote ID can front-run and steal the tokens that this operation mints.
The wallet MUST store the amount in the request and the quote id in the response in its database so it can later request the tokens after paying the request. After payment, the wallet continues with the next section.
"},{"location":"04/#check-mint-quote-state","title":"Check mint quote state","text":"
To check whether a mint quote has been paid, Alice makes a GET /v1/mint/quote/bolt11/{quote_id}.
GET https://mint.host:3338/v1/mint/quote/bolt11/{quote_id}\n
Like before, the mint Bob responds with a PostMintQuoteBolt11Response.
Example request of Alice with curl:
curl -X GET http://localhost:3338/v1/mint/quote/bolt11/DSGLX9kevM...\n
After requesting a mint quote and paying the request, the wallet proceeds with minting new tokens by calling the POST /v1/mint/{method} endpoint where method is the payment method requested (here bolt11).
POST https://mint.host:3338/v1/mint/bolt11\n
The wallet Alice includes the following PostMintBolt11Request data in its request
with the quote being the quote ID from the previous step and outputs being BlindedMessages (see NUT-00) that the wallet requests signatures on whose sum is amount as requested in the quote.
The mint Bob then responds with a PostMintBolt11Response:
{\n \"signatures\": <Array[BlindSignature]>\n}\n
where signatures is an array of blind signatures on the outputs.
Upon receiving the BlindSignatures from the mint Bob, the wallet of Alice unblinds them to generate Proofs (using the blinding factor r and the mint's public key K, see BDHKE NUT-00). The wallet then stores these Proofs in its database:
The settings for this nut indicate the supported method-unit pairs for minting and whether minting is disabled or not. They are part of the info response of the mint (NUT-06) which in this case reads
Melting tokens is the opposite of minting tokens (see NUT-04). Like minting tokens, melting is a two-step process: requesting a melt quote and melting tokens. Here, we describe both steps.
In the first request the wallet asks the mint for a quote for a request it wants paid by the mint and the unit the wallet would like to spend as inputs. The mint responds with a quote that includes a quote id and an amount the mint demands in the requested unit. For the method bolt11, the mint includes a fee_reserve field indicating the reserve fee for a Lightning payment.
In the second request, the wallet includes the quote id and provides inputs that sum up to amount+fee_reserve in the first response. For the method bolt11, the wallet can also include outputs in order for the mint to return overpaid Lightning fees (see NUT-08). The mint responds with a payment state. If the state is \"PAID\" the response includes a payment_preimage as a proof of payment. If the request included outputs, the mint may respond with change for the overpaid fees (see NUT-08).
We limit this document to mint quotes of unit=\"sat\" and method=\"bolt11\" which requests a bolt11 Lightning payment (typically paid by the mint from its Bitcoin reserves) using ecash denominated in Satoshis.
Where quote is the quote ID, amount the amount that needs to be provided, and fee_reserve the additional fee reserve that is required. The mint expects Alice to include Proofs of at least total_amount = amount + fee_reserve. expiry is the Unix timestamp until which the melt quote is valid. payment_preimage is the bolt11 payment preimage in case of a successful payment.
state is an enum string field with possible values \"UNPAID\", \"PENDING\", \"PAID\":
\"UNPAID\" means that the request has not been paid yet.
\"PENDING\" means that the request is currently being paid.
\"PAID\" means that the request has been paid successfully.
Now that Alice knows what the total amount is (amount + fee_reserve) in her requested unit, she can proceed to melting tokens for which a payment will be executed by the mint. She calls the POST /v1/melt/{method} endpoint where method is the payment method requested (here bolt11).
POST https://mint.host:3338/v1/melt/bolt11\n
\u26a0\ufe0f Attention: This call will block until the Lightning payment either succeeds or fails. This can take quite a long time in case the Lightning payment is slow. Make sure to use no (or a very long) timeout when making this call!
The wallet of Alice includes the following PostMeltBolt11Request data in its request
Here, quote is the melt quote ID to be paid and inputs are the proofs with a total amount of at least amount + fee_reserve (see previous melt quote response).
Like before, the mint Bob then responds with a PostMeltQuoteBolt11Response. If the payment was successful, the state field is set to \"PAID\" and the response includes the payment_preimage field containing the payment secret of the bolt11 payment.
If state==\"PAID\", Alice's wallet can delete the inputs from her database (or move them to a history). If state==\"UNPAID\", Alice can repeat the same request again until the payment is successful.
The mint's settings for this nut indicate the supported method-unit pairs for melting. They are part of the info response of the mint (NUT-06) which in this case reads
(optional) name is the name of the mint and should be recognizable.
(optional) pubkey is the hex pubkey of the mint.
(optional) version is the implementation name and the version of the software running on this mint separated with a slash \"/\".
(optional) description is a short description of the mint that can be shown in the wallet next to the mint's name.
(optional) description_long is a long description that can be shown in an additional field.
(optional) contact is an array of contact objects to reach the mint operator. A contact object consists of two fields. The method field denotes the contact method (like \"email\"), the info field denotes the identifier (like \"contact@me.com\").
(optional) motd is the message of the day that the wallet must display to the user. It should only be used to display important announcements to users, such as scheduled maintenances.
(optional) icon_url is the URL pointing to an image to be used as an icon for the mint. Recommended to be squared in shape.
(optional) time is the current time set on the server. The value is passed as a Unix timestamp integer.
(optional) nuts indicates each NUT specification that the mint supports and its settings. The settings are defined in each NUT separately.
With curl:
curl -X GET https://mint.host:3338/v1/info\n
"},{"location":"07/","title":"NUT-07: Token state check","text":"
optional
used in: NUT-17
With the token state check, wallets can ask the mint whether a specific proof is already spent and whether it is in-flight in a transaction. Wallets can also request the witness data that was used to spend a proof.
A proof is PENDING if it is being processed in a transaction (in an ongoing payment). A PENDING proof cannot be used in another transaction until it is live again.
A proof is SPENT if it has been redeemed and its secret is in the list of spent secrets of the mint.
Note: Before deleting spent proofs from their database, wallets can check if the proof is SPENT to make sure that they don't accidentally delete an unspent proof. Beware that this behavior can make it easier for the mint to correlate the sender to the receiver.
Important: Mints MUST remember which proofs are currently PENDING to avoid reuse of the same token in multiple concurrent transactions. This can be achieved with for example mutex lock whose key is the Proof's Y.
When Alice prepares a token to be sent to Carol, she can mark these tokens in her database as pending. She can then, periodically or upon user input, check with the mint if the token is UNSPENT or whether it has been redeemed by Carol already, i.e., is SPENT. If the proof is not spendable anymore (and, thus, has been redeemed by Carol), she can safely delete the proof from her database.
If Alice's melt operation takes a long time to complete (for example if she requests a very slow Lightning payment) and she closes her wallet in the meantime, the next time she comes online, she can check all proofs marked as pending in her database to determine whether the payment is still in flight (mint returns PENDING), it has succeeded (mint returns SPENT), or it has failed (mint returns UNSPENT).
With the data being of the form PostCheckStateRequest:
{\n \"Ys\": <Array[hex_str]>,\n}\n
Where the elements of the array in Ys are the hexadecimal representation of the compressed point Y = hash_to_curve(secret) of the Proof to check (see NUT-00).
Where Y belongs to the provided Proof to check in the request, state indicates its state, and witness is the witness data that was potentially provided in a previous spend operation (can be empty).
This document describes how the overpaid Lightning fees are handled and extends NUT-05 which describes melting tokens (i.e. paying a Lightning invoice). In short, a wallet includes blank outputs when paying a Lightning invoice which can be assigned a value by the mint if the user has overpaid Lightning fees. This can be the case due to the unpredictability of Lightning network fees. To solve this issue, we introduce so-called blank outputs which are blinded messages with an undetermined value.
Before requesting a Lightning payment as described in NUT-05, Alice produces a number of BlindedMessage which are similar to ordinary blinded messages but their value is yet to be determined by the mint Bob and are thus called blank outputs. The number of necessary blank outputs is max(ceil(log2(fee_reserve)), 1) which ensures that there is at least one output if there is any fee. If the fee_reserve is 0, then the number of blank outputs is 0 as well. The blank outputs will contain the overpaid fees that will be returned by the mint to the wallet.
This code calculates the number of necessary blank outputs in Python:
The wallet wants to pay an invoice with amount := 100 000 sat and determines by asking the mint that fee_reserve is 1000 sats. The wallet then provides 101 000 sat worth of proofs and 10 blank outputs to make the payment (since ceil(log2(1000))=ceil(9.96..)=10). The mint pays the invoice and determines that the actual fee was 100 sat, i.e, the overpaid fee to return is fee_return = 900 sat. The mint splits the amount 900 into summands of 2^n which is 4, 128, 256, 512. The mint inserts these amounts into the blank outputs it received form the wallet and generates 4 new promises. The mint then returns these BlindSignatures to the wallet together with the successful payment status.
The wallet asks the mint for the fee_reserve for paying a specific bolt11 invoice of value amount by calling POST /v1/melt/quote as described in NUT-05. The wallet then provides a PostMeltBolt11Request to POST /v1/melt/bolt11 that has (1) proofs of the value amount+fee_reserve, (2) the bolt11 invoice to be paid, and finally, as a new entry, (3) a field outputs that has n_blank_outputs blinded messages that are generated before the payment attempt to receive potential overpaid fees back to her.
Here we describe how the mint generates BlindSignatures for the overpaid fees. The mint Bob returns in PostMeltQuoteBolt11Response the field change ONLY IF Alice has previously provided outputs for the change AND if the Lightning actual_fees were smaller than the fee_reserve.
If the overpaid_fees = fee_reserve - actual_fees is positive, Bob decomposes it to values of 2^n (as in NUT-00) and then imprints them into the blank_outputs provided by Alice.
Bob then signs these blank outputs (now with the imprinted amounts) and thus generates BlindSignatures. Bob then returns a payment status to the wallet, and, in addition, all blind signatures it generated for the overpaid fees.
Importantly, while Bob does not necessarily return the same number of blind signatures as it received blank outputs from Alice (since some of them may be of value 0), Bob MUST return the all blank signatures with a value greater than 0 in the same order as the blank outputs were received and should omit all blind signatures with value 0. For example, if Bob receives 10 blank outputs but the overpaid fees only occupy 4 blind signatures, Bob will only return these 4 blind signatures with the appropriate imprinted amounts and omit the remaining 6 blind signatures with value 0. Due to the well-defined order of the returned blind signatures, Alice can map the blind signatures returned from Bob to the blank outputs it provided so that she can further apply the correct unblinding operations on them.
Everything here is the same as in NUT-05 except for outputs. The amount field in the BlindedMessages here are ignored by Bob so they can be set to any arbitrary value by Alice (they should be set to a value, like 1 so potential JSON validations do not error).
If the mint has made a successful payment, it will respond the following.
The field change is an array of BlindSignatures that account for the overpaid fees. Notice that the amount has been changed by the mint. Alice must take these and generate Proofs by unblinding them as described in NUT-00 and as she does in NUT-04 when minting new tokens. After generating the Proofs, Alice stores them in her database.
In this document, we describe how wallets can recover blind signatures, and with that their corresponding Proofs, by requesting from the mint to reissue the blind signatures. This can be used for a backup recovery of a lost wallet (see NUT-13) or for recovering the response of an interrupted swap request (see NUT-03).
Mints must store the BlindedMessage and the corresponding BlindSignature in their database every time they issue a BlindSignature. Wallets provide the BlindedMessage for which they request the BlindSignature. Mints only respond with a BlindSignature, if they have previously signed the BlindedMessage. Each returned BlindSignature also contains the amount and the keyset id (see NUT-00) which is all the necessary information for a wallet to recover a Proof.
Request of Alice:
POST https://mint.host:3338/v1/restore\n
With the data being of the form PostRestoreRequest:
{\n \"outputs\": <Array[BlindedMessages]>\n}\n
Response of Bob:
The mint Bob then responds with a PostRestoreResponse.
An ordinary ecash token is a set of Proofs each with a random string secret. To spend such a token in a swap or a melt operation, wallets include proofs in their request each with a unique secret. To autorize a transaction, the mint requires that the secret has not been seen before. This is the most fundamental spending condition in Cashu, which ensures that a token can't be double-spent.
In this NUT, we define a well-known format of secret that can be used to express more complex spending conditions. These conditions need to be met before the mint authorizes a transaction. Note that the specific type of spending condition is not part of this document but will be explained in other documents. Here, we describe the structure of secret which is expressed as a JSON Secret with a specific format.
Spending conditions are enforced by the mint which means that, upon encountering a Proof where Proof.secret can be parsed into the well-known format, the mint can require additional conditions to be met.
Caution: If the mint does not support spending conditions or a specific kind of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
An ecash transaction, i.e., a swap or a melt operation, with a spending condition consists of the following components:
Inputs referring to the Proofs being spent
Secret containing the rules for unlocking a Proof
Additional witness data satisfying the unlock conditions such as signatures
Outputs referring to the BlindMessages with new unlock conditions to which the Proofs are spent to
Spending conditions are defined for each individual Proof and not on a transaction level that can consist of multiple Proofs. Similarly, spending conditions must be satisfied by providing signatures or additional witness data for each Proof separately. For a transaction to be valid, all Proofs in that transaction must be unlocked successfully.
New Secrets of the outputs to which the inputs are spent to are provided as BlindMessages which means that they are blind-signed and not visible to the mint until they are actually spent.
Spending conditions are expressed in a well-known secret format that is revealed to the mint when spending (unlocking) a token, not when the token is minted (locked). The mint parses each Proof's secret. If it can deserialize it into the following format it executes additional spending conditions that are further specified in additional NUTs.
The well-known Secret stored in Proof.secret is a JSON of the format:
"},{"location":"11/","title":"NUT-11: Pay to Public Key (P2PK)","text":"
optional
depends on: NUT-10
This NUT describes Pay-to-Public-Key (P2PK) which is one kind of spending condition based on NUT-10's well-known Secret. Using P2PK, we can lock ecash tokens to a receiver's ECC public key and require a Schnorr signature with the corresponding private key to unlock the ecash. The spending condition is enforced by the mint.
Caution: If the mint does not support this type of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
If for a Proof, Proof.secret is a Secret of kind P2PK, the proof must be unlocked by providing a witness Proof.witness and one or more valid signatures in the array Proof.witness.signatures.
In the basic case, when spending a locked token, the mint requires one valid Schnorr signature in Proof.witness.signatures on Proof.secret by the public key in Proof.Secret.data.
To give a concrete example of the basic case, to mint a locked token we first create a P2PK Secret that reads:
Here, Secret.data is the public key of the recipient of the locked ecash. We serialize this Secret to a string in Proof.secret and get a blind signature by the mint that is stored in Proof.C (see NUT-03]).
The recipient who owns the private key of the public key Secret.data can spend this proof by providing a signature on the serialized Proof.secret string that is then added to Proof.witness.signatures:
To spend a token locked with P2PK, the spender needs to include signatures in the spent proofs. We use libsecp256k1's serialized 64 byte Schnorr signatures on the SHA256 hash of the message to sign. The message to sign is the field Proof.secret in the inputs. If indicated by Secret.tags.sigflag in the inputs, outputs might also require signatures on the message BlindedMessage.B_.
An ecash spending operation like swap and melt can have multiple inputs and outputs. If we have more than one input or output, we provide signatures in each Proof and BlindedMessage individually. The inputs are the Proofs provided in the inputs field and the outputs are the BlindedMessages in the outputs field in the request body (see PostMeltRequest in NUT-05 and PostSwapRequest in NUT-03).
"},{"location":"11/#tags","title":"Tags","text":"
More complex spending conditions can be defined in the tags in Proof.tags. All tags are optional. Tags are arrays with two or more strings being [\"key\", \"value1\", \"value2\", ...].
Supported tags are:
sigflag: <str> determines whether outputs have to be signed as well
n_sigs: <int> specifies the minimum number of valid signatures expected
pubkeys: <hex_str> are additional public keys that can provide signatures (allows multiple entries)
locktime: <int> is the Unix timestamp of when the lock expires
refund: <hex_str> are optional refund public keys that can exclusively spend after locktime (allows multiple entries)
Note: The tag serialization type is [<str>, <str>, ...] but some tag values are int. Wallets and mints must cast types appropriately for de/serialization.
Signatures must be provided in the field Proof.witness.signatures for each Proof which is an input. If the signature flag SIG_ALL is enforced, signatures must also be provided for every output in its field BlindedMessage.witness.signatures.
If the tag n_sigs is a positive integer, the mint will also consider signatures from public keys specified in the pubkeys tag additional to the public key in Secret.data. If the number of valid signatures is greater or equal to the number specified in n_sigs, the transaction is valid.
Expressed as an \"n-of-m\" scheme, n = n_sigs is the number of required signatures and m = 1 (\"data\" field) + len(pubkeys tag) is the number of public keys that could sign.
If the tag locktime is the unix time and the mint's local clock is greater than locktime, the Proof becomes spendable by anyone, except if the following condition is also true. Note: A Proof is considered spendable by anyone if it only requires a secret and a valid signature C to be spent (which is the default case).
"},{"location":"11/#refund-public-keys","title":"Refund public keys","text":"
If the locktime is in the past and a tag refund is present, the Proof is spendable only if a valid signature by one of the the refund pubkeys is provided in Proof.witness.signatures and, depending on the signature flag, in BlindedMessage.witness.signatures.
This is an example secret that locks a Proof with a Pay-to-Pubkey (P2PK) condition that requires 2-of-3 signatures from the public keys in the data field and the pubkeys tag. If the timelock has passed, the Proof becomes spendable with a single signature from the public key in the refund tag. The signature flag sigflag indicates that signatures are necessary on the inputs and the outputs of a transaction.
In this document, we present an extension of Cashu's crypto system to allow a user Alice to verify the mint Bob's signature using only Bob's public keys. We explain how another user Carol who receives ecash from Alice can execute the DLEQ proof as well. This is achieved using a Discrete Log Equality (DLEQ) proof. Previously, Bob's signature could only be checked by himself using his own private keys (NUT-00).
The purpose of this DLEQ is to prove that the mint has used the same private key a for creating its public key A (NUT-01) and for signing the BlindedMessage B'. Bob returns the DLEQ proof additional to the blind signature C' for a mint or swap operation.
The complete DLEQ proof reads
# DLEQ Proof\n\n(These steps occur when Bob returns C')\n\nBob:\nr = random nonce\nR1 = r*G\nR2 = r*B'\ne = hash(R1,R2,A,C')\ns = r + e*a\nreturn e, s\n\nAlice:\nR1 = s*G - e*A\nR2 = s*B' - e*C'\ne == hash(R1,R2,A,C')\n\nIf true, a in A = a*G must be equal to a in C' = a*B'\n
The hash(x) function generates a deterministic Sha256 hash for a given input list of PublicKey. The uncompressed hexadecimal representations of each PublicKey is concatenated before taking the Sha256 hash.
def hash_e(*publickeys: PublicKey) -> bytes:\n e_ = \"\"\n for p in publickeys:\n _p = p.serialize(compressed=False).hex()\n e_ += str(_p)\n e = hashlib.sha256(e_.encode(\"utf-8\")).digest()\n return e\n
"},{"location":"12/#mint-to-user-dleq-in-blindsignature","title":"Mint to user: DLEQ in BlindSignature","text":"
The mint produces these DLEQ proofs when returning BlindSignature's in the responses for minting (NUT-04) and swapping (NUT-03) tokens. The BlindSignature object is extended in the following way to include the DLEQ proof:
"},{"location":"12/#user-to-user-dleq-in-proof","title":"User to user: DLEQ in Proof","text":"
In order for Alice to communicate the DLEQ to another user Carol, we extend the Proof (see NUT-00) object and include the DLEQ proof. As explained below, we also need to include the blinding factor r for the proof to be convincing to another user Carol.
e and s are the challenge and response of the DLEQ proof returned by Bob, r is the blinding factor of Alice that was used to generate the Proof. Alice serializes these proofs like any other in a token (see NUT-00) to send it to another user Carol.
When minting or swapping tokens, Alice receives DLEQ proofs in the BlindSignature response from the mint Bob. Alice checks the validity of the DLEQ proofs for each ecash token she receives via the equations:
R1 = s*G - e*A\nR2 = s*B' - e*C'\ne == hash(R1,R2,A,C') # must be True\n
Here, the variables are
A \u2013\u00a0the public key Bob used to sign this Proof
(e, s) \u2013\u00a0the DLEQ proof returned by Bob
B' \u2013 Alice's BlindedMessage
C' \u2013 Bob's BlindSignature on B'
In order to execute the proof, Alice needs e, s that are returned in the BlindSignature by Bob. Alice further needs B' (the BlindedMessageAlice created and Bob signed) and C' (the blind signature in the BlindSignature response) from Bob, and A (the public key of Bob with which he signed the BlindedMessage). All these values are available to Alice during or after calling the mint and swap operations.
If a DLEQ proof is included in the mint's BlindSignature response, wallets MUST verify the DLEQ proof.
Carol is a user that receives Proofs in a token from another user Alice. When Alice sends Proofs with DLEQ proofs to Carol or when Alice posts the Proofs publicly, Carol can validate the DLEQ proof herself and verify Bob's signature without having to talk to Bob. Alice includes the following information in the Proof (see above):
(x, C) \u2013\u00a0the ecash Proof
(e, s) \u2013\u00a0the DLEQ proof revealed by Alice
r \u2013 Alice's blinding factor
Here, x is the Proof's secret, and C is the mint's signature on it. To execute the DLEQ proof like Alice did above, Carol needs (B', C') which she can compute herself using the blinding factor r that she receives from Alice.
To verify the DLEQ proof of a received token, Carol needs to reconstruct B' and C' using the blinding factor r that Alice has included in the Proof she sent to Carol. Since Carol now has all the necessary information, she can execute the same equations to verify the DLEQ proof as Alice did:
Y = hash_to_curve(x)\nC' = C + r*A\nB' = Y + r*G\n\nR1 = ... (same as Alice)\n
If a DLEQ proof is included in a received token, wallets MUST verify the proof.
In this document, we describe the process that allows wallets to recover their ecash balance with the help of the mint using a familiar 12 word seed phrase (mnemonic). This allows us to restore the wallet's previous state in case of a device loss or other loss of access to the wallet. The basic idea is that wallets that generate the ecash deterministically can regenerate the same tokens during a recovery process. For this, they ask the mint to reissue previously generated signatures using NUT-09.
An ecash token, or a Proof, consists of a secret generated by the wallet, and a signature C generated by the wallet and the mint in collaboration. Here, we describe how wallets can deterministically generate the secrets and blinding factors r necessary to generate the signatures C.
The wallet generates a private_key derived from a 12-word BIP39 mnemonic seed phrase that the user stores in a secure place. The wallet uses the private_key, to derive deterministic values for the secret and the blinding factors r for every new ecash token that it generates.
In order to do this, the wallet keeps track of a counter_k for each keyset_k it uses. The index k indicates that the wallet needs to keep track of a separate counter for each keyset k it uses. Typically, the wallet will need to keep track of multiple keysets for every mint it interacts with. counter_k is used to generate a BIP32 derivation path which can then be used to derive secret and r.
The following BIP32 derivation path is used. The derivation path depends on the keyset ID of keyset_k, and the counter_k of that keyset.
Purpose' = 129372' (UTF-8 for \ud83e\udd5c)
Coin type' = Always 0'
Keyset id' = Keyset ID represented as an integer (keyset_k_int)
Coin counter' = counter' (this value is incremented)
Here, {keyset_k_int} and {counter_k} are the only variables that can change. keyset_id_k_int is an integer representation (see below) of the keyset ID the token is generated with. This means that the derivation path is unique for each keyset. Note that the coin type is always 0', independent of the unit of the ecash.
The wallet starts with counter_k := 0 upon encountering a new keyset and increments it by 1 every time it has successfully minted new ecash with this keyset. The wallet stores the latest counter_k in its database for all keysets it uses. Note that we have a counter (and therefore a derivation path) for each keyset k. We omit the keyset index k in the following of this document.
The integer representation keyset_id_int of a keyset is calculated from its hexadecimal ID which has a length of 8 bytes or 16 hex characters. First, we convert the hex string to a big-endian sequence of bytes. This value is then modulo reduced by 2^31 - 1 to arrive at an integer that is a unique identifier keyset_id_int.
"},{"location":"13/#restore-from-seed-phrase","title":"Restore from seed phrase","text":"
Using deterministic secret derivation, a user's wallet can regenerate the same BlindedMessages in case of loss of a previous wallet state. To also restore the corresponding BlindSignatures to fully recover the ecash, the wallet can either requests the mint to re-issue past BlindSignatures on the regenerated BlindedMessages (see NUT-09) or by downloading the entire database of the mint (TBD).
The wallet takes the following steps during recovery:
To generate the BlindedMessages, the wallet starts with a counter := 0 and , for each increment of the counter, generates a secret using the BIP32 private key derived from secret_derivation_path and converts it to a hex string.
The wallet similarly generates a blinding factor r from the r_derivation_path:
r = self.bip32.get_privkey_from_path(r_derivation_path)\n
Note: For examples, see the test vectors.
Using the secret string and the private key r, the wallet generates a BlindedMessage. The wallet then increases the counter by 1 and repeats the same process for a given batch size. It is recommended to use a batch size of 100.
The user's wallet can now request the corresponding BlindSignatures for theses BlindedMessages from the mint using the NUT-09 restore endpoint or by downloading the entire mint's database.
Using the restored BlindSignatures and the r generated in the previous step, the wallet can unblind the signature to C. The triple (secret, C, amount) is a restored Proof.
If the wallet used the restore endpoint NUT-09 for regenerating the Proofs, it additionally needs to check for the Proofs spent state using NUT-07. The wallet deletes all Proofs which are already spent and keeps the unspent ones in its database.
Generally, the user won't remember the last state of counter when starting the recovery process. Therefore, wallets need to know how far they need to increment the counter during the restore process to be confident to have reached the most recent state.
In short, following approach is recommended:
Restore Proofs in batches of 100 and increment counter
Repeat until three consecutive batches are returned empty
Reset counter to the value at the last successful restore + 1
Wallets restore Proofs in batches of 100. The wallet starts with a counter=0 and increments it for every Proof it generated during one batch. When the wallet begins restoring the first Proofs, it is likely that the first few batches will only contain spent Proofs. Eventually, the wallet will reach a counter that will result in unspent Proofs which it stores in its database. The wallet then continues to restore until three successive batches are returned empty by the mint. This is to be confident that the restore process did not miss any Proofs that might have been generated with larger gaps in the counter by the previous wallet that we are restoring.
This NUT describes the use of Hashed Timelock Contracts (HTLCs) which defines a spending condition based on NUT-10's well-known Secret format. Using HTLCs, ecash tokens can be locked to the hash of a preimage or a timelock. This enables use cases such as atomic swaps of ecash between users, and atomic coupling of an ecash spending condition to a Lightning HTLC.
HTLC spending conditions can be thought of as an extension of P2PK locks NUT-11 but with a hash lock in Secret.data and a new Proof.witness.preimage witness in the locked inputs to be spent. The preimage that was used to spend a locked token can be retrieved using NUT-07. Caution: applications that rely on being able to retrieve the witness independent from the spender must check via the mint's info endpoint that NUT-07 is supported.
Caution: If the mint does not support this type of spending condition, proofs may be treated as a regular anyone-can-spend tokens. Applications need to make sure to check whether the mint supports a specific kind of spending condition by checking the mint's info endpoint.
"},{"location":"14/#htlc","title":"HTLC","text":"
NUT-10 Secret kind: HTLC
If for a Proof, Proof.secret is a Secret of kind HTLC, the hash of the lock is in Proof.secret.data. The preimage for unlocking the HTLC is in the witness Proof.witness.preimage. All additional tags from P2PK locks are used here as well, allowing us to add a locktime, signature flag, and use multisig (see NUT-11).
Here is a concrete example of a Secret of kind HTLC:
A Proof with this Secret can be spent in two ways. To spend the hash lock, the witness in Proof.witness includes the preimage to Secret.data and a signature from the key in Secret.tag.pubkeys. Additionally, if the current system time is later than Secret.tag.locktime, the Proof can be spent if Proof.witness includes a signature from the key in Secret.tags.refund.
The hash lock in Secret.data and the preimage in Proof.witness.preimage is treated as 32 byte data encoded as 64 character hex strings.
See NUT-11 for a description of the signature scheme, the additional use of signature flags, and how to require signature from multiple public keys (multisig).
In this document, we describe how wallets can instruct multiple mints to each pay a partial amount of a bolt11 Lightning invoice. The full payment is composed of partial payments (MPP) from multiple multi-path payments from different Lightning nodes. This way, wallets can pay a larger Lightning invoice combined from multiple smaller balances on different mints. Due to the atomic nature of MPP, either all payments will be successful or all of them will fail.
The Lightning backend of the mint must support paying a partial amount of an Invoice and multi-path payments (MPP, see BOLT 4). For example, the mint's Lightning node must be able to pay 50 sats of a 100 sat bolt11 invoice. The receiving Lightning node must support receiving multi-path payments as well.
Alice's wallet coordinates multiple MPPs on different mints that support the feature (see below for the indicated setting). For a given Lightning invoice of amount_total, Alice splits the total amount into several partial amounts amount_total = amount_1 + amount_2 + ... that each must be covered by her individual balances on the mints she wants to use for the payment. She constructs multiple PostMeltQuoteBolt11Request's that each include the corresponding partial amount in the payment option (see below) that she sends to all mints she wants to use for the payment. The mints then respond with a normal PostMeltQuoteBolt11Response (see NUT-05). Alice proceeds to pay the melt requests at each mint simultaneously. When all mints have sent out the partial Lightning payment, she receives a successful response from all mints individually.
To request a melt quote with a partial amount, the wallet of Alice makes a POST /v1/melt/quote/bolt11 similar to NUT-05.
POST https://mint.host:3338/v1/melt/quote/bolt11\n
The wallet Alice includes the following PostMeltQuoteBolt11Request data in its request which includes an additional (and optional) options object compared to the standard request in NUT-05:
Here, request is the bolt11 Lightning invoice to be paid, unit is the unit the wallet would like to pay with, and amount is the amount for the requested payment. The wallet then pays the returned melt quote the same way as in NUT-05.
The settings returned in the info endpoint (NUT-06) indicate that a mint supports this NUT. The mint MUST indicate each method and unit that supports mpp. It can indicate this in an array of objects for multiple method and unit pairs and the boolean flag mpp set to true.
QR codes are a great way to send and receive Cashu tokens. Before a token can be shared as a QR code, it needs to be serialized (see NUT-00).
"},{"location":"16/#static-qr-codes","title":"Static QR codes","text":"
If the serialized token is not too large (i.e. includes less than or equal to 2 proofs) it can usually be shared as a static QR code. This might not be the case if the secret includes long scripts or the token has a long memo or mint URL.
"},{"location":"16/#animated-qr-codes","title":"Animated QR codes","text":"
If a token is too large to be displayed as a single QR code, we use animated QR codes are based on the UR protocol. The sender produces an animated QR code from a serialized Cashu token. The receiver scans the animated QR code until the UR decoder is able to decode the token.
The websocket enables real-time subscriptions that wallets can use to receive notifications for a state change of a MintQuoteResponse (NUT-04), MeltQuoteResponse (NUT-05), CheckStateResponse (NUT-07).
A summary of the subscription flow is the following:
A wallet connects to the websocket endpoint and sends a WsRequest with the subscribe command.
The mint responds with a WsResponse containing an ok or an error.
If the subscription was accepted, the mint sends a WsNotification of the current state of the subscribed objects and whenever there is an update for the wallet's subscriptions.
To close a subscription, the wallet sends WsRequest with the unsubscribe command.
Note that id and subId are unrelated. The subId is the ID for each subscription, whereas id is part of the JSON-RPC spec and is an integer counter that must be incremented for every request sent over the websocket.
Important: If the subscription is accepted by the mint, the mint MUST first respond with the current state of the subscribed object and continue sending any further updates to it.
For example, if the wallet subscribes to a Proof.Y of a Proof that has not been spent yet, the mint will first respond with a ProofState with state == \"UNSPENT\". If the wallet then spends this Proof, the mint would send a ProofState with state == \"PENDING\" and then one with state == \"SPENT\". In total, the mint would send three notifications to the wallet.
The wallet should always unsubscribe any subscriptions that is isn't interested in anymore. The parameters for the \"unsubscribe\" command is only the subscription ID:
subId is the subscription ID (previously generated by the wallet) this notification corresponds to. NotificationPayload carries the subscription data which is a MintQuoteResponse (NUT-04), a MeltQuoteResponse (NUT-05), or a CheckStateResponse (NUT-07), depending on what the corresponding SubscriptionKind was.
To subscribe to the ProofState of a Proof, the wallet establishes a websocket connection to https://mint.com/v1/ws and sends a WsRequest with a filters chosen to be the a Proof.Y value of the Proof (see NUT-00). Note that filters is an array meaning multiple subscriptions of the same kind can be made in the same request.
While leaving the websocket connection open, the wallet then spends the ecash. The mint sends WsNotification updating the wallet about state changes of the ProofState accordingly:
Here, commands is an array of the commands that the mint supports. A mint that supports all commands would return [\"bolt11_mint_quote\", \"bolt11_melt_quote\", \"proof_state\"]. Supported commands are given for each method-unit pair.
This NUT introduces a standardised format for payment requests, that supply a sending wallet with all information necessary to complete the transaction. This enables many use-cases where a transaction is better initiated by the receiver (e.g. point of sale).
"},{"location":"18/#flow","title":"Flow","text":"
Receiver creates a payment request, encodes it and displays it to the sender
Sender scans the request and constructs a matching token
Sender sends the token according to the transport specified in the payment request
Receiver receives the token and finalises the transaction
Tags are an optional array of [tag, value, value, ...] tuples that can be used to specify additional features about the transport. A single tag can have multiple values.
The n tag specifies the NIPs the receiver supports. At least one tag value MUST be specified. For NIP-17 direct messages, the sender sends a PaymentRequestPayload as the message content.
Here, id is the payment id (corresponding to i in request), memo is an optional memo to be sent to the receiver with the payment, mint is the mint URL from which the ecash is from, unit is the unit of the payment, and proofs is an array of proofs (see NUT-00, can also include DLEQ proofs).
"},{"location":"error_codes/","title":"NUT Errors","text":"Code Description Relevant nuts 10002 Blinded message of output already signed NUT-03, NUT-04, NUT-05 10003 Token could not be verified NUT-03, NUT-05 11001 Token is already spent NUT-03, NUT-05 11002 Transaction is not balanced (inputs != outputs) NUT-02, NUT-03, NUT-05 11005 Unit in request is not supported NUT-04, NUT-05 11006 Amount outside of limit range NUT-04, NUT-05 12001 Keyset is not known NUT-02, NUT-04 12002 Keyset is inactive, cannot sign messages NUT-02, NUT-03, NUT-04 20001 Quote request is not paid NUT-04 20002 Tokens have already been issued for quote NUT-04 20003 Minting is disabled NUT-04 20005 Quote is pending NUT-04, NUT-05 20006 Invoice already paid NUT-05 20007 Quote is expired NUT-04, NUT-05"},{"location":"tests/","title":"Test Vectors","text":"
The files in this directory contain test vectors for NUTs that warrant them.
"},{"location":"tests/00-tests/","title":"NUT-00 Test Vectors","text":""},{"location":"tests/00-tests/#hash-to-curve-function","title":"Hash-to-curve function","text":"
The hash to curve function takes a message of any length and outputs a valid point on the secp256k1 curve. Note that unless you are using complex spend conditions (NUT-10), standardized secrets (random 32-bytes-long byte arrays) should be used in order to prevent wallet fingerprinting.
# Test 1 (hex encoded)\nMessage: 0000000000000000000000000000000000000000000000000000000000000000\nPoint: 024cce997d3b518f739663b757deaec95bcd9473c30a14ac2fd04023a739d1a725\n\n# Test 2 (hex encoded)\nMessage: 0000000000000000000000000000000000000000000000000000000000000001\nPoint: 022e7158e11c9506f1aa4248bf531298daa7febd6194f003edcd9b93ade6253acf\n\n# Test 3 (hex encoded)\n# Note that this message will take a few iterations of the loop before finding a valid point\nMessage: 0000000000000000000000000000000000000000000000000000000000000002\nPoint: 026cdbe15362df59cd1dd3c9c11de8aedac2106eca69236ecd9fbe117af897be4f\n
Both of the following v3 tokens are valid, one includes padding characters at the end and the other does not.
# Clients should be able to deserialize both\ncashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vODMzMy5zcGFjZTozMzM4IiwicHJvb2ZzIjpbeyJhbW91bnQiOjIsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6IjQwNzkxNWJjMjEyYmU2MWE3N2UzZTZkMmFlYjRjNzI3OTgwYmRhNTFjZDA2YTZhZmMyOWUyODYxNzY4YTc4MzciLCJDIjoiMDJiYzkwOTc5OTdkODFhZmIyY2M3MzQ2YjVlNDM0NWE5MzQ2YmQyYTUwNmViNzk1ODU5OGE3MmYwY2Y4NTE2M2VhIn0seyJhbW91bnQiOjgsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6ImZlMTUxMDkzMTRlNjFkNzc1NmIwZjhlZTBmMjNhNjI0YWNhYTNmNGUwNDJmNjE0MzNjNzI4YzcwNTdiOTMxYmUiLCJDIjoiMDI5ZThlNTA1MGI4OTBhN2Q2YzA5NjhkYjE2YmMxZDVkNWZhMDQwZWExZGUyODRmNmVjNjlkNjEyOTlmNjcxMDU5In1dfV0sInVuaXQiOiJzYXQiLCJtZW1vIjoiVGhhbmsgeW91IHZlcnkgbXVjaC4ifQ==\ncashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vODMzMy5zcGFjZTozMzM4IiwicHJvb2ZzIjpbeyJhbW91bnQiOjIsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6IjQwNzkxNWJjMjEyYmU2MWE3N2UzZTZkMmFlYjRjNzI3OTgwYmRhNTFjZDA2YTZhZmMyOWUyODYxNzY4YTc4MzciLCJDIjoiMDJiYzkwOTc5OTdkODFhZmIyY2M3MzQ2YjVlNDM0NWE5MzQ2YmQyYTUwNmViNzk1ODU5OGE3MmYwY2Y4NTE2M2VhIn0seyJhbW91bnQiOjgsImlkIjoiMDA5YTFmMjkzMjUzZTQxZSIsInNlY3JldCI6ImZlMTUxMDkzMTRlNjFkNzc1NmIwZjhlZTBmMjNhNjI0YWNhYTNmNGUwNDJmNjE0MzNjNzI4YzcwNTdiOTMxYmUiLCJDIjoiMDI5ZThlNTA1MGI4OTBhN2Q2YzA5NjhkYjE2YmMxZDVkNWZhMDQwZWExZGUyODRmNmVjNjlkNjEyOTlmNjcxMDU5In1dfV0sInVuaXQiOiJzYXQiLCJtZW1vIjoiVGhhbmsgeW91IHZlcnkgbXVjaC4ifQ\n
"},{"location":"tests/00-tests/#serialization-of-tokenv4","title":"Serialization of TokenV4","text":"
The following are JSON-formatted v4 tokens and their serialized counterparts. The h'' values are bytes but displayed as hex strings here.
The following are correct keysets that should be accepted by wallets implementing the NUT-01 specification. Note that the second (bigger) keyset's biggest amount is 9223372036854775808, one unit over what can fit into a 64-bit signed integer (often known as a Long). To handle this you'll need to use either an unsigned 64-bit integer or a 128-bit signed integer (sometimes known as a BigInteger).
"},{"location":"tests/12-tests/","title":"NUT-12 Test vectors","text":""},{"location":"tests/12-tests/#hash_e-function","title":"hash_e function","text":"
"},{"location":"tests/13-tests/","title":"NUT-13 Test vectors","text":""},{"location":"tests/13-tests/#keyset-id-integer-representation","title":"Keyset ID integer representation","text":"
The integer representation of a keyset with an ID 009a1f293253e41e and its corresponding derivation path for a counter of value {counter} are