extrakeys: add xonly_sort function

include/secp256k1_extrakeys.h

@@ -166,6 +166,20 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_
     const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5);
 
+/** Sorts xonly public keys according to secp256k1_xonly_pubkey_cmp
+ *
+ *  Returns: 0 if the arguments are invalid. 1 otherwise.
+ *
+ *  Args:     ctx: pointer to a context object
+ *  In:   pubkeys: array of pointers to pubkeys to sort
+ *      n_pubkeys: number of elements in the pubkeys array
+ */
+SECP256K1_API int secp256k1_xonly_sort(
+    const secp256k1_context* ctx,
+    const secp256k1_xonly_pubkey **pubkeys,
+    size_t n_pubkeys
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
+
 /** Compute the keypair for a secret key.
  *
  *  Returns: 1: secret was valid, keypair is ready to use

include/secp256k1_musig.h

@@ -137,8 +137,14 @@ typedef struct {
 } secp256k1_musig_partial_signature;
 
 /** Computes a combined public key and the hash of the given public keys.
+ *
  *  Different orders of `pubkeys` result in different `combined_pk`s.
  *
+ *  The pubkeys can be sorted before combining with `secp256k1_xonly_sort` which
+ *  ensures the same resulting `combined_pk` for the same multiset of pubkeys.
+ *  This is useful to do before pubkey_combine, such that the order of pubkeys
+ *  does not affect the combined public key.
+ *
  *  Returns: 1 if the public keys were successfully combined, 0 otherwise
  *  Args:        ctx: pointer to a context object initialized for verification
  *                    (cannot be NULL)