nips/60.md

# NIP-60
## Cashu Wallet
`draft` `optional`

This NIP defines the operations of a cashu-based wallet.

A cashu wallet is a wallet which information is stored in relays to make it accessible across applications.

The purpose of this NIP is:
* ease-of-use: new users immediately are able to receive funds without creating accounts with other services.
* interoperability: users' wallets follows them across applications.

This NIP doesn't deal with users' *receiving* money from someone else, it's just to keep state of the user's wallet.

# Event Kinds
- `kind:37375` contains relevant info for a wallet. Clients **SHOULD** check the current info event when loading the wallet.
- `kind:7373` wallet's reserved proofs. The proofs **MUST** be nip44-encrypted with the user's private key.
- `kind:7374` tracks pending quotes from a mint. This event **MAY** be used to keep track of the quote ID and its expiration.
- `kind:7375` represents the wallet's unspent proofs. The proofs **MUST** be nip44-encrypted with the user's private key.
- `kind:7376` provides the wallet's transaction history. The history is provided only for informational purposes and is not part of the wallet state.

## Wallet Event
```jsonc
{
    "kind": 37375,
    "content": nip44_encrypt([
        [ "balance", "100", "sat" ],
        [ "privkey", "hexkey" ] // explained in NIP-61
    ]),
    "tags": [
        [ "d", "my-wallet" ],
        [ "mint", "https://mint1" ],
        [ "mint", "https://mint2" ],
        [ "mint", "https://mint3" ],
        [ "name", "my shitposting wallet" ],
        [ "unit", "sat" ],
        [ "description", "a wallet for my day-to-day shitposting" ],
        [ "relay", "wss://relay1" ],
        [ "relay", "wss://relay2" ],
    ]
}
```

The wallet event is a parameterized replaceable event `kind:37375`.

Tags:
* `d` - wallet ID.
* `mint` - Mint(s) this wallet uses -- there MUST be one or more mint tags.
* `relay` - Relays where the wallet and related events can be found. -- one ore more relays SHOULD be specified. If missing, clients should follow [[NIP-65]].
* `unit` - Base unit of the wallet (e.g. "sat", "usd", etc).
* `name` - Optional human-readable name for the wallet.
* `description` - Optional human-readable description of the wallet.
* `balance` - Optional best-effort balance of the wallet that can serve as a placeholder while an accurate balance is computed from fetching all unspent proofs.
* `privkey` - Private key used to unlock P2PK ecash. MUST be stored encrypted in the `.content` field. **This is a different private key exclusively used for the wallet, not associated in any way to the user's nostr private key** -- This is only used when receiving funds from others, described in NIP-61.

Any tag, other than the `d` tag, can be [[NIP-44]] encrypted into the `.content` field.

### Deleting a wallet event
Due to PRE being hard to delete, if a user wants to delete a wallet, they should empty the event and keep just the `d` identifier and add a `deleted` tag.

## Token Event
Token events are used to store proofs of a wallet.

There can be multiple `kind:7375` events for the same mint, and multiple proofs inside each `kind:7375` event.

```jsonc
{
    "kind": 7375,
    "content": nip44_encrypt({
        "mint": "https://stablenut.umint.cash",
        "proofs": [
            {
                "id": "005c2502034d4f12",
                "amount": 1,
                "secret": "z+zyxAVLRqN9lEjxuNPSyRJzEstbl69Jc1vtimvtkPg=",
                "C": "0241d98a8197ef238a192d47edf191a9de78b657308937b4f7dd0aa53beae72c46"
            }
        ]
    }),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ]
    ]
}
```

`.content` is a [[NIP-44]] encrypted payload storing the mint and the unencoded proofs.
* `a` an optional tag linking the token to a specific wallet.

### Spending proofs
When one or more proofs of a token are spent, the token event should be [[NIP-09]]-deleted and, if some proofs are unspent from the same token event, a new token event should be created rolling over the unspent proofs and adding any change outputs to the new token event.

### Reserving proofs
A wallet can reserve proofs by deleting them from a `kind:7375` event and creating a `kind:7373` event. `kind:7373` and `kind:7375` events have the same structure.

