Internal API Documentation

In addition to the public API, the classes and functions documented here are available for use within HWI itself.

Base 58 conversion utilities

hwilib._base58.encode(b)

Encode bytes to a base58-encoded string

Parameters:: b (bytes) – Bytes to encode
Returns:: Base58 encoded string of b
Return type:: str

hwilib._base58.decode(s)

Decode a base58-encoding string, returning bytes

Parameters:: s (str) – Base48 string to decode
Returns:: Bytes encoded by s
Return type:: bytes

hwilib._base58.decode_check(s)

Decode a Base58Check encoded string, returning bytes

Parameters:: s (str) – Base58 string to decode
Returns:: Bytes encoded by s
Return type:: bytes

hwilib._base58.get_xpub_fingerprint(s)

Get the parent fingerprint from an extended public key

Parameters:: s (str) – The extended pubkey
Returns:: The parent fingerprint bytes
Return type:: bytes

hwilib._base58.get_xpub_fingerprint_hex(xpub)

Get the parent fingerprint as a hex string from an extended public key

Parameters:

s – The extended pubkey
xpub (str)

Returns:

The parent fingerprint as a hex string

Return type:

str

hwilib._base58.to_address(b, version)

Base58 Check Encode the data with the version number. Used to encode legacy style addresses.

Parameters:

b (bytes) – The data to encode
version (bytes) – The version number to encode with

Returns:

The Base58 Check Encoded string

Return type:

str

hwilib._base58.xpub_to_pub_hex(xpub)

Get the public key as a string from the extended public key.

Parameters:: xpub (str) – The extended pubkey
Returns:: The pubkey hex string
Return type:: str

hwilib._base58.xpub_to_xonly_pub_hex(xpub)

Get the public key as a string from the extended public key.

Parameters:: xpub (str) – The extended pubkey
Returns:: The pubkey hex string
Return type:: str

hwilib._base58.xpub_main_2_test(xpub)

Convert an extended pubkey from mainnet version to testnet version.

Parameters:: xpub (str) – The extended pubkey
Returns:: The extended pubkey re-encoded using testnet version bytes
Return type:: str

Bech32 Conversion Utilities

Reference implementation for Bech32 and segwit addresses.

class hwilib._bech32.Encoding(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): Enumeration type to list the various supported encodings.

hwilib._bech32.bech32_polymod(values)

Internal function that computes the Bech32 checksum.

Parameters:: values (List[int])
Return type:: int

hwilib._bech32.bech32_hrp_expand(hrp)

Expand the HRP into values for checksum computation.

Parameters:: hrp (str)
Return type:: List[int]

hwilib._bech32.bech32_verify_checksum(hrp, data)

Verify a checksum given HRP and converted data characters.

Parameters:

hrp (str)
data (List[int])

Return type:

Encoding | None

hwilib._bech32.bech32_create_checksum(encoding, hrp, data)

Compute the checksum values given HRP and data.

Parameters:

encoding (Encoding)
hrp (str)
data (List[int])

Return type:

List[int]

hwilib._bech32.bech32_encode(encoding, hrp, data)

Compute a Bech32 string given HRP and data values.

Parameters:

encoding (Encoding)
hrp (str)
data (List[int])

Return type:

str

hwilib._bech32.bech32_decode(bech)

Validate a Bech32 string, and determine HRP and data.

Parameters:: bech (str)
Return type:: Tuple[Encoding | None, str | None, List[int] | None]

hwilib._bech32.convertbits(data, frombits, tobits, pad=True)

General power-of-2 base conversion.

Parameters:

data (bytes | List[int])
frombits (int)
tobits (int)
pad (bool)

Return type:

List[int] | None

hwilib._bech32.decode(hrp, addr)

Decode a segwit address.

Parameters:

hrp (str)
addr (str)

Return type:

Tuple[int | None, List[int] | None]

hwilib._bech32.encode(hrp, witver, witprog)

Encode a segwit address.

Parameters:

hrp (str)
witver (int)
witprog (bytes)

Return type:

str | None

Bitcoin Script utilities

hwilib._script.is_opreturn(script)

Determine whether a script is an OP_RETURN output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is an OP_RETURN output script
Return type:: bool

hwilib._script.is_p2sh(script)

Determine whether a script is a P2SH output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2SH output script
Return type:: bool

hwilib._script.is_p2pkh(script)

Determine whether a script is a P2PKH output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2PKH output script
Return type:: bool

hwilib._script.is_p2pk(script)

Determine whether a script is a P2PK output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2PK output script
Return type:: bool

hwilib._script.is_witness(script)

Determine whether a script is a segwit output script. If so, also returns the witness version and witness program.

