Add documentation to musig2 functions (#97)

Usage of the Musig2 functions isn't intuitive at all, especially with
the key aggregation cache and session data. It's important to provide
accurate documentation to help users understand how to correctly produce
musig2 signatures.

We also change argument names to match Kotlin best practices instead of
using the same argument names as C functions.

Author: t-bast

jni/c/src/fr_acinq_secp256k1_Secp256k1CFunctions.c

@@ -687,7 +687,6 @@ JNIEXPORT jbyteArray JNICALL Java_fr_acinq_secp256k1_Secp256k1CFunctions_secp256
   secp256k1_context *ctx = (secp256k1_context *)jctx;
   jbyte *sig;
   secp256k1_ecdsa_signature signature;
-  ;
   unsigned char der[73];
   size_t size;
   int result = 0;
@@ -858,7 +857,7 @@ JNIEXPORT jbyteArray JNICALL Java_fr_acinq_secp256k1_Secp256k1CFunctions_secp256
   if (jseckey != NULL)
   {
     size = (*penv)->GetArrayLength(penv, jseckey);
-    CHECKRESULT(size != 32, "invalid session_id size");
+    CHECKRESULT(size != 32, "invalid private key size");
     copy_bytes_from_java(penv, jseckey, size, seckey);
   }
 
@@ -1016,7 +1015,6 @@ JNIEXPORT jbyteArray JNICALL Java_fr_acinq_secp256k1_Secp256k1CFunctions_secp256
   free_pubkeys(pubkeys, count);
   CHECKRESULT(!result, "secp256k1_musig_pubkey_agg failed");
 
-  size = 32;
   jpubkey = (*penv)->NewByteArray(penv, 32);
   pub = (*penv)->GetByteArrayElements(penv, jpubkey, 0);
   result = secp256k1_xonly_pubkey_serialize(ctx, (unsigned char *)pub, &combined);
@@ -1149,7 +1147,7 @@ JNIEXPORT jbyteArray JNICALL Java_fr_acinq_secp256k1_Secp256k1CFunctions_secp256
   CHECKRESULT((*penv)->GetArrayLength(penv, jmsg32) != 32, "invalid message size");
   if (jkeyaggcache == NULL)
     return NULL;
-  CHECKRESULT((*penv)->GetArrayLength(penv, jkeyaggcache) != fr_acinq_secp256k1_Secp256k1CFunctions_SECP256K1_MUSIG_KEYAGG_CACHE_SIZE, "invalid nonce size");
+  CHECKRESULT((*penv)->GetArrayLength(penv, jkeyaggcache) != fr_acinq_secp256k1_Secp256k1CFunctions_SECP256K1_MUSIG_KEYAGG_CACHE_SIZE, "invalid keyagg cache size");
 
   ptr = (*penv)->GetByteArrayElements(penv, jaggnonce, 0);
   result = secp256k1_musig_aggnonce_parse(ctx, &aggnonce, ptr);

jni/src/main/java/fr/acinq/secp256k1/Secp256k1CFunctions.java

@@ -29,20 +29,32 @@ public class Secp256k1CFunctions {
     public static final int SECP256K1_EC_COMPRESSED = (SECP256K1_FLAGS_TYPE_COMPRESSION | SECP256K1_FLAGS_BIT_COMPRESSION);
     public static final int SECP256K1_EC_UNCOMPRESSED = (SECP256K1_FLAGS_TYPE_COMPRESSION);
 
+    /**
+     * A musig2 public nonce is simply two elliptic curve points.
+     */
     public static final int SECP256K1_MUSIG_PUBLIC_NONCE_SIZE = 66;
 
+    /**
+     * A musig2 private nonce is basically two scalars, but should be treated as an opaque blob.
+     */
     public static final int SECP256K1_MUSIG_SECRET_NONCE_SIZE = 132;
 
+    /**
+     * When aggregating public keys, we cache information in an opaque blob (must not be interpreted).
+     */
     public static final int SECP256K1_MUSIG_KEYAGG_CACHE_SIZE = 197;
 
+    /**
+     * When creating partial signatures and aggregating them, session data is kept in an opaque blob (must not be interpreted).
+     */
     public static final int SECP256K1_MUSIG_SESSION_SIZE = 133;
 
     public static native long secp256k1_context_create(int flags);
 
     public static native void secp256k1_context_destroy(long ctx);
 
     public static native int secp256k1_ec_seckey_verify(long ctx, byte[] seckey);
-    
+
     public static native byte[] secp256k1_ec_pubkey_parse(long ctx, byte[] pubkey);
 
     public static native byte[] secp256k1_ec_pubkey_create(long ctx, byte[] seckey);
@@ -93,5 +105,5 @@ public class Secp256k1CFunctions {
 
     public static native int secp256k1_musig_partial_sig_verify(long ctx, byte[] psig, byte[] pubnonce, byte[] pubkey, byte[] keyagg_cache, byte[] session);
 
-    public static native byte[] secp256k1_musig_partial_sig_agg(long ctx, byte[] session, byte[][]  psigs);
+    public static native byte[] secp256k1_musig_partial_sig_agg(long ctx, byte[] session, byte[][] psigs);
 }

jni/src/main/kotlin/fr/acinq/secp256k1/NativeSecp256k1.kt

@@ -92,36 +92,36 @@ public object NativeSecp256k1 : Secp256k1 {
         return Secp256k1CFunctions.secp256k1_schnorrsig_sign(Secp256k1Context.getContext(), data, sec, auxrand32)
     }
 
-    override fun musigNonceGen(session_id32: ByteArray, seckey: ByteArray?, pubkey: ByteArray, msg32: ByteArray?, keyagg_cache: ByteArray?, extra_input32: ByteArray?): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_nonce_gen(Secp256k1Context.getContext(), session_id32, seckey, pubkey, msg32, keyagg_cache, extra_input32)
+    override fun musigNonceGen(sessionId32: ByteArray, privkey: ByteArray?, aggpubkey: ByteArray, msg32: ByteArray?, keyaggCache: ByteArray?, extraInput32: ByteArray?): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_nonce_gen(Secp256k1Context.getContext(), sessionId32, privkey, aggpubkey, msg32, keyaggCache, extraInput32)
     }
 
     override fun musigNonceAgg(pubnonces: Array<ByteArray>): ByteArray {
         return Secp256k1CFunctions.secp256k1_musig_nonce_agg(Secp256k1Context.getContext(), pubnonces)
     }
 
-    override fun musigPubkeyAgg(pubkeys: Array<ByteArray>, keyagg_cache: ByteArray?): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_pubkey_agg(Secp256k1Context.getContext(), pubkeys, keyagg_cache)
+    override fun musigPubkeyAgg(pubkeys: Array<ByteArray>, keyaggCache: ByteArray?): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_pubkey_agg(Secp256k1Context.getContext(), pubkeys, keyaggCache)
     }
 
