Utils¶

hdwallet.utils.generate_passphrase(length: int = 32) → str¶

Generate a random passphrase.

Parameters:: length (int) – The length of the passphrase (default is 32).
Returns:: A randomly generated passphrase consisting of ASCII letters and digits.
Return type:: str

hdwallet.utils.get_hmac(ecc_name: str) → bytes¶

Return the HMAC seed for the specified elliptic curve algorithm.

Parameters:: ecc_name (str) – The name of the elliptic curve algorithm.
Returns:: The HMAC seed corresponding to the elliptic curve algorithm.
Return type:: bytes

hdwallet.utils.exclude_keys(nested: dict, keys: set) → dict¶

Recursively exclude keys from a nested dictionary based on a set of keys.

Parameters:

nested (dict) – The nested dictionary from which keys are to be excluded.
keys (set) – A set of keys to exclude from the dictionary. Keys are checked after converting ‘-’ to ‘_’.

Returns:

A new dictionary with excluded keys.

Return type:

dict

hdwallet.utils.path_to_indexes(path: str) → List[int]¶

Convert a derivation path string into a list of indexes.

Parameters:: path (str) – The derivation path string, e.g., “m/0’/1/2’/2”. Should follow the format “m/0’/0” or similar.
Returns:: A list of indexes derived from the path, where hardened indexes have the highest bit set (0x80000000).
Return type:: List[int]

hdwallet.utils.indexes_to_path(indexes: List[int]) → str¶

Convert a list of indexes into a derivation path string.

Parameters:: indexes (List[int]) – A list of indexes, where hardened indexes have the highest bit set (0x80000000).
Returns:: The derivation path string generated from the list of indexes.
Return type:: str

hdwallet.utils.normalize_index(index: str | int | Tuple[int, int], hardened: bool = False) → Tuple[int, bool] | Tuple[int, int, bool]¶

Normalize an index or range of indexes for derivation.

Parameters:

index (Union[str, int, Tuple[int, int]]) – The index or range of indexes to normalize. Can be a single non-negative integer, a string representing a single index or range, or a tuple of two integers representing a range. For strings, the format should be “{non-negative-number}” or “{number}-{number}”.
hardened (bool) – Whether the index is hardened (default is False).

Returns:

A tuple representing the normalized index or range of indexes, optionally with hardened flag. For a single index: (index, hardened) For a range of indexes: (from_index, to_index, hardened)

Return type:

Union[Tuple[int, bool], Tuple[int, int, bool]]

hdwallet.utils.normalize_derivation(path: str | None = None, indexes: List[int] | None = None) → Tuple[str, List[int], List[tuple]]¶

Normalize a derivation path string or indexes into a consistent format.

Parameters:

path (Optional[str]) – The derivation path string to normalize, e.g., “m/0’/1/2’/2”. If provided, indexes should be None. If path is None, a default path “m/” is returned.
indexes (Optional[List[int]]) – A list of indexes to convert into a derivation path string. If provided, path should be None.

Returns:

A tuple containing the normalized derivation path string, list of indexes, and list of tuples representing derivation steps. The tuple structure: (normalized_path, normalized_indexes, derivations) where derivations is a list of tuples (index, hardened) or (from_index, to_index, hardened).

Return type:

Tuple[str, List[int], List[tuple]]

hdwallet.utils.index_tuple_to_integer(index: Tuple[int, bool] | Tuple[int, int, bool]) → int¶

Convert a tuple representing an index or range of indexes into a single integer.

Parameters:: index (Union[Tuple[int, bool], Tuple[int, int, bool]]) – The tuple representing an index or range of indexes. For a single index: (index, hardened) For a range of indexes: (from_index, to_index, hardened)
Returns:: The integer representation of the index, with hardening flag applied if present.
Return type:: int

hdwallet.utils.index_tuple_to_string(index: Tuple[int, bool] | Tuple[int, int, bool]) → str¶

Convert a tuple representing an index or range of indexes into a string representation.

Parameters:: index (Union[Tuple[int, bool], Tuple[int, int, bool]]) – The tuple representing an index or range of indexes. For a single index: (index, hardened) For a range of indexes: (from_index, to_index, hardened)
Returns:: The string representation of the index or range of indexes.
Return type:: str

hdwallet.utils.index_string_to_tuple(index: str) → Tuple[int, bool]¶

Convert a string representation of an index into a tuple.

Parameters:: index (str) – The string representation of the index, which may include a trailing apostrophe (‘).
Returns:: A tuple representing the index and whether it is hardened (True) or not (False).
Return type:: Tuple[int, bool]

hdwallet.utils.xor(data_1: bytes, data_2: bytes) → bytes¶

