bech32.h File Reference

Include dependency graph for bech32.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	bech32_decoder_state
	The state of a Bech32 decoder. More...
struct	bech32_encoder_state
	The state of a Bech32 encoder. More...

Typedefs
typedef uint_fast32_t	bech32_checksum_t
typedef uint_least32_t	bech32_constant_t

Functions
ssize_t	bech32_address_decode (unsigned char *restrict program, size_t n_program, const char *restrict address, size_t n_address, size_t *restrict n_hrp, unsigned *restrict version)
	Decodes a Bech32 address into a Segregated Witness program. More...
ssize_t	bech32_address_encode (char *restrict address, size_t n_address, const unsigned char *restrict program, size_t n_program, const char *restrict hrp, size_t n_hrp, unsigned version)
	Encodes a Segregated Witness program into a Bech32 address. More...
ssize_t	bech32_decode_begin (struct bech32_decoder_state *restrict state, const char *restrict in, size_t n_in)
	Begins a Bech32 decoding. More...
static size_t	bech32_decode_bits_remaining (const struct bech32_decoder_state *restrict state)
	Returns the number of data bits remaining in the Bech32 encoding, including any padding bits but excluding the checksum. More...
enum bech32_error	bech32_decode_data (struct bech32_decoder_state *restrict state, unsigned char *restrict out, size_t nbits_out)
	Pulls data from the Bech32 decoder. More...
ssize_t	bech32_decode_finish (struct bech32_decoder_state *restrict state, bech32_constant_t constant)
	Finishes a Bech32 decoding. More...
enum bech32_error	bech32_encode_begin (struct bech32_encoder_state *restrict state, char *restrict out, size_t n_out, const char *restrict hrp, size_t n_hrp)
	Begins a Bech32 encoding. More...
enum bech32_error	bech32_encode_data (struct bech32_encoder_state *restrict state, const unsigned char *restrict in, size_t nbits_in)
	Feeds data to the Bech32 encoder. More...
enum bech32_error	bech32_encode_finish (struct bech32_encoder_state *restrict state, bech32_constant_t constant)
	Finishes a Bech32 encoding. More...
size_t	bech32_encoded_size (size_t n_hrp, size_t nbits_in, size_t n_pad)
	Returns the size of the Bech32 encoding of the specified number of data bits. More...

Variables
static const size_t	BECH32_CHECKSUM_SIZE = 6
static const size_t	BECH32_HRP_MAX_SIZE = BECH32_MAX_SIZE - 1 - BECH32_CHECKSUM_SIZE
static const size_t	BECH32_HRP_MIN_SIZE = 1
static const size_t	BECH32_MAX_SIZE = 90
static const size_t	BECH32_MIN_SIZE = BECH32_HRP_MIN_SIZE + 1 + BECH32_CHECKSUM_SIZE
static const bech32_constant_t	BECH32M_CONST = UINT32_C(0x2bc830a3)
static const size_t	SEGWIT_ADDRESS_MIN_SIZE
static const size_t	WITNESS_PROGRAM_MAX_SIZE = 40
static const size_t	WITNESS_PROGRAM_MIN_SIZE = 2
static const size_t	WITNESS_PROGRAM_PKH_SIZE = 20
static const size_t	WITNESS_PROGRAM_SH_SIZE = 32
static const size_t	WITNESS_PROGRAM_TR_SIZE = 32

---

Data Structure Documentation

bech32_decoder_state

struct bech32_decoder_state

The state of a Bech32 decoder.

Data Fields
bech32_checksum_t	bits	The bits that have been consumed by the decoder but that do not yet appear in the output. Only the nbits least significant bits of this field are valid.
bech32_checksum_t	chk	The intermediate checksum state.
const char *restrict	in	A pointer to the next character that the decoder will consume.
size_t	n_in	The number of characters of input remaining at in.
size_t	nbits	The number of bits that have been consumed by the decoder but that do not yet appear in the output.

bech32_encoder_state

struct bech32_encoder_state

The state of a Bech32 encoder.

Data Fields
bech32_checksum_t	bits	The bits that have been consumed by the encoder but that do not yet appear in the output. Only the nbits least significant bits of this field are valid.
bech32_checksum_t	chk	The intermediate checksum state.
size_t	n_out	The number of characters of output buffer space remaining at out.
size_t	nbits	The number of bits that have been consumed by the encoder but that do not yet appear in the output.
char *restrict	out	A pointer to the next character that the encoder will produce.

Function Documentation

bech32_address_decode()

ssize_t bech32_address_decode	(	unsigned char *restrict	program,
		size_t	n_program,
		const char *restrict	address,
		size_t	n_address,
		size_t *restrict	n_hrp,
		unsigned *restrict	version
	)

Decodes a Bech32 address into a Segregated Witness program.

Parameters

[out]	program	A pointer to a buffer into which the witness program is to be written. This function will never write more than 40 bytes to this buffer.
	n_program	The size of the output buffer at program.
