_ Git - rust-lightning/blob - lightning/src/ln/features.rs

   1 //! Feature flag definitions for the Lightning protocol according to [BOLT #9].
   2 //!
   3 //! Lightning nodes advertise a supported set of operation through feature flags. Features are
   4 //! applicable for a specific context as indicated in some [messages]. [`Features`] encapsulates
   5 //! behavior for specifying and checking feature flags for a particular context. Each feature is
   6 //! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits). A
   7 //! [`Context`] is used to parameterize [`Features`] and defines which features it can support.
   8 //!
   9 //! Whether a feature is considered "known" or "unknown" is relative to the implementation, whereas
  10 //! the term "supports" is used in reference to a particular set of [`Features`]. That is, a node
  11 //! supports a feature if it advertises the feature (as either required or optional) to its peers.
  12 //! And the implementation can interpret a feature if the feature is known to it.
  13 //!
  14 //! [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md
  15 //! [messages]: ../msgs/index.html
  16 //! [`Features`]: struct.Features.html
  17 //! [`Context`]: sealed/trait.Context.html
  18
  19 use std::{cmp, fmt};
  20 use std::result::Result;
  21 use std::marker::PhantomData;
  22
  23 use ln::msgs::DecodeError;
  24 use util::ser::{Readable, Writeable, Writer};
  25
  26 mod sealed {
  27         /// The context in which [`Features`] are applicable. Defines which features are required and
  28         /// which are optional for the context.
  29         ///
  30         /// [`Features`]: ../struct.Features.html
  31         pub trait Context {
  32                 /// Features that are known to the implementation, where a required feature is indicated by
  33                 /// its even bit and an optional feature is indicated by its odd bit.
  34                 const KNOWN_FEATURE_FLAGS: &'static [u8];
  35
  36                 /// Bitmask for selecting features that are known to the implementation, regardless of
  37                 /// whether each feature is required or optional.
  38                 const KNOWN_FEATURE_MASK: &'static [u8];
  39         }
  40
  41         /// Defines a [`Context`] by stating which features it requires and which are optional. Features
  42         /// are specified as a comma-separated list of bytes where each byte is a pipe-delimited list of
  43         /// feature identifiers.
  44         ///
  45         /// [`Context`]: trait.Context.html
  46         macro_rules! define_context {
  47                 ($context: ident {
  48                         required_features: [$( $( $required_feature: ident )|*, )*],
  49                         optional_features: [$( $( $optional_feature: ident )|*, )*],
  50                 }) => {
  51                         pub struct $context {}
  52
  53                         impl Context for $context {
  54                                 const KNOWN_FEATURE_FLAGS: &'static [u8] = &[
  55                                         // For each byte, use bitwise-OR to compute the applicable flags for known
  56                                         // required features `r_i` and optional features `o_j` for all `i` and `j` such
  57                                         // that the following slice is formed:
  58                                         //
  59                                         // [
  60                                         //  `r_0` | `r_1` | ... | `o_0` | `o_1` | ...,
  61                                         //  ...,
  62                                         // ]
  63                                         $(
  64                                                 0b00_00_00_00 $(|
  65                                                         <Self as $required_feature>::REQUIRED_MASK)*
  66                                                 $(|
  67                                                         <Self as $optional_feature>::OPTIONAL_MASK)*,
  68                                         )*
  69                                 ];
  70
  71                                 const KNOWN_FEATURE_MASK: &'static [u8] = &[
  72                                         // Similar as above, but set both flags for each feature regardless of whether
  73                                         // the feature is required or optional.
  74                                         $(
  75                                                 0b00_00_00_00 $(|
  76                                                         <Self as $required_feature>::REQUIRED_MASK |
  77                                                         <Self as $required_feature>::OPTIONAL_MASK)*
  78                                                 $(|
  79                                                         <Self as $optional_feature>::REQUIRED_MASK |
  80                                                         <Self as $optional_feature>::OPTIONAL_MASK)*,
  81                                         )*
  82                                 ];
  83                         }
  84                 };
  85         }
  86
  87         define_context!(InitContext {
  88                 required_features: [
  89                         // Byte 0
  90                         ,
  91                         // Byte 1
  92                         ,
  93                         // Byte 2
  94                         ,
  95                 ],
  96                 optional_features: [
  97                         // Byte 0
  98                         DataLossProtect | InitialRoutingSync | UpfrontShutdownScript,
  99                         // Byte 1
 100                         VariableLengthOnion | PaymentSecret,
 101                         // Byte 2
 102                         BasicMPP,
 103                 ],
 104         });
 105         define_context!(NodeContext {
 106                 required_features: [
 107                         // Byte 0
 108                         ,
 109                         // Byte 1
 110                         ,
 111                         // Byte 2
 112                         ,
 113                 ],
 114                 optional_features: [
 115                         // Byte 0
 116                         DataLossProtect | UpfrontShutdownScript,
 117                         // Byte 1
 118                         VariableLengthOnion | PaymentSecret,
 119                         // Byte 2
 120                         BasicMPP,
 121                 ],
 122         });
 123         define_context!(ChannelContext {
 124                 required_features: [],
 125                 optional_features: [],
 126         });
 127
 128         /// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is
 129         /// useful for manipulating feature flags.
 130         ///
 131         /// [`Context`]: trait.Context.html
 132         macro_rules! define_feature {
 133                 ($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr) => {
 134                         #[doc = $doc]
 135                         ///
 136                         /// See [BOLT #9] for details.
 137                         ///
 138                         /// [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md
 139                         pub trait $feature: Context {
 140                                 /// The bit used to signify that the feature is required.
 141                                 const EVEN_BIT: usize = $odd_bit - 1;
 142
 143                                 /// The bit used to signify that the feature is optional.
 144                                 const ODD_BIT: usize = $odd_bit;
 145
 146                                 /// Assertion that [`EVEN_BIT`] is actually even.
 147                                 ///
 148                                 /// [`EVEN_BIT`]: #associatedconstant.EVEN_BIT
 149                                 const ASSERT_EVEN_BIT_PARITY: usize;
 150
 151                                 /// Assertion that [`ODD_BIT`] is actually odd.
 152                                 ///
 153                                 /// [`ODD_BIT`]: #associatedconstant.ODD_BIT
 154                                 const ASSERT_ODD_BIT_PARITY: usize;
 155
 156                                 /// The byte where the feature is set.
 157                                 const BYTE_OFFSET: usize = Self::EVEN_BIT / 8;
 158
 159                                 /// The bitmask for the feature's required flag relative to the [`BYTE_OFFSET`].
 160                                 ///
 161                                 /// [`BYTE_OFFSET`]: #associatedconstant.BYTE_OFFSET
 162                                 const REQUIRED_MASK: u8 = 1 << (Self::EVEN_BIT - 8 * Self::BYTE_OFFSET);
 163
 164                                 /// The bitmask for the feature's optional flag relative to the [`BYTE_OFFSET`].
 165                                 ///
 166                                 /// [`BYTE_OFFSET`]: #associatedconstant.BYTE_OFFSET
 167                                 const OPTIONAL_MASK: u8 = 1 << (Self::ODD_BIT - 8 * Self::BYTE_OFFSET);
 168
 169                                 /// Returns whether the feature is supported by the given flags.
 170                                 #[inline]
 171                                 fn supports_feature(flags: &Vec<u8>) -> bool {
 172                                         flags.len() > Self::BYTE_OFFSET &&
 173                                                 (flags[Self::BYTE_OFFSET] & (Self::REQUIRED_MASK | Self::OPTIONAL_MASK)) != 0
 174                                 }
 175
 176                                 /// Sets the feature's optional (odd) bit in the given flags.
 177                                 #[inline]
 178                                 fn set_optional_bit(flags: &mut Vec<u8>) {
 179                                         if flags.len() <= Self::BYTE_OFFSET {
 180                                                 flags.resize(Self::BYTE_OFFSET + 1, 0u8);
 181                                         }
 182
 183                                         flags[Self::BYTE_OFFSET] |= Self::OPTIONAL_MASK;
 184                                 }
 185
 186                                 /// Clears the feature's required (even) and optional (odd) bits from the given
 187                                 /// flags.
 188                                 #[inline]
 189                                 fn clear_bits(flags: &mut Vec<u8>) {
 190                                         if flags.len() > Self::BYTE_OFFSET {
 191                                                 flags[Self::BYTE_OFFSET] &= !Self::REQUIRED_MASK;
 192                                                 flags[Self::BYTE_OFFSET] &= !Self::OPTIONAL_MASK;
 193                                         }
 194                                 }
 195                         }
 196
 197                         $(
 198                                 impl $feature for $context {
 199                                         // EVEN_BIT % 2 == 0
 200                                         const ASSERT_EVEN_BIT_PARITY: usize = 0 - (<Self as $feature>::EVEN_BIT % 2);
 201
 202                                         // ODD_BIT % 2 == 1
 203                                         const ASSERT_ODD_BIT_PARITY: usize = (<Self as $feature>::ODD_BIT % 2) - 1;
 204                                 }
 205                         )*
 206                 }
 207         }
 208
 209         define_feature!(1, DataLossProtect, [InitContext, NodeContext],
 210                 "Feature flags for `option_data_loss_protect`.");
 211         // NOTE: Per Bolt #9, initial_routing_sync has no even bit.
 212         define_feature!(3, InitialRoutingSync, [InitContext],
 213                 "Feature flags for `initial_routing_sync`.");
 214         define_feature!(5, UpfrontShutdownScript, [InitContext, NodeContext],
 215                 "Feature flags for `option_upfront_shutdown_script`.");
 216         define_feature!(9, VariableLengthOnion, [InitContext, NodeContext],
 217                 "Feature flags for `var_onion_optin`.");
 218         define_feature!(15, PaymentSecret, [InitContext, NodeContext],
 219                 "Feature flags for `payment_secret`.");
 220         define_feature!(17, BasicMPP, [InitContext, NodeContext],
 221                 "Feature flags for `basic_mpp`.");
 222 }
 223
 224 /// Tracks the set of features which a node implements, templated by the context in which it
 225 /// appears.
 226 pub struct Features<T: sealed::Context> {
 227         /// Note that, for convenience, flags is LITTLE endian (despite being big-endian on the wire)
 228         flags: Vec<u8>,
 229         mark: PhantomData<T>,
 230 }
 231
 232 impl<T: sealed::Context> Clone for Features<T> {
 233         fn clone(&self) -> Self {
 234                 Self {
 235                         flags: self.flags.clone(),
 236                         mark: PhantomData,
 237                 }
 238         }
 239 }
 240 impl<T: sealed::Context> PartialEq for Features<T> {
 241         fn eq(&self, o: &Self) -> bool {
 242                 self.flags.eq(&o.flags)
 243         }
 244 }
 245 impl<T: sealed::Context> fmt::Debug for Features<T> {
 246         fn fmt(&self, fmt: &mut fmt::Formatter) -> Result<(), fmt::Error> {
 247                 self.flags.fmt(fmt)
 248         }
 249 }
 250
 251 /// Features used within an `init` message.
 252 pub type InitFeatures = Features<sealed::InitContext>;
 253 /// Features used within a `node_announcement` message.
 254 pub type NodeFeatures = Features<sealed::NodeContext>;
 255 /// Features used within a `channel_announcement` message.
 256 pub type ChannelFeatures = Features<sealed::ChannelContext>;
 257
 258 impl InitFeatures {
 259         /// Writes all features present up to, and including, 13.
 260         pub(crate) fn write_up_to_13<W: Writer>(&self, w: &mut W) -> Result<(), ::std::io::Error> {
 261                 let len = cmp::min(2, self.flags.len());
 262                 w.size_hint(len + 2);
 263                 (len as u16).write(w)?;
 264                 for i in (0..len).rev() {
 265                         if i == 0 {
 266                                 self.flags[i].write(w)?;
 267                         } else {
 268                                 // On byte 1, we want up-to-and-including-bit-13, 0-indexed, which is
 269                                 // up-to-and-including-bit-5, 0-indexed, on this byte:
 270                                 (self.flags[i] & 0b00_11_11_11).write(w)?;
 271                         }
 272                 }
 273                 Ok(())
 274         }
 275
 276         /// or's another InitFeatures into this one.
 277         pub(crate) fn or(mut self, o: InitFeatures) -> InitFeatures {
 278                 let total_feature_len = cmp::max(self.flags.len(), o.flags.len());
 279                 self.flags.resize(total_feature_len, 0u8);
 280                 for (byte, o_byte) in self.flags.iter_mut().zip(o.flags.iter()) {
 281                         *byte |= *o_byte;
 282                 }
 283                 self
 284         }
 285
 286         /// Converts `InitFeatures` to `Features<C>`. Only known `InitFeatures` relevant to context `C`
 287         /// are included in the result.
 288         pub(crate) fn to_context<C: sealed::Context>(&self) -> Features<C> {
 289                 self.to_context_internal()
 290         }
 291 }
 292
 293 impl<T: sealed::Context> Features<T> {
 294         /// Create a blank Features with no features set
 295         pub fn empty() -> Features<T> {
 296                 Features {
 297                         flags: Vec::new(),
 298                         mark: PhantomData,
 299                 }
 300         }
 301
 302         /// Creates features known by the implementation as defined by [`T::KNOWN_FEATURE_FLAGS`].
 303         ///
 304         /// [`T::KNOWN_FEATURE_FLAGS`]: sealed/trait.Context.html#associatedconstant.KNOWN_FEATURE_FLAGS
 305         pub fn known() -> Features<T> {
 306                 Self {
 307                         flags: T::KNOWN_FEATURE_FLAGS.to_vec(),
 308                         mark: PhantomData,
 309                 }
 310         }
 311
 312         /// Converts `Features<T>` to `Features<C>`. Only known `T` features relevant to context `C` are
 313         /// included in the result.
 314         fn to_context_internal<C: sealed::Context>(&self) -> Features<C> {
 315                 let byte_count = C::KNOWN_FEATURE_MASK.len();
 316                 let mut flags = Vec::new();
 317                 for (i, byte) in self.flags.iter().enumerate() {
 318                         if i < byte_count {
 319                                 let known_source_features = T::KNOWN_FEATURE_MASK[i];
 320                                 let known_target_features = C::KNOWN_FEATURE_MASK[i];
 321                                 flags.push(byte & known_source_features & known_target_features);
 322                         }
 323                 }
 324                 Features::<C> { flags, mark: PhantomData, }
 325         }
 326
 327         #[cfg(test)]
 328         /// Create a Features given a set of flags, in LE.
 329         pub fn from_le_bytes(flags: Vec<u8>) -> Features<T> {
 330                 Features {
 331                         flags,
 332                         mark: PhantomData,
 333                 }
 334         }
 335
 336         #[cfg(test)]
 337         /// Gets the underlying flags set, in LE.
 338         pub fn le_flags(&self) -> &Vec<u8> {
 339                 &self.flags
 340         }
 341
 342         pub(crate) fn requires_unknown_bits(&self) -> bool {
 343                 // Bitwise AND-ing with all even bits set except for known features will select required
 344                 // unknown features.
 345                 let byte_count = T::KNOWN_FEATURE_MASK.len();
 346                 self.flags.iter().enumerate().any(|(i, &byte)| {
 347                         let required_features = 0b01_01_01_01;
 348                         let unknown_features = if i < byte_count {
 349                                 !T::KNOWN_FEATURE_MASK[i]
 350                         } else {
 351                                 0b11_11_11_11
 352                         };
 353                         (byte & (required_features & unknown_features)) != 0
 354                 })
 355         }
 356
 357         pub(crate) fn supports_unknown_bits(&self) -> bool {
 358                 // Bitwise AND-ing with all even and odd bits set except for known features will select
 359                 // both required and optional unknown features.
 360                 let byte_count = T::KNOWN_FEATURE_MASK.len();
 361                 self.flags.iter().enumerate().any(|(i, &byte)| {
 362                         let unknown_features = if i < byte_count {
 363                                 !T::KNOWN_FEATURE_MASK[i]
 364                         } else {
 365                                 0b11_11_11_11
 366                         };
 367                         (byte & unknown_features) != 0
 368                 })
 369         }
 370
 371         /// The number of bytes required to represent the feature flags present. This does not include
 372         /// the length bytes which are included in the serialized form.
 373         pub(crate) fn byte_count(&self) -> usize {
 374                 self.flags.len()
 375         }
 376
 377         #[cfg(test)]
 378         pub(crate) fn set_require_unknown_bits(&mut self) {
 379                 let newlen = cmp::max(3, self.flags.len());
 380                 self.flags.resize(newlen, 0u8);
 381                 self.flags[2] |= 0x40;
 382         }
 383
 384         #[cfg(test)]
 385         pub(crate) fn clear_require_unknown_bits(&mut self) {
 386                 let newlen = cmp::max(3, self.flags.len());
 387                 self.flags.resize(newlen, 0u8);
 388                 self.flags[2] &= !0x40;
 389                 if self.flags.len() == 3 && self.flags[2] == 0 {
 390                         self.flags.resize(2, 0u8);
 391                 }
 392                 if self.flags.len() == 2 && self.flags[1] == 0 {
 393                         self.flags.resize(1, 0u8);
 394                 }
 395         }
 396 }
 397
 398 impl<T: sealed::DataLossProtect> Features<T> {
 399         pub(crate) fn supports_data_loss_protect(&self) -> bool {
 400                 <T as sealed::DataLossProtect>::supports_feature(&self.flags)
 401         }
 402 }
 403
 404 impl<T: sealed::UpfrontShutdownScript> Features<T> {
 405         pub(crate) fn supports_upfront_shutdown_script(&self) -> bool {
 406                 <T as sealed::UpfrontShutdownScript>::supports_feature(&self.flags)
 407         }
 408         #[cfg(test)]
 409         pub(crate) fn clear_upfront_shutdown_script(mut self) -> Self {
 410                 <T as sealed::UpfrontShutdownScript>::clear_bits(&mut self.flags);
 411                 self
 412         }
 413 }
 414
 415 impl<T: sealed::VariableLengthOnion> Features<T> {
 416         pub(crate) fn supports_variable_length_onion(&self) -> bool {
 417                 <T as sealed::VariableLengthOnion>::supports_feature(&self.flags)
 418         }
 419 }
 420
 421 impl<T: sealed::InitialRoutingSync> Features<T> {
 422         pub(crate) fn initial_routing_sync(&self) -> bool {
 423                 <T as sealed::InitialRoutingSync>::supports_feature(&self.flags)
 424         }
 425         pub(crate) fn clear_initial_routing_sync(&mut self) {
 426                 <T as sealed::InitialRoutingSync>::clear_bits(&mut self.flags)
 427         }
 428 }
 429
 430 impl<T: sealed::PaymentSecret> Features<T> {
 431         #[allow(dead_code)]
 432         // Note that we never need to test this since what really matters is the invoice - iff the
 433         // invoice provides a payment_secret, we assume that we can use it (ie that the recipient
 434         // supports payment_secret).
 435         pub(crate) fn supports_payment_secret(&self) -> bool {
 436                 <T as sealed::PaymentSecret>::supports_feature(&self.flags)
 437         }
 438 }
 439
 440 impl<T: sealed::BasicMPP> Features<T> {
 441         // We currently never test for this since we don't actually *generate* multipath routes.
 442         #[allow(dead_code)]
 443         pub(crate) fn supports_basic_mpp(&self) -> bool {
 444                 <T as sealed::BasicMPP>::supports_feature(&self.flags)
 445         }
 446 }
 447
 448 impl<T: sealed::Context> Writeable for Features<T> {
 449         fn write<W: Writer>(&self, w: &mut W) -> Result<(), ::std::io::Error> {
 450                 w.size_hint(self.flags.len() + 2);
 451                 (self.flags.len() as u16).write(w)?;
 452                 for f in self.flags.iter().rev() { // Swap back to big-endian
 453                         f.write(w)?;
 454                 }
 455                 Ok(())
 456         }
 457 }
 458
 459 impl<T: sealed::Context> Readable for Features<T> {
 460         fn read<R: ::std::io::Read>(r: &mut R) -> Result<Self, DecodeError> {
 461                 let mut flags: Vec<u8> = Readable::read(r)?;
 462                 flags.reverse(); // Swap to little-endian
 463                 Ok(Self {
 464                         flags,
 465                         mark: PhantomData,
 466                 })
 467         }
 468 }
 469
 470 #[cfg(test)]
 471 mod tests {
 472         use super::{ChannelFeatures, InitFeatures, NodeFeatures};
 473
 474         #[test]
 475         fn sanity_test_our_features() {
 476                 assert!(!ChannelFeatures::known().requires_unknown_bits());
 477                 assert!(!ChannelFeatures::known().supports_unknown_bits());
 478                 assert!(!InitFeatures::known().requires_unknown_bits());
 479                 assert!(!InitFeatures::known().supports_unknown_bits());
 480                 assert!(!NodeFeatures::known().requires_unknown_bits());
 481                 assert!(!NodeFeatures::known().supports_unknown_bits());
 482
 483                 assert!(InitFeatures::known().supports_upfront_shutdown_script());
 484                 assert!(NodeFeatures::known().supports_upfront_shutdown_script());
 485
 486                 assert!(InitFeatures::known().supports_data_loss_protect());
 487                 assert!(NodeFeatures::known().supports_data_loss_protect());
 488
 489                 assert!(InitFeatures::known().supports_variable_length_onion());
 490                 assert!(NodeFeatures::known().supports_variable_length_onion());
 491
 492                 assert!(InitFeatures::known().supports_payment_secret());
 493                 assert!(NodeFeatures::known().supports_payment_secret());
 494
 495                 assert!(InitFeatures::known().supports_basic_mpp());
 496                 assert!(NodeFeatures::known().supports_basic_mpp());
 497
 498                 let mut init_features = InitFeatures::known();
 499                 assert!(init_features.initial_routing_sync());
 500                 init_features.clear_initial_routing_sync();
 501                 assert!(!init_features.initial_routing_sync());
 502         }
 503
 504         #[test]
 505         fn sanity_test_unkown_bits_testing() {
 506                 let mut features = ChannelFeatures::known();
 507                 features.set_require_unknown_bits();
 508                 assert!(features.requires_unknown_bits());
 509                 features.clear_require_unknown_bits();
 510                 assert!(!features.requires_unknown_bits());
 511         }
 512
 513         #[test]
 514         fn convert_to_context_with_relevant_flags() {
 515                 let init_features = InitFeatures::known().clear_upfront_shutdown_script();
 516                 assert!(init_features.initial_routing_sync());
 517                 assert!(!init_features.supports_upfront_shutdown_script());
 518
 519                 let node_features: NodeFeatures = init_features.to_context();
 520                 {
 521                         // Check that the flags are as expected:
 522                         // - option_data_loss_protect
 523                         // - var_onion_optin | payment_secret
 524                         // - basic_mpp
 525                         assert_eq!(node_features.flags.len(), 3);
 526                         assert_eq!(node_features.flags[0], 0b00000010);
 527                         assert_eq!(node_features.flags[1], 0b10000010);
 528                         assert_eq!(node_features.flags[2], 0b00000010);
 529                 }
 530
 531                 // Check that cleared flags are kept blank when converting back:
 532                 // - initial_routing_sync was not applicable to NodeContext
 533                 // - upfront_shutdown_script was cleared before converting
 534                 let features: InitFeatures = node_features.to_context_internal();
 535                 assert!(!features.initial_routing_sync());
 536                 assert!(!features.supports_upfront_shutdown_script());
 537         }
 538 }