Skip to content

Commit

Permalink
docs: correctly document all library constants and flags, other minor…
Browse files Browse the repository at this point in the history 
… fixes

Constants and groups of constants (such as flags) are now are now linked in
the generated API documentation.
  • Loading branch information
@jgriffiths
jgriffiths committed Feb 12, 2023
1 parent d5d7508 commit b9e69df
Show file tree
Hide file tree
Showing 15 changed files with 395 additions and 386 deletions.
68 changes: 39 additions & 29 deletions include/wally_address.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ struct ext_key;
#define WALLY_CA_PREFIX_LIQUID_REGTEST 0x04 /** Liquid v1 confidential address prefix for regtest */
#define WALLY_CA_PREFIX_LIQUID_TESTNET 0x17 /** Liquid v1 confidential address prefix for testnet */

/*** address-networks Address network constants */
#define WALLY_NETWORK_NONE 0x00 /** Used for miniscript parsing only */
#define WALLY_NETWORK_BITCOIN_MAINNET 0x01 /** Bitcoin mainnet */
#define WALLY_NETWORK_BITCOIN_REGTEST 0xff /** Bitcoin regtest: Behaves as testnet except for segwit */
Expand All @@ -28,6 +29,7 @@ struct ext_key;
#define WALLY_ADDRESS_TYPE_P2SH_P2WPKH 0x02 /** P2SH-P2WPKH wrapped SegWit address ("3...") */
#define WALLY_ADDRESS_TYPE_P2WPKH 0x04 /** P2WPKH native SegWit address ("bc1...)" */

