frost: close remaining gaps against the BIP 445 reference

Four small divergences from the reference implementation and its API
contract, none of which changes any signature: the differential harness
(240 signing + 120 deterministic-signing cases against the Python
reference) produces byte-identical output before and after.

Length prefixes that do not fit
-------------------------------

secp256k1_frost_sha256_write_prefixed asserted, via VERIFY_CHECK, that
the length fits into its prefix. VERIFY_CHECK compiles away in release
builds, so a length that does not fit was silently truncated modulo
2^(8*prefix_size) instead of being rejected, yielding a nonce that does
not follow the spec. The reference raises OverflowError instead.

Only the 4-byte extra_in prefix of nonce_hash is affected, and only where
size_t is wider than 32 bits, so this needs an extra_in of 4 GiB to
trigger. It is nevertheless a silent deviation, so write_prefixed now
returns 0 without writing anything, and the failure is propagated:
secp256k1_frost_nonce_function and secp256k1_frost_det_nonce_function
return 0, and secp256k1_frost_nonce_gen returns 0 after wiping
session_secrand32 and the nonces. Checking the shifted-out bits (which
the loop already computes) rather than comparing extra_in_len against a
32-bit bound avoids a comparison that is always true on 32-bit platforms.
The bound is now documented on the extra_in_len parameter.

Identifiers equal to UINT32_MAX
-------------------------------

BIP 445 derive_interpolating_value accepts every identifier in
0 <= id < 2^32, but secp256k1_frost_ids_are_valid rejected UINT32_MAX
because the mapping to the polynomial x-coordinate, id + 1, overflows in
uint32_t arithmetic. The +1 is now added in scalar arithmetic, where it
cannot overflow, and the identifier restriction is gone. The denominator
never needed the +1 at all, since

    x_j - x_i = (id_j + 1) - (my_id + 1) = id_j - my_id

so it is computed directly from the identifiers.

This was unreachable through the public API -- validate_session_params
already bounds identifiers by n_participants, which is at most
SECP256K1_FROST_MAX_PARTICIPANTS = 128 -- but it made an internal helper
diverge from the algorithm it implements. frost_large_id_test covers it
by reconstructing the constant term of a random degree-2 polynomial from
shares held by identifiers 0, UINT32_MAX - 1 and UINT32_MAX.

Zero-length messages
--------------------

secp256k1_frost_session_init and secp256k1_frost_deterministic_sign
required a non-NULL msg, so an empty message -- which the reference
represents as the byte string b"" -- could only be passed as a pointer
that is never dereferenced. Both now accept NULL when msglen is 0,
matching secp256k1_schnorrsig_sign_custom and the msg parameter of
secp256k1_frost_nonce_gen. secp256k1_sha256_write guards both of its
memcpy calls on a non-zero length, so it is never reached with a NULL
pointer.

NonceGen keeps its distinction between a NULL msg and a zero-length msg:
there the BIP really does distinguish msg = None (hashed as the single
byte 0x00) from msg = b"" (hashed as 0x01 followed by an eight-byte zero
length), and the API expresses that as NULL versus non-NULL.

frost_empty_msg_test runs a signing round over a zero-length message
passed both ways and checks that the two session objects are identical.
The two API tests that relied on a NULL msg always being rejected now
pass an explicit non-zero msglen; previously they passed a random msglen
that could be 0.

Header documentation
--------------------

The parameter tables of eleven doc comments had names that did not line
up with their block's continuation column. All parameter tables are now
aligned consistently, with wrapped text two columns past the colon.

Verification
------------

  - gcc and clang, -std=c89 -pedantic-errors -Werror, with and without
    -DVERIFY: clean
  - tests (multiple seeds), noverify_tests and frost_example: pass
  - ctime_tests under MemorySanitizer: exits 0 with halt_on_error=1
  - vectors.h still reproduces exactly from the spec's JSON vectors
  - 240 signing + 120 deterministic-signing differential cases against
    the BIP 445 Python reference: byte-identical to the previous commit

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

