Merge branch 'master' into sync

# Conflicts: # .github/workflows/ci.yml # .gitignore # README.md # ci/ci.sh # src/ctime_tests.c # src/tests.c
2026-08-30 14:39:15 +02:00
parent 69d5e6bdc1 10366dbbbf
commit 0a3a3da14d
167 changed files with 20669 additions and 14575 deletions
--- a/include/secp256k1.h
+++ b/include/secp256k1.h
@@ -6,6 +6,7 @@ extern "C" {
 #endif

 #include <stddef.h>
+#include <stdint.h>

 /** Unless explicitly stated all pointer arguments must not be NULL.
 *
@@ -49,19 +50,6 @@ extern "C" {
 */
 typedef struct secp256k1_context_struct secp256k1_context;

-/** Opaque data structure that holds rewritable "scratch space"
- *
- *  The purpose of this structure is to replace dynamic memory allocations,
- *  because we target architectures where this may not be available. It is
- *  essentially a resizable (within specified parameters) block of bytes,
- *  which is initially created either by memory allocation or TODO as a pointer
- *  into some fixed rewritable space.
- *
- *  Unlike the context object, this cannot safely be shared between threads
- *  without additional synchronization logic.
- */
-typedef struct secp256k1_scratch_space_struct secp256k1_scratch_space;
-
 /** Opaque data structure that holds a parsed and valid public key.
 *
 *  The exact representation of data inside is implementation defined and not
@@ -71,11 +59,11 @@ typedef struct secp256k1_scratch_space_struct secp256k1_scratch_space;
 *  use secp256k1_ec_pubkey_serialize and secp256k1_ec_pubkey_parse. To
 *  compare keys, use secp256k1_ec_pubkey_cmp.
 */
-typedef struct {
+typedef struct secp256k1_pubkey {
    unsigned char data[64];
 } secp256k1_pubkey;

-/** Opaque data structured that holds a parsed ECDSA signature.
+/** Opaque data structure that holds a parsed ECDSA signature.
 *
 *  The exact representation of data inside is implementation defined and not
 *  guaranteed to be portable between different platforms or versions. It is
@@ -84,7 +72,7 @@ typedef struct {
 *  comparison, use the secp256k1_ecdsa_signature_serialize_* and
 *  secp256k1_ecdsa_signature_parse_* functions.
 */
-typedef struct {
+typedef struct secp256k1_ecdsa_signature {
    unsigned char data[64];
 } secp256k1_ecdsa_signature;

@@ -134,35 +122,57 @@ typedef int (*secp256k1_nonce_function)(
 #endif

 /* Symbol visibility. */
-#if defined(_WIN32)
-  /* GCC for Windows (e.g., MinGW) accepts the __declspec syntax
-   * for MSVC compatibility. A __declspec declaration implies (but is not
-   * exactly equivalent to) __attribute__ ((visibility("default"))), and so we
-   * actually want __declspec even on GCC, see "Microsoft Windows Function
-   * Attributes" in the GCC manual and the recommendations in
-   * https://gcc.gnu.org/wiki/Visibility. */
-# if defined(SECP256K1_BUILD)
-#  if defined(DLL_EXPORT) || defined(SECP256K1_DLL_EXPORT)
-    /* Building libsecp256k1 as a DLL.
-     * 1. If using Libtool, it defines DLL_EXPORT automatically.
-     * 2. In other cases, SECP256K1_DLL_EXPORT must be defined. */
-#   define SECP256K1_API extern __declspec (dllexport)
-#  endif
-  /* The user must define SECP256K1_STATIC when consuming libsecp256k1 as a static
-   * library on Windows. */
-# elif !defined(SECP256K1_STATIC)
-   /* Consuming libsecp256k1 as a DLL. */
-#  define SECP256K1_API extern __declspec (dllimport)
-# endif
+#if !defined(SECP256K1_API) && defined(SECP256K1_NO_API_VISIBILITY_ATTRIBUTES)
+     /* The user has requested that we don't specify visibility attributes in
+      * the public API.
+      *
+      * Since all our non-API declarations use the static qualifier, this means
+      * that the user can use -fvisibility=<value> to set the visibility of the
+      * API symbols. For instance, -fvisibility=hidden can be useful *even for
+      * the API symbols*, e.g., when building a static library which is linked
+      * into a shared library, and the latter should not re-export the
+      * libsecp256k1 API.
+      *
+      * While visibility is a concept that applies only to shared libraries,
+      * setting visibility will still make a difference when building a static
+      * library: the visibility settings will be stored in the static library,
+      * solely for the potential case that the static library will be linked into
+      * a shared library. In that case, the stored visibility settings will
+      * resurface and be honored for the shared library. */
+#    define SECP256K1_API extern
 #endif
-#ifndef SECP256K1_API
-# if defined(__GNUC__) && (__GNUC__ >= 4) && defined(SECP256K1_BUILD)
-   /* Building libsecp256k1 on non-Windows using GCC or compatible. */
-#  define SECP256K1_API extern __attribute__ ((visibility ("default")))
-# else
-   /* All cases not captured above. */
-#  define SECP256K1_API extern
-# endif
+#if !defined(SECP256K1_API)
+#    if defined(SECP256K1_BUILD)
+         /* On Windows, assume a shared library only if explicitly requested.
+          *   1. If using Libtool, it defines DLL_EXPORT automatically.
+          *   2. In other cases, SECP256K1_DLL_EXPORT must be defined. */
+#        if defined(_WIN32) && (defined(SECP256K1_DLL_EXPORT) || defined(DLL_EXPORT))
+             /* GCC for Windows (e.g., MinGW) accepts the __declspec syntax for
+              * MSVC compatibility. A __declspec declaration implies (but is not
+              * exactly equivalent to) __attribute__ ((visibility("default"))),
+              * and so we actually want __declspec even on GCC, see "Microsoft
+              * Windows Function Attributes" in the GCC manual and the
+              * recommendations in https://gcc.gnu.org/wiki/Visibility . */
+#            define SECP256K1_API extern __declspec(dllexport)
+         /* Avoid __attribute__ ((visibility("default"))) on Windows to get rid
+          * of warnings when compiling with -flto due to a bug in GCC, see
+          * https://gcc.gnu.org/bugzilla/show_bug.cgi?id=116478 . */
+#        elif !defined(_WIN32) && defined (__GNUC__) && (__GNUC__ >= 4)
+#            define SECP256K1_API extern __attribute__ ((visibility("default")))
+#        else
+#            define SECP256K1_API extern
+#        endif
+#    else
+         /* On Windows, SECP256K1_STATIC must be defined when consuming
+          * libsecp256k1 as a static library. Note that SECP256K1_STATIC is a
+          * "consumer-only" macro, and it has no meaning when building
+          * libsecp256k1. */
+#        if defined(_WIN32) && !defined(SECP256K1_STATIC)
+#            define SECP256K1_API extern __declspec(dllimport)
+#        else
+#            define SECP256K1_API extern
+#        endif
+#    endif
 #endif

 /* Warning attributes
@@ -233,10 +243,10 @@ typedef int (*secp256k1_nonce_function)(
 *
 *  It is highly recommended to call secp256k1_selftest before using this context.
 */
-SECP256K1_API const secp256k1_context *secp256k1_context_static;
+SECP256K1_API const secp256k1_context * const secp256k1_context_static;

 /** Deprecated alias for secp256k1_context_static. */
-SECP256K1_API const secp256k1_context *secp256k1_context_no_precomp
+SECP256K1_API const secp256k1_context * const secp256k1_context_no_precomp
 SECP256K1_DEPRECATED("Use secp256k1_context_static instead");

 /** Perform basic self tests (to be used in conjunction with secp256k1_context_static)
@@ -252,7 +262,7 @@ SECP256K1_DEPRECATED("Use secp256k1_context_static instead");
 *  secp256k1_context_create (or secp256k1_context_preallocated_create), which will
 *  take care of performing the self tests.
 *
- *  If the tests fail, this function will call the default error handler to abort the
+ *  If the tests fail, this function will call the default error callback to abort the
 *  program (see secp256k1_context_set_error_callback).
 */
 SECP256K1_API void secp256k1_selftest(void);
@@ -325,36 +335,38 @@ SECP256K1_API void secp256k1_context_destroy(
 *  an API call. It will only trigger for violations that are mentioned
 *  explicitly in the header.
 *
- *  The philosophy is that these shouldn't be dealt with through a
- *  specific return value, as calling code should not have branches to deal with
- *  the case that this code itself is broken.
+ *  The philosophy is that these shouldn't be dealt with through a specific
+ *  return value, as calling code should not have branches to deal with the case
+ *  that this code itself is broken.
 *
 *  On the other hand, during debug stage, one would want to be informed about
- *  such mistakes, and the default (crashing) may be inadvisable.
- *  When this callback is triggered, the API function called is guaranteed not
- *  to cause a crash, though its return value and output arguments are
- *  undefined.
+ *  such mistakes, and the default (crashing) may be inadvisable. Should this
+ *  callback return instead of crashing, the return value and output arguments
+ *  of the API function call are undefined. Moreover, the same API call may
+ *  trigger the callback again in this case.
 *
- *  When this function has not been called (or called with fn==NULL), then the
- *  default handler will be used. The library provides a default handler which
- *  writes the message to stderr and calls abort. This default handler can be
+ *  When this function has not been called (or called with fun==NULL), then the
+ *  default callback will be used. The library provides a default callback which
+ *  writes the message to stderr and calls abort. This default callback can be
 *  replaced at link time if the preprocessor macro
 *  USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build
- *  has been configured with --enable-external-default-callbacks. Then the
+ *  has been configured with --enable-external-default-callbacks (GNU Autotools) or
+ *  -DSECP256K1_USE_EXTERNAL_DEFAULT_CALLBACKS=ON (CMake). Then the
 *  following two symbols must be provided to link against:
 *   - void secp256k1_default_illegal_callback_fn(const char *message, void *data);
 *   - void secp256k1_default_error_callback_fn(const char *message, void *data);
- *  The library can call these default handlers even before a proper callback data
+ *  The library may call a default callback even before a proper callback data
 *  pointer could have been set using secp256k1_context_set_illegal_callback or
 *  secp256k1_context_set_error_callback, e.g., when the creation of a context
- *  fails. In this case, the corresponding default handler will be called with
+ *  fails. In this case, the corresponding default callback will be called with
 *  the data pointer argument set to NULL.
 *
 *  Args: ctx:  pointer to a context object.
 *  In:   fun:  pointer to a function to call when an illegal argument is
 *              passed to the API, taking a message and an opaque pointer.
- *              (NULL restores the default handler.)
- *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
+ *              (NULL restores the default callback.)
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
 *
 *  See also secp256k1_context_set_error_callback.
 */
@@ -371,8 +383,8 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
 *  to abort the program.
 *
 *  This can only trigger in case of a hardware failure, miscompilation,
- *  memory corruption, serious bug in the library, or other error would can
- *  otherwise result in undefined behaviour. It will not trigger due to mere
+ *  memory corruption, serious bug in the library, or other error that would
+ *  result in undefined behaviour. It will not trigger due to mere
 *  incorrect usage of the API (see secp256k1_context_set_illegal_callback
 *  for that). After this callback returns, anything may happen, including
 *  crashing.
@@ -380,9 +392,10 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
 *  Args: ctx:  pointer to a context object.
 *  In:   fun:  pointer to a function to call when an internal error occurs,
 *              taking a message and an opaque pointer (NULL restores the
- *              default handler, see secp256k1_context_set_illegal_callback
+ *              default callback, see secp256k1_context_set_illegal_callback
 *              for details).
- *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
 *
 *  See also secp256k1_context_set_illegal_callback.
 */
@@ -392,27 +405,44 @@ SECP256K1_API void secp256k1_context_set_error_callback(
    const void *data
 ) SECP256K1_ARG_NONNULL(1);

-/** Create a secp256k1 scratch space object.
+/** A pointer to a function implementing SHA256's internal compression function.
 *
- *  Returns: a newly created scratch space.
- *  Args: ctx:  pointer to a context object.
- *  In:   size: amount of memory to be available as scratch space. Some extra
- *              (<100 bytes) will be allocated for extra accounting.
+ * This function processes one or more contiguous 64-byte message blocks and
+ * updates the internal SHA256 state accordingly. The function is not responsible
+ * for counting consumed blocks or bytes, nor for performing padding.
+ *
+ * In/Out:  state:     pointer to eight 32-bit words representing the current internal state;
+ *                     the state is updated in place.
+ * In:      blocks64:  pointer to concatenation of n_blocks blocks, of 64 bytes each.
+ *                     no alignment guarantees are made for this pointer.
+ *          n_blocks:  number of contiguous 64-byte blocks to process.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_scratch_space *secp256k1_scratch_space_create(
-    const secp256k1_context *ctx,
-    size_t size
-) SECP256K1_ARG_NONNULL(1);
+typedef void (*secp256k1_sha256_compression_function)(
+    uint32_t *state,
+    const unsigned char *blocks64,
+    size_t n_blocks
+);

-/** Destroy a secp256k1 scratch space.
+/**
+ * Set a callback function to override the internal SHA256 compression function.
 *
- *  The pointer may not be used afterwards.
- *  Args:       ctx: pointer to a context object.
- *          scratch: space to destroy
+ * This installs a function to replace the built-in block-compression
+ * step used by the library's internal SHA256 implementation.
+ * The provided callback must exactly implement the effect of n_blocks
+ * repeated applications of the SHA256 compression function.
+ *
+ * This API exists to support environments that wish to route the
+ * SHA256 compression step through a hardware-accelerated or otherwise
+ * specialized implementation. It is NOT meant for replacing SHA256
+ * with a different hash function.
+ *
+ * Args:    ctx:             pointer to a context object.
+ * In:      fn_compression:  pointer to a function implementing the compression function;
+ *                           passing NULL restores the default implementation.
 */
-SECP256K1_API void secp256k1_scratch_space_destroy(
-    const secp256k1_context *ctx,
-    secp256k1_scratch_space *scratch
+SECP256K1_API void secp256k1_context_set_sha256_compression(
+        secp256k1_context *ctx,
+        secp256k1_sha256_compression_function fn_compression
 ) SECP256K1_ARG_NONNULL(1);

 /** Parse a variable-length public key into the pubkey object.
@@ -474,6 +504,20 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_cmp(
    const secp256k1_pubkey *pubkey2
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

+/** Sort public keys using lexicographic (of compressed serialization) order
+ *
+ *  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_ec_pubkey_sort(
+    const secp256k1_context *ctx,
+    const secp256k1_pubkey **pubkeys,
+    size_t n_pubkeys
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
+
 /** Parse an ECDSA signature in compact (64 bytes) format.
 *
 *  Returns: 1 when the signature could be parsed, 0 otherwise.
@@ -643,7 +687,7 @@ SECP256K1_API const secp256k1_nonce_function secp256k1_nonce_function_default;
 *  Returns: 1: signature created
 *           0: the nonce generation function failed, or the secret key was invalid.
 *  Args:    ctx:       pointer to a context object (not secp256k1_context_static).
- *  Out:     sig:       pointer to an array where the signature will be placed.
+ *  Out:     sig:       pointer to a signature object.
 *  In:      msghash32: the 32-byte message hash being signed.
 *           seckey:    pointer to a 32-byte secret key.
 *           noncefp:   pointer to a nonce generation function. If NULL,
@@ -665,12 +709,14 @@ SECP256K1_API int secp256k1_ecdsa_sign(
    const void *ndata
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);

-/** Verify an ECDSA secret key.
+/** Verify an elliptic curve secret key.
 *
 *  A secret key is valid if it is not 0 and less than the secp256k1 curve order
 *  when interpreted as an integer (most significant byte first). The
 *  probability of choosing a 32-byte string uniformly at random which is an
- *  invalid secret key is negligible.
+ *  invalid secret key is negligible. However, if it does happen it should
+ *  be assumed that the randomness source is severely broken and there should
+ *  be no retry.
 *
 *  Returns: 1: secret key is valid
 *           0: secret key is invalid
@@ -711,21 +757,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate(
    unsigned char *seckey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);

-/** Same as secp256k1_ec_seckey_negate, but DEPRECATED. Will be removed in
- *  future versions. */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate(
-    const secp256k1_context *ctx,
-    unsigned char *seckey
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2)
-  SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_negate instead");
-
 /** Negates a public key in place.
 *
 *  Returns: 1 always
 *  Args:   ctx:        pointer to a context object
 *  In/Out: pubkey:     pointer to the public key to be negated.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
+SECP256K1_API int secp256k1_ec_pubkey_negate(
    const secp256k1_context *ctx,
    secp256k1_pubkey *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
@@ -751,15 +789,6 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add(
    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in
- *  future versions. */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
-    const secp256k1_context *ctx,
-    unsigned char *seckey,
-    const unsigned char *tweak32
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3)
-  SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_tweak_add instead");
-
 /** Tweak a public key by adding tweak times the generator to it.
 *
 *  Returns: 0 if the arguments are invalid or the resulting public key would be
@@ -798,15 +827,6 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul(
    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in
- *  future versions. */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
-    const secp256k1_context *ctx,
-    unsigned char *seckey,
-    const unsigned char *tweak32
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3)
-  SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_tweak_mul instead");
-
 /** Tweak a public key by multiplying it by a tweak value.
 *
 *  Returns: 0 if the arguments are invalid. 1 otherwise.
@@ -893,7 +913,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine(
 *           msg: pointer to an array containing the message
 *        msglen: length of the message array
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_tagged_sha256(
+SECP256K1_API int secp256k1_tagged_sha256(
    const secp256k1_context *ctx,
    unsigned char *hash32,
    const unsigned char *tag,
--- a/include/secp256k1_ecdsa_s2c.h
+++ b/include/secp256k1_ecdsa_s2c.h
@@ -25,7 +25,7 @@ extern "C" {
 *  If you need to convert to a format suitable for storage, transmission, or
 *  comparison, use secp256k1_ecdsa_s2c_opening_serialize and secp256k1_ecdsa_s2c_opening_parse.
 */
-typedef struct {
+typedef struct secp256k1_ecdsa_s2c_opening {
    unsigned char data[64];
 } secp256k1_ecdsa_s2c_opening;

--- a/include/secp256k1_ellswift.h
+++ b/include/secp256k1_ellswift.h
@@ -35,7 +35,7 @@ extern "C" {
 *
 * If the Y coordinate is relevant, it is given the same parity as t.
 *
- * Changes w.r.t. the the paper:
+ * Changes w.r.t. the paper:
 * - The u=0, t=0, and u^3+t^2+7=0 conditions result in decoding to the point
 *   at infinity in the paper. Here they are remapped to finite points.
 * - The paper uses an additional encoding bit for the parity of y. Here the
@@ -130,7 +130,7 @@ SECP256K1_API int secp256k1_ellswift_decode(
 *
 *  Returns: 1: secret was valid, public key was stored.
 *           0: secret was invalid, try again.
- *  Args:    ctx:        pointer to a context object
+ *  Args:    ctx:        pointer to a context object (not secp256k1_context_static)
 *  Out:     ell64:      pointer to a 64-byte array to receive the ElligatorSwift
 *                       public key
 *  In:      seckey32:   pointer to a 32-byte secret key
--- a/include/secp256k1_extrakeys.h
+++ b/include/secp256k1_extrakeys.h
@@ -19,7 +19,7 @@ extern "C" {
 *  use secp256k1_xonly_pubkey_serialize and secp256k1_xonly_pubkey_parse. To
 *  compare keys, use secp256k1_xonly_pubkey_cmp.
 */
-typedef struct {
+typedef struct secp256k1_xonly_pubkey {
    unsigned char data[64];
 } secp256k1_xonly_pubkey;

@@ -30,7 +30,7 @@ typedef struct {
 *  guaranteed to be portable between different platforms or versions. It is
 *  however guaranteed to be 96 bytes in size, and can be safely copied/moved.
 */
-typedef struct {
+typedef struct secp256k1_keypair {
    unsigned char data[96];
 } secp256k1_keypair;

@@ -90,7 +90,7 @@ SECP256K1_API int secp256k1_xonly_pubkey_cmp(
 *                     the negation of the pubkey and set to 0 otherwise.
 *  In:        pubkey: pointer to a public key that is converted.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey(
+SECP256K1_API int secp256k1_xonly_pubkey_from_pubkey(
    const secp256k1_context *ctx,
    secp256k1_xonly_pubkey *xonly_pubkey,
    int *pk_parity,
@@ -155,10 +155,13 @@ 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);

-/** Compute the keypair for a secret key.
+/** Compute the keypair for a valid secret key.
 *
- *  Returns: 1: secret was valid, keypair is ready to use
- *           0: secret was invalid, try again with a different secret
+ *  See the documentation of `secp256k1_ec_seckey_verify` for more information
+ *  about the validity of secret keys.
+ *
+ *  Returns: 1: secret key is valid
+ *           0: secret key is invalid
 *  Args:    ctx: pointer to a context object (not secp256k1_context_static).
 *  Out: keypair: pointer to the created keypair.
 *  In:   seckey: pointer to a 32-byte secret key.
@@ -176,7 +179,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create(
 *  Out: seckey: pointer to a 32-byte buffer for the secret key.
 *  In: keypair: pointer to a keypair.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec(
+SECP256K1_API int secp256k1_keypair_sec(
    const secp256k1_context *ctx,
    unsigned char *seckey,
    const secp256k1_keypair *keypair
@@ -189,7 +192,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec(
 *  Out: pubkey: pointer to a pubkey object, set to the keypair public key.
 *  In: keypair: pointer to a keypair.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub(
+SECP256K1_API int secp256k1_keypair_pub(
    const secp256k1_context *ctx,
    secp256k1_pubkey *pubkey,
    const secp256k1_keypair *keypair
@@ -208,7 +211,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub(
 *               pk_parity argument of secp256k1_xonly_pubkey_from_pubkey.
 *  In: keypair: pointer to a keypair.
 */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub(
+SECP256K1_API int secp256k1_keypair_xonly_pub(
    const secp256k1_context *ctx,
    secp256k1_xonly_pubkey *pubkey,
    int *pk_parity,
@@ -240,21 +243,6 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_tweak_add
    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Sort public keys using lexicographic order of their compressed
- *  serialization.
- *
- *  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_pubkey_sort(
-    const secp256k1_context *ctx,
-    const secp256k1_pubkey **pubkeys,
-    size_t n_pubkeys
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
-
 #ifdef __cplusplus
 }
 #endif
--- a/include/secp256k1_generator.h
+++ b/include/secp256k1_generator.h
@@ -17,7 +17,7 @@ extern "C" {
 *  If you need to convert to a format suitable for storage, transmission, or
 *  comparison, use secp256k1_generator_serialize and secp256k1_generator_parse.
 */
-typedef struct {
+typedef struct secp256k1_generator {
    unsigned char data[64];
 } secp256k1_generator;

@@ -100,7 +100,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_generator_generate_blin
 *  comparison, use secp256k1_pedersen_commitment_serialize and
 *  secp256k1_pedersen_commitment_parse.
 */
-typedef struct {
+typedef struct secp256k1_pedersen_commitment {
    unsigned char data[64];
 } secp256k1_pedersen_commitment;

--- a/include/secp256k1_musig.h
+++ b/include/secp256k1_musig.h
@@ -8,38 +8,39 @@ extern "C" {
 #endif

 #include <stddef.h>
+#include <stdint.h>

 /** This module implements BIP 327 "MuSig2 for BIP340-compatible
- * Multi-Signatures"
- * (https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki)
- * v1.0.0. You can find an example demonstrating the musig module in
- * examples/musig.c.
+ *  Multi-Signatures"
+ *  (https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki)
+ *  v1.0.0. You can find an example demonstrating the musig module in
+ *  examples/musig.c.
 *
- * The module also supports BIP-341 ("Taproot") public key tweaking and adaptor
- * signatures as described in
- * https://github.com/ElementsProject/scriptless-scripts/pull/24.
+ *  The module also supports BIP 341 ("Taproot") public key tweaking and adaptor signatures.
 *
- * It is recommended to read the documentation in this include file carefully.
- * Further notes on API usage can be found in src/modules/musig/musig.md
+ *  It is recommended to read the documentation in this include file carefully.
+ *  Further notes on API usage can be found in doc/musig.md
 *
- * Since the first version of MuSig is essentially replaced by MuSig2, we use
- * MuSig, musig and MuSig2 synonymously unless noted otherwise.
+ *  Since the first version of MuSig is essentially replaced by MuSig2, we use
+ *  MuSig, musig and MuSig2 synonymously unless noted otherwise.
 */

 /** Opaque data structures
 *
- *  The exact representation of data inside is implementation defined and not
- *  guaranteed to be portable between different platforms or versions. If you
- *  need to convert to a format suitable for storage, transmission, or
- *  comparison, use the corresponding serialization and parsing functions.
+ *  The exact representation of data inside the opaque data structures is
+ *  implementation defined and not guaranteed to be portable between different
+ *  platforms or versions. With the exception of `secp256k1_musig_secnonce`, the
+ *  data structures can be safely copied/moved. If you need to convert to a
+ *  format suitable for storage, transmission, or comparison, use the
+ *  corresponding serialization and parsing functions.
 */

 /** Opaque data structure that caches information about public key aggregation.
 *
- *  Guaranteed to be 197 bytes in size. It can be safely copied/moved. No
- *  serialization and parsing functions (yet).
+ *  Guaranteed to be 197 bytes in size. No serialization and parsing functions
+ *  (yet).
 */
-typedef struct {
+typedef struct secp256k1_musig_keyagg_cache {
    unsigned char data[197];
 } secp256k1_musig_keyagg_cache;

@@ -50,44 +51,40 @@ typedef struct {
 *  WARNING: This structure MUST NOT be copied or read or written to directly. A
 *  signer who is online throughout the whole process and can keep this
 *  structure in memory can use the provided API functions for a safe standard
- *  workflow. See
- *  https://blockstream.com/2019/02/18/musig-a-new-multisignature-standard/ for
- *  more details about the risks associated with serializing or deserializing
- *  this structure.
+ *  workflow.
 *
- *  We repeat, copying this data structure can result in nonce reuse which will
- *  leak the secret signing key.
+ *  Copying this data structure can result in nonce reuse which will leak the
+ *  secret signing key.
 */
-typedef struct {
+typedef struct secp256k1_musig_secnonce {
    unsigned char data[132];
 } secp256k1_musig_secnonce;

 /** Opaque data structure that holds a signer's public nonce.
-*
-*  Guaranteed to be 132 bytes in size. It can be safely copied/moved. Serialized
-*  and parsed with `musig_pubnonce_serialize` and `musig_pubnonce_parse`.
-*/
-typedef struct {
+ *
+ *  Guaranteed to be 132 bytes in size. Serialized and parsed with
+ *  `musig_pubnonce_serialize` and `musig_pubnonce_parse`.
+ */
+typedef struct secp256k1_musig_pubnonce {
    unsigned char data[132];
 } secp256k1_musig_pubnonce;

 /** Opaque data structure that holds an aggregate public nonce.
 *
- *  Guaranteed to be 132 bytes in size. It can be safely copied/moved.
- *  Serialized and parsed with `musig_aggnonce_serialize` and
- *  `musig_aggnonce_parse`.
+ *  Guaranteed to be 132 bytes in size. Serialized and parsed with
+ *  `musig_aggnonce_serialize` and `musig_aggnonce_parse`.
 */
-typedef struct {
+typedef struct secp256k1_musig_aggnonce {
    unsigned char data[132];
 } secp256k1_musig_aggnonce;

 /** Opaque data structure that holds a MuSig session.
 *
 *  This structure is not required to be kept secret for the signing protocol to
- *  be secure. Guaranteed to be 133 bytes in size. It can be safely
- *  copied/moved. No serialization and parsing functions (yet).
+ *  be secure. Guaranteed to be 133 bytes in size. No serialization and parsing
+ *  functions (yet).
 */
-typedef struct {
+typedef struct secp256k1_musig_session {
    unsigned char data[133];
 } secp256k1_musig_session;

@@ -96,7 +93,7 @@ typedef struct {
 *  Guaranteed to be 36 bytes in size. Serialized and parsed with
 *  `musig_partial_sig_serialize` and `musig_partial_sig_parse`.
 */
-typedef struct {
+typedef struct secp256k1_musig_partial_sig {
    unsigned char data[36];
 } secp256k1_musig_partial_sig;

@@ -107,7 +104,7 @@ typedef struct {
 *  Out:   nonce: pointer to a nonce object
 *  In:     in66: pointer to the 66-byte nonce to be parsed
 */
-SECP256K1_API int secp256k1_musig_pubnonce_parse(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubnonce_parse(
    const secp256k1_context *ctx,
    secp256k1_musig_pubnonce *nonce,
    const unsigned char *in66
@@ -115,7 +112,7 @@ SECP256K1_API int secp256k1_musig_pubnonce_parse(

 /** Serialize a signer's public nonce
 *
- *  Returns: 1 when the nonce could be serialized, 0 otherwise
+ *  Returns: 1 always
 *  Args:    ctx: pointer to a context object
 *  Out:   out66: pointer to a 66-byte array to store the serialized nonce
 *  In:    nonce: pointer to the nonce
@@ -133,7 +130,7 @@ SECP256K1_API int secp256k1_musig_pubnonce_serialize(
 *  Out:   nonce: pointer to a nonce object
 *  In:     in66: pointer to the 66-byte nonce to be parsed
 */
-SECP256K1_API int secp256k1_musig_aggnonce_parse(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_aggnonce_parse(
    const secp256k1_context *ctx,
    secp256k1_musig_aggnonce *nonce,
    const unsigned char *in66
@@ -141,7 +138,7 @@ SECP256K1_API int secp256k1_musig_aggnonce_parse(

 /** Serialize an aggregate public nonce
 *
- *  Returns: 1 when the nonce could be serialized, 0 otherwise
+ *  Returns: 1 always
 *  Args:    ctx: pointer to a context object
 *  Out:   out66: pointer to a 66-byte array to store the serialized nonce
 *  In:    nonce: pointer to the nonce
@@ -152,9 +149,22 @@ SECP256K1_API int secp256k1_musig_aggnonce_serialize(
    const secp256k1_musig_aggnonce *nonce
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

+/** Parse a MuSig partial signature.
+ *
+ *  Returns: 1 when the signature could be parsed, 0 otherwise.
+ *  Args:    ctx: pointer to a context object
+ *  Out:     sig: pointer to a signature object
+ *  In:     in32: pointer to the 32-byte signature to be parsed
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_partial_sig_parse(
+    const secp256k1_context *ctx,
+    secp256k1_musig_partial_sig *sig,
+    const unsigned char *in32
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
+
 /** Serialize a MuSig partial signature
 *
- *  Returns: 1 when the signature could be serialized, 0 otherwise
+ *  Returns: 1 always
 *  Args:    ctx: pointer to a context object
 *  Out:   out32: pointer to a 32-byte array to store the serialized signature
 *  In:      sig: pointer to the signature
@@ -165,41 +175,17 @@ SECP256K1_API int secp256k1_musig_partial_sig_serialize(
    const secp256k1_musig_partial_sig *sig
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Parse a MuSig partial signature.
- *
- *  Returns: 1 when the signature could be parsed, 0 otherwise.
- *  Args:    ctx: pointer to a context object
- *  Out:     sig: pointer to a signature object
- *  In:     in32: pointer to the 32-byte signature to be parsed
- *
- *  After the call, sig will always be initialized. If parsing failed or the
- *  encoded numbers are out of range, signature verification with it is
- *  guaranteed to fail for every message and public key.
- */
-SECP256K1_API int secp256k1_musig_partial_sig_parse(
-    const secp256k1_context *ctx,
-    secp256k1_musig_partial_sig *sig,
-    const unsigned char *in32
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
-
 /** Computes an aggregate public key and uses it to initialize a keyagg_cache
 *
 *  Different orders of `pubkeys` result in different `agg_pk`s.
 *
- *  Before aggregating, the pubkeys can be sorted with `secp256k1_pubkey_sort`
+ *  Before aggregating, the pubkeys can be sorted with `secp256k1_ec_pubkey_sort`
 *  which ensures the same `agg_pk` result for the same multiset of pubkeys.
 *  This is useful to do before `pubkey_agg`, such that the order of pubkeys
 *  does not affect the aggregate public key.
 *
 *  Returns: 0 if the arguments are invalid, 1 otherwise
 *  Args:        ctx: pointer to a context object
- *           scratch: should be NULL because it is not yet implemented. If it
- *                    was implemented then the scratch space would be used to
- *                    compute the aggregate pubkey by multiexponentiation.
- *                    Generally, the larger the scratch space, the faster this
- *                    function. However, the returns of providing a larger
- *                    scratch space are diminishing. If NULL, an inefficient
- *                    algorithm is used.
 *  Out:      agg_pk: the MuSig-aggregated x-only public key. If you do not need it,
 *                    this arg can be NULL.
 *      keyagg_cache: if non-NULL, pointer to a musig_keyagg_cache struct that
@@ -210,14 +196,13 @@ SECP256K1_API int secp256k1_musig_partial_sig_parse(
 *                    aggregate public key.
 *         n_pubkeys: length of pubkeys array. Must be greater than 0.
 */
-SECP256K1_API int secp256k1_musig_pubkey_agg(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_agg(
    const secp256k1_context *ctx,
-    secp256k1_scratch_space *scratch,
    secp256k1_xonly_pubkey *agg_pk,
    secp256k1_musig_keyagg_cache *keyagg_cache,
    const secp256k1_pubkey * const *pubkeys,
    size_t n_pubkeys
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(5);
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(4);

 /** Obtain the aggregate public key from a keyagg_cache.
 *
@@ -237,9 +222,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_get(
    const secp256k1_musig_keyagg_cache *keyagg_cache
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Apply plain "EC" tweaking to a public key in a given keyagg_cache by
- *  adding the generator multiplied with `tweak32` to it. This is useful for
- *  deriving child keys from an aggregate public key via BIP32.
+/** Apply plain "EC" tweaking to a public key in a given keyagg_cache by adding
+ *  the generator multiplied with `tweak32` to it. This is useful for deriving
+ *  child keys from an aggregate public key via BIP 32 where `tweak32` is set to
+ *  a hash as defined in BIP 32.
+ *
+ *  Callers are responsible for deriving `tweak32` in a way that does not reduce
+ *  the security of MuSig (for example, by following BIP 32).
 *
 *  The tweaking method is the same as `secp256k1_ec_pubkey_tweak_add`. So after
 *  the following pseudocode buf and buf2 have identical contents (absent
@@ -248,29 +237,27 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_get(
 *  secp256k1_musig_pubkey_agg(..., keyagg_cache, pubkeys, ...)
 *  secp256k1_musig_pubkey_get(..., agg_pk, keyagg_cache)
 *  secp256k1_musig_pubkey_ec_tweak_add(..., output_pk, tweak32, keyagg_cache)
- *  secp256k1_ec_pubkey_serialize(..., buf, output_pk)
+ *  secp256k1_ec_pubkey_serialize(..., buf, ..., output_pk, ...)
 *  secp256k1_ec_pubkey_tweak_add(..., agg_pk, tweak32)
- *  secp256k1_ec_pubkey_serialize(..., buf2, agg_pk)
+ *  secp256k1_ec_pubkey_serialize(..., buf2, ..., agg_pk, ...)
 *
 *  This function is required if you want to _sign_ for a tweaked aggregate key.
- *  On the other hand, if you are only computing a public key, but not intending
- *  to create a signature for it, you can just use
- *  `secp256k1_ec_pubkey_tweak_add`.
+ *  If you are only computing a public key but not intending to create a
+ *  signature for it, use `secp256k1_ec_pubkey_tweak_add` instead.
 *
- *  Returns: 0 if the arguments are invalid or the resulting public key would be
- *           invalid (only when the tweak is the negation of the corresponding
- *           secret key). 1 otherwise.
+ *  Returns: 0 if the arguments are invalid, 1 otherwise
 *  Args:            ctx: pointer to a context object
 *  Out:   output_pubkey: pointer to a public key to store the result. Will be set
 *                        to an invalid value if this function returns 0. If you
 *                        do not need it, this arg can be NULL.
 *  In/Out: keyagg_cache: pointer to a `musig_keyagg_cache` struct initialized by
 *                       `musig_pubkey_agg`
- *  In:          tweak32: pointer to a 32-byte tweak. If the tweak is invalid
- *                        according to `secp256k1_ec_seckey_verify`, this function
- *                        returns 0. For uniformly random 32-byte arrays the
- *                        chance of being invalid is negligible (around 1 in
- *                        2^128).
+ *  In:          tweak32: pointer to a 32-byte tweak. The tweak is valid if it passes
+ *                        `secp256k1_ec_seckey_verify` and is not equal to the
+ *                        secret key corresponding to the public key represented
+ *                        by keyagg_cache or its negation. For uniformly random
+ *                        32-byte arrays the chance of being invalid is
+ *                        negligible (around 1 in 2^128).
 */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_ec_tweak_add(
    const secp256k1_context *ctx,
@@ -281,36 +268,38 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_ec_tweak_a

 /** Apply x-only tweaking to a public key in a given keyagg_cache by adding the
 *  generator multiplied with `tweak32` to it. This is useful for creating
- *  Taproot outputs.
+ *  Taproot outputs where `tweak32` is set to a TapTweak hash as defined in BIP
+ *  341.
+ *
+ *  Callers are responsible for deriving `tweak32` in a way that does not reduce
+ *  the security of MuSig (for example, by following Taproot BIP 341).
 *
 *  The tweaking method is the same as `secp256k1_xonly_pubkey_tweak_add`. So in
 *  the following pseudocode xonly_pubkey_tweak_add_check (absent earlier
 *  failures) returns 1.
 *
 *  secp256k1_musig_pubkey_agg(..., agg_pk, keyagg_cache, pubkeys, ...)
- *  secp256k1_musig_pubkey_xonly_tweak_add(..., output_pk, tweak32, keyagg_cache)
+ *  secp256k1_musig_pubkey_xonly_tweak_add(..., output_pk, keyagg_cache, tweak32)
 *  secp256k1_xonly_pubkey_serialize(..., buf, output_pk)
 *  secp256k1_xonly_pubkey_tweak_add_check(..., buf, ..., agg_pk, tweak32)
 *
 *  This function is required if you want to _sign_ for a tweaked aggregate key.
- *  On the other hand, if you are only computing a public key, but not intending
- *  to create a signature for it, you can just use
- *  `secp256k1_xonly_pubkey_tweak_add`.
+ *  If you are only computing a public key but not intending to create a
+ *  signature for it, use `secp256k1_xonly_pubkey_tweak_add` instead.
 *
- *  Returns: 0 if the arguments are invalid or the resulting public key would be
- *           invalid (only when the tweak is the negation of the corresponding
- *           secret key). 1 otherwise.
+ *  Returns: 0 if the arguments are invalid, 1 otherwise
 *  Args:            ctx: pointer to a context object
 *  Out:   output_pubkey: pointer to a public key to store the result. Will be set
 *                        to an invalid value if this function returns 0. If you
 *                        do not need it, this arg can be NULL.
 *  In/Out: keyagg_cache: pointer to a `musig_keyagg_cache` struct initialized by
 *                       `musig_pubkey_agg`
- *  In:          tweak32: pointer to a 32-byte tweak. If the tweak is invalid
- *                        according to secp256k1_ec_seckey_verify, this function
- *                        returns 0. For uniformly random 32-byte arrays the
- *                        chance of being invalid is negligible (around 1 in
- *                        2^128).
+ *  In:          tweak32: pointer to a 32-byte tweak. The tweak is valid if it passes
+ *                        `secp256k1_ec_seckey_verify` and is not equal to the
+ *                        secret key corresponding to the public key represented
+ *                        by keyagg_cache or its negation. For uniformly random
+ *                        32-byte arrays the chance of being invalid is
+ *                        negligible (around 1 in 2^128).
 */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_xonly_tweak_add(
    const secp256k1_context *ctx,
@@ -327,12 +316,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_xonly_twea
 *  MuSig differs from regular Schnorr signing in that implementers _must_ take
 *  special care to not reuse a nonce. This can be ensured by following these rules:
 *
- *  1. Each call to this function must have a UNIQUE session_id32 that must NOT BE
- *     REUSED in subsequent calls to this function.
- *     If you do not provide a seckey, session_id32 _must_ be UNIFORMLY RANDOM
- *     AND KEPT SECRET (even from other signers). If you do provide a seckey,
- *     session_id32 can instead be a counter (that must never repeat!). However,
- *     it is recommended to always choose session_id32 uniformly at random.
+ *  1. Each call to this function must have a UNIQUE session_secrand32 that must
+ *     NOT BE REUSED in subsequent calls to this function and must be KEPT
+ *     SECRET (even from other signers).
 *  2. If you already know the seckey, message or aggregate public key
 *     cache, they can be optionally provided to derive the nonce and increase
 *     misuse-resistance. The extra_input32 argument can be used to provide
@@ -341,6 +327,10 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_xonly_twea
 *  3. Avoid copying (or serializing) the secnonce. This reduces the possibility
 *     that it is used more than once for signing.
 *
+ *  If you don't have access to good randomness for session_secrand32, but you
+ *  have access to a non-repeating counter, then see
+ *  secp256k1_musig_nonce_gen_counter.
+ *
 *  Remember that nonce reuse will leak the secret key!
 *  Note that using the same seckey for multiple MuSig sessions is fine.
 *
@@ -348,14 +338,19 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_xonly_twea
 *  Args:         ctx: pointer to a context object (not secp256k1_context_static)
 *  Out:     secnonce: pointer to a structure to store the secret nonce
 *           pubnonce: pointer to a structure to store the public nonce
- *  In:  session_id32: a 32-byte session_id32 as explained above. Must be unique to this
- *                     call to secp256k1_musig_nonce_gen and must be uniformly random
- *                     unless you really know what you are doing.
+ *  In/Out:
+ *  session_secrand32: a 32-byte session_secrand32 as explained above. Must be unique to this
+ *                     call to secp256k1_musig_nonce_gen and must be uniformly
+ *                     random. If the function call is successful, the
+ *                     session_secrand32 buffer is invalidated to prevent reuse.
+ *  In:
 *             seckey: the 32-byte secret key that will later be used for signing, if
 *                     already known (can be NULL)
 *             pubkey: public key of the signer creating the nonce. The secnonce
 *                     output of this function cannot be used to sign for any
- *                     other public key.
+ *                     other public key. While the public key should correspond
+ *                     to the provided seckey, a mismatch will not cause the
+ *                     function to return 0.
 *              msg32: the 32-byte message that will later be signed, if already known
 *                     (can be NULL)
 *       keyagg_cache: pointer to the keyagg_cache that was used to create the aggregate
@@ -364,11 +359,11 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_pubkey_xonly_twea
 *      extra_input32: an optional 32-byte array that is input to the nonce
 *                     derivation function (can be NULL)
 */
-SECP256K1_API int secp256k1_musig_nonce_gen(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_nonce_gen(
    const secp256k1_context *ctx,
    secp256k1_musig_secnonce *secnonce,
    secp256k1_musig_pubnonce *pubnonce,
-    const unsigned char *session_id32,
+    unsigned char *session_secrand32,
    const unsigned char *seckey,
    const secp256k1_pubkey *pubkey,
    const unsigned char *msg32,
@@ -376,6 +371,68 @@ SECP256K1_API int secp256k1_musig_nonce_gen(
    const unsigned char *extra_input32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(6);

+
+/** Alternative way to generate a nonce and start a signing session
+ *
+ *  This function outputs a secret nonce that will be required for signing and a
+ *  corresponding public nonce that is intended to be sent to other signers.
+ *
+ *  This function differs from `secp256k1_musig_nonce_gen` by accepting a
+ *  non-repeating counter value instead of a secret random value. This requires
+ *  that a secret key is provided to `secp256k1_musig_nonce_gen_counter`
+ *  (through the keypair argument), as opposed to `secp256k1_musig_nonce_gen`
+ *  where the seckey argument is optional.
+ *
+ *  MuSig differs from regular Schnorr signing in that implementers _must_ take
+ *  special care to not reuse a nonce. This can be ensured by following these rules:
+ *
+ *  1. The nonrepeating_cnt argument must be a counter value that never repeats,
+ *     i.e., you must never call `secp256k1_musig_nonce_gen_counter` twice with
+ *     the same keypair and nonrepeating_cnt value. For example, this implies
+ *     that if the same keypair is used with `secp256k1_musig_nonce_gen_counter`
+ *     on multiple devices, none of the devices should have the same counter
+ *     value as any other device.
+ *  2. If the seckey, message or aggregate public key cache is already available
+ *     at this stage, any of these can be optionally provided, in which case
+ *     they will be used in the derivation of the nonce and increase
+ *     misuse-resistance. The extra_input32 argument can be used to provide
+ *     additional data that does not repeat in normal scenarios, such as the
+ *     current time.
+ *  3. Avoid copying (or serializing) the secnonce. This reduces the possibility
+ *     that it is used more than once for signing.
+ *
+ *  Remember that nonce reuse will leak the secret key!
+ *  Note that using the same keypair for multiple MuSig sessions is fine.
+ *
+ *  Returns: 0 if the arguments are invalid and 1 otherwise
+ *  Args:         ctx: pointer to a context object (not secp256k1_context_static)
+ *  Out:     secnonce: pointer to a structure to store the secret nonce
+ *           pubnonce: pointer to a structure to store the public nonce
+ *  In:
+ *   nonrepeating_cnt: the value of a counter as explained above. Must be
+ *                     unique to this call to secp256k1_musig_nonce_gen.
+ *            keypair: keypair of the signer creating the nonce. The secnonce
+ *                     output of this function cannot be used to sign for any
+ *                     other keypair.
+ *              msg32: the 32-byte message that will later be signed, if already known
+ *                     (can be NULL)
+ *       keyagg_cache: pointer to the keyagg_cache that was used to create the aggregate
+ *                     (and potentially tweaked) public key if already known
+ *                     (can be NULL)
+ *      extra_input32: an optional 32-byte array that is input to the nonce
+ *                     derivation function (can be NULL)
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_nonce_gen_counter(
+    const secp256k1_context *ctx,
+    secp256k1_musig_secnonce *secnonce,
+    secp256k1_musig_pubnonce *pubnonce,
+    uint64_t nonrepeating_cnt,
+    const secp256k1_keypair *keypair,
+    const unsigned char *msg32,
+    const secp256k1_musig_keyagg_cache *keyagg_cache,
+    const unsigned char *extra_input32
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(5);
+
 /** Aggregates the nonces of all signers into a single nonce
 *
 *  This can be done by an untrusted party to reduce the communication
@@ -383,6 +440,9 @@ SECP256K1_API int secp256k1_musig_nonce_gen(
 *  can be one party receiving all nonces, aggregating the nonces with this
 *  function and then sending only the aggregate nonce back to the signers.
 *
+ *  If the aggregator does not compute the aggregate nonce correctly, the final
+ *  signature will be invalid.
+ *
 *  Returns: 0 if the arguments are invalid, 1 otherwise
 *  Args:           ctx: pointer to a context object
 *  Out:       aggnonce: pointer to an aggregate public nonce object for
@@ -394,21 +454,20 @@ SECP256K1_API int secp256k1_musig_nonce_gen(
 */
 SECP256K1_API int secp256k1_musig_nonce_agg(
    const secp256k1_context *ctx,
-    secp256k1_musig_aggnonce  *aggnonce,
+    secp256k1_musig_aggnonce *aggnonce,
    const secp256k1_musig_pubnonce * const *pubnonces,
    size_t n_pubnonces
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

-/** Takes the public nonces of all signers and computes a session that is
- *  required for signing and verification of partial signatures.
+/** Takes the aggregate nonce and creates a session that is required for signing
+ *  and verification of partial signatures.
 *
 *  If the adaptor argument is non-NULL, then the output of
 *  musig_partial_sig_agg will be a pre-signature which is not a valid Schnorr
 *  signature. In order to create a valid signature, the pre-signature and the
 *  secret adaptor must be provided to `musig_adapt`.
 *
- *  Returns: 0 if the arguments are invalid or if some signer sent invalid
- *           pubnonces, 1 otherwise
+ *  Returns: 0 if the arguments are invalid, 1 otherwise
 *  Args:          ctx: pointer to a context object
 *  Out:       session: pointer to a struct to store the session
 *  In:       aggnonce: pointer to an aggregate public nonce object that is the
@@ -423,7 +482,7 @@ SECP256K1_API int secp256k1_musig_nonce_agg(
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_nonce_process(
    const secp256k1_context *ctx,
    secp256k1_musig_session *session,
-    const secp256k1_musig_aggnonce  *aggnonce,
+    const secp256k1_musig_aggnonce *aggnonce,
    const unsigned char *msg32,
    const secp256k1_musig_keyagg_cache *keyagg_cache,
    const secp256k1_pubkey *adaptor
@@ -485,10 +544,11 @@ SECP256K1_API int secp256k1_musig_partial_sign(
 *       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
- *  partial signature does not verify, the full signature will not verify either, so the
- *  problem will be caught. But this function allows determining the specific party
- *  who produced an invalid signature.
+ *  Without adaptor signatures, it is not required to call this function in regular MuSig sessions, because
+ *  if any partial signature does not verify, the final signature will not
+ *  verify either, so the problem will be caught. However, this function
+ *  provides the ability to identify which specific partial signature fails
+ *  verification.
 *
 *  Returns: 0 if the arguments are invalid or the partial signature does not
 *           verify, 1 otherwise
--- a/include/secp256k1_rangeproof.h
+++ b/include/secp256k1_rangeproof.h
@@ -10,6 +10,41 @@ extern "C" {

 #include <stdint.h>

+/** This module implements a variant of Back-Maxwell range proofs as described
+ * in the Confidential Assets paper (https://blockstream.com/bitcoin17-final41.pdf).
+ * The construction is based on Borromean ring signatures.
+ * (https://nt4tn.net/papers/borromean_draft_0.01_34241bb.pdf)
+ *
+ * This implementation differs from the variant in the paper mainly in that it
+ * omits an optimization that saves one scalar per ring. This optimization complicates
+ * the protocol and security analysis, as it requires differentiating cases where
+ * the i-th bit v_i = 0 versus otherwise, and makes calculating response points R_i less
+ * straightforward. The implemented version uses Borromean ring signatures in
+ * an unmodified way.
+ *
+ * Another difference is that the implementation omits the last ring's commitment
+ * from the proof, which is recovered by the verifier by subtracting all other digit
+ * commitments from the total, reducing proof size by one group element.
+ *
+ * Furthermore, in the implementation every hash calculation includes a message
+ * m=SHA256(C||H||header||C_0||...||C_(n-2)||extra_commit), binding the commitment C,
+ * generator H, proof header, the n-1 explicit digit commitments, and any extra data.
+ * This prevents an attack that would compromise non-malleability. In the paper's
+ * version of the protocol, a prover could pick distinct indices i, j and a scalar y,
+ * and modify digit commitments in the original proof by setting C'_i = C_i + yG and
+ * C'_j = C_j - yG, obtaining a different valid proof for the same commitment and
+ * witness.
+ *
+ * In the current implementation, up to 3968 bytes of message data can be
+ * embedded and recovered within maximally-sized proofs. The implemented embedding
+ * method using the forged parts of ring signatures could also be applied to the
+ * construction in the paper, but is not mentioned there. Message embedding is used
+ * in Confidential Assets to transmit values and blinding factors of the corresponding
+ * commitments. This is possible because randomness is generated by seeding HMAC-DRBG
+ * with the shared ECDH key, allowing the receiver to rewind the proof using the same
+ * random values the sender used.
+ */
+
 /** Length of a message that can be embedded into a maximally-sized rangeproof
 *
 * It is not be possible to fit a message of this size into a non-maximally-sized
@@ -90,7 +125,14 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_rangeproof_rewind(
 *          commit: the commitment being proved.
 *          blind:  32-byte blinding factor used by commit. The blinding factor may be all-zeros as long as min_bits is set to 3 or greater.
 *                  This is a side-effect of the underlying crypto, not a deliberate API choice, but it may be useful when balancing CT transactions.
- *          nonce:  32-byte secret nonce used to initialize the proof (value can be reverse-engineered out of the proof if this secret is known.)
+ *          nonce:  32-byte secret nonce used to initialize the proof.
+ *
+ *                  Each call to this function must have a UNIQUE nonce that
+ *                  MUST NOT BE REUSED in subsequent calls. The nonce must be
+ *                  KEPT SECRET except from parties authorized to rewind the
+ *                  proof. Anyone who knows the nonce can recover `value` and
+ *                  `blind` from the proof. Reusing the nonce may expose `blind`
+ *                  even to parties that do not know the nonce.
 *          exp:    Base-10 exponent. Digits below above will be made public, but the proof will be made smaller. Allowed range is -1 to 18.
 *                  (-1 is a special case that makes the value public. 0 is the most private.)
 *          min_bits: Number of bits of the value to keep private. (0 = auto/minimal, - 64).
--- a/include/secp256k1_recovery.h
+++ b/include/secp256k1_recovery.h
@@ -7,7 +7,7 @@
 extern "C" {
 #endif

-/** Opaque data structured that holds a parsed ECDSA signature,
+/** Opaque data structure that holds a parsed ECDSA signature,
 *  supporting pubkey recovery.
 *
 *  The exact representation of data inside is implementation defined and not
@@ -21,7 +21,7 @@ extern "C" {
 *  recoverability) will have identical representation, so they can be
 *  memcmp'ed.
 */
-typedef struct {
+typedef struct secp256k1_ecdsa_recoverable_signature {
    unsigned char data[65];
 } secp256k1_ecdsa_recoverable_signature;

@@ -73,7 +73,7 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact(
 *  Returns: 1: signature created
 *           0: the nonce generation function failed, or the secret key was invalid.
 *  Args:    ctx:       pointer to a context object (not secp256k1_context_static).
- *  Out:     sig:       pointer to an array where the signature will be placed.
+ *  Out:     sig:       pointer to a signature object.
 *  In:      msghash32: the 32-byte message hash being signed.
 *           seckey:    pointer to a 32-byte secret key.
 *           noncefp:   pointer to a nonce generation function. If NULL,
@@ -92,7 +92,17 @@ SECP256K1_API int secp256k1_ecdsa_sign_recoverable(

 /** Recover an ECDSA public key from a signature.
 *
- *  Returns: 1: public key successfully recovered (which guarantees a correct signature).
+ *  Successful public key recovery guarantees that the signature, after normalization,
+ *  passes `secp256k1_ecdsa_verify`. Thus, explicit verification is not necessary.
+ *
+ *  However, a recoverable signature that successfully passes `secp256k1_ecdsa_recover`,
+ *  when converted to a non-recoverable signature (using
+ *  `secp256k1_ecdsa_recoverable_signature_convert`), is not guaranteed to be
+ *  normalized and thus not guaranteed to pass `secp256k1_ecdsa_verify`. If a
+ *  normalized signature is required, call `secp256k1_ecdsa_signature_normalize`
+ *  after `secp256k1_ecdsa_recoverable_signature_convert`.
+ *
+ *  Returns: 1: public key successfully recovered
 *           0: otherwise.
 *  Args:    ctx:       pointer to a context object.
 *  Out:     pubkey:    pointer to the recovered public key.
--- a/include/secp256k1_schnorrsig.h
+++ b/include/secp256k1_schnorrsig.h
@@ -79,7 +79,7 @@ SECP256K1_API const secp256k1_nonce_function_hardened secp256k1_nonce_function_b
 *             secp256k1_nonce_function_bip340 is used, then ndata must be a
 *             pointer to 32-byte auxiliary randomness as per BIP-340.
 */
-typedef struct {
+typedef struct secp256k1_schnorrsig_extraparams {
    unsigned char magic[4];
    secp256k1_nonce_function_hardened noncefp;
    void *ndata;
--- a/include/secp256k1_surjectionproof.h
+++ b/include/secp256k1_surjectionproof.h
@@ -39,7 +39,7 @@ extern "C" {
 *  The representation is exposed to allow creation of these objects on the
 *  stack; please *do not* use these internals directly.
 */
-typedef struct {
+typedef struct secp256k1_surjectionproof {
 #ifdef VERIFY
    /** Mark whether this proof has gone through `secp256k1_surjectionproof_initialize` */
    int initialized;
@@ -100,7 +100,7 @@ SECP256K1_API int secp256k1_surjectionproof_serialize(
 * data the API user wants to use as an asset tag. Its contents have no
 * semantic meaning to libsecp whatsoever.
 */
-typedef struct {
+typedef struct secp256k1_fixed_asset_tag {
    unsigned char data[32];
 } secp256k1_fixed_asset_tag;

--- a/include/secp256k1_whitelist.h
+++ b/include/secp256k1_whitelist.h
@@ -31,7 +31,7 @@ extern "C" {
 *  stack; please *do not* use these internals directly. To learn the number
 *  of keys for a signature, use `secp256k1_whitelist_signature_n_keys`.
 */
-typedef struct {
+typedef struct secp256k1_whitelist_signature {
    size_t n_keys;
    /* e0, scalars */
    unsigned char data[32 * (1 + SECP256K1_WHITELIST_MAX_N_KEYS)];
@@ -68,6 +68,10 @@ SECP256K1_API int secp256k1_whitelist_signature_parse(
 *
 *  Returns: the number of keys for the given signature
 *  In: sig: pointer to a signature object
+ *
+ *  This count is a property of the signature only. It might not match the
+ *  number of public keys the caller has, and the caller should not truncate
+ *  their key set to match it.
 */
 SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
    const secp256k1_whitelist_signature *sig
@@ -109,6 +113,8 @@ SECP256K1_API int secp256k1_whitelist_signature_serialize(
 *     online_i + H(offline_i + whitelist)(offline_i + whitelist)
 * for each public key pair (offline_i, offline_i). Here H means sha256 of the
 * compressed serialization of the key.
+ *
+ * See secp256k1_whitelist_verify for the rationale on the degenerate destination W = -P_i.
 */
 SECP256K1_API int secp256k1_whitelist_sign(
  const secp256k1_context *ctx,
@@ -131,6 +137,13 @@ SECP256K1_API int secp256k1_whitelist_sign(
 *         offline_pubkeys: list of all offline pubkeys
 *         n_keys: the number of entries in each of the above two arrays
 *         sub_pubkey: the key to be whitelisted
+ *
+ *  When the destination W equals -P_i for a whitelisted offline key, the tweak
+ *  degenerates and the ring key collapses to K_i = Q_i, so the online key alone
+ *  produces a valid proof for that destination. This is accepted deliberately:
+ *  the output is spendable only by the holder of p_i (the discrete log of -P_i
+ *  is -p_i), i.e. the offline half of the same whitelist entry, so no funds can
+ *  be diverted.
 */
 SECP256K1_API int secp256k1_whitelist_verify(
  const secp256k1_context *ctx,