Small musig improvements

examples/musig.c

@@ -4,9 +4,9 @@
  * file COPYING or https://www.opensource.org/licenses/mit-license.php.*
  **********************************************************************/
 
-/**
- * This file demonstrates how to use the MuSig module to create a multisignature.
- * Additionally, see the documentation in include/secp256k1_musig.h.
+/** This file demonstrates how to use the MuSig module to create a
+ *  3-of-3 multisignature. Additionally, see the documentation in
+ *  include/secp256k1_musig.h and src/modules/musig/musig.md.
  */
 
 #include <stdio.h>

include/secp256k1_musig.h

@@ -398,6 +398,18 @@ SECP256K1_API int secp256k1_musig_partial_sign(
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(6);
 
 /** Verifies an individual signer's partial signature
+ *
+ *  The signature is verified for a specific signing session. In order to avoid
+ *  accidentally verifying a signature from a different or non-existing signing
+ *  session, you must ensure the following:
+ *    1. The `keyagg_cache` argument is identical to the one used to create the
+ *       `session` with `musig_nonce_process`.
+ *    2. The `pubkey` argument must be identical to the one sent by the signer
+ *       before aggregating it with `musig_pubkey_agg` to create the
+ *       `keyagg_cache`.
+ *    3. The `pubnonce` argument must be identical to the one sent by the signer
+ *       before aggregating it with `musig_nonce_agg` and using the result to
+ *       create the `session` with `musig_nonce_process`.
  *
  *  This function is essential when using protocols with adaptor signatures.
  *  However, it is not essential for regular MuSig sessions, in the sense that if any
@@ -408,13 +420,14 @@ SECP256K1_API int secp256k1_musig_partial_sign(
  *  Returns: 0 if the arguments are invalid or the partial signature does not
  *           verify, 1 otherwise
  *  Args         ctx: pointer to a context object, initialized for verification
- *  In:  partial_sig: pointer to partial signature to verify
- *          pubnonce: public nonce sent by the signer who produced the signature
- *            pubkey: public key of the signer who produced the signature
+ *  In:  partial_sig: pointer to partial signature to verify, sent by
+ *                    the signer associated with `pubnonce` and `pubkey`
+ *          pubnonce: public nonce of the signer in the signing session
+ *            pubkey: public key of the signer in the signing session
  *      keyagg_cache: pointer to the keyagg_cache that was output when the
- *                    aggregate public key for this session
+ *                    aggregate public key for this signing session
  *           session: pointer to the session that was created with
- *                    musig_nonce_process
+ *                    `musig_nonce_process`
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_partial_sig_verify(
     const secp256k1_context* ctx,

src/modules/musig/session_impl.h

@@ -664,13 +664,6 @@ int secp256k1_musig_partial_sig_verify(const secp256k1_context* ctx, const secp2
     secp256k1_musig_keyaggcoef(&mu, &cache_i, &pkp.x);
     secp256k1_scalar_mul(&e, &session_i.challenge, &mu);
 
-    /* If the MuSig-aggregate point has an odd Y coordinate, the signers will
-     * sign for the negation of their individual xonly public key. If the
-     * aggregate key is untweaked, then internal_key_parity is 0, so `e` is
-     * negated exactly when the aggregate key parity is odd. If the aggregate
-     * key is tweaked, then negation happens when the aggregate key has an odd Y
-     * coordinate XOR the internal key has an odd Y coordinate.*/
-
     /* When producing a partial signature, signer i uses a possibly
      * negated secret key:
      *