include/secp256k1_frost.h

@@ -225,15 +225,15 @@ SECP256K1_API int secp256k1_frost_partial_sig_serialize(
  *  Out:     secshares32: pointer to an n_participants*32-byte array to store
  *                        the secret shares; participant with id i receives
  *                        secshares32[i*32..(i+1)*32]
- *              thresh_pk: pointer to a pubkey object to store the threshold
+ *             thresh_pk: pointer to a pubkey object to store the threshold
  *                        public key (full point, parity is meaningful)
- *              pubshares: pointer to an array of n_participants pubkey
+ *             pubshares: pointer to an array of n_participants pubkey
  *                        objects to store the public shares; entry i belongs
  *                        to the participant with id i
- *  In:    n_participants: total number of participants n. Must be between 1
- *                         and SECP256K1_FROST_MAX_PARTICIPANTS.
- *               threshold: threshold t. Must be between 1 and n_participants.
- *     threshold_seckey32: pointer to the 32-byte threshold secret key
+ *  In:   n_participants: total number of participants n. Must be between 1
+ *                        and SECP256K1_FROST_MAX_PARTICIPANTS.
+ *             threshold: threshold t. Must be between 1 and n_participants.
+ *    threshold_seckey32: pointer to the 32-byte threshold secret key
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_trusted_dealer_keygen(
     const secp256k1_context *ctx,
@@ -254,12 +254,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_trusted_dealer_ke
  *  produced it.
  *
  *  Returns: 1 if the key material is valid and consistent, 0 otherwise
- *  Args:            ctx: pointer to a context object
+ *  Args:             ctx: pointer to a context object
  *  In:         thresh_pk: pointer to the threshold public key
  *              pubshares: array of n_participants pubkeys; entry i is the
  *                         public share of the participant with id i
  *         n_participants: total number of participants n
- *               threshold: threshold t
+ *              threshold: threshold t
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_threshold_info_validate(
     const secp256k1_context *ctx,
@@ -275,8 +275,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_threshold_info_va
  *  `frost_session_init`, even if no tweaks are applied.
  *
  *  Returns: 0 if the arguments are invalid, 1 otherwise
- *  Args:    ctx: pointer to a context object
- *  Out:   cache: pointer to the tweak cache to initialize
+ *  Args:     ctx: pointer to a context object
+ *  Out:    cache: pointer to the tweak cache to initialize
  *  In: thresh_pk: pointer to the (untweaked) threshold public key
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_tweak_cache_init(
@@ -294,7 +294,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_tweak_cache_init(
  *  Args:       ctx: pointer to a context object
  *  Out: tweaked_pk: pointer to an xonly_pubkey object to store the tweaked
  *                   threshold public key
- *  In:      cache: pointer to the tweak cache
+ *  In:       cache: pointer to the tweak cache
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_tweaked_pubkey_get(
     const secp256k1_context *ctx,
@@ -314,7 +314,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_tweaked_pubkey_ge
  *  Out: tweaked_pk: pointer to an xonly_pubkey object to store the tweaked
  *                   threshold public key. If you do not need it, this arg can
  *                   be NULL.
- *  In:      cache: pointer to the tweak cache
+ *  In:       cache: pointer to the tweak cache
  *          tweak32: pointer to the 32-byte tweak
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_pubkey_xonly_tweak_add(
@@ -336,7 +336,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_pubkey_xonly_twea
  *  Out: tweaked_pk: pointer to an xonly_pubkey object to store the tweaked
  *                   threshold public key. If you do not need it, this arg can
  *                   be NULL.
- *  In:      cache: pointer to the tweak cache
+ *  In:       cache: pointer to the tweak cache
  *          tweak32: pointer to the 32-byte tweak
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_pubkey_ec_tweak_add(
@@ -368,17 +368,18 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_pubkey_ec_tweak_a
  *                             randomness is masked with the share, see
  *                             BIP 445 "Modifications to Nonce Generation").
  *                   pubshare: pointer to the signer's public share, or NULL
- *             thresh_pk32: pointer to the 32-byte x-only encoding of the
+ *                thresh_pk32: pointer to the 32-byte x-only encoding of the
  *                             threshold public key the signature will verify
  *                             against (i.e. after applying tweaks, if any),
  *                             or NULL
  *                        msg: pointer to the message to be signed, or NULL if
  *                             the message is not known yet
  *                     msglen: length of msg. Must be 0 if msg is NULL.
- *                  extra_in: pointer to additional data to bind into the
+ *                   extra_in: pointer to additional data to bind into the
  *                             nonce derivation, or NULL
- *              extra_in_len: length of extra_in. Must be 0 if extra_in is
- *                             NULL.
+ *               extra_in_len: length of extra_in. Must be 0 if extra_in is
+ *                             NULL and at most 2^32 - 1 (the nonce hash
+ *                             commits to it in a 4-byte length prefix).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_nonce_gen(
     const secp256k1_context *ctx,
@@ -404,12 +405,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_nonce_gen(
  *           malformed, 1 otherwise
  *  Args:           ctx: pointer to a context object
  *  Out:       aggnonce: pointer to an aggnonce object
- *         error_index: if non-NULL, set to the index of the offending
- *                      pubnonce on failure
+ *          error_index: if non-NULL, set to the index of the offending
+ *                       pubnonce on failure
  *  In:       pubnonces: input array of pointers to pubnonces. The pubnonce at
  *                       index i must belong to the signer with ids[i] passed
  *                       to `frost_session_init`.
- *           n_pubnonces: length of the pubnonces array. Must be greater than
+ *          n_pubnonces: length of the pubnonces array. Must be greater than
  *                       0.
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_nonce_agg(
@@ -430,24 +431,25 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_nonce_agg(
  *
  *  Returns: 0 if the arguments are invalid (including inconsistent key
  *           material or duplicate signer ids), 1 otherwise
- *  Args:            ctx: pointer to a context object
- *  Out:        session: pointer to a session object
- *  In:        aggnonce: pointer to the aggregate nonce from
- *                       `frost_nonce_agg`
+ *  Args:             ctx: pointer to a context object
+ *  Out:          session: pointer to a session object
+ *  In:          aggnonce: pointer to the aggregate nonce from
+ *                         `frost_nonce_agg`
  *                    ids: array of the u signer identifiers. Every id must
  *                         be unique and smaller than n_participants.
  *              pubshares: array of u pubkeys with the public shares of the
  *                         signers (entry i belongs to ids[i]), or NULL if the
  *                         pubshares are unknown. If provided, they are
  *                         validated against the threshold public key.
- *             n_signers: number of signers u. Must be between threshold and
+ *              n_signers: number of signers u. Must be between threshold and
  *                         n_participants.
  *         n_participants: total number of participants n. Must be at most
  *                         SECP256K1_FROST_MAX_PARTICIPANTS.
  *              threshold: threshold t. Must be between 1 and n_participants.
- *             tweak_cache: pointer to the tweak cache holding the threshold
+ *            tweak_cache: pointer to the tweak cache holding the threshold
  *                         public key and all tweaks applied to it
- *                    msg: pointer to the message to sign
+ *                    msg: pointer to the message to sign, or NULL if
+ *                         msglen is 0
  *                 msglen: length of msg
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_session_init(
@@ -477,18 +479,18 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_session_init(
  *  here.
  *
  *  Returns: 0 if the arguments are invalid or signing fails, 1 otherwise
- *  Args:          ctx: pointer to a context object
- *  Out:   partial_sig: pointer to a partial_sig object
- *  In:       secnonce: pointer to the signer's secnonce from
- *                      `frost_nonce_gen`
+ *  Args:             ctx: pointer to a context object
+ *  Out:      partial_sig: pointer to a partial_sig object
+ *  In:          secnonce: pointer to the signer's secnonce from
+ *                         `frost_nonce_gen`
  *             secshare32: pointer to the signer's 32-byte secret share
- *               session: pointer to the session
+ *                session: pointer to the session
  *                    ids: array of the u signer identifiers (identical to
  *                         session_init)
  *              pubshares: array of u pubkeys with the signers' public shares
  *                         (identical to session_init), or NULL
- *             n_signers: number of signers u
- *                 my_id: this signer's identifier
+ *              n_signers: number of signers u
+ *                  my_id: this signer's identifier
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_sign(
     const secp256k1_context *ctx,
@@ -521,22 +523,23 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_sign(
  *  Returns: 0 if the arguments are invalid or signing fails, 1 otherwise
  *  Args:             ctx: pointer to a context object
  *  Out:      partial_sig: pointer to a partial_sig object
- *                pubnonce: pointer to a pubnonce object holding this signer's
+ *               pubnonce: pointer to a pubnonce object holding this signer's
  *                         public nonce, to be sent to the coordinator
  *  In:        secshare32: pointer to the signer's 32-byte secret share
- *                   my_id: this signer's identifier
- *           aggothernonce: pointer to the aggregate of the other signers'
+ *                  my_id: this signer's identifier
+ *          aggothernonce: pointer to the aggregate of the other signers'
  *                         public nonces, or NULL for a sole signer
- *                     ids: array of the u signer identifiers
- *               pubshares: array of u pubkeys with the signers' public
+ *                    ids: array of the u signer identifiers
+ *              pubshares: array of u pubkeys with the signers' public
  *                         shares, or NULL
- *               n_signers: number of signers u
- *           n_participants: total number of participants n
- *                threshold: threshold t
- *             tweak_cache: pointer to the tweak cache
- *                     msg: pointer to the message to sign
- *                  msglen: length of msg
- *              aux_rand32: pointer to 32 bytes of auxiliary randomness mixed
+ *              n_signers: number of signers u
+ *         n_participants: total number of participants n
+ *              threshold: threshold t
+ *            tweak_cache: pointer to the tweak cache
+ *                    msg: pointer to the message to sign, or NULL if
+ *                         msglen is 0
+ *                 msglen: length of msg
+ *             aux_rand32: pointer to 32 bytes of auxiliary randomness mixed
  *                         into the nonce derivation, or NULL
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_deterministic_sign(
@@ -565,15 +568,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_deterministic_sig
  *  verified.
  *
  *  Returns: 1 if the partial signature is valid, 0 otherwise
- *  Args:          ctx: pointer to a context object
- *  In:    partial_sig: pointer to the partial signature
+ *  Args:             ctx: pointer to a context object
+ *  In:       partial_sig: pointer to the partial signature
  *               pubnonce: pointer to the signer's public nonce
  *               pubshare: pointer to the signer's public share
- *               session: pointer to the session
+ *                session: pointer to the session
  *                    ids: array of the u signer identifiers (identical to
  *                         session_init)
- *             n_signers: number of signers u
- *          signer_index: index of the signer in the ids array
+ *              n_signers: number of signers u
+ *           signer_index: index of the signer in the ids array
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_partial_sig_verify(
     const secp256k1_context *ctx,
@@ -599,11 +602,11 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_partial_sig_verif
  *  Args:           ctx: pointer to a context object
  *  Out:          sig64: pointer to a 64-byte array to store the final
  *                       BIP340 signature
- *         error_index: if non-NULL, set to the index of the offending
- *                      partial signature on failure
+ *          error_index: if non-NULL, set to the index of the offending
+ *                       partial signature on failure
  *  In:         session: pointer to the session
  *         partial_sigs: input array of pointers to partial signatures
- *             n_sigs: length of the partial_sigs array. Must equal
+ *               n_sigs: length of the partial_sigs array. Must equal
  *                       n_signers from `frost_session_init`.
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_frost_partial_sig_agg(