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

   1 //! Wire encoding/decoding for Lightning messages according to [BOLT #1].
   2 //!
   3 //! Messages known by this module can be read from the wire using [`read`].
   4 //! The [`Message`] enum returned by [`read`] wraps the decoded message or the message type (if
   5 //! unknown) to use with pattern matching.
   6 //!
   7 //! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire
   8 //! using [`write`].
   9 //!
  10 //! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md
  11 //! [`read`]: fn.read.html
  12 //! [`write`]: fn.write.html
  13 //! [`Encode`]: trait.Encode.html
  14 //! [`Message`]: enum.Message.html
  15
  16 use ln::msgs;
  17 use util::ser::{Readable, Writeable, Writer};
  18
  19 /// A Lightning message returned by [`read`] when decoding bytes received over the wire. Each
  20 /// variant contains a message from [`ln::msgs`] or otherwise the message type if unknown.
  21 ///
  22 /// [`read`]: fn.read.html
  23 /// [`ln::msgs`]: ../msgs/index.html
  24 #[allow(missing_docs)]
  25 pub enum Message {
  26         Init(msgs::Init),
  27         Error(msgs::ErrorMessage),
  28         Ping(msgs::Ping),
  29         Pong(msgs::Pong),
  30         OpenChannel(msgs::OpenChannel),
  31         AcceptChannel(msgs::AcceptChannel),
  32         FundingCreated(msgs::FundingCreated),
  33         FundingSigned(msgs::FundingSigned),
  34         FundingLocked(msgs::FundingLocked),
  35         Shutdown(msgs::Shutdown),
  36         ClosingSigned(msgs::ClosingSigned),
  37         UpdateAddHTLC(msgs::UpdateAddHTLC),
  38         UpdateFulfillHTLC(msgs::UpdateFulfillHTLC),
  39         UpdateFailHTLC(msgs::UpdateFailHTLC),
  40         UpdateFailMalformedHTLC(msgs::UpdateFailMalformedHTLC),
  41         CommitmentSigned(msgs::CommitmentSigned),
  42         RevokeAndACK(msgs::RevokeAndACK),
  43         UpdateFee(msgs::UpdateFee),
  44         ChannelReestablish(msgs::ChannelReestablish),
  45         AnnouncementSignatures(msgs::AnnouncementSignatures),
  46         ChannelAnnouncement(msgs::ChannelAnnouncement),
  47         NodeAnnouncement(msgs::NodeAnnouncement),
  48         ChannelUpdate(msgs::ChannelUpdate),
  49         /// A message that could not be decoded because its type is unknown.
  50         Unknown(MessageType),
  51 }
  52
  53 /// A number identifying a message to determine how it is encoded on the wire.
  54 #[derive(Clone, Copy)]
  55 pub struct MessageType {
  56         number: u16,
  57 }
  58
  59 impl Message {
  60         /// Returns the type that was used to decode the message payload.
  61         pub fn type_id(&self) -> MessageType {
  62                 match self {
  63                         &Message::Init(ref msg) => msg.type_id(),
  64                         &Message::Error(ref msg) => msg.type_id(),
  65                         &Message::Ping(ref msg) => msg.type_id(),
  66                         &Message::Pong(ref msg) => msg.type_id(),
  67                         &Message::OpenChannel(ref msg) => msg.type_id(),
  68                         &Message::AcceptChannel(ref msg) => msg.type_id(),
  69                         &Message::FundingCreated(ref msg) => msg.type_id(),
  70                         &Message::FundingSigned(ref msg) => msg.type_id(),
  71                         &Message::FundingLocked(ref msg) => msg.type_id(),
  72                         &Message::Shutdown(ref msg) => msg.type_id(),
  73                         &Message::ClosingSigned(ref msg) => msg.type_id(),
  74                         &Message::UpdateAddHTLC(ref msg) => msg.type_id(),
  75                         &Message::UpdateFulfillHTLC(ref msg) => msg.type_id(),
  76                         &Message::UpdateFailHTLC(ref msg) => msg.type_id(),
  77                         &Message::UpdateFailMalformedHTLC(ref msg) => msg.type_id(),
  78                         &Message::CommitmentSigned(ref msg) => msg.type_id(),
  79                         &Message::RevokeAndACK(ref msg) => msg.type_id(),
  80                         &Message::UpdateFee(ref msg) => msg.type_id(),
  81                         &Message::ChannelReestablish(ref msg) => msg.type_id(),
  82                         &Message::AnnouncementSignatures(ref msg) => msg.type_id(),
  83                         &Message::ChannelAnnouncement(ref msg) => msg.type_id(),
  84                         &Message::NodeAnnouncement(ref msg) => msg.type_id(),
  85                         &Message::ChannelUpdate(ref msg) => msg.type_id(),
  86                         &Message::Unknown(type_id) => type_id,
  87                 }
  88         }
  89 }
  90
  91 impl MessageType {
  92         /// Returns whether the message type is even, indicating both endpoints must support it.
  93         pub fn is_even(&self) -> bool {
  94                 (self.number & 1) == 0
  95         }
  96 }
  97
  98 impl ::std::fmt::Display for MessageType {
  99         fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
 100                 write!(f, "{}", self.number)
 101         }
 102 }
 103
 104 /// Reads a message from the data buffer consisting of a 2-byte big-endian type and a
 105 /// variable-length payload conforming to the type.
 106 ///
 107 /// # Errors
 108 ///
 109 /// Returns an error if the message payload code not be decoded as the specified type.
 110 pub fn read<R: ::std::io::Read>(buffer: &mut R) -> Result<Message, msgs::DecodeError> {
 111         let message_type = <u16 as Readable<R>>::read(buffer)?;
 112         match message_type {
 113                 msgs::Init::TYPE => {
 114                         Ok(Message::Init(Readable::read(buffer)?))
 115                 },
 116                 msgs::ErrorMessage::TYPE => {
 117                         Ok(Message::Error(Readable::read(buffer)?))
 118                 },
 119                 msgs::Ping::TYPE => {
 120                         Ok(Message::Ping(Readable::read(buffer)?))
 121                 },
 122                 msgs::Pong::TYPE => {
 123                         Ok(Message::Pong(Readable::read(buffer)?))
 124                 },
 125                 msgs::OpenChannel::TYPE => {
 126                         Ok(Message::OpenChannel(Readable::read(buffer)?))
 127                 },
 128                 msgs::AcceptChannel::TYPE => {
 129                         Ok(Message::AcceptChannel(Readable::read(buffer)?))
 130                 },
 131                 msgs::FundingCreated::TYPE => {
 132                         Ok(Message::FundingCreated(Readable::read(buffer)?))
 133                 },
 134                 msgs::FundingSigned::TYPE => {
 135                         Ok(Message::FundingSigned(Readable::read(buffer)?))
 136                 },
 137                 msgs::FundingLocked::TYPE => {
 138                         Ok(Message::FundingLocked(Readable::read(buffer)?))
 139                 },
 140                 msgs::Shutdown::TYPE => {
 141                         Ok(Message::Shutdown(Readable::read(buffer)?))
 142                 },
 143                 msgs::ClosingSigned::TYPE => {
 144                         Ok(Message::ClosingSigned(Readable::read(buffer)?))
 145                 },
 146                 msgs::UpdateAddHTLC::TYPE => {
 147                         Ok(Message::UpdateAddHTLC(Readable::read(buffer)?))
 148                 },
 149                 msgs::UpdateFulfillHTLC::TYPE => {
 150                         Ok(Message::UpdateFulfillHTLC(Readable::read(buffer)?))
 151                 },
 152                 msgs::UpdateFailHTLC::TYPE => {
 153                         Ok(Message::UpdateFailHTLC(Readable::read(buffer)?))
 154                 },
 155                 msgs::UpdateFailMalformedHTLC::TYPE => {
 156                         Ok(Message::UpdateFailMalformedHTLC(Readable::read(buffer)?))
 157                 },
 158                 msgs::CommitmentSigned::TYPE => {
 159                         Ok(Message::CommitmentSigned(Readable::read(buffer)?))
 160                 },
 161                 msgs::RevokeAndACK::TYPE => {
 162                         Ok(Message::RevokeAndACK(Readable::read(buffer)?))
 163                 },
 164                 msgs::UpdateFee::TYPE => {
 165                         Ok(Message::UpdateFee(Readable::read(buffer)?))
 166                 },
 167                 msgs::ChannelReestablish::TYPE => {
 168                         Ok(Message::ChannelReestablish(Readable::read(buffer)?))
 169                 },
 170                 msgs::AnnouncementSignatures::TYPE => {
 171                         Ok(Message::AnnouncementSignatures(Readable::read(buffer)?))
 172                 },
 173                 msgs::ChannelAnnouncement::TYPE => {
 174                         Ok(Message::ChannelAnnouncement(Readable::read(buffer)?))
 175                 },
 176                 msgs::NodeAnnouncement::TYPE => {
 177                         Ok(Message::NodeAnnouncement(Readable::read(buffer)?))
 178                 },
 179                 msgs::ChannelUpdate::TYPE => {
 180                         Ok(Message::ChannelUpdate(Readable::read(buffer)?))
 181                 },
 182                 _ => {
 183                         Ok(Message::Unknown(MessageType { number: message_type }))
 184                 },
 185         }
 186 }
 187
 188 /// Writes a message to the data buffer encoded as a 2-byte big-endian type and a variable-length
 189 /// payload.
 190 ///
 191 /// # Errors
 192 ///
 193 /// Returns an I/O error if the write could not be completed.
 194 pub fn write<M: Encode + Writeable, W: Writer>(message: &M, buffer: &mut W) -> Result<(), ::std::io::Error> {
 195         M::TYPE.write(buffer)?;
 196         message.write(buffer)
 197 }
 198
 199 /// Defines a type-identified encoding for sending messages over the wire.
 200 ///
 201 /// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`].
 202 ///
 203 /// [`Writeable`]: ../../util/ser/trait.Writeable.html
 204 /// [`write`]: fn.write.html
 205 pub trait Encode {
 206         /// The type identifying the message payload.
 207         const TYPE: u16;
 208
 209         /// Returns the type identifying the message payload. Convenience method for accessing
 210         /// [`TYPE`](TYPE).
 211         fn type_id(&self) -> MessageType {
 212                 MessageType { number: Self::TYPE }
 213         }
 214 }
 215
 216 impl Encode for msgs::Init {
 217         const TYPE: u16 = 16;
 218 }
 219
 220 impl Encode for msgs::ErrorMessage {
 221         const TYPE: u16 = 17;
 222 }
 223
 224 impl Encode for msgs::Ping {
 225         const TYPE: u16 = 18;
 226 }
 227
 228 impl Encode for msgs::Pong {
 229         const TYPE: u16 = 19;
 230 }
 231
 232 impl Encode for msgs::OpenChannel {
 233         const TYPE: u16 = 32;
 234 }
 235
 236 impl Encode for msgs::AcceptChannel {
 237         const TYPE: u16 = 33;
 238 }
 239
 240 impl Encode for msgs::FundingCreated {
 241         const TYPE: u16 = 34;
 242 }
 243
 244 impl Encode for msgs::FundingSigned {
 245         const TYPE: u16 = 35;
 246 }
 247
 248 impl Encode for msgs::FundingLocked {
 249         const TYPE: u16 = 36;
 250 }
 251
 252 impl Encode for msgs::Shutdown {
 253         const TYPE: u16 = 38;
 254 }
 255
 256 impl Encode for msgs::ClosingSigned {
 257         const TYPE: u16 = 39;
 258 }
 259
 260 impl Encode for msgs::UpdateAddHTLC {
 261         const TYPE: u16 = 128;
 262 }
 263
 264 impl Encode for msgs::UpdateFulfillHTLC {
 265         const TYPE: u16 = 130;
 266 }
 267
 268 impl Encode for msgs::UpdateFailHTLC {
 269         const TYPE: u16 = 131;
 270 }
 271
 272 impl Encode for msgs::UpdateFailMalformedHTLC {
 273         const TYPE: u16 = 135;
 274 }
 275
 276 impl Encode for msgs::CommitmentSigned {
 277         const TYPE: u16 = 132;
 278 }
 279
 280 impl Encode for msgs::RevokeAndACK {
 281         const TYPE: u16 = 133;
 282 }
 283
 284 impl Encode for msgs::UpdateFee {
 285         const TYPE: u16 = 134;
 286 }
 287
 288 impl Encode for msgs::ChannelReestablish {
 289         const TYPE: u16 = 136;
 290 }
 291
 292 impl Encode for msgs::AnnouncementSignatures {
 293         const TYPE: u16 = 259;
 294 }
 295
 296 impl Encode for msgs::ChannelAnnouncement {
 297         const TYPE: u16 = 256;
 298 }
 299
 300 impl Encode for msgs::NodeAnnouncement {
 301         const TYPE: u16 = 257;
 302 }
 303
 304 impl Encode for msgs::ChannelUpdate {
 305         const TYPE: u16 = 258;
 306 }
 307
 308 #[cfg(test)]
 309 mod tests {
 310         use super::*;
 311         use util::byte_utils;
 312
 313         // Big-endian wire encoding of Pong message (type = 19, byteslen = 2).
 314         const ENCODED_PONG: [u8; 6] = [0u8, 19u8, 0u8, 2u8, 0u8, 0u8];
 315
 316         #[test]
 317         fn read_empty_buffer() {
 318                 let buffer = [];
 319                 let mut reader = ::std::io::Cursor::new(buffer);
 320                 assert!(read(&mut reader).is_err());
 321         }
 322
 323         #[test]
 324         fn read_incomplete_type() {
 325                 let buffer = &ENCODED_PONG[..1];
 326                 let mut reader = ::std::io::Cursor::new(buffer);
 327                 assert!(read(&mut reader).is_err());
 328         }
 329
 330         #[test]
 331         fn read_empty_payload() {
 332                 let buffer = &ENCODED_PONG[..2];
 333                 let mut reader = ::std::io::Cursor::new(buffer);
 334                 assert!(read(&mut reader).is_err());
 335         }
 336
 337         #[test]
 338         fn read_invalid_message() {
 339                 let buffer = &ENCODED_PONG[..4];
 340                 let mut reader = ::std::io::Cursor::new(buffer);
 341                 assert!(read(&mut reader).is_err());
 342         }
 343
 344         #[test]
 345         fn read_known_message() {
 346                 let buffer = &ENCODED_PONG[..];
 347                 let mut reader = ::std::io::Cursor::new(buffer);
 348                 let message = read(&mut reader).unwrap();
 349                 match message {
 350                         Message::Pong(_) => (),
 351                         _ => panic!("Expected pong message; found message type: {}", message.type_id()),
 352                 }
 353         }
 354
 355         #[test]
 356         fn read_unknown_message() {
 357                 let buffer = &byte_utils::be16_to_array(::std::u16::MAX);
 358                 let mut reader = ::std::io::Cursor::new(buffer);
 359                 let message = read(&mut reader).unwrap();
 360                 match message {
 361                         Message::Unknown(MessageType { number: ::std::u16::MAX }) => (),
 362                         _ => panic!("Expected message type {}; found: {}", ::std::u16::MAX, message.type_id()),
 363                 }
 364         }
 365
 366         #[test]
 367         fn write_message_with_type() {
 368                 let message = msgs::Pong { byteslen: 2u16 };
 369                 let mut buffer = Vec::new();
 370                 assert!(write(&message, &mut buffer).is_ok());
 371
 372                 let type_length = ::std::mem::size_of::<u16>();
 373                 let (type_bytes, payload_bytes) = buffer.split_at(type_length);
 374                 assert_eq!(byte_utils::slice_to_be16(type_bytes), msgs::Pong::TYPE);
 375                 assert_eq!(payload_bytes, &ENCODED_PONG[type_length..]);
 376         }
 377
 378         #[test]
 379         fn read_message_encoded_with_write() {
 380                 let message = msgs::Pong { byteslen: 2u16 };
 381                 let mut buffer = Vec::new();
 382                 assert!(write(&message, &mut buffer).is_ok());
 383
 384                 let mut reader = ::std::io::Cursor::new(buffer);
 385                 let decoded_message = read(&mut reader).unwrap();
 386                 match decoded_message {
 387                         Message::Pong(msgs::Pong { byteslen: 2u16 }) => (),
 388                         Message::Pong(msgs::Pong { byteslen }) => {
 389                                 panic!("Expected byteslen {}; found: {}", message.byteslen, byteslen);
 390                         },
 391                         _ => panic!("Expected pong message; found message type: {}", decoded_message.type_id()),
 392                 }
 393         }
 394
 395         #[test]
 396         fn is_even_message_type() {
 397                 let message = Message::Unknown(MessageType { number: 42 });
 398                 assert!(message.type_id().is_even());
 399         }
 400
 401         #[test]
 402         fn is_odd_message_type() {
 403                 let message = Message::Unknown(MessageType { number: 43 });
 404                 assert!(!message.type_id().is_even());
 405         }
 406 }