Skip to content

Latest commit

 

History

History
99 lines (75 loc) · 3.53 KB

07.md

File metadata and controls

99 lines (75 loc) · 3.53 KB

NUT-07: Token state check

optional author: calle author: tb

With the token state check, wallets can ask the mint whether a specific proof is already spent (spendable) and whether it is in-flight in a transaction (pending). Both of these attributes are returned as sepearte lists of booleans.

Token states

A wallet can internally represent the combination of these booleans the proof's state. A proof can either be live (spendable == true && pending == false), burned (spendable == false && pending == (true || false)), or in-flight (spendable == true && pending == true).

  • A proof is live if it has been minted but not spent yet.
  • A proof is burned if it has been redeemed and its secret is in the list of spent secrets of the mint.
  • A proof is in-flight if it is being processed in a transaction (in an ongoing payment). An in-flight proof cannot be used in another transaction until it is live again.

Important: Before deleting spent proofs from their database, wallets MUST check if the proof is still spendable to make sure that they don't delete an unspent proof by accident.

Note: Mints MUST remember which proofs are currently pending to avoid reuse of the same token in multiple concurrent transactions. This can be achieved with a mutex whose key is the proof's secret.

Use cases

Example 1: Ecash transaction

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 still spendable (mint returns True for spendable) or whether it has been redeemed by Carol already (mint retrns False for spendable). If the proof is not spendable anymore (and, thus, has been redeemed by Carol), she can safely delete the proof from her database.

Example 2: Lightning payments

If Alice pays a very slow Lightning invoice (for example a HODL invoice) and closes her wallet in the meantime, the next time she comes online, she can check all proof marked as pending in her database to determine, whether the payment is still in flight (mint returns True for pending and spendable), it has succeeded (mint returns False for pending and spendable), or it has failed (mint returns False for pending and True for spendable).

Example

Request of Alice:

POST https://mint.host:3338/check

With the data being of the form CheckStateRequest:

{
  "proofs": Proofs
}

Proofs is a list (array) of Proofs (see NUT-0). Alice CAN provide a full Proof but MUST provide at least the secret (which is the only thing that Bob needs to check whether the token has been spent).

With curl:

curl -X POST https://mint.host:3338/check -d \
{
  "proofs": 
    [
      {
        "secret": "S+tDfc1Lfsrb06zaRdVTed6Izg"
      },
      {
      ...
      }
    ]
}

Response of Bob:

Bob will respond with a CheckStateResponse

{
  "spendable": Array[bool],
  "pending": Array[bool]
}

Where [bool] is an array of booleans indicating whether the provided Proof is still spendable or pending.

Important: The list of booleans MUST be in the same order as the proofs provided by Alice in the request.