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