[in]	address	A pointer to the Bech32 address to decode. It may be in either the uppercase or lowercase form.
	n_address	The size of the address at address, not including any null terminator that may be present but is not required.
[out]	n_hrp	A pointer to a variable that is to receive the size of the human-readable prefix in characters.
[out]	version	A pointer to a variable that is to receive the witness version, which will be between 0 and 16. Addresses using witness version 0 are decoded using Bech32; all others are decoded using Bech32m.

Returns

The size of the witness program if the decoding was successful, or a negative number if an error occurred, which may be BECH32_TOO_SHORT because the address is too short, BECH32_TOO_LONG because the address is too long, BECH32_NO_SEPARATOR because the address contains no separator, BECH32_HRP_TOO_SHORT because the human-readable prefix is empty, BECH32_HRP_TOO_LONG because no separator was found, BECH32_HRP_ILLEGAL_CHAR because the human-readable prefix contains an illegal character, BECH32_ILLEGAL_CHAR because the address contains an illegal character, BECH32_MIXED_CASE because the address uses mixed case, SEGWIT_PROGRAM_TOO_SHORT because the witness program is too short, SEGWIT_PROGRAM_TOO_LONG because the witness program is too long, BECH32_BUFFER_INADEQUATE because n_program is too small, SEGWIT_VERSION_ILLEGAL because the witness version is illegal, SEGWIT_PROGRAM_ILLEGAL_SIZE because the witness program is of an illegal size for the encoded witness version, BECH32_PADDING_ERROR because of a padding error, or BECH32_CHECKSUM_FAILURE because checksum verification failed.

bech32_address_encode()

ssize_t bech32_address_encode	(	char *restrict	address,
		size_t	n_address,
		const unsigned char *restrict	program,
		size_t	n_program,
		const char *restrict	hrp,
		size_t	n_hrp,
		unsigned	version
	)

Encodes a Segregated Witness program into a Bech32 address.

Parameters

[out]	address	A pointer to a buffer into which the address is to be written. This function will never write more than 91 characters to this buffer, including the null terminator.
	n_address	The size of the output buffer at address.
[in]	program	A pointer to the witness program to encode.
	n_program	The size of the witness program at program.
[in]	hrp	A pointer to a character sequence specifying the human-readable prefix to use. Should be "bc" for Bitcoin mainnet or "tb" for Bitcoin testnet.
	n_hrp	The size of the human-readable prefix, not including any null terminator that may be present but is not required.
	version	The witness version to use. Must be between 0 and 16. Addresses using witness version 0 are encoded using Bech32; all others are encoded using Bech32m.

Returns

The size of the address (not including the null terminator) if the encoding was successful, or a negative number if an error occurred, which may be SEGWIT_PROGRAM_TOO_SHORT because the witness program is too short, SEGWIT_PROGRAM_TOO_LONG because the witness program is too long, SEGWIT_VERSION_ILLEGAL because the witness version is illegal, SEGWIT_PROGRAM_ILLEGAL_SIZE because the witness program is of an illegal size for the specified witness version, BECH32_BUFFER_INADEQUATE because n_address is too small, BECH32_HRP_TOO_SHORT because the human-readable prefix is empty, BECH32_HRP_TOO_LONG because the human-readable prefix is too long, BECH32_HRP_ILLEGAL_CHAR because the human-readable prefix contains an illegal character, or BECH32_CHECKSUM_FAILURE because the encoding failed its internal checksum check (due to a software bug or hardware failure).

bech32_decode_begin()

ssize_t bech32_decode_begin	(	struct bech32_decoder_state *restrict	state,
		const char *restrict	in,
		size_t	n_in
	)

Begins a Bech32 decoding.

Parameters

[out]	state	A pointer to the decoder state to initialize.
[in]	in	A pointer to the encoding to be decoded.
	n_in	The size of the encoding at in.

Returns

The size of the human-readable prefix of the encoding at in if the parameters were accepted and the state structure was initialized, or a negative number if an error occurred, which may be BECH32_TOO_SHORT because the encoding is too short, BECH32_TOO_LONG because the encoding is too long, BECH32_NO_SEPARATOR because the encoding contains no separator, BECH32_HRP_TOO_SHORT because the human-readable prefix is empty, BECH32_HRP_TOO_LONG because the human-readable prefix is too long, BECH32_HRP_ILLEGAL_CHAR because the human-readable prefix contains an illegal character, BECH32_ILLEGAL_CHAR because the encoding contains an illegal character, or BECH32_MIXED_CASE because the encoding uses mixed case.

bech32_decode_bits_remaining()

static size_t bech32_decode_bits_remaining ( const struct bech32_decoder_state *restrict  state )

inlinestatic

Returns the number of data bits remaining in the Bech32 encoding, including any padding bits but excluding the checksum.

Parameters

[in]

state

A pointer to the decoder state, which must previously have been initialized by a call to bech32_decode_begin().

bech32_decode_data()

enum bech32_error bech32_decode_data	(	struct bech32_decoder_state *restrict	state,
		unsigned char *restrict	out,
		size_t	nbits_out
	)

