Autodoc for elements functions

include/wally_elements.h

@@ -11,6 +11,8 @@ extern "C" {
 
 #define ASSET_TAG_LEN 32 /** Length of an Asset Tag */
 
+#define BLINDING_FACTOR_LEN 32 /** Length of a Blinding Factor (or blinder) */
+
 #define ASSET_GENERATOR_LEN 33 /** Length of an Asset Generator */
 
 #define ASSET_COMMITMENT_LEN 33 /** Length of an Asset Value Commitment */
@@ -35,6 +37,21 @@ WALLY_CORE_API int wally_asset_generator_from_bytes(
     unsigned char *bytes_out,
     size_t len);
 
+/**
+ * Generate the final value blinding factor required for blinding a confidential transaction.
+ *
+ * :param values: Array of transaction input values in satoshi
+ * :param values_len: Length of ``values``, also the number of elements in all three of the input arrays, which is equal
+ *|     to ``num_inputs`` plus the number of outputs.
+ * :param num_inputs: Number of elements in the input arrays that represent transaction inputs. The number of outputs is
+ *|     implicitly ``values_len`` - ``num_inputs``.
+ * :param abf:  Array of bytes representing ``values_len`` asset blinding factors.
+ * :param abf_len: Length of ``abf`` in bytes. Must be ``values_len`` * ``BLINDING_FACTOR_LEN``.
+ * :param vbf: Array of bytes representing (``values_len`` - 1) value blinding factors.
+ * :param vbf_len: Length of ``vbf`` in bytes. Must be (``values_len`` - 1) * ``BLINDING_FACTOR_LEN``.
+ * :param bytes_out: Buffer to received the final value blinding factor.
+ * :param len: Length of ``bytes_out``. Must be ``BLINDING_FACTOR_LEN``.
+ */
 WALLY_CORE_API int wally_asset_final_vbf(
     const uint64_t *values,
     size_t values_len,
@@ -46,6 +63,17 @@ WALLY_CORE_API int wally_asset_final_vbf(
     unsigned char *bytes_out,
     size_t len);
 
+/**
+ * Calculate the value commitment for a transaction output.
+ *
+ * :param value: Output value in satoshi.
+ * :param vbf: Value Blinding Factor.
+ * :param vbf_len: Length of ``vbf``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param generator: Asset generator from `wally_asset_generator_from_bytes`.
+ * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN``.
+ * :param bytes_out: Buffer to receive value commitment.
+ * :param len: Length of ``bytes_out``. Must be ``ASSET_GENERATOR_LEN``.
+ */
 WALLY_CORE_API int wally_asset_value_commitment(
     uint64_t value,
     const unsigned char *vbf,
@@ -78,6 +106,34 @@ WALLY_CORE_API int wally_asset_rangeproof_with_nonce(
     size_t len,
     size_t *written);
 
+/**
+ * Generate a rangeproof for a transaction output.
+ *
+ * :param value: Value of the output in satoshi.
+ * :param pub_key: Public blinding key for the output. See `wally_confidential_addr_to_ec_public_key`.
+ * :param pub_key_len: Length of ``pub_key``. Must be ``EC_PUBLIC_KEY_LEN``
+ * :param priv_key: Pivate ephemeral key. Should be randomly generated for each output.
+ * :param priv_key_length: Length of ``priv_key``.
+ * :param asset: Asset id of output.
+ * :param asset_len: Length of ``asset``. Must be ``ASSET_TAG_LEN``.
+ * :param abf: Asset blinding factor. Randomly generated for each output.
+ * :param abf_len: Length of ``abf``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param vbf: Value blinding factor. Randomly generated for each output except the last, which is generate by calling
+ *|     `wally_asset_final_vbf`.
+ * :param vbf_len: Length of ``vbf``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param commitment: Value commitment from `wally_asset_value_commitment`.
+ * :param commitment_len: Length of ``commitment``. Must be ``ASSET_COMMITMENT_LEN``.
+ * :param extra: Set this to the script pubkey of the output.
+ * :param extra_len: Length of ``extra``, i.e. script pubkey.
+ * :param generator: Asset generator from `wally_asset_generator_from_bytes`.
+ * :param generator_len: Length of ``generator`. Must be ``ASSET_GENERATOR_LEN``.
+ * :param min_value: Recommended value 1.
+ * :param exp: Exponent value. -1 >= ``exp`` >= 18. Recommended value 0.
+ * :param min_bits: 0 >= min_bits >= 64. Recommended value 36.
+ * :param bytes_out: Buffer to receive rangeproof.
+ * :param len: Length of ``bytes_out``. See ``ASSET_RANGEPROOF_MAX_LEN``.
+ * :param written: Number of bytes actually written to ``bytes_out``.
+ */
 WALLY_CORE_API int wally_asset_rangeproof(
     uint64_t value,
     const unsigned char *pub_key,
@@ -103,10 +159,37 @@ WALLY_CORE_API int wally_asset_rangeproof(
     size_t len,
     size_t *written);
 
+/**
+ * Return the required buffer size for receiving a surjection proof
+ *
+ * :param num_inputs: Number of transaction inputs.
+ * :param written: Destination for the surjection proof size.
+ */
 WALLY_CORE_API int wally_asset_surjectionproof_size(
     size_t num_inputs,
     size_t *written);
 
+/**
+ * Generate a surjection proof for a transaction output
+ *
+ * :param output_asset: asset id for the output.
+ * :param output_asset_len: Length of ``asset``. Must be ``ASSET_TAG_LEN``.
+ * :param output_abf: Asset blinding factor for the output. Generated randomly for each output.
+ * :param output_abf_len: Length of ``output_abf``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param output_generator: Asset generator from `wally_asset_generator_from_bytes`.
+ * :param output_generator_len: Length of ``output_generator`. Must be ``ASSET_GENERATOR_LEN``.
+ * :param bytes: Must be generated randomly for each output.
+ * :param bytes_len: Length of ``bytes``. Must be 32.
+ * :param asset: Array of input asset tags.
+ * :param asset_len: Length of ``asset`. Must be ``ASSET_TAG_LEN`` * number of inputs.
+ * :param abf: Array of asset blinding factors from the transaction inputs.
+ * :param abf_len: Length of ``abf``. Must be ``BLINDING_FACTOR_LEN`` * number of inputs.
+ * :param generator: Array of asset generators from transaction inputs.
+ * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN`` * number of inputs.
+ * :param bytes_out: Buffer to receive surjection proof.
+ * :param bytes_out_len: Length of ``bytes_out``. See `wally_asset_surjectionproof_size`.
+ * :param written: Number of bytes actually written to ``bytes_out``.
+ */
 WALLY_CORE_API int wally_asset_surjectionproof(
     const unsigned char *output_asset,
     size_t output_asset_len,
@@ -145,6 +228,29 @@ WALLY_CORE_API int wally_asset_unblind_with_nonce(
     size_t vbf_out_len,
     uint64_t *value_out);
 
+/**
+ * Unblind a confidential transaction output.
+ *
+ * :param pub_key: From :c:func:`wally_tx_get_output_nonce`.
+ * :param pub_key_len: Length of ``pub_key``. Must be ``EC_PUBLIC_KEY_LEN``.
+ * :param priv_key: Private blinding key corresponding to public blinding key used to generate destination address. See
+ *|     :c:func:`wally_asset_blinding_key_to_ec_private_key`.
+ * :param proof: Rangeproof from :c:func:`wally_tx_get_output_rangeproof`.
+ * :param proof_len: Length of ``proof``.
+ * :param commitment: Value commitment from :c:func:`wally_tx_get_output_value`.
+ * :param commitment_len: Length of ``commitment``.
+ * :param extra: Script pubkey from :c:func:`wally_tx_get_output_script`.
+ * :param extra_len: Length of ``extra``.
+ * :param generator: Asset generator from :c:func:`wally_tx_get_output_asset`.
+ * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN``.
+ * :param asset_out: Buffer to receive unblinded asset id.
+ * :param asset_out_len: Length of ``asset_out``. Must be ``ASSET_TAG_LEN``.
+ * :param abf_out: Buffer to receive asset blinding factor.
+ * :param abf_out_len: Length of ``abf_out``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param vbf_out: Buffer to receive asset blinding factor.
+ * :param vbf_out_len: Length of ``vbf_out``. Must be ``BLINDING_FACTOR_LEN``.
+ * :param value_out: Destination for unblinded transaction output value.
+ */
 WALLY_CORE_API int wally_asset_unblind(
     const unsigned char *pub_key,
     size_t pub_key_len,
@@ -166,12 +272,32 @@ WALLY_CORE_API int wally_asset_unblind(
     size_t vbf_out_len,
     uint64_t *value_out);
 
+/**
+ * Generate a master blinding key from a seed as specified in SLIP-0077.
+ *
+ * :param bytes: Seed value. See :c:func:`bip39_mnemonic_to_seed`.
+ * :param bytes_len: Length of ``seed``. Must be one of ``BIP32_ENTROPY_LEN_128``, ``BIP32_ENTROPY_LEN_256`` or
+ *|     ``BIP32_ENTROPY_LEN_512``.
+ * :param bytes_out: Buffer to receive master blinding key. The master blinding key can be used to generate blinding
+ *|     keys for specific outputs by passing it to `wally_asset_blinding_key_to_ec_private_key`.
+ * :param len: Length of ``bytes_out``. Must be ``HMAC_SHA512_LEN``.
+ */
 WALLY_CORE_API int wally_asset_blinding_key_from_seed(
     const unsigned char *bytes,
     size_t bytes_len,
     unsigned char *bytes_out,
     size_t len);
 
+/**
+ * Generate a blinding key for a script pubkey.
+ *
+ * :param bytes: Master blinding key from `wally_asset_blinding_key_from_seed`.
+ * :param bytes_len: Length of ``bytes``. Must be ``HMAC_SHA512_LEN``.
+ * :param script: The script pubkey for the confidential output address.
+ * :param script_len: Length of ``script``.
+ * :param bytes_out: Buffer to receive blinding key.
+ * :param len: Length of ``bytes_out``. Must be ``EC_PRIVATE_KEY_LEN``.
+ */
 WALLY_CORE_API int wally_asset_blinding_key_to_ec_private_key(
     const unsigned char *bytes,
     size_t bytes_len,
@@ -180,7 +306,7 @@ WALLY_CORE_API int wally_asset_blinding_key_to_ec_private_key(
     unsigned char *bytes_out,
     size_t len);
 
-/*
+/**
  * Calculate the size in bytes of the whitelist proof.
  *
  * :param num_keys: The number of offline/online keys.
@@ -190,7 +316,7 @@ WALLY_CORE_API int wally_asset_pak_whitelistproof_size(
     size_t num_keys,
     size_t *written);
 
-/*
+/**
  * Generate the whitelist proof for the pegout script.
  *
  * :param online_keys: The list of online keys.