## Spending History Event
Clients SHOULD publish `kind:7376` events to create a transaction history when their balance changes.

```jsonc
{
    "kind": 7376,
    "content": nip44_encrypt([
        [ "direction", "in" ], // in = received, out = sent
        [ "amount", "1", "sat" ],
        [ "e", "<event-id-of-spent-token>", "<relay-hint>", "created" ],
    ]),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ],
    ]
}
```

* `direction` - The direction of the transaction; `in` for received funds, `out` for sent funds.
* `a` - The wallet the transaction is related to.

Clients MUST add `e` tags to create references of destroyed and created token events along with the marker of the meaning of the tag:
* `created` - A new token event was created.
* `destroyed` - A token event was destroyed.
* `redeemed` - A [[NIP-61]] nutzap was redeemed.

All tags can be [[NIP-44]] encrypted. Clients SHOULD leave `e` tags with a `redeemed` marker unencrypted.

Multiple `e` tags can be added to a `kind:7376` event.

# Flow
A client that wants to check for user's wallets information starts by fetching `kind:10019` events from the user's relays, if no event is found, it should fall back to using the user's [[NIP-65]] relays.

## Fetch wallet and token list
From those relays, the client should fetch wallet and token events.

`"kinds": [37375, 7375], "authors": ["<my-pubkey>"]`

## Fetch proofs
While the client is fetching (and perhaps validating) proofs it can use the optional `balance` tag of the wallet event to display a estimate of the balance of the wallet.

## Spending token
If Alice spends 4 sats from this token event
```jsonconc
{
    "kind": 7375,
    "id": "event-id-1",
    "content": nip44_encrypt({
        "mint": "https://stablenut.umint.cash",
        "proofs": [
            { "id": "1", "amount": 1 },
            { "id": "2", "amount": 2 },
            { "id": "3", "amount": 4 },
            { "id": "4", "amount": 8 },
        ]
    }),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ]
    ]
}
```

Her client:
* MUST roll over the unspent proofs:
```jsonconc
{
    "kind": 7375,
    "id": "event-id-2",
    "content": nip44_encrypt({
        "mint": "https://stablenut.umint.cash",
        "proofs": [
            { "id": "1", "amount": 1 },
            { "id": "2", "amount": 2 },
            { "id": "4", "amount": 8 },
        ]
    }),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ]
    ]
}
```
* MUST delete event `event-id-1`
* SHOULD create a `kind:7376` event to record the spend
```jsonconc
{
    "kind": 7376,
    "content": nip44_encrypt([
        [ "direction", "out" ],
        [ "amount", "4", "sats" ],
        [ "e", "<event-id-1>", "<relay-hint>", "destroyed" ],
        [ "e", "<event-id-2>", "<relay-hint>", "created" ],
    ]),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ],
    ]
}
```

## Redeeming a quote (optional)
When creating a quote at a mint, an event can be used to keep the state of the quote ID, which will be used to check when the quote has been paid. These events should be created with an expiration tag [[NIP-40]] matching the expiration of the bolt11 received from the mint; this signals to relays when they can safely discard these events.

Application developers are encouraged to use local state when possible and only publish this event when it makes sense in the context of their application.

```jsonc
{
    "kind": 7374,
    "content": nip44_encrypt("quote-id"),
    "tags": [
        [ "expiration", "<expiration-timestamp>" ],
        [ "mint", "<mint-url>" ],
        [ "a", "37375:<pubkey>:my-wallet" ]
    ]
}
```

## Appendix 1: Validating proofs
Clients can optionally validate proofs to make sure they are not working from an old state; this logic is left up to particular implementations to decide when and why to do it, but if some proofs are checked and deemed to have been spent, the client should delete the token and roll over any unspent proof.

## Appendix 2: Validating relays
Clients might want to optionally check that the relays the user chooses to store the proofs respond well to [[NIP-09]] event deletion requests and, periodically, check that the different relays are consistent with the state they report. These checks are left up to particular implementations to decide when and why to do them.