1 // This file is Copyright its original authors, visible in version control
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
10 //! Message handling for async payments.
13 use crate::ln::msgs::DecodeError;
14 use crate::onion_message::packet::OnionMessageContents;
15 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer};
17 // TLV record types for the `onionmsg_tlv` TLV stream as defined in BOLT 4.
18 const HELD_HTLC_AVAILABLE_TLV_TYPE: u64 = 72;
19 const RELEASE_HELD_HTLC_TLV_TYPE: u64 = 74;
21 /// Possible async payment messages sent and received via an [`OnionMessage`].
23 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
24 #[derive(Clone, Debug)]
25 pub enum AsyncPaymentsMessage {
26 /// An HTLC is being held upstream for the often-offline recipient, to be released via
27 /// [`ReleaseHeldHtlc`].
28 HeldHtlcAvailable(HeldHtlcAvailable),
30 /// Releases the HTLC corresponding to an inbound [`HeldHtlcAvailable`] message.
31 ReleaseHeldHtlc(ReleaseHeldHtlc),
34 /// An HTLC destined for the recipient of this message is being held upstream. The reply path
35 /// accompanying this onion message should be used to send a [`ReleaseHeldHtlc`] response, which
36 /// will cause the upstream HTLC to be released.
37 #[derive(Clone, Debug)]
38 pub struct HeldHtlcAvailable {
39 /// The secret that will be used by the recipient of this message to release the held HTLC.
40 pub payment_release_secret: [u8; 32],
43 /// Releases the HTLC corresponding to an inbound [`HeldHtlcAvailable`] message.
44 #[derive(Clone, Debug)]
45 pub struct ReleaseHeldHtlc {
46 /// Used to release the HTLC held upstream if it matches the corresponding
47 /// [`HeldHtlcAvailable::payment_release_secret`].
48 pub payment_release_secret: [u8; 32],
51 impl OnionMessageContents for ReleaseHeldHtlc {
52 fn tlv_type(&self) -> u64 {
53 RELEASE_HELD_HTLC_TLV_TYPE
55 fn msg_type(&self) -> &'static str {
60 impl_writeable_tlv_based!(HeldHtlcAvailable, {
61 (0, payment_release_secret, required),
64 impl_writeable_tlv_based!(ReleaseHeldHtlc, {
65 (0, payment_release_secret, required),
68 impl AsyncPaymentsMessage {
69 /// Returns whether `tlv_type` corresponds to a TLV record for async payment messages.
70 pub fn is_known_type(tlv_type: u64) -> bool {
72 HELD_HTLC_AVAILABLE_TLV_TYPE | RELEASE_HELD_HTLC_TLV_TYPE => true,
78 impl OnionMessageContents for AsyncPaymentsMessage {
79 fn tlv_type(&self) -> u64 {
81 Self::HeldHtlcAvailable(_) => HELD_HTLC_AVAILABLE_TLV_TYPE,
82 Self::ReleaseHeldHtlc(msg) => msg.tlv_type(),
85 fn msg_type(&self) -> &'static str {
87 Self::HeldHtlcAvailable(_) => "Held HTLC Available",
88 Self::ReleaseHeldHtlc(msg) => msg.msg_type(),
93 impl Writeable for AsyncPaymentsMessage {
94 fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
96 Self::HeldHtlcAvailable(message) => message.write(w),
97 Self::ReleaseHeldHtlc(message) => message.write(w),
102 impl ReadableArgs<u64> for AsyncPaymentsMessage {
103 fn read<R: io::Read>(r: &mut R, tlv_type: u64) -> Result<Self, DecodeError> {
105 HELD_HTLC_AVAILABLE_TLV_TYPE => Ok(Self::HeldHtlcAvailable(Readable::read(r)?)),
106 RELEASE_HELD_HTLC_TLV_TYPE => Ok(Self::ReleaseHeldHtlc(Readable::read(r)?)),
107 _ => Err(DecodeError::InvalidValue),