nutshell/docs/specs/00.md

# NUT-0: Notation and Models

Sending user: `Alice`
Receiving 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 (BDHKE)

- 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 (**blinding**)
- `Bob` sends back to `Alice` blinded key: `Q = kT` (these two steps are the DH key exchange) (**signing**)
- `Alice` can calculate the unblinded key as `Q - rK = kY + krG - krG = kY = Z` (**unblinding**)
- 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` (**verification**), and if so treats it as a valid spend of a token, adding `x`  to the list of spent secrets.

## 0.1 - Models

### `BlindedMessage`

An encrypted ("blinded") secret and an amount is sent from `Alice` to `Bob` for [minting tokens][04] or for [splitting tokens][06]. A `BlindedMessage` is also called an `output`.

```json
{
  "amount": int,
  "B_": str
}
```

 `amount` is the value of the requested token and `B_` is the encrypted secret message generated by `Alice`.

### `BlindedSignature`

A signature on the `BlindedMessage` is sent from `Bob` to `Alice` after [minting tokens][04] or after [splitting tokens][06]. A `BlindedSignature` is also called a `promise`.

```json
{
  "amount": int,
  "C_": str,
  "id": str | None
}
```

`amount` is the value of the blinded token, `C_` is the blinded signature on the secret message `B_` sent in the previous step. `id` is the [keyset id][02] of the mint public keys that signed the token.

### `Proof`

A `Proof` is sent to `Bob` for [melting tokens][05]. A `Proof` can also be sent from `Alice` to `Carol` for which it is first can be [serialized](#serialization-of-proofs). Upon receiving the token, `Carol` deserializes it and requests a [split][06] from `Bob` to receive new tokens. 

```json
{
  "amount": int, 
  "secret": str,
  "C": str,
  "id": None | str,
  "script": P2SHScript | None,
}
```

`amount` is the value of the `Proof`, `secret` is the secret message, `C` is the unblinded signature on `secret`, `id` is the [keyset id][02] of the mint public keys that signed the token. `script` is a `P2SHScript` that specifies the spending condition for this `Proof` [TODO: P2SH documentation].

### `Proofs`

An array (list) of `Proof`'s. In general, this will be used for most operations instead of a single `Proof`. `Proofs` must be serialized before sending between wallets (see [Serialization of proofs](#serialization-of-proofs)).

## 0.2 - Methods

### Serialization of `Proofs`

To send and receive `Proofs`, wallets serialize them in a `base64_urlsafe` format. There are two versions of the serialization format. 

#### 0.2.1 - V1 tokens

This token format is a list of `Proof`s. Each `Proof` contains the keyset id in the field `id` that can be used by a wallet to identify the mint of this token. A wallet that encounters an unknown `id`, it CAN ask the user to enter the mint url of this yet unknown mint. The wallet SHOULD explicity ask the user whether they trust the mint.

##### Example JSON:

```json
[
  {
    "id": "DSAl9nvvyfva",
    "amount": 8,
    "secret": "DbRKIya0etdwI5sFAN0AXQ",
    "C": "02df7f2fc29631b71a1db11c163b0b1cb40444aa2b3d253d43b68d77a72ed2d625"
  },
  {
    "id": "DSAl9nvvyfva",
    "amount": 16,
    "secret": "d_PPc5KpuAB2M60WYAW5-Q",
    "C": "0270e0a37f7a0b21eab43af751dd3c03f61f04c626c0448f603f1d1f5ae5a7d7e6"
  }
]
```

When serialized, this becomes:

```
W3siaWQiOiAiRFNBbDludnZ5ZnZhIiwgImFtb3VudCI6IDgsICJzZWNyZXQiOiAiRGJSS0l5YTBldGR3STVzRkFOMEFYUSIsICJDIjogIjAyZGY3ZjJmYzI5NjMxYjcxYTFkYjExYzE2M2IwYjFjYjQwNDQ0YWEyYjNkMjUzZDQzYjY4ZDc3YTcyZWQyZDYyNSJ9LCB7ImlkIjogIkRTQWw5bnZ2eWZ2YSIsICJhbW91bnQiOiAxNiwgInNlY3JldCI6ICJkX1BQYzVLcHVBQjJNNjBXWUFXNS1RIiwgIkMiOiAiMDI3MGUwYTM3ZjdhMGIyMWVhYjQzYWY3NTFkZDNjMDNmNjFmMDRjNjI2YzA0NDhmNjAzZjFkMWY1YWU1YTdkN2U2In1d
```

#### 0.2.2 - V2 tokens

This token format includes information about the mint as well. The field `proofs` is like a V1 token. Additionally, the field `mints` can include an array (list) of multiple mints from which the `proofs` are from. The `url` field is the URL of the mint. `ids` is a list of the keyset IDs belonging to this mint. It is important that all keyset IDs of the `proofs` must be present here to allow a wallet to map each proof to a mint.

##### Example JSON:

```json
{
  "proofs": [
    {
      "id": "DSAl9nvvyfva",
      "amount": 2,
      "secret": "EhpennC9qB3iFlW8FZ_pZw",
      "C": "02c020067db727d586bc3183aecf97fcb800c3f4cc4759f69c626c9db5d8f5b5d4"
    },
    {
      "id": "DSAl9nvvyfva",
      "amount": 8,
      "secret": "TmS6Cv0YT5PU_5ATVKnukw",
      "C": "02ac910bef28cbe5d7325415d5c263026f15f9b967a079ca9779ab6e5c2db133a7"
    }
  ],
  "mints": [
    {
      "url": "https://8333.space:3338",
      "ids": ["DSAl9nvvyfva"]
    }
  ]
}
```

When serialized, this becomes:

```
eyJwcm9vZnMiOlt7ImlkIjoiRFNBbDludnZ5ZnZhIiwiYW1vdW50IjoyLCJzZWNyZXQiOiJFaHBlbm5DOXFCM2lGbFc4RlpfcFp3IiwiQyI6IjAyYzAyMDA2N2RiNzI3ZDU4NmJjMzE4M2FlY2Y5N2ZjYjgwMGMzZjRjYzQ3NTlmNjljNjI2YzlkYjVkOGY1YjVkNCJ9LHsiaWQiOiJEU0FsOW52dnlmdmEiLCJhbW91bnQiOjgsInNlY3JldCI6IlRtUzZDdjBZVDVQVV81QVRWS251a3ciLCJDIjoiMDJhYzkxMGJlZjI4Y2JlNWQ3MzI1NDE1ZDVjMjYzMDI2ZjE1ZjliOTY3YTA3OWNhOTc3OWFiNmU1YzJkYjEzM2E3In1dLCJtaW50cyI6W3sidXJsIjoiaHR0cHM6Ly84MzMzLnNwYWNlOjMzMzgiLCJpZHMiOlsiRFNBbDludnZ5ZnZhIl19XX0=
```

[00]: 00.md
[01]: 01.md
[02]: 02.md
[03]: 03.md
[04]: 04.md
[05]: 05.md
[06]: 06.md
[07]: 07.md
[08]: 08.md
[09]: 09.md
[10]: 10.md
[11]: 11.md
[12]: 12.md
[13]: 13.md
[14]: 14.md
[15]: 15.md
[16]: 16.md
[17]: 17.md
[18]: 18.md
[19]: 19.md
[20]: 20.md