frost/secp256k1-zkp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

include: make docs more consistent

Browse Source 
Like upstream https://github.com/bitcoin-core/secp256k1/pull/1476 .
This commit is contained in:
Tim Ruffing 2024-01-18 11:37:18 +01:00
parent e626f00d1e
commit c29f28e638
5 changed files with 49 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
include/secp256k1_ecdsa_adaptor.h
View File

@ -71,7 +71,7 @@ SECP256K1_API const secp256k1_nonce_function_hardened_ecdsa_adaptor secp256k1_no
* this file and applied the suggested countermeasures. * this file and applied the suggested countermeasures.
* *
* Returns: 1 on success, 0 on failure * Returns: 1 on success, 0 on failure
* Args: ctx: a secp256k1 context object (not secp256k1_context_static) * Args: ctx: pointer to a context object (not secp256k1_context_static)
* Out: adaptor_sig162: pointer to 162 byte to store the returned signature * Out: adaptor_sig162: pointer to 162 byte to store the returned signature
* In: seckey32: pointer to 32 byte secret key that will be used for * In: seckey32: pointer to 32 byte secret key that will be used for
* signing * signing
@ -101,7 +101,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_encrypt(
* and the completed ECDSA signature. * and the completed ECDSA signature.
* *
* Returns: 1 on success, 0 on failure * Returns: 1 on success, 0 on failure
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* In: adaptor_sig162: pointer to 162-byte signature to verify * In: adaptor_sig162: pointer to 162-byte signature to verify
* pubkey: pointer to the public key corresponding to the secret key * pubkey: pointer to the public key corresponding to the secret key
* used for signing * used for signing
@ -121,7 +121,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_verify(
* Derives an ECDSA signature from an adaptor signature and an adaptor decryption key. * Derives an ECDSA signature from an adaptor signature and an adaptor decryption key.
* *
* Returns: 1 on success, 0 on failure * Returns: 1 on success, 0 on failure
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: sig: pointer to the ECDSA signature to create * Out: sig: pointer to the ECDSA signature to create
* In: deckey32: pointer to 32-byte decryption secret key for the adaptor * In: deckey32: pointer to 32-byte decryption secret key for the adaptor
* encryption public key * encryption public key
@ -140,7 +140,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_decrypt(
* signature. * signature.
* *
* Returns: 1 on success, 0 on failure * Returns: 1 on success, 0 on failure
* Args: ctx: a secp256k1 context object (not secp256k1_context_static) * Args: ctx: pointer to a context object (not secp256k1_context_static)
* Out: deckey32: pointer to 32-byte adaptor decryption key for the adaptor * Out: deckey32: pointer to 32-byte adaptor decryption key for the adaptor
* encryption public key * encryption public key
* In: sig: pointer to ECDSA signature to recover the adaptor decryption * In: sig: pointer to ECDSA signature to recover the adaptor decryption

10
include/secp256k1_ecdsa_s2c.h
View File

@ -33,7 +33,7 @@ typedef struct {
* *
* Returns: 1 if the opening could be parsed * Returns: 1 if the opening could be parsed
* 0 if the opening could not be parsed * 0 if the opening could not be parsed
* Args: ctx: a secp256k1 context object. * Args: ctx: pointer to a context object
* Out: opening: pointer to an opening object. If 1 is returned, it is set to a * Out: opening: pointer to an opening object. If 1 is returned, it is set to a
* parsed version of input. If not, its value is unspecified. * parsed version of input. If not, its value is unspecified.
* In: input33: pointer to 33-byte array with a serialized opening * In: input33: pointer to 33-byte array with a serialized opening
@ -49,9 +49,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_parse
* *
* Returns: 1 if the opening was successfully serialized. * Returns: 1 if the opening was successfully serialized.
* 0 if the opening could not be serialized * 0 if the opening could not be serialized
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: output33: pointer to a 33-byte array to place the serialized opening in * Out: output33: pointer to a 33-byte array to place the serialized opening in
* In: opening: a pointer to an initialized `secp256k1_ecdsa_s2c_opening` * In: opening: pointer to an initialized `secp256k1_ecdsa_s2c_opening`
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_serialize( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_s2c_opening_serialize(
const secp256k1_context *ctx, const secp256k1_context *ctx,
@ -84,7 +84,7 @@ SECP256K1_API int secp256k1_ecdsa_s2c_sign(
* Returns: 1: the signature contains a commitment to data32 (though it does * Returns: 1: the signature contains a commitment to data32 (though it does
* not necessarily need to be a valid siganture!) * not necessarily need to be a valid siganture!)
* 0: incorrect opening * 0: incorrect opening
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* In: sig: the signature containing the sign-to-contract commitment (cannot be NULL) * In: sig: the signature containing the sign-to-contract commitment (cannot be NULL)
* data32: the 32-byte data that was committed to (cannot be NULL) * data32: the 32-byte data that was committed to (cannot be NULL)
* opening: pointer to the opening created during signing (cannot be NULL) * opening: pointer to the opening created during signing (cannot be NULL)
@ -211,7 +211,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_anti_exfil_sign(
* *
* Returns: 1: the signature is valid and contains a commitment to host_data32 * Returns: 1: the signature is valid and contains a commitment to host_data32
* 0: incorrect opening * 0: incorrect opening
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* In: sig: the signature produced by the signer (cannot be NULL) * In: sig: the signature produced by the signer (cannot be NULL)
* msghash32: the 32-byte message hash being verified (cannot be NULL) * msghash32: the 32-byte message hash being verified (cannot be NULL)
* pubkey: pointer to the signer's public key (cannot be NULL) * pubkey: pointer to the signer's public key (cannot be NULL)

24
include/secp256k1_generator.h
View File

@ -29,7 +29,7 @@ SECP256K1_API const secp256k1_generator *secp256k1_generator_h;
/** Parse a 33-byte generator byte sequence into a generator object. /** Parse a 33-byte generator byte sequence into a generator object.
* *
* Returns: 1 if input contains a valid generator. * Returns: 1 if input contains a valid generator.
* Args: ctx: a secp256k1 context object. * Args: ctx: pointer to a context object
* Out: gen: pointer to the output generator object * Out: gen: pointer to the output generator object
* In: input: pointer to a 33-byte serialized generator * In: input: pointer to a 33-byte serialized generator
*/ */
@ -42,9 +42,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_generator_parse(
/** Serialize a 33-byte generator into a serialized byte sequence. /** Serialize a 33-byte generator into a serialized byte sequence.
* *
* Returns: 1 always. * Returns: 1 always.
* Args: ctx: a secp256k1 context object. * Args: ctx: pointer to a context object
* Out: output: a pointer to a 33-byte byte array * Out: output: pointer to a 33-byte byte array
* In: gen: a pointer to a generator * In: gen: pointer to a generator object
*/ */
SECP256K1_API int secp256k1_generator_serialize( SECP256K1_API int secp256k1_generator_serialize(
const secp256k1_context *ctx, const secp256k1_context *ctx,
@ -56,8 +56,8 @@ SECP256K1_API int secp256k1_generator_serialize(
* *
* Returns: 0 in the highly unlikely case the seed is not acceptable, * Returns: 0 in the highly unlikely case the seed is not acceptable,
* 1 otherwise. * 1 otherwise.
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: gen: a generator object * Out: gen: pointer to a the new generator object
* In: seed32: a 32-byte seed * In: seed32: a 32-byte seed
* *
* If successful a valid generator will be placed in gen. The produced * If successful a valid generator will be placed in gen. The produced
@ -75,8 +75,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_generator_generate(
* *
* Returns: 0 in the highly unlikely case the seed is not acceptable or when * Returns: 0 in the highly unlikely case the seed is not acceptable or when
* blind is out of range. 1 otherwise. * blind is out of range. 1 otherwise.
* Args: ctx: a secp256k1 context object (not secp256k1_context_static) * Args: ctx: pointer to a context object (not secp256k1_context_static)
* Out: gen: a generator object * Out: gen: pointer to a generator object
* In: seed32: a 32-byte seed * In: seed32: a 32-byte seed
* blind32: a 32-byte secret value to blind the generator with. * blind32: a 32-byte secret value to blind the generator with.
* *
@ -107,7 +107,7 @@ typedef struct {
/** Parse a 33-byte commitment into a commitment object. /** Parse a 33-byte commitment into a commitment object.
* *
* Returns: 1 if input contains a valid commitment. * Returns: 1 if input contains a valid commitment.
* Args: ctx: a secp256k1 context object. * Args: ctx: pointer to a context object
* Out: commit: pointer to the output commitment object * Out: commit: pointer to the output commitment object
* In: input: pointer to a 33-byte serialized commitment key * In: input: pointer to a 33-byte serialized commitment key
*/ */
@ -120,9 +120,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_pedersen_commitment_par
/** Serialize a commitment object into a serialized byte sequence. /** Serialize a commitment object into a serialized byte sequence.
* *
* Returns: 1 always. * Returns: 1 always.
* Args: ctx: a secp256k1 context object. * Args: ctx: pointer to a context object
* Out: output: a pointer to a 33-byte byte array * Out: output: pointer to a 33-byte byte array
* In: commit: a pointer to a secp256k1_pedersen_commitment containing an * In: commit: pointer to a secp256k1_pedersen_commitment containing an
* initialized commitment * initialized commitment
*/ */
SECP256K1_API int secp256k1_pedersen_commitment_serialize( SECP256K1_API int secp256k1_pedersen_commitment_serialize(

33
include/secp256k1_surjectionproof.h
View File

@ -56,9 +56,9 @@ typedef struct {
/** Parse a surjection proof /** Parse a surjection proof
* *
* Returns: 1 when the proof could be parsed, 0 otherwise. * Returns: 1 when the proof could be parsed, 0 otherwise.
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: proof: a pointer to a proof object * Out: proof: pointer to a proof object
* In: input: a pointer to the array to parse * In: input: pointer to the array to parse
* inputlen: length of the array pointed to by input * inputlen: length of the array pointed to by input
* *
* The proof must consist of: * The proof must consist of:
@ -79,12 +79,11 @@ SECP256K1_API int secp256k1_surjectionproof_parse(
/** Serialize a surjection proof /** Serialize a surjection proof
* *
* Returns: 1 if enough space was available to serialize, 0 otherwise * Returns: 1 if enough space was available to serialize, 0 otherwise
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: output: a pointer to an array to store the serialization * Out: output: pointer to an array to store the serialization
* In/Out: outputlen: a pointer to an integer which is initially set to the * In/Out: outputlen: pointer to an integer which is initially set to the size
* size of output, and is overwritten with the written * of output, and is overwritten with the written size.
* size. * In: proof: pointer to an initialized proof object
* In: proof: a pointer to an initialized proof object
* *
* See secp256k1_surjectionproof_parse for details about the encoding. * See secp256k1_surjectionproof_parse for details about the encoding.
*/ */
@ -109,7 +108,7 @@ typedef struct {
* *
* Returns: the number of inputs for the given proof * Returns: the number of inputs for the given proof
* In: ctx: pointer to a context object * In: ctx: pointer to a context object
* proof: a pointer to a proof object * proof: pointer to a proof object
*/ */
SECP256K1_API size_t secp256k1_surjectionproof_n_total_inputs( SECP256K1_API size_t secp256k1_surjectionproof_n_total_inputs(
const secp256k1_context *ctx, const secp256k1_context *ctx,
@ -120,7 +119,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_n_total_inputs(
* *
* Returns: the number of inputs for the given proof * Returns: the number of inputs for the given proof
* In: ctx: pointer to a context object * In: ctx: pointer to a context object
* proof: a pointer to a proof object * proof: pointer to a proof object
*/ */
SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs( SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs(
const secp256k1_context *ctx, const secp256k1_context *ctx,
@ -131,7 +130,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs(
* *
* Returns: the total size * Returns: the total size
* In: ctx: pointer to a context object * In: ctx: pointer to a context object
* proof: a pointer to a proof object * proof: pointer to a proof object
*/ */
SECP256K1_API size_t secp256k1_surjectionproof_serialized_size( SECP256K1_API size_t secp256k1_surjectionproof_serialized_size(
const secp256k1_context *ctx, const secp256k1_context *ctx,
@ -156,7 +155,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_serialized_size(
* limited to 256 the probability of giving up is smaller than * limited to 256 the probability of giving up is smaller than
* (255/256)^(n_input_tags_to_use*max_n_iterations). * (255/256)^(n_input_tags_to_use*max_n_iterations).
* *
* random_seed32: a random seed to be used for input selection * random_seed32: random seed to be used for input selection
* Out: proof: The proof whose bitvector will be initialized. In case of failure, * Out: proof: The proof whose bitvector will be initialized. In case of failure,
* the state of the proof is undefined. * the state of the proof is undefined.
* input_index: The index of the actual input that is secretly mapped to the output * input_index: The index of the actual input that is secretly mapped to the output
@ -179,8 +178,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_surjectionproof_initial
* n: inputs were selected after n iterations of random selection * n: inputs were selected after n iterations of random selection
* *
* In: ctx: pointer to a context object * In: ctx: pointer to a context object
* proof_out_p: a pointer to a pointer to `secp256k1_surjectionproof*`. * proof_out_p: pointer to a pointer to `secp256k1_surjectionproof*`.
* the newly-allocated struct pointer will be saved here. * The newly-allocated struct pointer will be saved here.
* fixed_input_tags: fixed input tags `A_i` for all inputs. (If the fixed tag is not known, * fixed_input_tags: fixed input tags `A_i` for all inputs. (If the fixed tag is not known,
* e.g. in a coinjoin with others' inputs, an ephemeral tag can be given; * e.g. in a coinjoin with others' inputs, an ephemeral tag can be given;
* this won't match the output tag but might be used in the anonymity set.) * this won't match the output tag but might be used in the anonymity set.)
@ -192,8 +191,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_surjectionproof_initial
* limited to 256 the probability of giving up is smaller than * limited to 256 the probability of giving up is smaller than
* (255/256)^(n_input_tags_to_use*max_n_iterations). * (255/256)^(n_input_tags_to_use*max_n_iterations).
* *
* random_seed32: a random seed to be used for input selection * random_seed32: random seed to be used for input selection
* Out: proof_out_p: The pointer to newly-allocated proof whose bitvector will be initialized. * Out: proof_out_p: pointer to newly-allocated proof whose bitvector will be initialized.
* In case of failure, the pointer will be NULL. * In case of failure, the pointer will be NULL.
* input_index: The index of the actual input that is secretly mapped to the output * input_index: The index of the actual input that is secretly mapped to the output
*/ */

14
include/secp256k1_whitelist.h
View File

@ -40,9 +40,9 @@ typedef struct {
/** Parse a whitelist signature /** Parse a whitelist signature
* *
* Returns: 1 when the signature could be parsed, 0 otherwise. * Returns: 1 when the signature could be parsed, 0 otherwise.
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: sig: a pointer to a signature object * Out: sig: pointer to a signature object
* In: input: a pointer to the array to parse * In: input: pointer to the array to parse
* input_len: the length of the above array * input_len: the length of the above array
* *
* The signature must consist of a 1-byte n_keys value, followed by a 32-byte * The signature must consist of a 1-byte n_keys value, followed by a 32-byte
@ -67,7 +67,7 @@ SECP256K1_API int secp256k1_whitelist_signature_parse(
/** Returns the number of keys a signature expects to have. /** Returns the number of keys a signature expects to have.
* *
* Returns: the number of keys for the given signature * Returns: the number of keys for the given signature
* In: sig: a pointer to a signature object * In: sig: pointer to a signature object
*/ */
SECP256K1_API size_t secp256k1_whitelist_signature_n_keys( SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
const secp256k1_whitelist_signature *sig const secp256k1_whitelist_signature *sig
@ -76,10 +76,10 @@ SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
/** Serialize a whitelist signature /** Serialize a whitelist signature
* *
* Returns: 1 * Returns: 1
* Args: ctx: a secp256k1 context object * Args: ctx: pointer to a context object
* Out: output64: a pointer to an array to store the serialization * Out: output64: pointer to an array to store the serialization
* In/Out: output_len: length of the above array, updated with the actual serialized length * In/Out: output_len: length of the above array, updated with the actual serialized length
* In: sig: a pointer to an initialized signature object * In: sig: pointer to an initialized signature object
* *
* See secp256k1_whitelist_signature_parse for details about the encoding. * See secp256k1_whitelist_signature_parse for details about the encoding.
*/ */