diff --git a/docs/musig2.md b/docs/musig2.md index 6a445bbef..e46398832 100644 --- a/docs/musig2.md +++ b/docs/musig2.md @@ -13,6 +13,8 @@ partial signatures. some smaller details in the signing protocol could change in the future that might not be backward compatible. So this API must be seen as highly experimental and backward compatibility can't be guaranteed at this point. +See the [versions and compatibility matrix](#versions-and-compatibility-matrix) +below. ## References * [MuSig2 paper](https://eprint.iacr.org/2020/1261.pdf) @@ -115,3 +117,44 @@ combined key and then spend it through a Taproot script spend with an script and the control block (which contains the internal public key and the inclusion proof if there were any other script leaves). + +# Versions and compatibility matrix + +The [MuSig2 BIP +draft](https://github.com/jonasnick/bips/blob/musig2/bip-musig2.mediawiki) +underwent (and is likely still undergoing) multiple changes and is being +versioned for that reason. Starting with `lnd v0.16.0-beta` the MuSig2 RPCs will +offer backward compatibility in order to support applications that might already +have created MuSig2 based outputs on chain with an earlier version of the +protocol. + +## MuSig2 versions in lnd + +* `lnd v0.15.x-beta`: Uses MuSig2 `v0.4.0` exclusively. +* `lnd v0.16.x-beta`: Supports MuSig2 `v0.4.0` and `v1.0.0rc2` by introducing a + new **mandatory version** enum `MuSig2Version` that must be specified for the + `MuSig2CombineKeys` and `MuSig2CreateSession` RPCs. A session created with a + specific version will use that version during its lifetime (e.g. calls to + RPCs that specify the `session_id` field automatically know what version of + the MuSig2 API to use under the hood). + +## Upgrading client applications + +Client software using the MuSig2 API (such as Loop or Pool) will stop working +with `lnd v0.16.0-beta` if they aren't also updated because the added version +enum mentioned above is mandatory. In order to prepare for the `lnd 0.16.0-beta` +release such client software should use one of the following two strategies to +make sure forward compatibility is ensured: + - Compile against `lnd` on `master` branch to pull in updated RPC definitions. + Use the `GetVersion` RPC in the `verrpc` package to determine what `lnd` + version the application is connected to. Expect MuSig2 `v0.4.0` to be used + for `lnd v0.15.x-beta` and expect to explicitly set the `version` field on + the `MuSig2CombineKeys` and `MuSig2CreateSession` RPCs for + `lnd-v0.16.x-beta`. This is the recommended approach. + - Compile against `lnd` on `master` branch to pull in updated RPC definitions. + Always set the `version` field on the `MuSig2CombineKeys` and + `MuSig2CreateSession` RPCs and check the `version` field in their respective + response messages. If the `version` in the response reflects the version + sent in the request, you're using `lnd v0.16.x-beta` or later. If the + `version` is returned as `MUSIG2_VERSION_UNDEFINED` you're using + `lnd v0.15.x-beta` and only `v0.4.0` is supported. diff --git a/docs/release-notes/release-notes-0.16.0.md b/docs/release-notes/release-notes-0.16.0.md index 648f3795a..cceca8fa6 100644 --- a/docs/release-notes/release-notes-0.16.0.md +++ b/docs/release-notes/release-notes-0.16.0.md @@ -105,6 +105,16 @@ current gossip sync query status. `SignOutputRaw` call will now properly work for taproot signatures with a non-default sighash. +* [The experimental MuSig2 RPC in the `signrpc` package was upgraded to the BIP + draft version `v1.0.0rc2`](https://github.com/lightningnetwork/lnd/pull/7171). + To remain backward compatible with applications that have on-chain funds on + keys that were created with the previous version of the MuSig2 BIP draft + `v0.4.0` (such as Pool accounts) a version flag was added to the + `MuSig2CombineKeys` and `MuSig2CreateSession` RPC calls. That version flag is + mandatory, which means software using MuSig2 (such as Pool or Loop) must + update in order to use the new versioned RPC and upgrade any on-chain outputs + to the new version. + ## Wallet * [Allows Taproot public keys and tap scripts to be imported as watch-only