bolt9

commit dbba328c885adeea056c1b7c735dca300bca6510
parent 39bd0dcf9fe8bd5afba7a873e6f450245a69fe2d
Author: Jared Tobin <jared@jtobin.io>
Date:   Mon, 20 Apr 2026 14:52:40 +0800

features: add KnownFeature newtype

Wraps Feature with proof that it exists in the BOLT #9 known
features table. Smart constructors knownFeatureByBit and
knownFeatureByName validate membership at construction time.

Diffstat:
M
lib/Lightning/Protocol/BOLT9/Features.hs
 | 
41
+++++++++++++++++++++++++++++++++++++++++

1 file changed, 41 insertions(+), 0 deletions(-)
diff --git a/lib/Lightning/Protocol/BOLT9/Features.hs b/lib/Lightning/Protocol/BOLT9/Features.hs
@@ -15,6 +15,11 @@ module Lightning.Protocol.BOLT9.Features (
     -- * Feature
     Feature(..)
 
+    -- * Known feature
+  , KnownFeature(..)
+  , knownFeatureByBit
+  , knownFeatureByName
+
     -- * Lookup
   , featureByBit
   , featureByName
@@ -50,6 +55,42 @@ data Feature = Feature {
 
 instance NFData Feature
 
+-- | A feature that is known to be in the BOLT #9 specification.
+--
+-- Constructed via 'knownFeatureByBit' or 'knownFeatureByName',
+-- which validate that the feature exists in the known table.
+newtype KnownFeature = KnownFeature {
+    unKnownFeature :: Feature
+    -- ^ Extract the underlying 'Feature'.
+  }
+  deriving (Eq, Show, Generic)
+
+instance NFData KnownFeature
+
+-- | Look up a known feature by bit number.
+--
+--   Accepts either the even (compulsory) or odd (optional) bit.
+--
+--   >>> fmap (featureName . unKnownFeature) (knownFeatureByBit 16)
+--   Just "basic_mpp"
+--   >>> knownFeatureByBit 999
+--   Nothing
+knownFeatureByBit :: Word16 -> Maybe KnownFeature
+knownFeatureByBit !bit = fmap KnownFeature (featureByBit bit)
+{-# INLINE knownFeatureByBit #-}
+
+-- | Look up a known feature by its canonical name.
+--
+--   >>> fmap (featureName . unKnownFeature)
+--   ...       (knownFeatureByName "basic_mpp")
+--   Just "basic_mpp"
+--   >>> knownFeatureByName "nonexistent"
+--   Nothing
+knownFeatureByName :: String -> Maybe KnownFeature
+knownFeatureByName !name =
+  fmap KnownFeature (featureByName name)
+{-# INLINE knownFeatureByName #-}
+
 -- | The complete table of known features from BOLT #9.
 knownFeatures :: [Feature]
 knownFeatures = [