1 //! Wire encoding/decoding for Lightning messages according to [BOLT #1].
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.
7 //! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire
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
17 use util::ser::{Readable, Writeable, Writer};
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.
22 /// [`read`]: fn.read.html
23 /// [`ln::msgs`]: ../msgs/index.html
24 #[allow(missing_docs)]
27 Error(msgs::ErrorMessage),
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.
53 /// A number identifying a message to determine how it is encoded on the wire.
54 #[derive(Clone, Copy)]
55 pub struct MessageType(u16);
58 /// Returns the type that was used to decode the message payload.
59 pub fn type_id(&self) -> MessageType {
61 &Message::Init(ref msg) => msg.type_id(),
62 &Message::Error(ref msg) => msg.type_id(),
63 &Message::Ping(ref msg) => msg.type_id(),
64 &Message::Pong(ref msg) => msg.type_id(),
65 &Message::OpenChannel(ref msg) => msg.type_id(),
66 &Message::AcceptChannel(ref msg) => msg.type_id(),
67 &Message::FundingCreated(ref msg) => msg.type_id(),
68 &Message::FundingSigned(ref msg) => msg.type_id(),
69 &Message::FundingLocked(ref msg) => msg.type_id(),
70 &Message::Shutdown(ref msg) => msg.type_id(),
71 &Message::ClosingSigned(ref msg) => msg.type_id(),
72 &Message::UpdateAddHTLC(ref msg) => msg.type_id(),
73 &Message::UpdateFulfillHTLC(ref msg) => msg.type_id(),
74 &Message::UpdateFailHTLC(ref msg) => msg.type_id(),
75 &Message::UpdateFailMalformedHTLC(ref msg) => msg.type_id(),
76 &Message::CommitmentSigned(ref msg) => msg.type_id(),
77 &Message::RevokeAndACK(ref msg) => msg.type_id(),
78 &Message::UpdateFee(ref msg) => msg.type_id(),
79 &Message::ChannelReestablish(ref msg) => msg.type_id(),
80 &Message::AnnouncementSignatures(ref msg) => msg.type_id(),
81 &Message::ChannelAnnouncement(ref msg) => msg.type_id(),
82 &Message::NodeAnnouncement(ref msg) => msg.type_id(),
83 &Message::ChannelUpdate(ref msg) => msg.type_id(),
84 &Message::Unknown(type_id) => type_id,
90 /// Returns whether the message type is even, indicating both endpoints must support it.
91 pub fn is_even(&self) -> bool {
96 impl ::std::fmt::Display for MessageType {
97 fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
98 write!(f, "{}", self.0)
102 /// Reads a message from the data buffer consisting of a 2-byte big-endian type and a
103 /// variable-length payload conforming to the type.
107 /// Returns an error if the message payload code not be decoded as the specified type.
108 pub fn read<R: ::std::io::Read>(buffer: &mut R) -> Result<Message, msgs::DecodeError> {
109 let message_type = <u16 as Readable<R>>::read(buffer)?;
111 msgs::Init::TYPE => {
112 Ok(Message::Init(Readable::read(buffer)?))
114 msgs::ErrorMessage::TYPE => {
115 Ok(Message::Error(Readable::read(buffer)?))
117 msgs::Ping::TYPE => {
118 Ok(Message::Ping(Readable::read(buffer)?))
120 msgs::Pong::TYPE => {
121 Ok(Message::Pong(Readable::read(buffer)?))
123 msgs::OpenChannel::TYPE => {
124 Ok(Message::OpenChannel(Readable::read(buffer)?))
126 msgs::AcceptChannel::TYPE => {
127 Ok(Message::AcceptChannel(Readable::read(buffer)?))
129 msgs::FundingCreated::TYPE => {
130 Ok(Message::FundingCreated(Readable::read(buffer)?))
132 msgs::FundingSigned::TYPE => {
133 Ok(Message::FundingSigned(Readable::read(buffer)?))
135 msgs::FundingLocked::TYPE => {
136 Ok(Message::FundingLocked(Readable::read(buffer)?))
138 msgs::Shutdown::TYPE => {
139 Ok(Message::Shutdown(Readable::read(buffer)?))
141 msgs::ClosingSigned::TYPE => {
142 Ok(Message::ClosingSigned(Readable::read(buffer)?))
144 msgs::UpdateAddHTLC::TYPE => {
145 Ok(Message::UpdateAddHTLC(Readable::read(buffer)?))
147 msgs::UpdateFulfillHTLC::TYPE => {
148 Ok(Message::UpdateFulfillHTLC(Readable::read(buffer)?))
150 msgs::UpdateFailHTLC::TYPE => {
151 Ok(Message::UpdateFailHTLC(Readable::read(buffer)?))
153 msgs::UpdateFailMalformedHTLC::TYPE => {
154 Ok(Message::UpdateFailMalformedHTLC(Readable::read(buffer)?))
156 msgs::CommitmentSigned::TYPE => {
157 Ok(Message::CommitmentSigned(Readable::read(buffer)?))
159 msgs::RevokeAndACK::TYPE => {
160 Ok(Message::RevokeAndACK(Readable::read(buffer)?))
162 msgs::UpdateFee::TYPE => {
163 Ok(Message::UpdateFee(Readable::read(buffer)?))
165 msgs::ChannelReestablish::TYPE => {
166 Ok(Message::ChannelReestablish(Readable::read(buffer)?))
168 msgs::AnnouncementSignatures::TYPE => {
169 Ok(Message::AnnouncementSignatures(Readable::read(buffer)?))
171 msgs::ChannelAnnouncement::TYPE => {
172 Ok(Message::ChannelAnnouncement(Readable::read(buffer)?))
174 msgs::NodeAnnouncement::TYPE => {
175 Ok(Message::NodeAnnouncement(Readable::read(buffer)?))
177 msgs::ChannelUpdate::TYPE => {
178 Ok(Message::ChannelUpdate(Readable::read(buffer)?))
181 Ok(Message::Unknown(MessageType(message_type)))
186 /// Writes a message to the data buffer encoded as a 2-byte big-endian type and a variable-length
191 /// Returns an I/O error if the write could not be completed.
192 pub fn write<M: Encode + Writeable, W: Writer>(message: &M, buffer: &mut W) -> Result<(), ::std::io::Error> {
193 M::TYPE.write(buffer)?;
194 message.write(buffer)
197 /// Defines a type-identified encoding for sending messages over the wire.
199 /// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`].
201 /// [`Writeable`]: ../../util/ser/trait.Writeable.html
202 /// [`write`]: fn.write.html
204 /// The type identifying the message payload.
207 /// Returns the type identifying the message payload. Convenience method for accessing
209 fn type_id(&self) -> MessageType {
210 MessageType(Self::TYPE)
214 impl Encode for msgs::Init {
215 const TYPE: u16 = 16;
218 impl Encode for msgs::ErrorMessage {
219 const TYPE: u16 = 17;
222 impl Encode for msgs::Ping {
223 const TYPE: u16 = 18;
226 impl Encode for msgs::Pong {
227 const TYPE: u16 = 19;
230 impl Encode for msgs::OpenChannel {
231 const TYPE: u16 = 32;
234 impl Encode for msgs::AcceptChannel {
235 const TYPE: u16 = 33;
238 impl Encode for msgs::FundingCreated {
239 const TYPE: u16 = 34;
242 impl Encode for msgs::FundingSigned {
243 const TYPE: u16 = 35;
246 impl Encode for msgs::FundingLocked {
247 const TYPE: u16 = 36;
250 impl Encode for msgs::Shutdown {
251 const TYPE: u16 = 38;
254 impl Encode for msgs::ClosingSigned {
255 const TYPE: u16 = 39;
258 impl Encode for msgs::UpdateAddHTLC {
259 const TYPE: u16 = 128;
262 impl Encode for msgs::UpdateFulfillHTLC {
263 const TYPE: u16 = 130;
266 impl Encode for msgs::UpdateFailHTLC {
267 const TYPE: u16 = 131;
270 impl Encode for msgs::UpdateFailMalformedHTLC {
271 const TYPE: u16 = 135;
274 impl Encode for msgs::CommitmentSigned {
275 const TYPE: u16 = 132;
278 impl Encode for msgs::RevokeAndACK {
279 const TYPE: u16 = 133;
282 impl Encode for msgs::UpdateFee {
283 const TYPE: u16 = 134;
286 impl Encode for msgs::ChannelReestablish {
287 const TYPE: u16 = 136;
290 impl Encode for msgs::AnnouncementSignatures {
291 const TYPE: u16 = 259;
294 impl Encode for msgs::ChannelAnnouncement {
295 const TYPE: u16 = 256;
298 impl Encode for msgs::NodeAnnouncement {
299 const TYPE: u16 = 257;
302 impl Encode for msgs::ChannelUpdate {
303 const TYPE: u16 = 258;
309 use util::byte_utils;
311 // Big-endian wire encoding of Pong message (type = 19, byteslen = 2).
312 const ENCODED_PONG: [u8; 6] = [0u8, 19u8, 0u8, 2u8, 0u8, 0u8];
315 fn read_empty_buffer() {
317 let mut reader = ::std::io::Cursor::new(buffer);
318 assert!(read(&mut reader).is_err());
322 fn read_incomplete_type() {
323 let buffer = &ENCODED_PONG[..1];
324 let mut reader = ::std::io::Cursor::new(buffer);
325 assert!(read(&mut reader).is_err());
329 fn read_empty_payload() {
330 let buffer = &ENCODED_PONG[..2];
331 let mut reader = ::std::io::Cursor::new(buffer);
332 assert!(read(&mut reader).is_err());
336 fn read_invalid_message() {
337 let buffer = &ENCODED_PONG[..4];
338 let mut reader = ::std::io::Cursor::new(buffer);
339 assert!(read(&mut reader).is_err());
343 fn read_known_message() {
344 let buffer = &ENCODED_PONG[..];
345 let mut reader = ::std::io::Cursor::new(buffer);
346 let message = read(&mut reader).unwrap();
348 Message::Pong(_) => (),
349 _ => panic!("Expected pong message; found message type: {}", message.type_id()),
354 fn read_unknown_message() {
355 let buffer = &byte_utils::be16_to_array(::std::u16::MAX);
356 let mut reader = ::std::io::Cursor::new(buffer);
357 let message = read(&mut reader).unwrap();
359 Message::Unknown(MessageType(::std::u16::MAX)) => (),
360 _ => panic!("Expected message type {}; found: {}", ::std::u16::MAX, message.type_id()),
365 fn write_message_with_type() {
366 let message = msgs::Pong { byteslen: 2u16 };
367 let mut buffer = Vec::new();
368 assert!(write(&message, &mut buffer).is_ok());
370 let type_length = ::std::mem::size_of::<u16>();
371 let (type_bytes, payload_bytes) = buffer.split_at(type_length);
372 assert_eq!(byte_utils::slice_to_be16(type_bytes), msgs::Pong::TYPE);
373 assert_eq!(payload_bytes, &ENCODED_PONG[type_length..]);
377 fn read_message_encoded_with_write() {
378 let message = msgs::Pong { byteslen: 2u16 };
379 let mut buffer = Vec::new();
380 assert!(write(&message, &mut buffer).is_ok());
382 let mut reader = ::std::io::Cursor::new(buffer);
383 let decoded_message = read(&mut reader).unwrap();
384 match decoded_message {
385 Message::Pong(msgs::Pong { byteslen: 2u16 }) => (),
386 Message::Pong(msgs::Pong { byteslen }) => {
387 panic!("Expected byteslen {}; found: {}", message.byteslen, byteslen);
389 _ => panic!("Expected pong message; found message type: {}", decoded_message.type_id()),
394 fn is_even_message_type() {
395 let message = Message::Unknown(MessageType(42));
396 assert!(message.type_id().is_even());
400 fn is_odd_message_type() {
401 let message = Message::Unknown(MessageType(43));
402 assert!(!message.type_id().is_even());