Add missing documentation for several functions
What changed, and why it matters
This commit only adds or updates comments describing what several existing functions do. No program code, logic, or behavior was changed. It is a documentation-only change and does not affect security.
No security action needed. Treat as routine documentation maintenance.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff updates header comments for five helper functions related to Merkle tree handling in the Ledger Bitcoin app. It replaces ‘TODO: docs’ placeholders with descriptive Doxygen-style comments and fixes a stray backslash in one existing note. There are no code modifications, no API changes, and no executable behavior changes.
Changed components
src/handler/lib/get_merkle_leaf_element.hsrc/handler/lib/get_merkle_leaf_hash.hsrc/handler/lib/get_merkle_leaf_index.hsrc/handler/lib/get_merkleized_map.hsrc/handler/lib/get_merkleized_map_value_hash.hInspect captured patch +24 / −7
diff --git a/src/handler/lib/get_merkle_leaf_element.h b/src/handler/lib/get_merkle_leaf_element.h
index 7212fe7..fbe7935 100644
--- a/src/handler/lib/get_merkle_leaf_element.h
+++ b/src/handler/lib/get_merkle_leaf_element.h
@@ -4,7 +4,10 @@
#include "dispatcher.h"
/**
- * TODO: docs
+ * Retrieves the preimage of the leaf at `leaf_index` in the Merkle tree identified by
+ * `merkle_root` and `tree_size`, and stores it in `out_ptr`.
+ *
+ * Returns the length of the preimage on success, or a negative number on failure.
*/
int call_get_merkle_leaf_element(dispatcher_context_t *dispatcher_context,
const uint8_t merkle_root[static 32],
diff --git a/src/handler/lib/get_merkle_leaf_hash.h b/src/handler/lib/get_merkle_leaf_hash.h
index 6585e43..1bc1a2f 100644
--- a/src/handler/lib/get_merkle_leaf_hash.h
+++ b/src/handler/lib/get_merkle_leaf_hash.h
@@ -4,10 +4,14 @@
#include "dispatcher.h"
/**
- * TODO: docs
+ * Retrieves the hash of the leaf at `leaf_index` in the Merkle tree identified by `merkle_root`
+ * and `tree_size`, and verifies the proof returned by the host against `merkle_root`.
+ *
+ * On success, writes the 32-byte leaf hash to `out` and returns 0. Returns a negative value on
+ * failure.
*/
int call_get_merkle_leaf_hash(dispatcher_context_t *dispatcher_context,
const uint8_t merkle_root[static 32],
uint32_t tree_size,
uint32_t leaf_index,
- uint8_t out[static 32]);
\ No newline at end of file
+ uint8_t out[static 32]);
diff --git a/src/handler/lib/get_merkle_leaf_index.h b/src/handler/lib/get_merkle_leaf_index.h
index c14ea4e..e1afff1 100644
--- a/src/handler/lib/get_merkle_leaf_index.h
+++ b/src/handler/lib/get_merkle_leaf_index.h
@@ -4,9 +4,14 @@
#include "dispatcher.h"
/**
- * TODO: docs
+ * Retrieves the index of the leaf whose hash is `leaf_hash` in the Merkle tree identified by
+ * `root` and `size`.
+ *
+ * Returns the leaf index on success, or a negative value on failure. This function validates the
+ * index returned by the host by retrieving the leaf hash at that index and checking that it matches
+ * `leaf_hash`.
*/
int call_get_merkle_leaf_index(dispatcher_context_t *dispatcher_context,
size_t size,
const uint8_t root[static 32],
- const uint8_t leaf_hash[static 32]);
\ No newline at end of file
+ const uint8_t leaf_hash[static 32]);
diff --git a/src/handler/lib/get_merkleized_map.h b/src/handler/lib/get_merkleized_map.h
index c7ddc01..0672046 100644
--- a/src/handler/lib/get_merkleized_map.h
+++ b/src/handler/lib/get_merkleized_map.h
@@ -6,7 +6,12 @@
#include "merkle.h"
/**
- * TODO: docs
+ * Fetches the `index`-th element of a Merkle tree of merkleized maps, decodes it into `out_ptr`,
+ * and verifies that the keys in the tree are lexicographically sorted. If `callback` is not `NULL`,
+ * it is invoked once for each key element while checking the keys; `callback_state` is passed
+ * through unchanged.
+ *
+ * Returns 0 on success, or a negative number if the leaf cannot be fetched, decoded, or validated.
*/
int call_get_merkleized_map_with_callback(dispatcher_context_t *dispatcher_context,
void *callback_state,
diff --git a/src/handler/lib/get_merkleized_map_value_hash.h b/src/handler/lib/get_merkleized_map_value_hash.h
index b3b42b3..030207d 100644
--- a/src/handler/lib/get_merkleized_map_value_hash.h
+++ b/src/handler/lib/get_merkleized_map_value_hash.h
@@ -14,7 +14,7 @@
* success.
*
* NOTE: this does _not_ check that the keys are lexicographically sorted; the sanity check needs to
- * be done before.\
+ * be done before.
*/
int call_get_merkleized_map_value_hash(dispatcher_context_t *dispatcher_context,
const merkleized_map_commitment_t *map,
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.