Perform bitwise XOR operation between two bytes objects.

Parameters:

data_1 (bytes) – The first bytes object for XOR operation.
data_2 (bytes) – The second bytes object for XOR operation. It must be of the same length as data_1.

Returns:

The result of XOR operation as a bytes object.

Return type:

bytes

hdwallet.utils.add_no_carry(data_1: bytes, data_2: bytes) → bytes¶

Perform addition without carry between two bytes objects.

Parameters:

data_1 (bytes) – The first bytes object for addition without carry.
data_2 (bytes) – The second bytes object for addition without carry. It must be of the same length as data_1.

Returns:

The result of addition without carry as a bytes object.

Return type:

bytes

hdwallet.utils.multiply_scalar_no_carry(data: bytes, scalar: int) → bytes¶

Multiply each byte in a bytes object by a scalar without carry.

Parameters:

data (bytes) – The bytes object to multiply.
scalar (int) – The scalar value to multiply each byte by.

Returns:

The result of multiplying each byte by the scalar, without carry, as a bytes object.

Return type:

bytes

hdwallet.utils.is_bits_set(value: int, bit_num: int) → bool¶

Check if a specific bit in an integer value is set (i.e., equals 1).

Parameters:

value (int) – The integer value to check.
bit_num (int) – The bit number to check (0-indexed, from the right).

Returns:

True if the specified bit in value is set (equals 1), False otherwise.

Return type:

bool

hdwallet.utils.are_bits_set(value: int, bit_mask: int) → bool¶

Check if specific bits in an integer value are set according to a bitmask.

Parameters:

value (int) – The integer value to check.
bit_mask (int) – The bitmask representing which bits to check. Bits set to 1 in the bitmask will be checked in value.

Returns:

True if any of the bits set in bit_mask are also set in value, False otherwise.

Return type:

bool

hdwallet.utils.set_bit(value: int, bit_num: int) → int¶

Set a specific bit in an integer value to 1.

Parameters:

value (int) – The integer value in which to set the bit.
bit_num (int) – The bit number to set (0-indexed, from the right).

Returns:

The integer value with the specified bit set to 1.

Return type:

int

hdwallet.utils.set_bits(value: int, bit_mask: int) → int¶

Set specific bits in an integer value according to a bitmask.

Parameters:

value (int) – The integer value in which to set the bits.
bit_mask (int) – The bitmask representing which bits to set. Bits set to 1 in the bitmask will be set in value.

Returns:

The integer value with the specified bits set according to the bitmask.

Return type:

int

hdwallet.utils.reset_bit(value: int, bit_num: int) → int¶

Reset (clear) a specific bit in an integer value to 0.

Parameters:

value (int) – The integer value in which to reset the bit.
bit_num (int) – The bit number to reset (0-indexed, from the right).

Returns:

The integer value with the specified bit reset to 0.

Return type:

int

hdwallet.utils.reset_bits(value: int, bit_mask: int) → int¶

Reset (clear) specific bits in an integer value according to a bitmask.

Parameters:

value (int) – The integer value in which to reset the bits.
bit_mask (int) – The bitmask representing which bits to reset. Bits set to 1 in the bitmask will be cleared in value.

Returns:

The integer value with the specified bits reset according to the bitmask.

Return type:

int

hdwallet.utils.get_bytes(data: AnyStr, unhexlify: bool = True) → bytes¶

Convert input data to bytes format.

Parameters:

data (Union[bytes, str]) – The input data to convert. Can be bytes or string.
unhexlify (bool) – Flag indicating whether to interpret strings as hexadecimal (default True).

Returns:

The input data converted to bytes format.

Return type:

bytes

hdwallet.utils.bytes_reverse(data: bytes) → bytes¶

Reverse the order of bytes in a bytes object.

Parameters:: data (bytes) – The bytes object to reverse.
Returns:: The bytes object with its byte order reversed.
Return type:: bytes

hdwallet.utils.bytes_to_string(data: bytes | str) → str¶

Convert bytes or string data to a hexadecimal string representation.

Parameters:: data (Union[bytes, str]) – The bytes or string data to convert to hexadecimal string.
Returns:: The hexadecimal string representation of the input data.
Return type:: str

hdwallet.utils.bytes_to_integer(data: bytes, endianness: Literal['little', 'big'] = 'big', signed: bool = False) → int¶

Convert bytes to an integer based on specified endianness and signedness.

Parameters:

data (bytes) – The bytes object to convert to an integer.
endianness (Literal["little", "big"]) – The byte order (“little” or “big”).
signed (bool) – Flag indicating whether the integer is signed (default False).

Returns:

The integer value converted from bytes.

