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.

High-level flow

1. A user has a kind:37375 event that represents a wallet.
2. A user has kind:7375 events that represent the unspent proofs of the wallet. -- The proofs are encrypted with the user's private key.
3. A user has kind:7376 events that represent the spending history of the wallet -- This history is for informational purposes only and is completely optional.

Wallet Event

{
    "kind": 37375,
    "content": nip44_encrypt([
        [ "balance", "100", "sats" ],
        [ "privkey", "hexkey" ] // explained in Appendix 2
    ]),
    "tags": [
        [ "d", "my-wallet" ],
        [ "mint", "https://mint1" ],
        [ "mint", "https://mint2" ],
        [ "mint", "https://mint3" ],
        [ "name", "my shitposting wallet" ],
        [ "unit", "sats" ],
        [ "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. "sats", "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 record the unspent proofs that come from the mint.

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

{
    "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.

Spending History Event

Clients SHOULD publish kind:7376 events to create a transaction history when their balance changes.

{
    "kind": 7376,
    "content": nip44_encrypt([
        [ "direction", "in" ], // in = received, out = sent
        [ "amount", "1", "sats" ],
        [ "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

{
    "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:

{
    "kind": 7375,
    "id": "event-id-2",
    "content": nip44_encrypt({
        "mint": "https://stablenut.umint.cash",
        "proofs": [
            { "id": "1", "amount": 1 },
            { "id": "2", "amount": 2 },
            { "id": "8", "amount": 8 },
        ]
    }),
    "tags": [
        [ "a", "37375:<pubkey>:my-wallet" ]
    ]
}

• MUST delete event event-id-1
• SHOULD create a kind:7376 event to record the spend

{
    "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" ],
    ]
}

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 even and roll over any unspent proof.

Appendix 2: Alternative P2PK pubkey

Sometimes clients might not have access to the user's private key (i.e. NIP-07, NIP-46 signing) and, as such, the private key to sign cashu spends might not be available, which would make spending the P2PK incoming nutzaps impossible.

For this scenarios clients can:

• add a pubkey tag to the kind:10019 (indicating which pubkey senders should P2PK to)
• store the private key in the kind:37375 event in the nip44-encrypted content field.

This is to avoid depending on NIP-07/46 adaptations to sign cashu payloads.