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.
*
* 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
* In: seckey32: pointer to 32 byte secret key that will be used for
* signing
@ -101,7 +101,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_encrypt(
* and the completed ECDSA signature.
*
* 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
* pubkey: pointer to the public key corresponding to the secret key
* 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.
*
* 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
* In: deckey32: pointer to 32-byte decryption secret key for the adaptor
* encryption public key
@ -140,7 +140,7 @@ SECP256K1_API int secp256k1_ecdsa_adaptor_decrypt(
* signature.
*
* 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
* encryption public key
* 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
* 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
* parsed version of input. If not, its value is unspecified.
* 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.
* 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
* 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(
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
* not necessarily need to be a valid siganture!)
* 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)
* data32: the 32-byte data that was committed to (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
* 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)
* msghash32: the 32-byte message hash being verified (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.
*
* 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
* 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.
*
* Returns: 1 always.
* Args: ctx: a secp256k1 context object.
* Out: output: a pointer to a 33-byte byte array
* In: gen: a pointer to a generator
* Args: ctx: pointer to a context object
* Out: output: pointer to a 33-byte byte array
* In: gen: pointer to a generator object
*/
SECP256K1_API int secp256k1_generator_serialize(
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,
* 1 otherwise.
* Args: ctx: a secp256k1 context object
* Out: gen: a generator object
* Args: ctx: pointer to a context object
* Out: gen: pointer to a the new generator object
* In: seed32: a 32-byte seed
*
* 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
* blind is out of range. 1 otherwise.
* Args: ctx: a secp256k1 context object (not secp256k1_context_static)
* Out: gen: a generator object
* Args: ctx: pointer to a context object (not secp256k1_context_static)
* Out: gen: pointer to a generator object
* In: seed32: a 32-byte seed
* 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.
*
* 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
* 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.
*
* Returns: 1 always.
* Args: ctx: a secp256k1 context object.
* Out: output: a pointer to a 33-byte byte array
* In: commit: a pointer to a secp256k1_pedersen_commitment containing an
* Args: ctx: pointer to a context object
* Out: output: pointer to a 33-byte byte array
* In: commit: pointer to a secp256k1_pedersen_commitment containing an
* initialized commitment
*/
SECP256K1_API int secp256k1_pedersen_commitment_serialize(

33
include/secp256k1_surjectionproof.h
View File

@ -56,9 +56,9 @@ typedef struct {
/** Parse a surjection proof
*
* Returns: 1 when the proof could be parsed, 0 otherwise.
* Args: ctx: a secp256k1 context object
* Out: proof: a pointer to a proof object
* In: input: a pointer to the array to parse
* Args: ctx: pointer to a context object
* Out: proof: pointer to a proof object
* In: input: pointer to the array to parse
* inputlen: length of the array pointed to by input
*
* The proof must consist of:
@ -79,12 +79,11 @@ SECP256K1_API int secp256k1_surjectionproof_parse(
/** Serialize a surjection proof
*
* Returns: 1 if enough space was available to serialize, 0 otherwise
* Args: ctx: a secp256k1 context object
* Out: output: a pointer to an array to store the serialization
* In/Out: outputlen: a pointer to an integer which is initially set to the
* size of output, and is overwritten with the written
* size.
* In: proof: a pointer to an initialized proof object
* Args: ctx: pointer to a context object
* Out: output: pointer to an array to store the serialization
* In/Out: outputlen: pointer to an integer which is initially set to the size
* of output, and is overwritten with the written size.
* In: proof: pointer to an initialized proof object
*
* See secp256k1_surjectionproof_parse for details about the encoding.
*/
@ -109,7 +108,7 @@ typedef struct {
*
* Returns: the number of inputs for the given proof
* 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(
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
* 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(
const secp256k1_context *ctx,
@ -131,7 +130,7 @@ SECP256K1_API size_t secp256k1_surjectionproof_n_used_inputs(
*
* Returns: the total size
* 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(
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
* (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,
* the state of the proof is undefined.
* 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
*
* In: ctx: pointer to a context object
* proof_out_p: a pointer to a pointer to `secp256k1_surjectionproof*`.
* the newly-allocated struct pointer will be saved here.
* proof_out_p: pointer to a pointer to `secp256k1_surjectionproof*`.
* 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,
* 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.)
@ -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
* (255/256)^(n_input_tags_to_use*max_n_iterations).
*
* random_seed32: a random seed to be used for input selection
* Out: proof_out_p: The pointer to newly-allocated proof whose bitvector will be initialized.
* random_seed32: random seed to be used for input selection
* Out: proof_out_p: pointer to newly-allocated proof whose bitvector will be initialized.
* In case of failure, the pointer will be NULL.
* 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
*
* Returns: 1 when the signature could be parsed, 0 otherwise.
* Args: ctx: a secp256k1 context object
* Out: sig: a pointer to a signature object
* In: input: a pointer to the array to parse
* Args: ctx: pointer to a context object
* Out: sig: pointer to a signature object
* In: input: pointer to the array to parse
* input_len: the length of the above array
*
* 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 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(
const secp256k1_whitelist_signature *sig
@ -76,10 +76,10 @@ SECP256K1_API size_t secp256k1_whitelist_signature_n_keys(
/** Serialize a whitelist signature
*
* Returns: 1
* Args: ctx: a secp256k1 context object
* Out: output64: a pointer to an array to store the serialization
* Args: ctx: pointer to a context object
* 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: 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.
*/