+ /// The context in which [`Features`] are applicable. Defines which features are known to the
+ /// implementation, though specification of them as required or optional is up to the code
+ /// constructing a features object.
+ pub trait Context {
+ /// Bitmask for selecting features that are known to the implementation.
+ const KNOWN_FEATURE_MASK: &'static [u8];
+ }
+
+ /// Defines a [`Context`] by stating which features it requires and which are optional. Features
+ /// are specified as a comma-separated list of bytes where each byte is a pipe-delimited list of
+ /// feature identifiers.
+ macro_rules! define_context {
+ ($context: ident, [$( $( $known_feature: ident )|*, )*]) => {
+ #[derive(Eq, PartialEq)]
+ pub struct $context {}
+
+ impl Context for $context {
+ const KNOWN_FEATURE_MASK: &'static [u8] = &[
+ $(
+ 0b00_00_00_00 $(|
+ <Self as $known_feature>::REQUIRED_MASK |
+ <Self as $known_feature>::OPTIONAL_MASK)*,
+ )*
+ ];
+ }
+
+ impl alloc::fmt::Display for Features<$context> {
+ fn fmt(&self, fmt: &mut alloc::fmt::Formatter) -> Result<(), alloc::fmt::Error> {
+ $(
+ $(
+ fmt.write_fmt(format_args!("{}: {}, ", stringify!($known_feature),
+ if <$context as $known_feature>::requires_feature(&self.flags) { "required" }
+ else if <$context as $known_feature>::supports_feature(&self.flags) { "supported" }
+ else { "not supported" }))?;
+ )*
+ {} // Rust gets mad if we only have a $()* block here, so add a dummy {}
+ )*
+ fmt.write_fmt(format_args!("unknown flags: {}",
+ if self.requires_unknown_bits() { "required" }
+ else if self.supports_unknown_bits() { "supported" } else { "none" }))
+ }
+ }
+ };
+ }
+
+ define_context!(InitContext, [
+ // Byte 0
+ DataLossProtect | InitialRoutingSync | UpfrontShutdownScript | GossipQueries,
+ // Byte 1
+ VariableLengthOnion | StaticRemoteKey | PaymentSecret,
+ // Byte 2
+ BasicMPP | Wumbo | AnchorsNonzeroFeeHtlcTx | AnchorsZeroFeeHtlcTx,
+ // Byte 3
+ RouteBlinding | ShutdownAnySegwit | Taproot,
+ // Byte 4
+ OnionMessages,
+ // Byte 5
+ ChannelType | SCIDPrivacy,
+ // Byte 6
+ ZeroConf,
+ // Byte 7
+ Trampoline,
+ ]);
+ define_context!(NodeContext, [
+ // Byte 0
+ DataLossProtect | UpfrontShutdownScript | GossipQueries,
+ // Byte 1
+ VariableLengthOnion | StaticRemoteKey | PaymentSecret,
+ // Byte 2
+ BasicMPP | Wumbo | AnchorsNonzeroFeeHtlcTx | AnchorsZeroFeeHtlcTx,
+ // Byte 3
+ RouteBlinding | ShutdownAnySegwit | Taproot,
+ // Byte 4
+ OnionMessages,
+ // Byte 5
+ ChannelType | SCIDPrivacy,
+ // Byte 6
+ ZeroConf | Keysend,
+ // Byte 7
+ Trampoline,
+ ]);
+ define_context!(ChannelContext, []);
+ define_context!(Bolt11InvoiceContext, [
+ // Byte 0
+ ,
+ // Byte 1
+ VariableLengthOnion | PaymentSecret,
+ // Byte 2
+ BasicMPP,
+ // Byte 3
+ ,
+ // Byte 4
+ ,
+ // Byte 5
+ ,
+ // Byte 6
+ PaymentMetadata,
+ // Byte 7
+ Trampoline,
+ ]);
+ define_context!(OfferContext, []);
+ define_context!(InvoiceRequestContext, []);
+ define_context!(Bolt12InvoiceContext, [
+ // Byte 0
+ ,
+ // Byte 1
+ ,
+ // Byte 2
+ BasicMPP,
+ ]);
+ define_context!(BlindedHopContext, []);
+ // This isn't a "real" feature context, and is only used in the channel_type field in an
+ // `OpenChannel` message.
+ define_context!(ChannelTypeContext, [
+ // Byte 0
+ ,
+ // Byte 1
+ StaticRemoteKey,
+ // Byte 2
+ AnchorsNonzeroFeeHtlcTx | AnchorsZeroFeeHtlcTx,
+ // Byte 3
+ Taproot,
+ // Byte 4
+ ,
+ // Byte 5
+ SCIDPrivacy,
+ // Byte 6
+ ZeroConf,
+ ]);
+
+ /// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is
+ /// useful for manipulating feature flags.
+ macro_rules! define_feature {
+ ($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident,
+ $required_setter: ident, $supported_getter: ident) => {
+ #[doc = $doc]
+ ///
+ /// See [BOLT #9] for details.
+ ///
+ /// [BOLT #9]: https://github.com/lightning/bolts/blob/master/09-features.md
+ pub trait $feature: Context {
+ /// The bit used to signify that the feature is required.
+ const EVEN_BIT: usize = $odd_bit - 1;
+
+ /// The bit used to signify that the feature is optional.
+ const ODD_BIT: usize = $odd_bit;
+
+ /// Assertion that [`EVEN_BIT`] is actually even.
+ ///
+ /// [`EVEN_BIT`]: #associatedconstant.EVEN_BIT
+ const ASSERT_EVEN_BIT_PARITY: usize;
+
+ /// Assertion that [`ODD_BIT`] is actually odd.
+ ///
+ /// [`ODD_BIT`]: #associatedconstant.ODD_BIT
+ const ASSERT_ODD_BIT_PARITY: usize;
+
+ /// Assertion that the bits are set in the context's [`KNOWN_FEATURE_MASK`].
+ ///
+ /// [`KNOWN_FEATURE_MASK`]: Context::KNOWN_FEATURE_MASK
+ #[cfg(not(test))] // We violate this constraint with `UnknownFeature`
+ const ASSERT_BITS_IN_MASK: u8;
+
+ /// The byte where the feature is set.
+ const BYTE_OFFSET: usize = Self::EVEN_BIT / 8;
+
+ /// The bitmask for the feature's required flag relative to the [`BYTE_OFFSET`].
+ ///
+ /// [`BYTE_OFFSET`]: #associatedconstant.BYTE_OFFSET
+ const REQUIRED_MASK: u8 = 1 << (Self::EVEN_BIT - 8 * Self::BYTE_OFFSET);
+
+ /// The bitmask for the feature's optional flag relative to the [`BYTE_OFFSET`].
+ ///
+ /// [`BYTE_OFFSET`]: #associatedconstant.BYTE_OFFSET
+ const OPTIONAL_MASK: u8 = 1 << (Self::ODD_BIT - 8 * Self::BYTE_OFFSET);
+
+ /// Returns whether the feature is required by the given flags.
+ #[inline]
+ fn requires_feature(flags: &Vec<u8>) -> bool {
+ flags.len() > Self::BYTE_OFFSET &&
+ (flags[Self::BYTE_OFFSET] & Self::REQUIRED_MASK) != 0
+ }
+
+ /// Returns whether the feature is supported by the given flags.
+ #[inline]
+ fn supports_feature(flags: &Vec<u8>) -> bool {
+ flags.len() > Self::BYTE_OFFSET &&
+ (flags[Self::BYTE_OFFSET] & (Self::REQUIRED_MASK | Self::OPTIONAL_MASK)) != 0
+ }
+
+ /// Sets the feature's required (even) bit in the given flags.
+ #[inline]
+ fn set_required_bit(flags: &mut Vec<u8>) {
+ if flags.len() <= Self::BYTE_OFFSET {
+ flags.resize(Self::BYTE_OFFSET + 1, 0u8);
+ }
+
+ flags[Self::BYTE_OFFSET] |= Self::REQUIRED_MASK;
+ flags[Self::BYTE_OFFSET] &= !Self::OPTIONAL_MASK;
+ }
+
+ /// Sets the feature's optional (odd) bit in the given flags.
+ #[inline]
+ fn set_optional_bit(flags: &mut Vec<u8>) {
+ if flags.len() <= Self::BYTE_OFFSET {
+ flags.resize(Self::BYTE_OFFSET + 1, 0u8);
+ }
+
+ flags[Self::BYTE_OFFSET] |= Self::OPTIONAL_MASK;
+ }
+
+ /// Clears the feature's required (even) and optional (odd) bits from the given
+ /// flags.
+ #[inline]
+ fn clear_bits(flags: &mut Vec<u8>) {
+ if flags.len() > Self::BYTE_OFFSET {
+ flags[Self::BYTE_OFFSET] &= !Self::REQUIRED_MASK;
+ flags[Self::BYTE_OFFSET] &= !Self::OPTIONAL_MASK;
+ }
+
+ let last_non_zero_byte = flags.iter().rposition(|&byte| byte != 0);
+ let size = if let Some(offset) = last_non_zero_byte { offset + 1 } else { 0 };
+ flags.resize(size, 0u8);
+ }
+ }
+
+ impl <T: $feature> Features<T> {
+ /// Set this feature as optional.
+ pub fn $optional_setter(&mut self) {
+ <T as $feature>::set_optional_bit(&mut self.flags);
+ }
+
+ /// Set this feature as required.
+ pub fn $required_setter(&mut self) {
+ <T as $feature>::set_required_bit(&mut self.flags);
+ }
+
+ /// Checks if this feature is supported.
+ pub fn $supported_getter(&self) -> bool {
+ <T as $feature>::supports_feature(&self.flags)
+ }
+ }
+
+ $(
+ impl $feature for $context {
+ // EVEN_BIT % 2 == 0
+ const ASSERT_EVEN_BIT_PARITY: usize = 0 - (<Self as $feature>::EVEN_BIT % 2);
+
+ // ODD_BIT % 2 == 1
+ const ASSERT_ODD_BIT_PARITY: usize = (<Self as $feature>::ODD_BIT % 2) - 1;
+
+ // (byte & (REQUIRED_MASK | OPTIONAL_MASK)) >> (EVEN_BIT % 8) == 3
+ #[cfg(not(test))] // We violate this constraint with `UnknownFeature`
+ const ASSERT_BITS_IN_MASK: u8 =
+ ((<$context>::KNOWN_FEATURE_MASK[<Self as $feature>::BYTE_OFFSET] & (<Self as $feature>::REQUIRED_MASK | <Self as $feature>::OPTIONAL_MASK))
+ >> (<Self as $feature>::EVEN_BIT % 8)) - 3;
+ }
+ )*
+ };
+ ($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident,
+ $required_setter: ident, $supported_getter: ident, $required_getter: ident) => {
+ define_feature!($odd_bit, $feature, [$($context),+], $doc, $optional_setter, $required_setter, $supported_getter);
+ impl <T: $feature> Features<T> {
+ /// Checks if this feature is required.
+ pub fn $required_getter(&self) -> bool {
+ <T as $feature>::requires_feature(&self.flags)
+ }
+ }
+ }
+ }