_ Git - rust-lightning/blob - lightning/src/onion_message/offers.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 //! Message handling for BOLT 12 Offers.
  11
  12 use core::convert::TryFrom;
  13 use crate::io::{self, Read};
  14 use crate::ln::msgs::DecodeError;
  15 use crate::offers::invoice_error::InvoiceError;
  16 use crate::offers::invoice_request::InvoiceRequest;
  17 use crate::offers::invoice::Bolt12Invoice;
  18 use crate::offers::parse::Bolt12ParseError;
  19 use crate::onion_message::OnionMessageContents;
  20 use crate::onion_message::messenger::PendingOnionMessage;
  21 use crate::util::logger::Logger;
  22 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer};
  23
  24 use crate::prelude::*;
  25
  26 // TLV record types for the `onionmsg_tlv` TLV stream as defined in BOLT 4.
  27 const INVOICE_REQUEST_TLV_TYPE: u64 = 64;
  28 const INVOICE_TLV_TYPE: u64 = 66;
  29 const INVOICE_ERROR_TLV_TYPE: u64 = 68;
  30
  31 /// A handler for an [`OnionMessage`] containing a BOLT 12 Offers message as its payload.
  32 ///
  33 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
  34 pub trait OffersMessageHandler {
  35         /// Handles the given message by either responding with an [`Bolt12Invoice`], sending a payment,
  36         /// or replying with an error.
  37         ///
  38         /// The returned [`OffersMessage`], if any, is enqueued to be sent by [`OnionMessenger`].
  39         ///
  40         /// [`OnionMessenger`]: crate::onion_message::OnionMessenger
  41         fn handle_message(&self, message: OffersMessage) -> Option<OffersMessage>;
  42
  43         /// Releases any [`OffersMessage`]s that need to be sent.
  44         ///
  45         /// Typically, this is used for messages initiating a payment flow rather than in response to
  46         /// another message. The latter should use the return value of [`Self::handle_message`].
  47         #[cfg(not(c_bindings))]
  48         fn release_pending_messages(&self) -> Vec<PendingOnionMessage<OffersMessage>> { vec![] }
  49
  50         /// Releases any [`OffersMessage`]s that need to be sent.
  51         ///
  52         /// Typically, this is used for messages initiating a payment flow rather than in response to
  53         /// another message. The latter should use the return value of [`Self::handle_message`].
  54         #[cfg(c_bindings)]
  55         fn release_pending_messages(&self) -> Vec<(OffersMessage, crate::onion_message::Destination, Option<crate::blinded_path::BlindedPath>)> { vec![] }
  56 }
  57
  58 /// Possible BOLT 12 Offers messages sent and received via an [`OnionMessage`].
  59 ///
  60 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
  61 #[derive(Clone, Debug)]
  62 pub enum OffersMessage {
  63         /// A request for a [`Bolt12Invoice`] for a particular [`Offer`].
  64         ///
  65         /// [`Offer`]: crate::offers::offer::Offer
  66         InvoiceRequest(InvoiceRequest),
  67
  68         /// A [`Bolt12Invoice`] sent in response to an [`InvoiceRequest`] or a [`Refund`].
  69         ///
  70         /// [`Refund`]: crate::offers::refund::Refund
  71         Invoice(Bolt12Invoice),
  72
  73         /// An error from handling an [`OffersMessage`].
  74         InvoiceError(InvoiceError),
  75 }
  76
  77 impl OffersMessage {
  78         /// Returns whether `tlv_type` corresponds to a TLV record for Offers.
  79         pub fn is_known_type(tlv_type: u64) -> bool {
  80                 match tlv_type {
  81                         INVOICE_REQUEST_TLV_TYPE | INVOICE_TLV_TYPE | INVOICE_ERROR_TLV_TYPE => true,
  82                         _ => false,
  83                 }
  84         }
  85
  86         fn parse(tlv_type: u64, bytes: Vec<u8>) -> Result<Self, Bolt12ParseError> {
  87                 match tlv_type {
  88                         INVOICE_REQUEST_TLV_TYPE => Ok(Self::InvoiceRequest(InvoiceRequest::try_from(bytes)?)),
  89                         INVOICE_TLV_TYPE => Ok(Self::Invoice(Bolt12Invoice::try_from(bytes)?)),
  90                         _ => Err(Bolt12ParseError::Decode(DecodeError::InvalidValue)),
  91                 }
  92         }
  93 }
  94
  95 impl OnionMessageContents for OffersMessage {
  96         fn tlv_type(&self) -> u64 {
  97                 match self {
  98                         OffersMessage::InvoiceRequest(_) => INVOICE_REQUEST_TLV_TYPE,
  99                         OffersMessage::Invoice(_) => INVOICE_TLV_TYPE,
 100                         OffersMessage::InvoiceError(_) => INVOICE_ERROR_TLV_TYPE,
 101                 }
 102         }
 103 }
 104
 105 impl Writeable for OffersMessage {
 106         fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 107                 match self {
 108                         OffersMessage::InvoiceRequest(message) => message.write(w),
 109                         OffersMessage::Invoice(message) => message.write(w),
 110                         OffersMessage::InvoiceError(message) => message.write(w),
 111                 }
 112         }
 113 }
 114
 115 impl<L: Logger + ?Sized> ReadableArgs<(u64, &L)> for OffersMessage {
 116         fn read<R: Read>(r: &mut R, read_args: (u64, &L)) -> Result<Self, DecodeError> {
 117                 let (tlv_type, logger) = read_args;
 118                 if tlv_type == INVOICE_ERROR_TLV_TYPE {
 119                         return Ok(Self::InvoiceError(InvoiceError::read(r)?));
 120                 }
 121
 122                 let mut bytes = Vec::new();
 123                 r.read_to_end(&mut bytes).unwrap();
 124
 125                 match Self::parse(tlv_type, bytes) {
 126                         Ok(message) => Ok(message),
 127                         Err(Bolt12ParseError::Decode(e)) => Err(e),
 128                         Err(Bolt12ParseError::InvalidSemantics(e)) => {
 129                                 log_trace!(logger, "Invalid semantics for TLV type {}: {:?}", tlv_type, e);
 130                                 Err(DecodeError::InvalidValue)
 131                         },
 132                         Err(Bolt12ParseError::InvalidSignature(e)) => {
 133                                 log_trace!(logger, "Invalid signature for TLV type {}: {:?}", tlv_type, e);
 134                                 Err(DecodeError::InvalidValue)
 135                         },
 136                         Err(_) => Err(DecodeError::InvalidValue),
 137                 }
 138         }
 139 }