nutshell/docs/specs/cashu_client_spec.md

Notation

Sending user: Alice Receivung user: Carol Mint: Bob

Bob (mint)

• k private key of mint (one for each amount)
• K public key of mint
• Q promise (blinded signature)

Alice (user)

• x random string (secret message), corresponds to point Y on curve
• r private key (blinding factor)
• T blinded message
• Z proof (unblinded signature)

Blind Diffie-Hellmann key exchange (BDH)

• Mint Bob publishes K = kG
• Alice picks secret x and computes Y = hash_to_curve(x)
• Alice sends to Bob: T = Y + rG with r being a random nonce
• Bob sends back to Alice blinded key: Q = kT (these two steps are the DH key exchange)
• Alice can calculate the unblinded key as Q - rK = kY + krG - krG = kY = Z
• Alice can take the pair (x, Z) as a token and can send it to Carol.
• Carol can send (x, Z) to Bob who then checks that k*hash_to_curve(x) == Z, and if so treats it as a valid spend of a token, adding x to the list of spent secrets.

Cashu client protocol

1 - Request public keys from mint

Alice receives public keys from mint Bob via GET /keys and stores them in a key-value store like a dictionary. Keys are received as a JSON of the form {<amount_1> : <mint_pubkey_1>, <amount_2> : ...} for each <amount_i> of the amounts the mint Bob supports. [NOTE: mint_pubkey should be consistent with the notation above.]

2 - Mint tokens

Step 1: Alice requests mint

• Alice requests the minting of tokens of value amount : int via GET /mint?amount=<amount>
• Bob responds with a JSON {"pr": <payment_request>, "hash": <payment_hash>} where payment_request is the bolt11 Lightning invoice that Alice needs to pay and payment_hash is the hash of the invoice necessary for alice to request minting of tokens later. Alice stores payment_hash. [NOTE: <payment_hash> does not need to be passed by Bob, can be derived from <payment_request>]
• Alice pays bolt11 invoice payment_request using a Bitcoin Lightning wallet.

Step 2: Request tokens

• To request tokens of value amount : int, Alice decomposes amount into a sum of values of 2^n, e.g. 13 is amounts : List[int] = [1, 4, 8]. This can be easily done by representing amount as binary and using each binary digit that is 1 as part of the sum, e.g. 8 would be 1101 wich is 2^0 + 2^2 + 2^3. In this example, Alice will request N = len(amounts) = 3 tokens.
• Alice generates a random secret string x_i of 128 random bits with i \in [0,..,N-1]for each of the N requested tokens and encodes them in base64. [TODO: remove index i]
• Alice remembers x for the construction of the proof in Step 5.

Step 3: Generate blinded message

Here we see how Alice generates N blinded messages T_i. The following steps are executed for each of the N tokens that Alice requests. The index i is dropped for simplicity. [TODO: either write everything independent of i or not, don't mix]

• Alice generates a point Y on the elliptic curve from the secret x using the deterministic function Y = hash_to_curve(hash(x : string)) : Point.
• h = hash(x : string) : string can be the SHA256 hash function.
• Y = hash_to_curve(h : string) : Point verifies that Y is an element of the elliptic curve.
• Alice generates a random nonce r : int that is a private key and computes the public key from it using r*G.
• Alice generates the blinded message T = Y + r*G
• Alice remembers r for the construction of the proof in Step 5.

Step 4: Request tokens

• Alice constructs JSON MintRequest = {"blinded_messages" : ["amount" : <amount>, "B_" : <blinded_message>] } [NOTE: rename "blinded_messages", rename "B_", rename "MintRequest"]
• Alice requests tokens via POST /mint?payment_hash=<payment_hash> with body MintRequest [NOTE: rename MintRequest]
• Alice receives from Bob a list of blinded signatures List[BlindedSignature], one for each token, e.g. [{"amount" : <amount>, "C_" : <blinded_signature>}, ...] [NOTE: rename C_]
• If an error occured, Alice receives JSON {"error" : <error_reason>}}[TODO: Specify case of error]

Step 5: Construct proofs

Here, Alice construct proofs for each token using the tuple (blinded_signature, r, s). Again, all steps are repeated for each token separately but we show it here for only one token.

• Alice unblinds blinded_signature by subtracting r*<mint_pubkey> from it. Note that <mint_pubkey> must be according to the <amount> of the token. The result is the proof Z. [Note: in notation, this is Z = Q - r*K]
• Alice constructs spendable token as a tuple (<amount>, Z, s) and stores it in her database.

3 - Send tokens

Here we describe how Alice sends tokens to Carol.

3.1 – Split tokens to desired amount

Alice wants to send tokens of total value <total> to Carol but doesn't necessarily have a set of tokens that sum to <total>. Say Alice has tokens of the amount <alice_balance> which is greater than <total> in here database. Note that <alice_balance> does not need to include all of Alice's tokens but only at least tokens of a total amount of <total>. Therefore, Alice sends tokens of amount <alice_balance> to Bob asks Bob to issue two new sets of tokens of value <total> and <alice_balance>-<total> each.

• Alice performs a split on the amounts <total> and <alice_balance>-<total> separately as in 2.2 - Request tokens. [TODO: fix reference]
• Alice constructs two new sets of blinded messages like in 2.3 - Generate blind messages [TODO: fix reference], one for each of the two amounts <total> and <alice_balance>-<total>.
• Alice concatenates both sets of blinded messages into the list <blinded_messages> [TODO: list?]
• Alice constructs a JSON out of multiple tokens from her database that sum to <alice_balance> of the form {"amount" : <total>, "proofs" : [{"amount" : <amount>, "secret" : s, "C" : Z}, ...], "outputs" : ["amount" : <amount>, "B_" : <blinded_message>]}. The blinded messages in "outputs" are the list of concatenated blinded message from the previous step. [TODO: refer to this as BlindMessages or something and reuse in Section 4 and 2]