-    override fun musigPubkeyTweakAdd(keyagg_cache: ByteArray, tweak32: ByteArray): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_pubkey_ec_tweak_add(Secp256k1Context.getContext(), keyagg_cache, tweak32)
+    override fun musigPubkeyTweakAdd(keyaggCache: ByteArray, tweak32: ByteArray): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_pubkey_ec_tweak_add(Secp256k1Context.getContext(), keyaggCache, tweak32)
     }
 
-    override fun musigPubkeyXonlyTweakAdd(keyagg_cache: ByteArray, tweak32: ByteArray): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_pubkey_xonly_tweak_add(Secp256k1Context.getContext(), keyagg_cache, tweak32)
+    override fun musigPubkeyXonlyTweakAdd(keyaggCache: ByteArray, tweak32: ByteArray): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_pubkey_xonly_tweak_add(Secp256k1Context.getContext(), keyaggCache, tweak32)
     }
 
-    override fun musigNonceProcess(aggnonce: ByteArray, msg32: ByteArray, keyagg_cache: ByteArray,): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_nonce_process(Secp256k1Context.getContext(), aggnonce, msg32, keyagg_cache)
+    override fun musigNonceProcess(aggnonce: ByteArray, msg32: ByteArray, keyaggCache: ByteArray): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_nonce_process(Secp256k1Context.getContext(), aggnonce, msg32, keyaggCache)
     }
 