Pulls data from the Bech32 decoder.

Parameters

[in,out]	state	A pointer to the decoder state, which must previously have been initialized by a call to bech32_decode_begin().
[out]	out	A pointer to a buffer into which the decoder is to place the decoded data.
	nbits_out	The number of data bits to place in the buffer at out. If this is not an integer multiple of CHAR_BIT, then the valid bits in the last output byte will be aligned to the least significant bit.

Returns

0 if the requested data bits were produced, or a negative number if an error occurred, which may be BECH32_BUFFER_INADEQUATE because insufficient characters remain in the input buffer or BECH32_ILLEGAL_CHAR because the decoder encountered an illegal character in the encoding.

bech32_decode_finish()

ssize_t bech32_decode_finish	(	struct bech32_decoder_state *restrict	state,
		bech32_constant_t	constant
	)

Finishes a Bech32 decoding.

Parameters

[in,out]	state	A pointer to the decoder state, which must previously have been initialized by a call to bech32_decode_begin().
	constant	The constant to add to the checksum. It should be 1 for the original Bech32 specification or BECH32M_CONST for Bech32m.

Returns

The number of unconsumed padding bits remaining at the end of the encoding if the decoder successfully finished the decoding and verified the checksum, or a negative number if an error occurred, which may be BECH32_PADDING_ERROR because of a padding error (more than 5 data bits remain unconsumed or an unconsumed data bit is set), BECH32_ILLEGAL_CHAR because the decoder encountered an illegal character in the encoding, or BECH32_CHECKSUM_FAILURE because checksum verification failed.

bech32_encode_begin()

enum bech32_error bech32_encode_begin	(	struct bech32_encoder_state *restrict	state,
		char *restrict	out,
		size_t	n_out,
		const char *restrict	hrp,
		size_t	n_hrp
	)

Begins a Bech32 encoding.

Parameters

[out]	state	A pointer to the encoder state to initialize.
[out]	out	A pointer to a buffer into which the encoder is to write the encoding. Call bech32_encoded_size() to calculate the required size of this buffer.
	n_out	The size of the buffer at out.
[in]	hrp	A pointer to a character sequence specifying the human-readable prefix of the encoding.
	n_hrp	The size of the human-readable prefix in characters.

Returns

0 if the parameters were accepted and the state structure was initialized, or a negative number if an error occurred, which may be BECH32_HRP_TOO_SHORT because the human-readable prefix is empty, BECH32_HRP_TOO_LONG because the human-readable prefix is too long, BECH32_HRP_ILLEGAL_CHAR because the human-readable prefix contains an illegal character, or BECH32_BUFFER_INADEQUATE because n_out is too small.

bech32_encode_data()

enum bech32_error bech32_encode_data	(	struct bech32_encoder_state *restrict	state,
		const unsigned char *restrict	in,
		size_t	nbits_in
	)

Feeds data to the Bech32 encoder.

Parameters

[in,out]	state	A pointer to the encoder state, which must previously have been initialized by a call to bech32_encode_begin().
[in]	in	A pointer to the data to encode.
	nbits_in	The number of valid bits in the data at in. If this is not an integer multiple of CHAR_BIT, then the valid bits in the last input byte must be aligned to the least significant bit.

Returns

0 if the given data bits were consumed, or a negative number if an error occurred, which may be BECH32_BUFFER_INADEQUATE because insufficient space remains in the output buffer.

bech32_encode_finish()

enum bech32_error bech32_encode_finish	(	struct bech32_encoder_state *restrict	state,
		bech32_constant_t	constant
	)

Finishes a Bech32 encoding.

Parameters

[in,out]	state	A pointer to the encoder state, which must previously have been initialized by a call to bech32_encode_begin().
	constant	The constant to add to the checksum. It should be 1 for the original Bech32 specification or BECH32M_CONST for Bech32m.

Returns

0 if the encoder successfully finished the encoding, or a negative number if an error occurred, which may be BECH32_BUFFER_INADEQUATE because insufficient space remains in the output buffer or BECH32_CHECKSUM_FAILURE because the encoding failed its internal checksum check (due to a software bug or hardware failure).

bech32_encoded_size()

size_t bech32_encoded_size	(	size_t	n_hrp,
		size_t	nbits_in,
		size_t	n_pad
	)

Returns the size of the Bech32 encoding of the specified number of data bits.

Parameters

n_hrp	The size of the human-readable prefix in characters.
nbits_in	The number of data bits to be encoded.
n_pad	The number of excess bytes to include in the returned size.

Returns

The size of the specified Bech32 encoding, or SIZE_MAX upon overflow.

Variable Documentation

SEGWIT_ADDRESS_MIN_SIZE

const size_t SEGWIT_ADDRESS_MIN_SIZE

static

Initial value:

= BECH32_HRP_MIN_SIZE + 1 + 1 +
            ((WITNESS_PROGRAM_MIN_SIZE * CHAR_BIT + 4) / 5) + BECH32_CHECKSUM_SIZE