3.2 - Request new tokens for sending

• Alice constructs a JSON out of multiple tokens of the form [{"amount" : <amount>, "secret" : s, "C" : Z}, ...] and serializes is as a Base64 string TOKEN which is then sent to Carol as a payment of value sum(<amount_i>). [NOTE: rename C, rewrite sum, find consistency in writing labels, values, TOKEN, in code this is called Proof]
• Alice requests new tokens via POST /mint with the JSON as the body of the request.
• Alice receives a JSON of the form {"fst" : <signatures_to_keep>}, "snd" : <signatures_to_send> with both entries being of the type List[BlindedSignature]. Alice constructs proofs <keep_proofs> and <send_proofs> from both of these entries like in Step 2.5 [TODO: fix reference].
• Alice stores the proofs <keep_proofs> and <send_proofs> in her database and flags <send_proofs> as pending (for example in a separate column).
• Alice may also give the set of <send_proofs> a unique ID send_id so that she can later connect each set of pending tokens with every send attempt.

3.3 - Serialize tokens for sending

Here, Alice serializes the proofs from the set <send_proofs> for sending to Carol.

• Alice constructs a JSON of the form [{"amount" : <amount>, "secret" : s, "C" : Z}, ...] from <send_proofs> and encodes it as a Base64 string using url-safe Base64 encoder. [NOTE: it probably doesn't need to be url-safe, maybe it shouldn't if this is not widespread or consistent across languages]
• Alice sends the resulting TOKEN as the string W3siYW1vdW50IjogMiwgInNlY3... to Carol.

4 - Receive new tokens

Here we describe how Carol can redeem new tokens from Bob that she previously received from Alice. Carol receives tokens as a url-safe [NOTE: remove url-safe?] base64-encoded string TOKEN that, when decoded, is a JSON of the form [{"amount" : <amount>, "secret" : s, "C" : Z}, ...]. In the following, we will refer to the tuple (<amount>, Z, s) as a single token. [NOTE: clarify whether a TOKEN is a single token or a list of tokens] To redeem a token, Carol sends it to Bob and receives a one of the same value.

Carol essentially performs the same procedure to receive tokens as Alice did earlier when she prepared her tokens for sending: She sends constructs new blinded messages and sends them together with the tokens she received in order to receive a newly-issued set of tokens which settles the transaction between Alice and Carol.

Note that the following steps can also be performed by Alice herself if she wants to cancel the pending token transfer and claim them for herself.

• Carol constructs a list of <blinded_message>'s each with the same amount as the list list of tokens that she received. This can be done by the same procedure as during the minting of new tokens in Section 2 [TODO: update ref] or during sending in Section 3 [TODO: update ref] since the splitting into amounts is deterministic.
• Carol performs the same steps as Alice when she split the tokens before sending it to her and calls the endpoint POIT /split with the JSON SplitRequests as the body of the request.

5 - Burn sent tokens

Here we describe how Alice checks with the mint whether the tokens she sent Carol have been redeemed so she can safely delete them from her database. This step is optional but highly recommended so Alice can properly account for the tokens and adjust her balance accordingly.

• Alice loads all <send_proofs> with pending=True from her database and might group them by the send_id.
• Alice constructs a JSON of the form {"proofs" : [{"amount" : <amount>, "secret" : s, "C" : Z}, ...]} from these (grouped) tokens. [TODO: this object is called CheckRequest]
• Alice sends them to the mint Bob via the endpoint POST /check with the JSON as the body of the request.
• Alice receives a JSON of the form {"1" : <spendable : bool>, "2" : ...} where "1" is the index of the proof she sent to the mint before and <spendable> is a boolean that is True if the token has not been claimed yet by Carol and False if it has already been claimed.
• If <spendable> is False, Alice removes the proof [NOTE: consistent name?] from her list of spendable proofs.

6 - Pay a Lightning invoice

Here we describe how Alice can request from Bob to make a Lightning payment for her and burn an appropriate amount of tokens in return. Alice wants to pay a bolt11 invoice with the amount <invoice_amount>. She has to add a fee to the request to account for the possible Lightning fees which results in a request with tokens with the total amount of <total>.

• Alice wants to pay the bolt11 invoice <invoice>.
• Alice asks Bob for the Lightning fee via GET /checkfee with the body CheckFeeRequest being the json {pr : <invoice>}
• Alice receives the CheckFeeResponse in the form of the json {"fee" : <fee>} resulting in <total> = <invoice_amount> + <fee>.
• Alice now performs the same set of instructions as in Step 3.1 and 3.2 and splits her spendable tokens into a set <keep_proofs> that she keeps and and a set <send_proofs> with a sum of at least <total> that she can send for making the Lightning payment.
• Alice constructs the JSON MeltRequest of the form {"proofs" : <List[Proof]>, "invoice" : <invoice>} [NOTE: Maybe use notation List[Proof] everywhere. Used MeltRequest here, maybe define each payload at the beginning of each section.]
• Alice requests a payment from Bob via the endpoint POST /melt with the JSON as the body of the request.
• Alice receives a JSON of the form {"paid" : <status:bool>} with <status> being True if the payment was successful and False otherwise.
• If <status> == True, Alice removes <send_proofs> from her database of spendable tokens [NOTE: called it tokens again]

Todo:

• Call subsections 1. and 1.2 etc so they can be referenced
• Define objets like MintRequest and SplitRequests once when they appear and reuse them.
• Clarify whether a TOKEN is a single Proof or a list of Proofs