Add documentation to utils functions

src/utils.rs

@@ -26,6 +26,7 @@ const OP_CHECKSIG: u8 = 0xAC;
 const COMPRESSED_PUBKEY_SIZE: usize = 33;
 
 // script templates for inputs allowed in BIP352 shared secret derivation
+/// Check if a script_pub_key is taproot.
 pub fn is_p2tr(spk: &[u8]) -> bool {
     matches!(spk, [OP_1, OP_PUSHBYTES_32, ..] if spk.len() == 34)
 }
@@ -42,6 +43,23 @@ fn is_p2pkh(spk: &[u8]) -> bool {
     matches!(spk, [OP_DUP, OP_HASH160, OP_PUSHBYTES_20, .., OP_EQUALVERIFY, OP_CHECKSIG] if spk.len() == 25)
 }
 
+/// Get the public keys from a set of input data.
+///
+/// # Arguments
+///
+/// * `script_sig` - The script signature as a byte array.
+/// * `txinwitness` - The witness data.
+/// * `script_pub_key` - The scriptpubkey from the output spent. This requires looking up the previous output.
+///
+/// # Returns
+///
+/// If no errors occur, this function will optionally return a PublicKey if this input is silent payment-eligible.
+///
+/// # Errors
+///
+/// This function will error if:
+///
+/// * The provided Vin data is incorrect.
 pub fn get_pubkey_from_input(
     script_sig: &[u8],
     txinwitness: &Vec<Vec<u8>>,

src/utils/receiving.rs

@@ -1,6 +1,25 @@
 use crate::{utils::calculate_input_hash, Result};
 use secp256k1::{PublicKey, SecretKey};
 
+/// Calculate just the tweak data of a transaction.
+/// This is useful for indexing servers that don't have access to the recipient scan key.
+/// Wallets should use `calculate_shared_secret` instead.
+///
+/// # Arguments
+///
+/// * `input_pub_keys` - The list of public keys that are used as input for this transaction. Only the public keys for inputs that are silent payment eligible should be given.
+/// * `outpoints_data` - All prevout outpoints used as input for this transaction. Note that the txid is given in String format, which is displayed in reverse order from the inner byte array.
+///
+/// # Returns
+///
+/// This function returns the tweak data for this transaction. The tweak data is an intermediary result that can be used to calculate the final shared secret.
+///
+/// # Errors
+///
+/// This function will error if:
+///
+/// * The input public keys array is of length zero, or the summing results in an invalid key.
+/// * The outpoints_data is of length zero, or invalid.
 pub fn calculate_tweak_data(
     input_pub_keys: &[&PublicKey],
     outpoints_data: &[(String, u32)],
@@ -12,6 +31,24 @@ pub fn calculate_tweak_data(
     Ok(A_sum.mul_tweak(&secp, &input_hash)?)
 }
 
+/// Calculate the shared secret of a transaction.
+///
+/// # Arguments
+///
+/// * `input_pub_keys` - The list of public keys that are used as input for this transaction. Only the public keys for inputs that are silent payment eligible should be given.
+/// * `outpoints_data` - All prevout outpoints used as input for this transaction. Note that the txid is given in String format, which is displayed in reverse order from the inner byte array.
+/// * `b_scan` - The scan private key used by the wallet.
+///
+/// # Returns
+///
+/// This function returns the shared secret of this transaction. This shared secret can be used to scan the transaction of outputs that are for the current user. See `receiving::scan_transaction`.
+///
+/// # Errors
+///
+/// This function will error if:
+///
+/// * The input public keys array is of length zero, or the summing results in an invalid key.
+/// * The outpoints_data is of length zero, or invalid.
 pub fn calculate_shared_secret(
     input_pub_keys: &[&PublicKey],
     outpoints_data: &[(String, u32)],

src/utils/sending.rs

@@ -3,6 +3,23 @@ use secp256k1::{Secp256k1, SecretKey};
 
 use super::calculate_input_hash;
 
+/// Calculate the partial secret that is needed for generating the recipient pubkeys.
+///
+/// # Arguments
+///
+/// * `input_keys` - A reference to a list of tuples, each tuple containing a `SecretKey` and `bool`. The `SecretKey` is the private key used in the input, and the `bool` indicates whether this was from a taproot address.
+/// * `outpoints_data` - The prevout outpoints used as input for this transaction. Note that the txid is given in String format, which is displayed in reverse order from the inner byte array.
+///
+/// # Returns
+///
+/// This function returns the partial secret, which represents the sum of all (eligible) input keys multiplied with the input hash.
+///
+/// # Errors
+///
+/// This function will error if:
+///
+/// * The input keys array is of length zero, or the summing results in an invalid key.
+/// * The outpoints_data is of length zero, or invalid.
 pub fn calculate_partial_secret(
     input_keys: &[(SecretKey, bool)],
     outpoints_data: &[(String, u32)],