Add documentation to musig2 functions

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.
      */