BOLT9.hs (3709B)
1 {-# OPTIONS_HADDOCK prune #-} 2 {-# LANGUAGE BangPatterns #-} 3 {-# LANGUAGE DeriveGeneric #-} 4 5 -- | 6 -- Module: Lightning.Protocol.BOLT9 7 -- Copyright: (c) 2025 Jared Tobin 8 -- License: MIT 9 -- Maintainer: Jared Tobin <jared@ppad.tech> 10 -- 11 -- Feature flags for the Lightning Network, per 12 -- [BOLT #9](https://github.com/lightning/bolts/blob/master/09-features.md). 13 -- 14 -- == Overview 15 -- 16 -- BOLT #9 defines feature flags that Lightning nodes advertise to indicate 17 -- support for optional protocol features. Features are represented as bit 18 -- positions in a variable-length bit vector, where even bits indicate 19 -- required (compulsory) support and odd bits indicate optional support. 20 -- 21 -- This library provides: 22 -- 23 -- * Type-safe feature vectors with efficient bit manipulation 24 -- * A complete table of known features from the BOLT #9 specification 25 -- * Validation for both locally-created and remotely-received vectors 26 -- * Context-aware validation (init, node_announcement, invoice, etc.) 27 -- 28 -- == Quick Start 29 -- 30 -- Create a feature vector and set some features: 31 -- 32 -- >>> import Lightning.Protocol.BOLT9 33 -- >>> let Just mpp = featureByName "basic_mpp" 34 -- >>> let fv = setFeature mpp Optional empty 35 -- >>> hasFeature mpp fv 36 -- Just Optional 37 -- 38 -- Validate a feature vector for a specific context: 39 -- 40 -- >>> validateLocal Init fv 41 -- Left [MissingDependency "basic_mpp" "payment_secret"] 42 -- 43 -- Fix by adding the dependency: 44 -- 45 -- >>> let Just ps = featureByName "payment_secret" 46 -- >>> let fv' = setFeature ps Optional (setFeature mpp Optional empty) 47 -- >>> validateLocal Init fv' 48 -- Right () 49 -- 50 -- == Bit Numbering 51 -- 52 -- Features use paired bits: even bits (0, 2, 4, ...) indicate required 53 -- support, while odd bits (1, 3, 5, ...) indicate optional support. 54 -- For example, @basic_mpp@ uses bit 16 (required) and 17 (optional). 55 -- 56 -- A node setting bit 16 requires all peers to support @basic_mpp@. 57 -- A node setting bit 17 indicates optional support (peers without it 58 -- may still connect). 59 60 module Lightning.Protocol.BOLT9 ( 61 -- * Context 62 -- | Contexts specify where feature flags appear in the protocol. 63 Context(..) 64 , isChannelContext 65 , channelParity 66 67 -- * Bit indices 68 -- | Low-level bit index types for direct bit manipulation. 69 , BitIndex 70 , unBitIndex 71 , bitIndex 72 73 -- * Required/optional level 74 -- | Whether a feature is set as required or optional. 75 , FeatureLevel(..) 76 77 -- * Required/optional bits 78 -- | Type-safe wrappers ensuring correct parity. 79 , RequiredBit 80 , unRequiredBit 81 , requiredBit 82 , requiredFromBitIndex 83 84 , OptionalBit 85 , unOptionalBit 86 , optionalBit 87 , optionalFromBitIndex 88 89 -- * Feature vectors 90 -- | The core feature vector type and basic operations. 91 , FeatureVector 92 , unFeatureVector 93 , FV.empty 94 , fromByteString 95 , set 96 , clear 97 , member 98 99 -- * Known features 100 -- | The BOLT #9 feature table and lookup functions. 101 , Feature(..) 102 , featureByBit 103 , featureByName 104 , knownFeatures 105 106 -- * Parsing and rendering 107 -- | Wire format conversion. 108 , parse 109 , render 110 111 -- * Low-level bit operations 112 -- | Direct bit manipulation by index. 113 , Codec.setBit 114 , Codec.clearBit 115 , Codec.testBit 116 117 -- * Feature operations 118 -- | High-level operations using 'Feature' values. 119 , setFeature 120 , hasFeature 121 , isFeatureSet 122 , listFeatures 123 124 -- * Validation 125 -- | Validate feature vectors for correctness. 126 , ValidationError(..) 127 , validateLocal 128 , validateRemote 129 , highestSetBit 130 , Validate.setBits 131 ) where 132 133 import Lightning.Protocol.BOLT9.Codec as Codec 134 import Lightning.Protocol.BOLT9.Features 135 import Lightning.Protocol.BOLT9.Types as FV 136 import Lightning.Protocol.BOLT9.Validate as Validate