ppad-bolt9-0.0.1: Feature flags per BOLT #9
Copyright(c) 2025 Jared Tobin
LicenseMIT
MaintainerJared Tobin <jared@ppad.tech>
Safe HaskellSafe-Inferred
LanguageHaskell2010

Lightning.Protocol.BOLT9.Validate

Description

Validation for BOLT #9 feature vectors.

Synopsis

Error types

data ValidationError Source #

Validation errors for feature vectors.

Constructors

BothBitsSet !Word16 !String

Both optional and required bits are set for a feature. Arguments: base bit index, feature name.

MissingDependency !String !String

A feature's dependency is not set. Arguments: feature name, missing dependency name.

ContextNotAllowed !String !Context

A feature is not allowed in the given context. Arguments: feature name, context.

UnknownRequiredBit !Word16

An unknown required (even) bit is set (remote validation only). Argument: bit index.

InvalidParity !Word16 !Context

A bit has invalid parity for a channel context. Arguments: bit index, context (ChanAnnOdd or ChanAnnEven).

Instances

Instances details
NFData ValidationError Source # 
Instance details

Defined in Lightning.Protocol.BOLT9.Validate

Methods

rnf :: ValidationError -> () #

Generic ValidationError Source # 
Instance details

Defined in Lightning.Protocol.BOLT9.Validate

Show ValidationError Source # 
Instance details

Defined in Lightning.Protocol.BOLT9.Validate

Eq ValidationError Source # 
Instance details

Defined in Lightning.Protocol.BOLT9.Validate

type Rep ValidationError Source # 
Instance details

Defined in Lightning.Protocol.BOLT9.Validate

Local validation

validateLocal :: Context -> FeatureVector -> Either [ValidationError] () Source #

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 ()

Remote validation

validateRemote :: Context -> FeatureVector -> Either [ValidationError] () Source #

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]

Helpers

highestSetBit :: FeatureVector -> Maybe Word16 Source #

Find the highest set bit in a feature vector.

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

setBits :: FeatureVector -> [Word16] Source #

Collect all set bits in a feature vector.

Returns a list of bit indices in ascending order.