/*** address-versions Address versions */
#define WALLY_ADDRESS_VERSION_P2PKH_MAINNET 0x00 /** P2PKH address on mainnet */
#define WALLY_ADDRESS_VERSION_P2PKH_TESTNET 0x6F /** P2PKH address on testnet */
#define WALLY_ADDRESS_VERSION_P2PKH_LIQUID 0x39 /** P2PKH address on liquid v1 */
Expand All @@ -51,11 +53,12 @@ struct ext_key;
* Create a segwit native address from a v0 or later witness program.
*
* :param bytes: Witness program bytes, including the version and data push opcode.
* :param bytes_len: Length of ``bytes`` in bytes. Must be ``HASH160_LEN``
*| or ``SHA256_LEN`` for v0 witness programs.
* :param bytes_len: Length of ``bytes`` in bytes. Must be `HASH160_LEN`
*| or `SHA256_LEN` for v0 witness programs.
* :param addr_family: Address family to generate, e.g. "bc" or "tb".
* :param flags: For future use. Must be 0.
* :param output: Destination for the resulting segwit native address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_addr_segwit_from_bytes(
const unsigned char *bytes,
Expand Down Expand Up @@ -130,10 +133,9 @@ WALLY_CORE_API int wally_addr_segwit_n_get_version(
* Infer a scriptPubKey from an address.
*
* :param addr: Base58 encoded address to infer the scriptPubKey from.
*| For confidential Liquid addresses first call :c:func:`wally_confidential_addr_to_addr`
* :param network: One of ``WALLY_NETWORK_BITCOIN_MAINNET``, ``WALLY_NETWORK_BITCOIN_TESTNET``,
*| ``WALLY_NETWORK_LIQUID``, ``WALLY_NETWORK_LIQUID_REGTEST``.
* :param bytes_out: Destination for the resulting scriptPubKey
*| For confidential Liquid addresses first call `wally_confidential_addr_to_addr`.
* :param network: Network the address is for. One of the :ref:`address-networks`.
* :param bytes_out: Destination for the resulting scriptPubKey.
* MAX_SIZED_OUTPUT(len, bytes_out, WALLY_ADDRESS_PUBKEY_MAX_LEN)
* :param written: Destination for the number of bytes written to ``bytes_out``.
*/
Expand All @@ -145,14 +147,16 @@ WALLY_CORE_API int wally_address_to_scriptpubkey(
size_t *written);

/**
* Infer address from a scriptPubKey. For SegWit addresses, use `wally_addr_segwit_from_bytes`
* instead. To find out if an address is SegWit, use `wally_scriptpubkey_get_type`.
* Infer an address from a scriptPubKey.
*
* :param scriptpubkey: scriptPubKey bytes.
* :param scriptpubkey_len: Length of ``scriptpubkey`` in bytes.
* :param network: One of ``WALLY_NETWORK_BITCOIN_MAINNET``, ``WALLY_NETWORK_BITCOIN_TESTNET``,
*| ``WALLY_NETWORK_LIQUID``, ``WALLY_NETWORK_LIQUID_REGTEST``.
* :param network: Network to generate the address for. One of the :ref:`address-networks`.
* :param output: Destination for the resulting Base58 encoded address string.
*| The string returned should be freed using `wally_free_string`.
*
* For SegWit addresses, use `wally_addr_segwit_from_bytes` instead. To
* determine if a scriptPubKey is SegWit, use `wally_scriptpubkey_get_type`.
*/
WALLY_CORE_API int wally_scriptpubkey_to_address(
const unsigned char *scriptpubkey,
Expand All @@ -164,12 +168,13 @@ WALLY_CORE_API int wally_scriptpubkey_to_address(
* Convert a private key to Wallet Import Format.
*
* :param priv_key: Private key bytes.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be ``EC_PRIVATE_KEY_LEN``.
* :param prefix: Expected prefix byte, e.g. ``WALLY_ADDRESS_VERSION_WIF_MAINNET``
*| or ``WALLY_ADDRESS_VERSION_WIF_TESTNET``.
* :param flags: Pass ``WALLY_WIF_FLAG_COMPRESSED`` if the corresponding pubkey is compressed,
*| otherwise ``WALLY_WIF_FLAG_UNCOMPRESSED``.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`.
* :param prefix: Expected prefix byte, e.g. `WALLY_ADDRESS_VERSION_WIF_MAINNET`
*| or `WALLY_ADDRESS_VERSION_WIF_TESTNET`.
* :param flags: Pass `WALLY_WIF_FLAG_COMPRESSED` if the corresponding pubkey is compressed,
*| otherwise `WALLY_WIF_FLAG_UNCOMPRESSED`.
* :param output: Destination for the resulting Wallet Import Format string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_wif_from_bytes(
const unsigned char *priv_key,
Expand All @@ -182,10 +187,10 @@ WALLY_CORE_API int wally_wif_from_bytes(
* Convert a Wallet Import Format string to a private key.
*
* :param wif: Private key in Wallet Import Format.
* :param prefix: Prefix byte to use, e.g. ``WALLY_ADDRESS_VERSION_WIF_MAINNET``
*| or ``WALLY_ADDRESS_VERSION_WIF_TESTNET``.
* :param flags: Pass ``WALLY_WIF_FLAG_COMPRESSED`` if the corresponding pubkey is compressed,
*| otherwise ``WALLY_WIF_FLAG_UNCOMPRESSED``.
* :param prefix: Prefix byte to use, e.g. `WALLY_ADDRESS_VERSION_WIF_MAINNET`
*| or `WALLY_ADDRESS_VERSION_WIF_TESTNET`.
* :param flags: Pass `WALLY_WIF_FLAG_COMPRESSED` if the corresponding pubkey is compressed,
*| otherwise `WALLY_WIF_FLAG_UNCOMPRESSED`.
* :param bytes_out: Destination for the private key.
* FIXED_SIZED_OUTPUT(len, bytes_out, EC_PRIVATE_KEY_LEN)
*/
Expand All @@ -210,7 +215,8 @@ WALLY_CORE_API int wally_wif_is_uncompressed(
* Create a public key corresponding to a private key in Wallet Import Format.
*
* :param wif: Private key in Wallet Import Format.
* :param prefix: Prefix byte to use, e.g. 0x80, 0xef.
* :param prefix: Expected prefix byte, e.g. `WALLY_ADDRESS_VERSION_WIF_MAINNET`
*| or `WALLY_ADDRESS_VERSION_WIF_TESTNET`.
* :param bytes_out: Destination for the resulting public key.
* :param len: The length of ``bytes_out``.
* :param written: Destination for the number of bytes written to ``bytes_out``.
Expand All @@ -226,11 +232,11 @@ WALLY_CORE_API int wally_wif_to_public_key(
* Create a legacy or wrapped SegWit address corresponding to a BIP32 key.
*
* :param hdkey: The extended key to use.
* :param flags: ``WALLY_ADDRESS_TYPE_P2PKH`` for a legacy address, ``WALLY_ADDRESS_TYPE_P2SH_P2WPKH``
* :param flags: `WALLY_ADDRESS_TYPE_P2PKH` for a legacy address, `WALLY_ADDRESS_TYPE_P2SH_P2WPKH`
*| for P2SH-wrapped SegWit.
* :param version: Version byte to generate address, e.g. with Bitcoin: ``WALLY_ADDRESS_VERSION_P2PKH_MAINNET``,
*| ``WALLY_ADDRESS_VERSION_P2PKH_TESTNET``, ``WALLY_ADDRESS_VERSION_P2SH_MAINNET`` and ``WALLY_ADDRESS_VERSION_P2SH_TESTNET``.
* :param version: Address version to generate. One of the :ref:`address-versions`.
* :param output: Destination for the resulting address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_bip32_key_to_address(
const struct ext_key *hdkey,
Expand All @@ -245,6 +251,7 @@ WALLY_CORE_API int wally_bip32_key_to_address(
* :param addr_family: Address family to generate, e.g. "bc" or "tb".
* :param flags: For future use. Must be 0.
* :param output: Destination for the resulting segwit native address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_bip32_key_to_addr_segwit(
const struct ext_key *hdkey,
Expand All @@ -257,8 +264,9 @@ WALLY_CORE_API int wally_bip32_key_to_addr_segwit(
*
* :param wif: Private key in Wallet Import Format.
* :param prefix: Prefix byte to use, e.g. 0x80, 0xef.
* :param version: Version byte to generate address, e.g. ``WALLY_ADDRESS_VERSION_P2PKH_MAINNET``, ``WALLY_ADDRESS_VERSION_P2PKH_TESTNET``.
* :param version: Address version to generate. One of the :ref:`address-versions`.
* :param output: Destination for the resulting address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_wif_to_address(
const char *wif,
Expand All @@ -271,8 +279,9 @@ WALLY_CORE_API int wally_wif_to_address(
* Extract the address from a confidential address.
*
* :param address: The base58 encoded confidential address to extract the address from.
* :param prefix: The confidential address prefix byte, e.g. ``WALLY_CA_PREFIX_LIQUID``.
* :param prefix: The confidential address prefix byte, e.g. `WALLY_CA_PREFIX_LIQUID`.
* :param output: Destination for the resulting address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_confidential_addr_to_addr(
const char *address,
Expand All @@ -283,7 +292,7 @@ WALLY_CORE_API int wally_confidential_addr_to_addr(
* Extract the blinding public key from a confidential address.
*
* :param address: The base58 encoded confidential address to extract the public key from.
* :param prefix: The confidential address prefix byte, e.g. ``WALLY_CA_PREFIX_LIQUID``.
* :param prefix: The confidential address prefix byte, e.g. `WALLY_CA_PREFIX_LIQUID`.
* :param bytes_out: Destination for the public key.
* FIXED_SIZED_OUTPUT(len, bytes_out, EC_PUBLIC_KEY_LEN)
*/
Expand All @@ -297,10 +306,11 @@ WALLY_CORE_API int wally_confidential_addr_to_ec_public_key(
* Create a confidential address from an address and blinding public key.
*
* :param address: The base58 encoded address to make confidential.
* :param prefix: The confidential address prefix byte, e.g. ``WALLY_CA_PREFIX_LIQUID``.
* :param prefix: The confidential address prefix byte, e.g. `WALLY_CA_PREFIX_LIQUID`.
* :param pub_key: The blinding public key to associate with ``address``.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be ``EC_PUBLIC_KEY_LEN``.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`.
* :param output: Destination for the resulting address string.
*| The string returned should be freed using `wally_free_string`.
*/
WALLY_CORE_API int wally_confidential_addr_from_addr(
const char *address,
Expand Down Expand Up @@ -345,7 +355,7 @@ WALLY_CORE_API int wally_confidential_addr_segwit_to_ec_public_key(
* :param addr_family: The address family to generate.
* :param confidential_addr_family: The confidential address family to generate.
* :param pub_key: The blinding public key to associate with ``address``.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be ``EC_PUBLIC_KEY_LEN``.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`.
* :param output: Destination for the resulting address string.
*| The string returned should be freed using `wally_free_string`.
*/
Expand Down
34 changes: 17 additions & 17 deletions include/wally_anti_exfil.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ extern "C" {
*| be revealed to the client until after the host has received the client
*| commitment.
* :param entropy_len: The length of ``entropy`` in bytes. Must be
*| ``WALLY_S2C_DATA_LEN``.
* :param flags: Must be ``EC_FLAG_ECDSA``.
*| `WALLY_S2C_DATA_LEN`.
* :param flags: Must be `EC_FLAG_ECDSA`.
* :param bytes_out: Destination for the resulting compact signature.
* FIXED_SIZED_OUTPUT(len, bytes_out, WALLY_HOST_COMMITMENT_LEN)
*/
Expand All @@ -36,13 +36,13 @@ WALLY_CORE_API int wally_ae_host_commit_from_bytes(
* Compute signer's original nonce.
*
* :param priv_key: The private key used for signing.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be ``EC_PRIVATE_KEY_LEN``.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`.
* :param bytes: The message hash to be signed.
* :param bytes_len: The length of ``bytes`` in bytes. Must be ``EC_MESSAGE_HASH_LEN``.
* :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`.
* :param commitment: Randomness commitment from the host.
* :param commitment_len: The length of ``commitment`` in bytes. Must be
*| ``WALLY_HOST_COMMITMENT_LEN``.
* :param flags: Must be ``EC_FLAG_ECDSA``.
*| `WALLY_HOST_COMMITMENT_LEN`.
* :param flags: Must be `EC_FLAG_ECDSA`.
* :param s2c_opening_out: Destination for the resulting opening information.
* FIXED_SIZED_OUTPUT(s2c_opening_out_len, s2c_opening_out, WALLY_S2C_OPENING_LEN)
*/
Expand All @@ -58,15 +58,15 @@ WALLY_CORE_API int wally_ae_signer_commit_from_bytes(
size_t s2c_opening_out_len);

/**
* Same as ``wally_ec_sig_from_bytes``, but commits to the host randomness.
* Same as `wally_ec_sig_from_bytes`, but commits to the host randomness.
*
* :param priv_key: The private key to sign with.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be ``EC_PRIVATE_KEY_LEN``.
* :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`.
* :param bytes: The message hash to sign.
* :param bytes_len: The length of ``bytes`` in bytes. Must be ``EC_MESSAGE_HASH_LEN``.
* :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`.
* :param entropy: Host provided randomness.
* :param entropy_len: The length of ``entropy`` in bytes. Must be ``WALLY_S2C_DATA_LEN``.
* :param flags: Must be ``EC_FLAG_ECDSA``.
* :param entropy_len: The length of ``entropy`` in bytes. Must be `WALLY_S2C_DATA_LEN`.
* :param flags: Must be `EC_FLAG_ECDSA`.
* :param bytes_out: Destination for the resulting compact signature.
* FIXED_SIZED_OUTPUT(len, bytes_out, EC_SIGNATURE_LEN)
*/
Expand All @@ -85,17 +85,17 @@ WALLY_CORE_API int wally_ae_sig_from_bytes(
* Verify a signature was correctly constructed using the Anti-Exfil Protocol.
*
* :param pub_key: The public key to verify with.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be ``EC_PUBLIC_KEY_LEN``.
* :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`.
* :param bytes: The message hash to verify.
* :param bytes_len: The length of ``bytes`` in bytes. Must be ``EC_MESSAGE_HASH_LEN``.
* :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`.
* :param entropy: Randomness provided by the host.
* :param entropy_len: The length of ``entropy`` in bytes. Must be ``WALLY_S2C_DATA_LEN``.
* :param entropy_len: The length of ``entropy`` in bytes. Must be `WALLY_S2C_DATA_LEN`.
* :param s2c_opening: Opening information provided by the signer.
* :param s2c_opening_len: The length of ``s2c_opening`` in bytes. Must be
*| ``WALLY_S2C_OPENING_LEN``.
* :param flags: Must be ``EC_FLAG_ECDSA``.
*| `WALLY_S2C_OPENING_LEN`.
* :param flags: Must be `EC_FLAG_ECDSA`.
* :param sig: The compact signature of the message in ``bytes``.
* :param sig_len: The length of ``sig`` in bytes. Must be ``EC_SIGNATURE_LEN``.
* :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_LEN`.
*/
WALLY_CORE_API int wally_ae_verify(
const unsigned char *pub_key,
Expand Down
Loading

0 comments on commit b9e69df

Please sign in to comment.