chore: Added documentation for btc_input_valiadator

apps/btc_family/btc_inputs_validator.c

@@ -90,7 +90,26 @@
 /*****************************************************************************
  * STATIC FUNCTIONS
  *****************************************************************************/
-// https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+
+/**
+ * @brief Decodes a variable-length integer (VarInt) from the byte stream.
+ *
+ * This function reads the first byte from the stream to determine how many more
+ * bytes are needed to decode the full integer. The number of bytes varies based
+ * on the value of the first byte (0xfd, 0xfe, or 0xff for extended length
+ * encoding).
+ *
+ * @param stream Pointer to the byte stream from which the VarInt is decoded.
+ * @param hash_ctx Pointer to an SHA256 context for updating the hash
+ * (optional).
+ *
+ * ref:
+ * https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+ *
+ * @return The decoded 64-bit integer value.
+ * @note If the stream is invalid, or if there's an error reading from the
+ * stream, 0 is returned.
+ */
 static uint64_t decode_varint(byte_stream_t *stream, SHA256_CTX *hash_ctx) {
   uint8_t buffer[MAX_VARINT_SIZE] = {0};
   if (stream == NULL) {

apps/btc_family/btc_inputs_validator.h

@@ -29,11 +29,33 @@ typedef enum {
 #define TX_IN_SEQ_NO_SIZE 4
 #define MAX_VARINT_SIZE 9
 #define SHA256_DIGEST_LENGTH 32
-#define SLICE_SIZE 1024    // Adjust as needed based on system requirements
+#define SLICE_SIZE 1024
 
 #define TX_IN_INDEX_OFFSET 1
 #define TX_OUT_INDEX_OFFSET 1
 
+/**
+ * @brief Validates the inputs of a Bitcoin transaction.
+ *
+ * This function performs a series of checks to validate each input of a
+ * transaction:
+ * - Decodes the transaction version and checks the validity of input values.
+ * - Verifies the previous transaction hash and the output value for each input.
+ * - Ensures that the output index matches the provided value for the input.
+ *
+ * It also computes a SHA256 hash of the transaction (including inputs, outputs,
+ * and lock time) and compares it against the expected transaction hash.
+ *
+ * @param stream Pointer to the byte stream containing the transaction data.
+ * @param input Pointer to the input structure to validate.
+ *
+ * @return BTC_VALIDATE_SUCCESS on success, or an error code if validation
+ * fails:
+ * - BTC_VALIDATE_ERR_INVALID_PARAMS
+ * - BTC_VALIDATE_ERR_READ_STREAM
+ * - BTC_VALIDATE_ERR_INVALID_TX_HASH
+ * - BTC_VALIDATE_ERR_INVALID_OUTPUT_VALUE
+ */
 btc_validation_error_e btc_validate_inputs(byte_stream_t *stream,
                                            const btc_sign_txn_input_t *input);