Presentation context for feature flags.

Per BOLT #9, features are presented in different message contexts:

• Init - the init message
• NodeAnn - node_announcement messages
• ChanAnn - channel_announcement messages (normal)
• ChanAnnOdd - channel_announcement, always odd (optional)
• ChanAnnEven - channel_announcement, always even (required)
• Invoice - BOLT 11 invoices
• Blinded - allowed_features field of a blinded path
• ChanType - channel_type field when opening channels

Check if a context is a channel announcement context (C, C-, or C+).

For channel contexts with forced parity, return Just the required parity: True for even (C+), False for odd (C-). Returns Nothing for contexts without forced parity.

A bit index into a feature vector. Bit 0 is the least significant bit.

Valid range: 0-65535 (sufficient for any practical feature flag).

Smart constructor for BitIndex. Always succeeds since all Word16 values are valid.

Whether a feature is set as required or optional.

Per BOLT #9, each feature has a pair of bits: the even bit indicates required (compulsory) support, the odd bit indicates optional support.

A required (compulsory) feature bit. Required bits are always even.

Smart constructor for RequiredBit. Returns Nothing if the bit index is odd.

>>> requiredBit 16
Just (RequiredBit {unRequiredBit = 16})
>>> requiredBit 17
Nothing

Convert a BitIndex to a RequiredBit. Returns Nothing if odd.

An optional feature bit. Optional bits are always odd.

Smart constructor for OptionalBit. Returns Nothing if the bit index is even.

>>> optionalBit 17
Just (OptionalBit {unOptionalBit = 17})
>>> optionalBit 16
Nothing

Convert a BitIndex to an OptionalBit. Returns Nothing if even.

A feature vector represented as a strict ByteString.

The vector is stored in big-endian byte order (most significant byte first), with bits numbered from the least significant bit of the last byte. Bit 0 is at position 0 of the last byte.

The empty feature vector (no features set).

>>> empty
FeatureVector {unFeatureVector = ""}

Wrap a ByteString as a FeatureVector.

Set a bit in the feature vector.

>>> set (bitIndex 0) empty
FeatureVector {unFeatureVector = "\SOH"}
>>> set (bitIndex 8) empty
FeatureVector {unFeatureVector = "\SOH\NUL"}

Clear a bit in the feature vector.

Test if a bit is set in the feature vector.

>>> member (bitIndex 0) (set (bitIndex 0) empty)
True
>>> member (bitIndex 1) (set (bitIndex 0) empty)
False

A known feature from the BOLT #9 specification.

Look up a feature by bit number.

Accepts either the even (compulsory) or odd (optional) bit of the pair.

>>> fmap featureName (featureByBit 16)
Just "basic_mpp"
>>> fmap featureName (featureByBit 17)  -- odd bit also works
Just "basic_mpp"
>>> featureByBit 999
Nothing

Look up a feature by its canonical name.

>>> fmap featureBaseBit (featureByName "basic_mpp")
Just 16
>>> featureByName "nonexistent"
Nothing

The complete table of known features from BOLT #9.

Parse a ByteString into a FeatureVector.

Alias for fromByteString.

Render a FeatureVector to a ByteString, trimming leading zero bytes for compact encoding.

Set a bit by raw index.

>>> setBit 17 empty
FeatureVector {unFeatureVector = "\STX"}

Clear a bit by raw index.

>>> clearBit 17 (setBit 17 empty)
FeatureVector {unFeatureVector = ""}

Test if a bit is set.

>>> testBit 17 (setBit 17 empty)
True
>>> testBit 16 (setBit 17 empty)
False

Set a feature's bit at the given level.

Required sets the even bit, Optional sets the odd bit.

>>> import Data.Maybe (fromJust)
>>> let mpp = fromJust (featureByName "basic_mpp")
>>> setFeature mpp Optional empty  -- set optional bit (17)
FeatureVector {unFeatureVector = "\STX"}
>>> setFeature mpp Required empty  -- set required bit (16)
FeatureVector {unFeatureVector = "\SOH"}

Check if a feature is set in the vector.

Returns:

• Just Required if the required (even) bit is set
• Just Optional if the optional (odd) bit is set (and required is not)
• Nothing if neither bit is set

>>> import Data.Maybe (fromJust)
>>> let mpp = fromJust (featureByName "basic_mpp")
>>> hasFeature mpp (setFeature mpp Optional empty)
Just Optional
>>> hasFeature mpp (setFeature mpp Required empty)
Just Required
>>> hasFeature mpp empty
Nothing

Check if either bit of a feature is set in the vector.

>>> import Data.Maybe (fromJust)
>>> let mpp = fromJust (featureByName "basic_mpp")
>>> isFeatureSet mpp (setFeature mpp Optional empty)
True
>>> isFeatureSet mpp empty
False

List all known features that are set in the vector.

Returns pairs of (Feature, FeatureLevel) indicating whether each feature is set as required or optional.

>>> import Data.Maybe (fromJust)
>>> let mpp = fromJust (featureByName "basic_mpp")
>>> let ps = fromJust (featureByName "payment_secret")
>>> let fv = setFeature mpp Optional (setFeature ps Required empty)
>>> map (\(f, l) -> (featureName f, l)) (listFeatures fv)
[("payment_secret",Required),("basic_mpp",Optional)]

Validation errors for feature vectors.

Validate a feature vector for local use (vectors we create/send).

Checks:

• No feature has both optional and required bits set
• All set features are valid for the given context
• All dependencies of set features are also set
• C- context forces odd bits only, C+ forces even bits only

>>> import Data.Maybe (fromJust)
>>> import Lightning.Protocol.BOLT9.Codec (setFeature)
>>> let mpp = fromJust (featureByName "basic_mpp")
>>> let ps = fromJust (featureByName "payment_secret")
>>> validateLocal Init (setFeature mpp False empty)
Left [MissingDependency "basic_mpp" "payment_secret"]
>>> validateLocal Init (setFeature mpp False (setFeature ps False empty))
Right ()

Validate a feature vector received from a remote peer.

Checks:

• Unknown odd (optional) bits are acceptable (ignored)
• Unknown even (required) bits are errors
• If both bits of a pair are set, treat as required (not an error)
• Context restrictions still apply for known features

>>> import Lightning.Protocol.BOLT9.Codec (setBit)
>>> validateRemote Init (setBit 999 empty)  -- unknown odd bit: ok
Right ()
>>> validateRemote Init (setBit 998 empty)  -- unknown even bit: error
Left [UnknownRequiredBit 998]

Find the highest set bit in a feature vector.

Returns Nothing if the vector is empty or has no bits set.

Collect all set bits in a feature vector.

Returns a list of bit indices in ascending order.