kernel: document overwritten validation state outputs
What the developer wrote
Authored by w0xlt
kernel: document overwritten validation state outputs
Document btck_transaction_check and btck_block_check validation state output parameters as overwritten in-place. This matches their reset-on-entry behavior and avoids implying callers should preserve prior state.
What changed, and why it matters
This commit only changes comments in a public header file. It clarifies that two Bitcoin kernel functions overwrite their validation-state output parameter rather than preserving any prior contents. No code behavior is changed, so there is no security impact.
No action required. This is a non-functional documentation change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch updates Doxygen-style documentation for btck_transaction_check and btck_block_check in src/kernel/bitcoinkernel.h. It rewords the description of the validation_state parameter from ‘Reset on entry … updated in-place’ / ‘in,out’ to ‘Overwritten in-place’ / ‘out’. The underlying reset-on-entry behavior is unchanged; this is a pure documentation clarification.
Changed components
src/kernel/bitcoinkernel.h (documentation only)Inspect captured patch +7 / −7
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index d91a4a63..1540f20e 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -675,10 +675,9 @@ BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transac
*
* @param[in] tx Non-null, the transaction to validate.
* @param[out] validation_state Non-null, previously created with
- * btck_tx_validation_state_create. Reset on
- * entry (any prior contents are overwritten)
- * and updated in-place with the validation
- * result before this function returns.
+ * btck_tx_validation_state_create.
+ * Overwritten in-place with the validation
+ * result.
* @return 1 if valid, 0 if invalid.
* @note Only btck_TxValidationResult_UNSET and
* btck_TxValidationResult_CONSENSUS are
@@ -1383,9 +1382,10 @@ typedef uint32_t btck_BlockCheckFlags;
* optional POW and merkle-root checks. Use
* btck_BlockCheckFlags_BASE to run only the base
* checks.
- * @param[in,out] validation_state Non-null, previously created with
- * btck_block_validation_state_create and updated
- * in-place with the validation result.
+ * @param[out] validation_state Non-null, previously created with
+ * btck_block_validation_state_create.
+ * Overwritten in-place with the validation
+ * result.
* @return 1 if the btck_Block passed the checks, 0 otherwise.
*/
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_check(
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.