Keyset ID V2

[davidcaseria]

Summary

This PR introduces keyset ID version 2 and updates the key derivation function to improve security and eliminate mint ambiguity.

Changes

Keyset ID v2 (NUT-02)

• Full keyset ID: 33 bytes (version 01 + 32-byte SHA256 hash)
• Token keyset ID: 8 bytes (version byte + first 7 bytes of hash)
• Keyset derivation now includes unit and optional final expiry timestamp
• Wallets expand abbreviated token IDs to full keyset IDs
• Added final_expiry field for keyset expiration

Versioned Secret Derivation (NUT-13)

• Version-based derivation: Secret derivation method determined by keyset ID version
• Legacy support: Keyset version 00 uses BIP32 derivation (backward compatible)
• Keyset version 01 uses HMAC-SHA512 derivation
• Wallets determine correct method by inspecting keyset version
• Uses HMAC_SHA512(seed, "Cashu_KDF_HMAC_SHA512" || keyset_id_bytes || counter_bytes)

Implementation Status

• CDK Keysets V2 cdk#702
• Nutshell
• cashu-ts
• gonuts
• nutmix

[callebtc]

Thank you!

Please:

• add a verbose description in the PR what this is about
• we should keep at least 7 bytes, as others have mentioned
• this PR seems to replace the old keyset ID instead of adding a new version. Everything would break. We should instead add a new additional version.

[prusnak]

Quite honest, I am not sure such small change justifies creating a new keyset version and the headache attached to it.

Maybe we should keep this improvement in mind and apply it together with some future proposal that changes something significant?

[davidcaseria]

@prusnak this was suggested to enable wallets to store proofs without referencing mint URLs. @thesimplekid @ok300 do you think this is still necessary?

[thesimplekid]

this was suggested to enable wallets to store proofs without referencing mint URLs.

The longer keyset ids to reduce the chance of a collision and the keyset expiry are things we've talked about awhile and I would like to see, I think it makes sense to move forward with this. I cant think of anything else we wanted to include that we should hold this for, but if there is I am open to it.

[prusnak]

the keyset expiry are things we've talked about awhile and I would like to see, I think it makes sense to move forward with this

I agree. This is exactly the kind of change I was mentioning when I said to "justify" creating a new keyset version.

[ok300]

A few NITs, otherwise it's an ACK from me:

The specified behavior is a bit ambiguous in 2 places.

The keyset id is in each Proof so it can be used by wallets to identify which mint and keyset it was generated from.

This doesn't say if it's the long or short ID. It should probably say "short ID" or rename the variable to s_id for clarity.

To save space, a Token, as defined in [NUT-00][00], SHOULD contain an abbreviated version of the keyset id in the Proof, (the s_id).

This makes it sound preferable, but optional to use the shorter s_id in the proof, whereas the PR text indicates it's mandatory, since the Token size is kept unchanged.

[prusnak]

I think it would be better if the long keyset ID was 32-bytes:

• Keyset version byte
• the first 31-bytes out of the 32-bytes SHA-256 digest

Why?

[prusnak]

I think it's less confusing if we keep the same process and only change what is needed to be changed.

It is non-standard and does not bring any single benefit imo. Only headache.

[ok300]

IMO there is an ambiguity in the new spec:

To save space, a Token, as defined in [NUT-00][00], SHOULD contain an abbreviated version of the keyset id in the Proof, (the s_id).

This implies the Proofs in a Token could use either the short ID or the long ID.

Is there any reason where the long ID makes sense?

If not, I'd suggest to change that SHOULD to a MUST.

---

The only reason I can think of is to avoid short ID collisions, but that's already covered by another section:

If the abbreviated s_id is ambiguous (i.e., multiple keyset ids are resolvable), the wallet MUST error. The full keyset id is only needed when the wallet interacts with the mint.

[robwoodgate]

I think this is out of scope for this PR.

Fair point - was just that adding final_expiry to keys in this PR reminded me of it.

I've raised a seperate issue for consideration: #289

[callebtc]

But we should know better and not push discussed drafts into production before they are accepted.

agreed

• We drop the separators: since the keys are serialized to bytes, the result would be unreadable anyway;

having two different separators is ugly and we're only going to hash the result anyway.

I'd also vote for 1 in favor of dropping all separators (, and |).

[callebtc]

redundant comments?

[thesimplekid]

ACK 1efb5a4

[SatsAndSports]

Update: this comment is now OUTDATED. See @callebtc below

Could we add an active_at_least_until field in active keysets?

As the SIG_ALL message change (#302) commits the outputs to a particular keyset, and holders of (partially-) signed transactions might want to be able to hold the transactions for a longer time, they would like some confidence that an active keyset in their output will remain active

One example of this is the Cashu Channel, where - like in Lightning - you want users to keep their transactions away from mint until their are ready to close the channel.

[callebtc]

Could we add an active_at_least_until field in active keysets?

As the SIG_ALL message change (#302) commits the outputs to a particular keyset, and holders of (partially-) signed transactions might want to be able to hold the transactions for a longer time, they would like some confidence that an active keyset in their output will remain active

One example of this is the Cashu Channel, where - like in Lightning - you want users to keep their transactions away from mint until their are ready to close the channel.

Update: SIG_ALL does not contain the keyset ID anymore, I think we can mark this comment as outdated.

[asmogo]

ACK 1efb5a4

[thesimplekid]

ACK 9f5a747

[callebtc]

Seems unnecessary to try both methods, assuming that we transition to the new KDF only for V2 keysets

[thesimplekid]

ACK 97b9573

[robwoodgate]

Just flagging one area of concern.

[robwoodgate]

The keyset ID derivation doesn't protect/guarantee the amounts have not been tampered with, only that the amounts are still ordered the same.

What stops a mint from changing the amounts bound to each key to devalue and "inflate" away their liabilities?

eg: 1, 2, 4, 8, 16, 32, 64

could become: 1, 2, 3, 4, 8, 16, 32
or maybe even: 1, 1, 1, 1, 1, 1, 1

Perhaps we should concat all the amounts in order too... or maybe just adding the sum of key amounts would be enough to reduce the risk of serious damage?