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=None, *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