All BOLT #1 messages.

BOLT #1 message type codes.

Get the numeric type code for a message type.

A 32-byte channel identifier.

Use channelId to construct, which validates the length. Use allChannels for connection-level errors (all-zeros channel ID).

Construct a ChannelId from a 32-byte ByteString.

Returns Nothing if the input is not exactly 32 bytes.

>>> channelId (BS.replicate 32 0x00)
Just (ChannelId "\NUL\NUL...")
>>> channelId "too short"
Nothing

The all-zeros channel ID, used for connection-level errors.

Per BOLT #1, setting channel_id to all zeros means the error applies to the connection rather than a specific channel.

The init message (type 16).

The error message (type 17).

The warning message (type 1).

The ping message (type 18).

The pong message (type 19).

The peer_storage message (type 7).

The peer_storage_retrieval message (type 9).

A single TLV record.

A TLV stream (series of TLV records).

Smart constructor for TlvStream that validates records are strictly increasing by type.

Returns Nothing if types are not strictly increasing.

Unsafe constructor for TlvStream that skips validation.

Use only when ordering is already guaranteed (e.g., in decode functions).

TLV decoding errors.

Encode a TLV stream.

Decode a TLV stream with BOLT #1 init_tlvs validation.

This uses the default known types for init messages (1 and 3). For other contexts, use decodeTlvStreamWith with an appropriate predicate.

Decode a TLV stream with configurable known-type predicate.

Per BOLT #1: - Types must be strictly increasing - Unknown even types cause failure - Unknown odd types are skipped

The predicate determines which types are "known" for the context.

Decode a TLV stream without any known-type validation.

This decoder only enforces structural validity: - Types must be strictly increasing - Lengths must not exceed bounds

All records are returned regardless of type. Note: this does NOT enforce the BOLT #1 unknown-even-type rule. Use decodeTlvStreamWith with an appropriate predicate for spec-compliant parsing.

TLV records for init message.

A chain hash (32-byte hash identifying a blockchain).

Construct a chain hash from a 32-byte bytestring.

Returns Nothing if the input is not exactly 32 bytes.

Extract the raw bytes from a chain hash.

A complete message envelope with type, payload, and optional extension.

Encoding errors.

Encode a message to its payload bytes.

Checks that the payload does not exceed 65533 bytes (the maximum possible given the 2-byte type field and 65535-byte message limit).

Encode a message as a complete envelope (type + payload + extension).

Per BOLT #1, the total message size must not exceed 65535 bytes.

Decoding errors.

Decode a message from its type and payload.

Returns the decoded message and any remaining bytes (for extensions). For unknown types, returns an appropriate error.

Decode a complete envelope (type + payload + optional extension).

Per BOLT #1: - Unknown odd message types are ignored (returns Nothing for message) - Unknown even message types cause connection close (returns error) - Invalid extension TLV causes connection close (returns error)

This uses the default policy of treating all extension TLV types as unknown. Use decodeEnvelopeWith for configurable extension handling.

Returns the decoded message (if known) and any extension TLVs.

Decode a complete envelope with configurable extension TLV handling.

The predicate determines which extension TLV types are "known" and should be preserved. Unknown even types cause failure; unknown odd types are skipped.

Use decodeEnvelopeWith (const False) to reject all even extension types (the default behavior of decodeEnvelope).

Use decodeEnvelopeWith (const True) to accept all extension types.

Encode a 16-bit unsigned integer (big-endian).

>>> encodeU16 0x0102
"\SOH\STX"

Encode a 32-bit unsigned integer (big-endian).

>>> encodeU32 0x01020304
"\SOH\STX\ETX\EOT"

Encode a 64-bit unsigned integer (big-endian).

>>> encodeU64 0x0102030405060708
"\SOH\STX\ETX\EOT\ENQ\ACK\a\b"

Encode an 8-bit signed integer.

>>> encodeS8 42
"*"
>>> encodeS8 (-42)
"\214"

Encode a 16-bit signed integer (big-endian two's complement).

>>> encodeS16 0x0102
"\SOH\STX"
>>> encodeS16 (-1)
"\255\255"

Encode a 32-bit signed integer (big-endian two's complement).

>>> encodeS32 0x01020304
"\SOH\STX\ETX\EOT"
>>> encodeS32 (-1)
"\255\255\255\255"

Encode a 64-bit signed integer (big-endian two's complement).

>>> encodeS64 0x0102030405060708
"\SOH\STX\ETX\EOT\ENQ\ACK\a\b"
>>> encodeS64 (-1)
"\255\255\255\255\255\255\255\255"

Encode a truncated 16-bit unsigned integer (0-2 bytes).

Leading zeros are omitted per BOLT #1. Zero encodes to empty.

>>> encodeTu16 0
""
>>> encodeTu16 1
"\SOH"
>>> encodeTu16 256
"\SOH\NUL"

Encode a truncated 32-bit unsigned integer (0-4 bytes).

Leading zeros are omitted per BOLT #1. Zero encodes to empty.

>>> encodeTu32 0
""
>>> encodeTu32 1
"\SOH"
>>> encodeTu32 0x010000
"\SOH\NUL\NUL"

Encode a truncated 64-bit unsigned integer (0-8 bytes).

Leading zeros are omitted per BOLT #1. Zero encodes to empty.

>>> encodeTu64 0
""
>>> encodeTu64 1
"\SOH"
>>> encodeTu64 0x0100000000
"\SOH\NUL\NUL\NUL\NUL"

Encode a signed 64-bit integer using minimal bytes.

Uses the smallest number of bytes that can represent the value in two's complement. Per BOLT #1 Appendix D test vectors.

>>> encodeMinSigned 0
"\NUL"
>>> encodeMinSigned 127
"\DEL"
>>> encodeMinSigned 128
"\NUL\128"
>>> encodeMinSigned (-1)
"\255"
>>> encodeMinSigned (-128)
"\128"
>>> encodeMinSigned (-129)
"\255\DEL"

Encode a BigSize value (variable-length unsigned integer).

>>> encodeBigSize 0
"\NUL"
>>> encodeBigSize 252
"\252"
>>> encodeBigSize 253
"\253\NUL\253"
>>> encodeBigSize 65536
"\254\NUL\SOH\NUL\NUL"

Decode a 16-bit unsigned integer (big-endian).

Decode a 32-bit unsigned integer (big-endian).

Decode a 64-bit unsigned integer (big-endian).

Decode an 8-bit signed integer.

Decode a 16-bit signed integer (big-endian two's complement).

Decode a 32-bit signed integer (big-endian two's complement).

Decode a 64-bit signed integer (big-endian two's complement).

Decode a truncated 16-bit unsigned integer (0-2 bytes).

Returns Nothing if the encoding is non-minimal (has leading zeros).

Decode a truncated 32-bit unsigned integer (0-4 bytes).

Returns Nothing if the encoding is non-minimal (has leading zeros).

Decode a truncated 64-bit unsigned integer (0-8 bytes).

Returns Nothing if the encoding is non-minimal (has leading zeros).

Decode a minimal signed integer (1, 2, 4, or 8 bytes).

Validates that the encoding is minimal: the value could not be represented in fewer bytes. Per BOLT #1 Appendix D test vectors.

Decode a BigSize value with minimality check.