Parameters:: script (bytes) – The script
Returns:: A tuple of a bool indicating whether the script is a segwit output script, an int representing the witness version, and the bytes of the witness program.
Return type:: Tuple[bool, int, bytes]

hwilib._script.is_p2wpkh(script)

Determine whether a script is a P2WPKH output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2WPKH output script
Return type:: bool

hwilib._script.is_p2wsh(script)

Determine whether a script is a P2WSH output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2WSH output script
Return type:: bool

hwilib._script.is_p2tr(script)

Determine whether a script is a P2TR output script.

Parameters:: script (bytes) – The script
Returns:: Whether the script is a P2TR output script
Return type:: bool

hwilib._script.parse_multisig(script)

Determine whether a script is a multisig script. If so, determine the parameters of that multisig.

Parameters:: script (bytes) – The script
Returns:: None if the script is not multisig. If multisig, returns a tuple of the number of signers required, and a sequence of public key bytes.
Return type:: Tuple[int, Sequence[bytes]] | None

Bitcoin Object Python Serializations

Modified from the test/test_framework/mininode.py file from the Bitcoin repository

class hwilib._serialize.Readable(*args, **kwargs)

Parameters:

args (Any)
kwargs (Any)

Return type:

Any

class hwilib._serialize.Deserializable(*args, **kwargs)

Parameters:

args (Any)
kwargs (Any)

Return type:

Any

class hwilib._serialize.Serializable(*args, **kwargs)

Parameters:

args (Any)
kwargs (Any)

Return type:

Any

hwilib._serialize.ser_compact_size(size)

Serialize an integer using Bitcoin’s compact size unsigned integer serialization.

Parameters:: size (int) – The int to serialize
Returns:: The int serialized as a compact size unsigned integer
Return type:: bytes

hwilib._serialize.deser_compact_size(f)

Deserialize a compact size unsigned integer from the beginning of the byte stream.

Parameters:: f (Readable) – The byte stream
Returns:: The integer that was serialized
Return type:: int

hwilib._serialize.deser_string(f)

Deserialize a variable length byte string serialized with Bitcoin’s variable length string serialization from a byte stream.

Parameters:: f (Readable) – The byte stream
Returns:: The byte string that was serialized
Return type:: bytes

hwilib._serialize.ser_string(s)

Serialize a byte string with Bitcoin’s variable length string serialization.

Parameters:: s (bytes) – The byte string to be serialized
Returns:: The serialized byte string
Return type:: bytes

hwilib._serialize.deser_uint256(f)

Deserialize a 256 bit integer serialized with Bitcoin’s 256 bit integer serialization from a byte stream.

Parameters:: f (Readable) – The byte stream.
Returns:: The integer that was serialized
Return type:: int

hwilib._serialize.ser_uint256(u)

Serialize a 256 bit integer with Bitcoin’s 256 bit integer serialization.

Parameters:: u (int) – The integer to serialize
Returns:: The serialized 256 bit integer
Return type:: bytes

hwilib._serialize.uint256_from_str(s)

Deserialize a 256 bit integer serialized with Bitcoin’s 256 bit integer serialization from a byte string.

Parameters:: s (bytes) – The byte string
Returns:: The integer that was serialized
Return type:: int

hwilib._serialize.deser_vector(f, c)

Deserialize a vector of objects with Bitcoin’s object vector serialization from a byte stream.

Parameters:

f (Readable) – The byte stream
c (Callable[[], D]) – The class of object to deserialize for each object in the vector

Returns:

A list of objects that were serialized

Return type:

List[D]

hwilib._serialize.ser_vector(v)

Serialize a vector of objects with Bitcoin’s object vector serialzation.

Parameters:: v (Sequence[Serializable]) – The list of objects to serialize
Returns:: The serialized objects
Return type:: bytes

hwilib._serialize.deser_string_vector(f)

Deserialize a vector of byte strings from a byte stream.

Parameters:: f (Readable) – The byte stream
Returns:: The list of byte strings that were serialized
Return type:: List[bytes]

hwilib._serialize.ser_string_vector(v)

Serialize a list of byte strings as a vector of byte strings.

Parameters:: v (List[bytes]) – The list of byte strings to serialize
Returns:: The serialized list of byte strings
Return type:: bytes

hwilib._serialize.ser_sig_der(r, s)

Serialize the r and s values of an ECDSA signature using DER.

Parameters:

r (bytes) – The r value bytes
s (bytes) – The s value bytes

Returns:

The DER encoded signature

Return type:

bytes

hwilib._serialize.ser_sig_compact(r, s, recid)

Serialize the r and s values of an ECDSA signature using the compact signature serialization scheme.

Parameters:

r (bytes) – The r value bytes
s (bytes) – The s value bytes
recid (bytes)

Returns:

The compact signature

Return type:

bytes