3131#define BITCOINKERNEL_WARN_UNUSED_RESULT
3232#endif
3333#if !defined(BITCOINKERNEL_BUILD) && defined(__GNUC__) && BITCOINKERNEL_GNUC_PREREQ(3, 4)
34- #define BITCOINKERNEL_ARG_NONNULL (_x ) __attribute__((__nonnull__(_x )))
34+ #define BITCOINKERNEL_ARG_NONNULL (... ) __attribute__((__nonnull__(__VA_ARGS__ )))
3535#else
3636#define BITCOINKERNEL_ARG_NONNULL (_x )
3737#endif
@@ -43,13 +43,14 @@ extern "C" {
4343/* *
4444 * ------ Context ------
4545 *
46- * The library provides a built-in static constant kernel context. This context
47- * offers only limited functionality. It detects and self-checks the correct
48- * sha256 implementation, initializes the random number generator and
49- * self-checks the secp256k1 static context. It is used internally for otherwise
50- * "context-free" operations.
46+ * The library provides a built-in static constant kernel context. This static
47+ * context offers only limited functionality. It detects and self-checks the
48+ * correct sha256 implementation, initializes the random number generator and
49+ * self-checks the secp256k1 static context. It is used internally for
50+ * otherwise "context-free" operations. This means that the user is not
51+ * required to initialize their own context before using the library.
5152 *
52- * The user can create their own context for passing it to state-rich validation
53+ * The user should create their own context for passing it to state-rich validation
5354 * functions and holding callbacks for kernel events.
5455 *
5556 * ------ Error handling ------
@@ -73,11 +74,13 @@ extern "C" {
7374 * returned by functions. Typically pointers returned by *_create(...) functions
7475 * can be de-allocated by corresponding *_destroy(...) functions.
7576 *
76- * Pointer arguments make no assumptions on their lifetime. Once the function
77- * returns the user can safely de-allocate the passed in arguments.
77+ * A function that takes pointer arguments makes no assumptions on their
78+ * lifetime. Once the function returns the user can safely de-allocate the
79+ * passed in arguments.
7880 *
79- * Pointers passed by callbacks are not owned by the user and are only valid for
80- * the duration of it. They should not be de-allocated by the user.
81+ * Pointers passed by callbacks are not owned by the user and are only valid
82+ * for the duration of the callback. They are always marked as `const` and must
83+ * not be de-allocated by the user.
8184 *
8285 * Array lengths follow the pointer argument they describe.
8386 */
@@ -128,8 +131,9 @@ typedef struct kernel_Notifications kernel_Notifications;
128131 *
129132 * Once a kernel context has been created from these options, they may be
130133 * destroyed. The options hold the notification callbacks as well as the
131- * selected chain type until they are passed to the context. Their content and
132- * scope can be expanded over time.
134+ * selected chain type until they are passed to the context. If no options are
135+ * configured, the context will be instantiated with no callbacks and for
136+ * mainnet. Their content and scope can be expanded over time.
133137 */
134138typedef struct kernel_ContextOptions kernel_ContextOptions;
135139
@@ -266,7 +270,7 @@ typedef void (*kernel_LogCallback)(void* user_data, const char* message);
266270/* *
267271 * Function signatures for the kernel notifications.
268272 */
269- typedef void (*kernel_NotifyBlockTip)(void * user_data, kernel_SynchronizationState state, kernel_BlockIndex* index);
273+ typedef void (*kernel_NotifyBlockTip)(void * user_data, kernel_SynchronizationState state, const kernel_BlockIndex* index);
270274typedef void (*kernel_NotifyHeaderTip)(void * user_data, kernel_SynchronizationState state, int64_t height, int64_t timestamp, bool presync);
271275typedef void (*kernel_NotifyProgress)(void * user_data, const char * title, int progress_percent, bool resume_possible);
272276typedef void (*kernel_NotifyWarningSet)(void * user_data, kernel_Warning warning, const char * message);
@@ -311,7 +315,7 @@ typedef enum {
311315 * callbacks easier.
312316 */
313317typedef struct {
314- void * user_data; // !< Holds a user-defined opaque structure that is passed to the validation
318+ const void * user_data; // !< Holds a user-defined opaque structure that is passed to the validation
315319 // !< interface callbacks.
316320 kernel_ValidationInterfaceBlockChecked block_checked; // !< Called when a new block has been checked. Contains the
317321 // !< result of its validation.
@@ -326,7 +330,7 @@ typedef struct {
326330 * safe unwinding.
327331 */
328332typedef struct {
329- void * user_data; // !< Holds a user-defined opaque structure that is passed to the notification callbacks.
333+ const void * user_data; // !< Holds a user-defined opaque structure that is passed to the notification callbacks.
330334 kernel_NotifyBlockTip block_tip; // !< The chain's tip was updated to the provided block index.
331335 kernel_NotifyHeaderTip header_tip; // !< A new best block header was added.
332336 kernel_NotifyProgress progress; // !< Reports on current block synchronization progress.
@@ -493,7 +497,8 @@ void kernel_transaction_output_destroy(kernel_TransactionOutput* transaction_out
493497
494498/* *
495499 * @brief Verify if the input at input_index of tx_to spends the script pubkey
496- * under the constraints specified by flags. If the witness flag is set the
500+ * under the constraints specified by flags. If the
501+ * `kernel_SCRIPT_FLAGS_VERIFY_WITNESS` flag is set in the flags bitfield, the
497502 * amount parameter is used. If the taproot flag is set, the spent outputs
498503 * parameter is used to validate taproot transactions.
499504 *
@@ -518,7 +523,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_verify_script(
518523 unsigned int input_index,
519524 unsigned int flags,
520525 kernel_ScriptVerifyStatus* status
521- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 3 );
526+ ) BITCOINKERNEL_ARG_NONNULL(1 , 3 );
522527
523528/* *
524529 * @brief This disables the global internal logger. No log messages will be
@@ -570,7 +575,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_disable_log_category(const kernel_L
570575 */
571576kernel_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_logging_connection_create (
572577 kernel_LogCallback callback,
573- void * user_data,
578+ const void * user_data,
574579 const kernel_LoggingOptions options
575580) BITCOINKERNEL_ARG_NONNULL(1 );
576581
@@ -622,7 +627,7 @@ kernel_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_context_options_c
622627void kernel_context_options_set_chainparams (
623628 kernel_ContextOptions* context_options,
624629 const kernel_ChainParameters* chain_parameters
625- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
630+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
626631
627632/* *
628633 * @brief Set the kernel notifications for the context options. The context
@@ -634,7 +639,7 @@ void kernel_context_options_set_chainparams(
634639void kernel_context_options_set_notifications (
635640 kernel_ContextOptions* context_options,
636641 const kernel_Notifications* notifications
637- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
642+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
638643
639644/* *
640645 * Destroy the context options.
@@ -682,7 +687,7 @@ void kernel_context_destroy(kernel_Context* context);
682687kernel_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_options_create (
683688 const kernel_Context* context,
684689 const char * data_directory
685- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
690+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
686691
687692/* *
688693 * Destroy the chainstate manager options.
@@ -703,7 +708,7 @@ void kernel_chainstate_manager_options_destroy(kernel_ChainstateManagerOptions*
703708kernel_BlockManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_manager_options_create (
704709 const kernel_Context* context,
705710 const char * blocks_directory
706- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
711+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
707712
708713/* *
709714 * @brief Set the number of available worker threads used during validation.
@@ -735,10 +740,10 @@ void kernel_block_manager_options_destroy(kernel_BlockManagerOptions* block_mana
735740 * @return The allocated chainstate manager, or null on error.
736741 */
737742kernel_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_create (
743+ const kernel_Context* context,
738744 kernel_ChainstateManagerOptions* chainstate_manager_options,
739- kernel_BlockManagerOptions* block_manager_options,
740- const kernel_Context* context
741- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL(2 ) BITCOINKERNEL_ARG_NONNULL(3 );
745+ kernel_BlockManagerOptions* block_manager_options
746+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
742747
743748/* *
744749 * Destroy the chainstate manager.
@@ -770,7 +775,7 @@ kernel_ValidationInterface* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_validation_i
770775bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_validation_interface_register (
771776 kernel_Context* context,
772777 kernel_ValidationInterface* validation_interface
773- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
778+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
774779
775780/* *
776781 * @brief Unregister a validation interface from the internal task runner
@@ -784,7 +789,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_validation_interface_register(
784789bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_validation_interface_unregister (
785790 kernel_Context* context,
786791 kernel_ValidationInterface* validation_interface
787- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
792+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
788793
789794/* *
790795 * Destroy the validation interface. This should be done after unregistering it
@@ -860,7 +865,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_load_chainstate(
860865 const kernel_Context* context,
861866 kernel_ChainstateLoadOptions* chainstate_load_options,
862867 kernel_ChainstateManager* chainstate_manager
863- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
868+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
864869
865870/* *
866871 * @brief May be called after kernel_chainstate_manager_load_chainstate to
@@ -877,7 +882,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_load_chainstate(
877882bool kernel_import_blocks (const kernel_Context* context,
878883 kernel_ChainstateManager* chainstate_manager,
879884 const char ** block_file_paths, size_t block_file_paths_len
880- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
885+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
881886
882887/* *
883888 * @brief Process and validate the passed in block with the chainstate
@@ -897,7 +902,7 @@ bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_process_block(
897902 kernel_ChainstateManager* chainstate_manager,
898903 kernel_Block* block,
899904 bool * new_block
900- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
905+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
901906
902907/* *
903908 * @brief Parse a serialized raw block into a new block object.
@@ -985,7 +990,7 @@ kernel_BlockValidationResult kernel_get_block_validation_result_from_block_valid
985990kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_tip (
986991 const kernel_Context* context,
987992 kernel_ChainstateManager* chainstate_manager
988- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
993+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
989994
990995/* *
991996 * @brief Get the block index entry of the genesis block.
@@ -997,7 +1002,7 @@ kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_
9971002kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_genesis (
9981003 const kernel_Context* context,
9991004 kernel_ChainstateManager* chainstate_manager
1000- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
1005+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
10011006
10021007/* *
10031008 * @brief Retrieve a block index by its block hash.
@@ -1011,7 +1016,7 @@ kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_by_ha
10111016 const kernel_Context* context,
10121017 kernel_ChainstateManager* chainstate_manager,
10131018 kernel_BlockHash* block_hash
1014- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
1019+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
10151020
10161021/* *
10171022 * @brief Retrieve a block index by its height in the currently active chain.
@@ -1026,7 +1031,7 @@ kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_by_he
10261031 const kernel_Context* context,
10271032 kernel_ChainstateManager* chainstate_manager,
10281033 int block_height
1029- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 );
1034+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 );
10301035
10311036/* *
10321037 * @brief Return the next block index in the currently active chain, or null if
@@ -1042,7 +1047,7 @@ kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_next_block_index(
10421047 const kernel_Context* context,
10431048 kernel_BlockIndex* block_index,
10441049 kernel_ChainstateManager* chainstate_manager
1045- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
1050+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
10461051
10471052/* *
10481053 * @brief Returns the previous block index in the chain, or null if the current
@@ -1068,7 +1073,7 @@ kernel_Block* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_read_block_from_disk(
10681073 const kernel_Context* context,
10691074 kernel_ChainstateManager* chainstate_manager,
10701075 kernel_BlockIndex* block_index
1071- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
1076+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
10721077
10731078/* *
10741079 * @brief Reads the block undo data the passed in block index points to from
@@ -1083,7 +1088,7 @@ kernel_BlockUndo* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_read_block_undo_from_d
10831088 const kernel_Context* context,
10841089 kernel_ChainstateManager* chainstate_manager,
10851090 kernel_BlockIndex* block_index
1086- ) BITCOINKERNEL_ARG_NONNULL(1 ) BITCOINKERNEL_ARG_NONNULL( 2 ) BITCOINKERNEL_ARG_NONNULL( 3 );
1091+ ) BITCOINKERNEL_ARG_NONNULL(1 , 2 , 3 );
10871092
10881093/* *
10891094 * @brief Destroy the block index.
0 commit comments