Context

The library provides a built-in static constant kernel context. This static context offers only limited functionality. It detects and self-checks the correct sha256 implementation, initializes the random number generator and self-checks the secp256k1 static context. It is used internally for otherwise "context-free" operations. This means that the user is not required to initialize their own context before using the library.

The user should create their own context for passing it to state-rich validation functions and holding callbacks for kernel events.

Error handling

Functions communicate an error through their return types, usually returning a nullptr, or false if an error is encountered. Additionally, verification functions, e.g. for scripts, may communicate more detailed error information through status code out parameters.

Fine-grained validation information is communicated through the validation interface.

The kernel notifications issue callbacks for errors. These are usually indicative of a system error. If such an error is issued, it is recommended to halt and tear down the existing kernel objects. Remediating the error may require system intervention by the user.

Pointer and argument conventions

The user is responsible for de-allocating the memory owned by pointers returned by functions. Typically pointers returned by *_create(...) functions can be de-allocated by corresponding *_destroy(...) functions.

A function that takes pointer arguments makes no assumptions on their lifetime. Once the function returns the user can safely de-allocate the passed in arguments.

Pointers passed by callbacks are not owned by the user and are only valid for the duration of the callback. They are always marked as const and must not be de-allocated by the user.

Array lengths follow the pointer argument they describe.