-    override fun musigPartialSign(secnonce: ByteArray, privkey: ByteArray, keyagg_cache: ByteArray, session: ByteArray): ByteArray {
-        return Secp256k1CFunctions.secp256k1_musig_partial_sign(Secp256k1Context.getContext(), secnonce, privkey, keyagg_cache, session)
+    override fun musigPartialSign(secnonce: ByteArray, privkey: ByteArray, keyaggCache: ByteArray, session: ByteArray): ByteArray {
+        return Secp256k1CFunctions.secp256k1_musig_partial_sign(Secp256k1Context.getContext(), secnonce, privkey, keyaggCache, session)
     }
 
-    override fun musigPartialSigVerify(psig: ByteArray, pubnonce: ByteArray, pubkey: ByteArray, keyagg_cache: ByteArray, session: ByteArray): Int {
-        return Secp256k1CFunctions.secp256k1_musig_partial_sig_verify(Secp256k1Context.getContext(), psig, pubnonce, pubkey, keyagg_cache, session)
+    override fun musigPartialSigVerify(psig: ByteArray, pubnonce: ByteArray, pubkey: ByteArray, keyaggCache: ByteArray, session: ByteArray): Int {
+        return Secp256k1CFunctions.secp256k1_musig_partial_sig_verify(Secp256k1Context.getContext(), psig, pubnonce, pubkey, keyaggCache, session)
     }
 
     override fun musigPartialSigAgg(session: ByteArray, psigs: Array<ByteArray>): ByteArray {

src/commonMain/kotlin/fr/acinq/secp256k1/Secp256k1.kt

@@ -55,7 +55,7 @@ public interface Secp256k1 {
      */
     public fun signSchnorr(data: ByteArray, sec: ByteArray, auxrand32: ByteArray?): ByteArray
 
-   /**
+    /**
      * Convert an ECDSA signature to a normalized lower-S form (bitcoin standardness rule).
      * Returns the normalized signature and a boolean set to true if the input signature was not normalized.
      *
@@ -149,29 +149,108 @@ public interface Secp256k1 {
                 compressed[0] = if (pubkey.last() % 2 == 0) 2.toByte() else 3.toByte()
                 compressed
             }
+
             else -> throw Secp256k1Exception("invalid public key")
         }
     }
 
-    public fun musigNonceGen(session_id32: ByteArray, seckey: ByteArray?, pubkey: ByteArray, msg32: ByteArray?, keyagg_cache: ByteArray?, extra_input32: ByteArray?): ByteArray
+    /**
+     * Generate a secret nonce to be used in a musig2 signing session.
+     * This nonce must never be persisted or reused across signing sessions.
+     * All optional arguments exist to enrich the quality of the randomness used, which is critical for security.
+     *
+     * @param sessionId32 unique 32-byte session ID.
+     * @param privkey (optional) signer's private key.
+     * @param aggpubkey aggregated public key of all participants in the signing session.
+     * @param msg32 (optional) 32-byte message that will be signed, if already known.
+     * @param keyaggCache (optional) key aggregation cache data from the signing session.
+     * @param extraInput32 (optional) additional 32-byte random data.
+     * @return serialized version of the secret nonce and the corresponding public nonce.
+     */
+    public fun musigNonceGen(sessionId32: ByteArray, privkey: ByteArray?, aggpubkey: ByteArray, msg32: ByteArray?, keyaggCache: ByteArray?, extraInput32: ByteArray?): ByteArray
 
+    /**
+     * Aggregate public nonces from all participants of a signing session.
+     *
+     * @param pubnonces public nonces (one per participant).
+     * @return 66-byte aggregate public nonce (two public keys) or throws an exception is a nonce is invalid.
+     */
     public fun musigNonceAgg(pubnonces: Array<ByteArray>): ByteArray
 
-    public fun musigPubkeyAgg(pubkeys: Array<ByteArray>, keyagg_cache: ByteArray?): ByteArray
+    /**
+     * Aggregate public keys from all participants of a signing session.
+     *
+     * @param pubkeys public keys of all participants in the signing session.
+     * @param keyaggCache (optional) key aggregation cache data from the signing session. If an empty byte array is
+     * provided, it will be filled with key aggregation data that can be used for the next steps of the signing process.
+     * @return 32-byte x-only public key.
+     */
+    public fun musigPubkeyAgg(pubkeys: Array<ByteArray>, keyaggCache: ByteArray?): ByteArray
 
-    public fun musigPubkeyTweakAdd(keyagg_cache: ByteArray, tweak32: ByteArray): ByteArray
+    /**
+     * Tweak the aggregated public key of a signing session.
+     *
+     * @param keyaggCache key aggregation cache filled by [musigPubkeyAgg].
+     * @param tweak32 private key tweak to apply.
+     * @return P + tweak32 * G (where P is the aggregated public key from [keyaggCache]). The key aggregation cache will
+     * be updated with the tweaked public key.
+     */
+    public fun musigPubkeyTweakAdd(keyaggCache: ByteArray, tweak32: ByteArray): ByteArray
 
-    public fun musigPubkeyXonlyTweakAdd(keyagg_cache: ByteArray, tweak32: ByteArray): ByteArray
+    /**
+     * Tweak the aggregated public key of a signing session, treating it as an x-only public key (e.g. when using taproot).
+     *
+     * @param keyaggCache key aggregation cache filled by [musigPubkeyAgg].
+     * @param tweak32 private key tweak to apply.
+     * @return with_even_y(P) + tweak32 * G (where P is the aggregated public key from [keyaggCache]). The key aggregation
+     * cache will be updated with the tweaked public key.
+     */
+    public fun musigPubkeyXonlyTweakAdd(keyaggCache: ByteArray, tweak32: ByteArray): ByteArray
 
-    public fun musigNonceProcess(aggnonce: ByteArray, msg32: ByteArray, keyagg_cache: ByteArray): ByteArray
+    /**
+     * Create a signing session context based on the public information from all participants.
+     *
+     * @param aggnonce aggregated public nonce (see [musigNonceAgg]).
+     * @param msg32 32-byte message that will be signed.
+     * @param keyaggCache aggregated public key cache filled by calling [musigPubkeyAgg] with the public keys of all participants.
+     * @return signing session context that can be used to create partial signatures and aggregate them.
+     */
+    public fun musigNonceProcess(aggnonce: ByteArray, msg32: ByteArray, keyaggCache: ByteArray): ByteArray
 
-    public fun musigPartialSign(secnonce: ByteArray, privkey: ByteArray, keyagg_cache: ByteArray, session: ByteArray): ByteArray
+    /**
+     * Create a partial signature.
+     *
+     * @param secnonce signer's secret nonce (see [musigNonceGen]).
+     * @param privkey signer's private key.
+     * @param keyaggCache aggregated public key cache filled by calling [musigPubkeyAgg] with the public keys of all participants.
+     * @param session signing session context (see [musigNonceProcess]).
+     * @return 32-byte partial signature.
+     */
+    public fun musigPartialSign(secnonce: ByteArray, privkey: ByteArray, keyaggCache: ByteArray, session: ByteArray): ByteArray
 
-    public fun musigPartialSigVerify(psig: ByteArray, pubnonce: ByteArray, pubkey: ByteArray, keyagg_cache: ByteArray, session: ByteArray): Int
+    /**
+     * Verify the partial signature from one of the signing session's participants.
+     *
+     * @param psig 32-byte partial signature.
+     * @param pubnonce individual public nonce of the signing participant.
+     * @param pubkey individual public key of the signing participant.
+     * @param keyaggCache aggregated public key cache filled by calling [musigPubkeyAgg] with the public keys of all participants.
+     * @param session signing session context (see [musigNonceProcess]).
+     * @return result code (1 if the partial signature is valid, 0 otherwise).
+     */
+    public fun musigPartialSigVerify(psig: ByteArray, pubnonce: ByteArray, pubkey: ByteArray, keyaggCache: ByteArray, session: ByteArray): Int
 
+    /**
+     * Aggregate partial signatures from all participants into a single schnorr signature. If some of the partial
+     * signatures are invalid, this function will return an invalid aggregated signature without raising an error.
+     * It is recommended to use [musigPartialSigVerify] to verify partial signatures first.
+     *
+     * @param session signing session context (see [musigNonceProcess]).
+     * @param psigs list of 32-byte partial signatures.
+     * @return 64-byte aggregated schnorr signature.
+     */
     public fun musigPartialSigAgg(session: ByteArray, psigs: Array<ByteArray>): ByteArray
 
-
     /**
      * Delete the secp256k1 context from dynamic memory.
      */