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 {
60 /// Returns the type that was used to decode the message payload.
61 pub fn type_id(&self) -> MessageType {
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,
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
98 impl ::std::fmt::Display for MessageType {
99 fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
100 write!(f, "{}", self.number)
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.
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)?;
113 msgs::Init::TYPE => {
114 Ok(Message::Init(Readable::read(buffer)?))
116 msgs::ErrorMessage::TYPE => {
117 Ok(Message::Error(Readable::read(buffer)?))
119 msgs::Ping::TYPE => {
120 Ok(Message::Ping(Readable::read(buffer)?))
122 msgs::Pong::TYPE => {
123 Ok(Message::Pong(Readable::read(buffer)?))
125 msgs::OpenChannel::TYPE => {
126 Ok(Message::OpenChannel(Readable::read(buffer)?))
128 msgs::AcceptChannel::TYPE => {
129 Ok(Message::AcceptChannel(Readable::read(buffer)?))
131 msgs::FundingCreated::TYPE => {
132 Ok(Message::FundingCreated(Readable::read(buffer)?))
134 msgs::FundingSigned::TYPE => {
135 Ok(Message::FundingSigned(Readable::read(buffer)?))
137 msgs::FundingLocked::TYPE => {
138 Ok(Message::FundingLocked(Readable::read(buffer)?))
140 msgs::Shutdown::TYPE => {
141 Ok(Message::Shutdown(Readable::read(buffer)?))
143 msgs::ClosingSigned::TYPE => {
144 Ok(Message::ClosingSigned(Readable::read(buffer)?))
146 msgs::UpdateAddHTLC::TYPE => {
147 Ok(Message::UpdateAddHTLC(Readable::read(buffer)?))
149 msgs::UpdateFulfillHTLC::TYPE => {
150 Ok(Message::UpdateFulfillHTLC(Readable::read(buffer)?))
152 msgs::UpdateFailHTLC::TYPE => {
153 Ok(Message::UpdateFailHTLC(Readable::read(buffer)?))
155 msgs::UpdateFailMalformedHTLC::TYPE => {
156 Ok(Message::UpdateFailMalformedHTLC(Readable::read(buffer)?))
158 msgs::CommitmentSigned::TYPE => {
159 Ok(Message::CommitmentSigned(Readable::read(buffer)?))
161 msgs::RevokeAndACK::TYPE => {
162 Ok(Message::RevokeAndACK(Readable::read(buffer)?))
164 msgs::UpdateFee::TYPE => {
165 Ok(Message::UpdateFee(Readable::read(buffer)?))
167 msgs::ChannelReestablish::TYPE => {
168 Ok(Message::ChannelReestablish(Readable::read(buffer)?))
170 msgs::AnnouncementSignatures::TYPE => {
171 Ok(Message::AnnouncementSignatures(Readable::read(buffer)?))
173 msgs::ChannelAnnouncement::TYPE => {
174 Ok(Message::ChannelAnnouncement(Readable::read(buffer)?))
176 msgs::NodeAnnouncement::TYPE => {
177 Ok(Message::NodeAnnouncement(Readable::read(buffer)?))
179 msgs::ChannelUpdate::TYPE => {
180 Ok(Message::ChannelUpdate(Readable::read(buffer)?))
183 Ok(Message::Unknown(MessageType { number: message_type }))
188 /// Writes a message to the data buffer encoded as a 2-byte big-endian type and a variable-length
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)
199 /// Defines a type-identified encoding for sending messages over the wire.
201 /// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`].
203 /// [`Writeable`]: ../../util/ser/trait.Writeable.html
204 /// [`write`]: fn.write.html
206 /// The type identifying the message payload.
209 /// Returns the type identifying the message payload. Convenience method for accessing
211 fn type_id(&self) -> MessageType {
212 MessageType { number: Self::TYPE }
216 impl Encode for msgs::Init {
217 const TYPE: u16 = 16;
220 impl Encode for msgs::ErrorMessage {
221 const TYPE: u16 = 17;
224 impl Encode for msgs::Ping {
225 const TYPE: u16 = 18;
228 impl Encode for msgs::Pong {
229 const TYPE: u16 = 19;
232 impl Encode for msgs::OpenChannel {
233 const TYPE: u16 = 32;
236 impl Encode for msgs::AcceptChannel {
237 const TYPE: u16 = 33;
240 impl Encode for msgs::FundingCreated {
241 const TYPE: u16 = 34;
244 impl Encode for msgs::FundingSigned {
245 const TYPE: u16 = 35;
248 impl Encode for msgs::FundingLocked {
249 const TYPE: u16 = 36;
252 impl Encode for msgs::Shutdown {
253 const TYPE: u16 = 38;
256 impl Encode for msgs::ClosingSigned {
257 const TYPE: u16 = 39;
260 impl Encode for msgs::UpdateAddHTLC {
261 const TYPE: u16 = 128;
264 impl Encode for msgs::UpdateFulfillHTLC {
265 const TYPE: u16 = 130;
268 impl Encode for msgs::UpdateFailHTLC {
269 const TYPE: u16 = 131;
272 impl Encode for msgs::UpdateFailMalformedHTLC {
273 const TYPE: u16 = 135;
276 impl Encode for msgs::CommitmentSigned {
277 const TYPE: u16 = 132;
280 impl Encode for msgs::RevokeAndACK {
281 const TYPE: u16 = 133;
284 impl Encode for msgs::UpdateFee {
285 const TYPE: u16 = 134;
288 impl Encode for msgs::ChannelReestablish {
289 const TYPE: u16 = 136;
292 impl Encode for msgs::AnnouncementSignatures {
293 const TYPE: u16 = 259;
296 impl Encode for msgs::ChannelAnnouncement {
297 const TYPE: u16 = 256;
300 impl Encode for msgs::NodeAnnouncement {
301 const TYPE: u16 = 257;
304 impl Encode for msgs::ChannelUpdate {
305 const TYPE: u16 = 258;
311 use util::byte_utils;
313 // Big-endian wire encoding of Pong message (type = 19, byteslen = 2).
314 const ENCODED_PONG: [u8; 6] = [0u8, 19u8, 0u8, 2u8, 0u8, 0u8];
317 fn read_empty_buffer() {
319 let mut reader = ::std::io::Cursor::new(buffer);
320 assert!(read(&mut reader).is_err());
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());
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());
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());
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();
350 Message::Pong(_) => (),
351 _ => panic!("Expected pong message; found message type: {}", message.type_id()),
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();
361 Message::Unknown(MessageType { number: ::std::u16::MAX }) => (),
362 _ => panic!("Expected message type {}; found: {}", ::std::u16::MAX, message.type_id()),
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());
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..]);
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());
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);
391 _ => panic!("Expected pong message; found message type: {}", decoded_message.type_id()),
396 fn is_even_message_type() {
397 let message = Message::Unknown(MessageType { number: 42 });
398 assert!(message.type_id().is_even());
402 fn is_odd_message_type() {
403 let message = Message::Unknown(MessageType { number: 43 });
404 assert!(!message.type_id().is_even());