Return type:

int

hdwallet.utils.integer_to_bytes(data: int, bytes_num: int | None = None, endianness: Literal['little', 'big'] = 'big', signed: bool = False) → bytes¶

Convert an integer to bytes based on specified parameters.

Parameters:

data (int) – The integer to convert to bytes.
bytes_num (Optional[int]) – Optional number of bytes to use for the conversion. If not provided, it is calculated based on the integer’s bit length.
endianness (Literal["little", "big"]) – The byte order (“little” or “big”).
signed (bool) – Flag indicating whether the integer is signed (default False).

Returns:

The bytes object representing the integer.

Return type:

bytes

hdwallet.utils.integer_to_binary_string(data: int, zero_pad_bit_len: int = 0) → str¶

Convert an integer to a binary string representation.

Parameters:

data (int) – The integer to convert to binary string.
zero_pad_bit_len (int) – Optional number of bits to zero-pad the binary string (default 0).

Returns:

The binary string representation of the integer.

Return type:

str

hdwallet.utils.binary_string_to_integer(data: bytes | str) → int¶

Convert a binary string representation to an integer.

Parameters:: data (Union[bytes, str]) – The binary string or bytes object to convert to an integer.
Returns:: The integer value converted from the binary representation.
Return type:: int

hdwallet.utils.bytes_to_binary_string(data: bytes, zero_pad_bit_len: int = 0) → str¶

Convert bytes to a binary string representation.

Parameters:

data (bytes) – The bytes object to convert to binary string.
zero_pad_bit_len (int) – Optional number of bits to zero-pad the binary string (default 0).

Returns:

The binary string representation of the bytes.

Return type:

str

hdwallet.utils.binary_string_to_bytes(data: bytes | str, zero_pad_byte_len: int = 0) → bytes¶

Convert a binary string representation to bytes.

Parameters:

data (Union[bytes, str]) – The binary string or bytes object to convert to bytes.
zero_pad_byte_len (int) – Optional number of bytes to zero-pad the resulting bytes object (default 0).

Returns:

The bytes object converted from the binary representation.

Return type:

bytes

hdwallet.utils.decode(data: bytes | str, encoding: str = 'utf-8') → str¶

Decode bytes or return a string unchanged.

Parameters:

data (Union[bytes, str]) – The bytes or string data to decode.
encoding (str) – The encoding to use when decoding bytes (default is ‘utf-8’).

Returns:

The decoded string if data is bytes; otherwise, returns the input string unchanged.

Return type:

str

hdwallet.utils.encode(data: bytes | str, encoding: str = 'utf-8') → bytes¶

Encode string or return bytes unchanged.

Parameters:

data (Union[bytes, str]) – The string or bytes data to encode.
encoding (str) – The encoding to use when encoding a string to bytes (default is ‘utf-8’).

Returns:

The encoded bytes if data is string; otherwise, returns the input bytes unchanged.

Return type:

bytes

hdwallet.utils.convert_bits(data: bytes | List[int], from_bits: int, to_bits: int) → List[int] | None¶

Convert data represented by ‘from_bits’ into ‘to_bits’ per element.

Parameters:

data (Union[bytes, List[int]]) – The data to convert, represented as bytes or a list of integers.
from_bits (int) – Number of bits each element of ‘data’ represents initially.
to_bits (int) – Number of bits each element of the result should represent after conversion.

Returns:

The converted data as a list of integers, or None if conversion fails.

Return type:

Optional[List[int]]

hdwallet.utils.bytes_chunk_to_words(bytes_chunk: bytes, words_list: List[str], endianness: Literal['little', 'big']) → List[str]¶

Convert a bytes chunk into a list of words based on a given word list and endianness.

Parameters:

bytes_chunk (bytes) – The bytes chunk to convert into words.
words_list (List[str]) – The list of words to choose from when converting.
endianness (Literal["little", "big"]) – The endianness to use when interpreting the bytes chunk (“little” or “big”).

Returns:

A list of three words selected from words_list based on the bytes chunk.

Return type:

List[str]

hdwallet.utils.words_to_bytes_chunk(word_1: str, word_2: str, word_3: str, words_list: List[str], endianness: Literal['little', 'big']) → bytes¶

Convert three words into a bytes chunk based on a given word list and endianness.

Parameters:

word_1 (str) – The first word to convert.
word_2 (str) – The second word to convert.
word_3 (str) – The third word to convert.
words_list (List[str]) – The list of words from which to select the words.
endianness (Literal["little", "big"]) – The endianness to use when encoding the chunk into bytes (“little” or “big”).

Returns:

The bytes chunk representing the three words.

Return type:

bytes