Receiving Cashu Token

[gudnuf]

Receiving a Cashu Token

The following describes how a user will claim a Cashu token

Input Process

1. User inputs a Cashu token by pasting or scanning it:

   cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW
   

2. Token Validation: Check if the token is already spent via the /v1/checkstate endpoint (NUT-07) :

   • If spent, determine whether it was:
     • Successfully claimed by this user or another (completely unspendable)
     • This user started to claim, but an error occurred when trying to store the proofs (identified by a corresponding claim_cashu_token_draft still present our DB)

3. The user chooses whether to:

   • Claim to the token's source mint
   • Claim to another account via lightning payment

Claiming to Source Mint

1. Prepare Data:

   • Get proofs from token: const proofs = getDecodedToken(token).proofs
   • Create deterministic output data for an amount matching the token amount

2. Create cashu-receive-token for Recovery:

   {
       "token_hash": "<SHA256(token)>", // For identification without storing the token
       "token_proofs": "<encrypted_proofs_to_claim>"
       // everything below is used for recovering from failure  to store new proofs
       "currency": "BTC" | "USD",
       "keyset_id": "<proofs_keyset_id>",
       "keyest_counter": "<counter_for_deterministic_data>",
       "output_amounts": number[], 
   }

3. Swap (NUT-03:

   • Call POST /v1/swap endpoint:

Request payload:
ts { "inputs": "<Array[Proof]>", // claimCashuTokenDraft.proofs "outputs": "<Array[BlindedMessage]>" // deterministic outputs created from the draft data }

• If swap fails with "Token already spent" (11001) error, use the /v1/restore endpoint. QUESTION: can we completely avoid this case? If we call /v1/checkstate on the proofs we will know they are spent, and if spent and there is a pending draft, then we know we have to go straight to recovery.

4. Finalize:
   This should all happen in a single transaction
   • Store the fresh proofs
   • Delete the draft
   • Add to transaction history (token is now claimed)

Claiming to a BOLT11 Invoice

1. Prepare Quotes:

   • Get an invoice matching the token amount from receiving account and a melt quote from source account
   • If receiving account is Cashu, follow the protocol for receiving Cashu via lightning after obtaining a valid melt quote

2. Melt:
   Call /v1/melt to pay the invoice. If this fails, then we just give the user an error and maybe should delete the cashu-receive-quote

3. Finalize:

   • Once invoice is paid and proofs are spent, proceed with claiming proofs on the receiving account
   • Add to transaction history when proofs are safely stored in DB