Skip to content

Commit 9c5d746

Browse files
shaavanshaavan
committed
Move create_refund_builder to OffersMessageFlow
1 parent 92e633a commit 9c5d746

File tree

5 files changed

+206
-176
lines changed

5 files changed

+206
-176
lines changed

‎lightning/src/ln/channelmanager.rs

Lines changed: 16 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ use crate::offers::invoice_request::{InvoiceRequest, InvoiceRequestBuilder};
7070
use crate::offers::nonce::Nonce;
7171
use crate::offers::offer::Offer;
7272
use crate::offers::parse::Bolt12SemanticError;
73-
use crate::offers::refund::{Refund, RefundBuilder};
73+
use crate::offers::refund::Refund;
7474
use crate::offers::signer;
7575
#[cfg(async_payments)]
7676
use crate::offers::static_invoice::StaticInvoice;
@@ -102,8 +102,6 @@ use {
102102
crate::routing::scoring::{ProbabilisticScorer, ProbabilisticScoringFeeParameters},
103103
crate::sign::KeysManager,
104104
};
105-
#[cfg(c_bindings)]
106-
use crate::offers::refund::RefundMaybeWithDerivedMetadataBuilder;
107105

108106
use lightning_invoice::{Bolt11Invoice, Bolt11InvoiceDescription, CreationError, Currency, Description, InvoiceBuilder as Bolt11InvoiceBuilder, SignOrCreationError, DEFAULT_EXPIRY_TIME};
109107

@@ -1975,6 +1973,7 @@ where
19751973
/// # use lightning::events::{Event, EventsProvider};
19761974
/// # use lightning::types::payment::PaymentHash;
19771975
/// # use lightning::ln::channelmanager::{AChannelManager, PaymentId, RecentPaymentDetails, RecipientOnionFields, Retry};
1976+
/// # use lightning::offers::flow::OffersMessageCommons;
19781977
/// # use lightning::routing::router::RouteParameters;
19791978
/// #
19801979
/// # fn example<T: AChannelManager>(
@@ -2029,6 +2028,7 @@ where
20292028
/// ```
20302029
/// # use lightning::events::{Event, EventsProvider};
20312030
/// # use lightning::ln::channelmanager::{AChannelManager, PaymentId, RecentPaymentDetails, Retry};
2031+
/// # use lightning::offers::flow::OffersMessageCommons;
20322032
/// # use lightning::offers::offer::Offer;
20332033
/// #
20342034
/// # fn example<T: AChannelManager>(
@@ -2075,67 +2075,8 @@ where
20752075
/// ```
20762076
///
20772077
/// ## BOLT 12 Refunds
2078-
///
2079-
/// A [`Refund`] is a request for an invoice to be paid. Like *paying* for an [`Offer`], *creating*
2080-
/// a [`Refund`] involves maintaining state since it represents a future outbound payment.
2081-
/// Therefore, use [`create_refund_builder`] when creating one, otherwise [`ChannelManager`] will
2082-
/// refuse to pay any corresponding [`Bolt12Invoice`] that it receives.
2083-
///
2084-
/// ```
2085-
/// # use core::time::Duration;
2086-
/// # use lightning::events::{Event, EventsProvider};
2087-
/// # use lightning::ln::channelmanager::{AChannelManager, PaymentId, RecentPaymentDetails, Retry};
2088-
/// # use lightning::offers::parse::Bolt12SemanticError;
2089-
/// #
2090-
/// # fn example<T: AChannelManager>(
2091-
/// # channel_manager: T, amount_msats: u64, absolute_expiry: Duration, retry: Retry,
2092-
/// # max_total_routing_fee_msat: Option<u64>
2093-
/// # ) -> Result<(), Bolt12SemanticError> {
2094-
/// # let channel_manager = channel_manager.get_cm();
2095-
/// let payment_id = PaymentId([42; 32]);
2096-
/// let refund = channel_manager
2097-
/// .create_refund_builder(
2098-
/// amount_msats, absolute_expiry, payment_id, retry, max_total_routing_fee_msat
2099-
/// )?
2100-
/// # ;
2101-
/// # // Needed for compiling for c_bindings
2102-
/// # let builder: lightning::offers::refund::RefundBuilder<_> = refund.into();
2103-
/// # let refund = builder
2104-
/// .description("coffee".to_string())
2105-
/// .payer_note("refund for order 1234".to_string())
2106-
/// .build()?;
2107-
/// let bech32_refund = refund.to_string();
2108-
///
2109-
/// // First the payment will be waiting on an invoice
2110-
/// let expected_payment_id = payment_id;
2111-
/// assert!(
2112-
/// channel_manager.list_recent_payments().iter().find(|details| matches!(
2113-
/// details,
2114-
/// RecentPaymentDetails::AwaitingInvoice { payment_id: expected_payment_id }
2115-
/// )).is_some()
2116-
/// );
2117-
///
2118-
/// // Once the invoice is received, a payment will be sent
2119-
/// assert!(
2120-
/// channel_manager.list_recent_payments().iter().find(|details| matches!(
2121-
/// details,
2122-
/// RecentPaymentDetails::Pending { payment_id: expected_payment_id, .. }
2123-
/// )).is_some()
2124-
/// );
2125-
///
2126-
/// // On the event processing thread
2127-
/// channel_manager.process_pending_events(&|event| {
2128-
/// match event {
2129-
/// Event::PaymentSent { payment_id: Some(payment_id), .. } => println!("Paid {}", payment_id),
2130-
/// Event::PaymentFailed { payment_id, .. } => println!("Failed paying {}", payment_id),
2131-
/// // ...
2132-
/// # _ => {},
2133-
/// }
2134-
/// Ok(())
2135-
/// });
2136-
/// # Ok(())
2137-
/// # }
2138-
/// ```
2078+
///
2079+
/// For more information on creating refunds, see [`create_refund_builder`].
21392080
///
21402081
/// Use [`request_refund_payment`] to send a [`Bolt12Invoice`] for receiving the refund. Similar to
21412082
/// *creating* an [`Offer`], this is stateless as it represents an inbound payment.
@@ -2264,7 +2205,6 @@ where
22642205
/// [`offers`]: crate::offers
22652206
/// [`pay_for_offer`]: Self::pay_for_offer
22662207
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
2267-
/// [`create_refund_builder`]: Self::create_refund_builder
22682208
/// [`request_refund_payment`]: Self::request_refund_payment
22692209
/// [`peer_disconnected`]: msgs::ChannelMessageHandler::peer_disconnected
22702210
/// [`funding_created`]: msgs::FundingCreated
@@ -2274,6 +2214,7 @@ where
22742214
/// [`ChannelUpdate`]: msgs::ChannelUpdate
22752215
/// [`read`]: ReadableArgs::read
22762216
/// [`create_offer_builder`]: crate::offers::flow::OffersMessageFlow::create_offer_builder
2217+
/// [`create_refund_builder`]: crate::offers::flow::OffersMessageFlow::create_refund_builder
22772218
//
22782219
// Lock order:
22792220
// The tree structure below illustrates the lock order requirements for the different locks of the
@@ -2772,12 +2713,14 @@ const MAX_NO_CHANNEL_PEERS: usize = 250;
27722713
/// The maximum expiration from the current time where an [`Offer`] or [`Refund`] is considered
27732714
/// short-lived, while anything with a greater expiration is considered long-lived.
27742715
///
2775-
/// Using [`OffersMessageFlow::create_offer_builder`] or [`ChannelManager::create_refund_builder`],
2716+
/// Using [`OffersMessageFlow::create_offer_builder`] or [`OffersMessageFlow::create_refund_builder`],
27762717
/// will included a [`BlindedMessagePath`] created using:
27772718
/// - [`MessageRouter::create_compact_blinded_paths`] when short-lived, and
27782719
/// - [`MessageRouter::create_blinded_paths`] when long-lived.
27792720
///
27802721
/// [`OffersMessageFlow::create_offer_builder`]: crate::offers::flow::OffersMessageFlow::create_offer_builder
2722+
/// [`OffersMessageFlow::create_refund_builder`]: crate::offers::flow::OffersMessageFlow::create_refund_builder
2723+
///
27812724
///
27822725
/// Using compact [`BlindedMessagePath`]s may provide better privacy as the [`MessageRouter`] could select
27832726
/// more hops. However, since they use short channel ids instead of pubkeys, they are more likely to
@@ -9671,87 +9614,6 @@ impl Default for Bolt11InvoiceParameters {
96719614
}
96729615
}
96739616

9674-
macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
9675-
/// Creates a [`RefundBuilder`] such that the [`Refund`] it builds is recognized by the
9676-
/// [`ChannelManager`] when handling [`Bolt12Invoice`] messages for the refund.
9677-
///
9678-
/// # Payment
9679-
///
9680-
/// The provided `payment_id` is used to ensure that only one invoice is paid for the refund.
9681-
/// See [Avoiding Duplicate Payments] for other requirements once the payment has been sent.
9682-
///
9683-
/// The builder will have the provided expiration set. Any changes to the expiration on the
9684-
/// returned builder will not be honored by [`ChannelManager`]. For non-`std`, the highest seen
9685-
/// block time minus two hours is used for the current time when determining if the refund has
9686-
/// expired.
9687-
///
9688-
/// To revoke the refund, use [`ChannelManager::abandon_payment`] prior to receiving the
9689-
/// invoice. If abandoned, or an invoice isn't received before expiration, the payment will fail
9690-
/// with an [`Event::PaymentFailed`].
9691-
///
9692-
/// If `max_total_routing_fee_msat` is not specified, The default from
9693-
/// [`RouteParameters::from_payment_params_and_value`] is applied.
9694-
///
9695-
/// # Privacy
9696-
///
9697-
/// Uses [`MessageRouter`] to construct a [`BlindedMessagePath`] for the refund based on the given
9698-
/// `absolute_expiry` according to [`MAX_SHORT_LIVED_RELATIVE_EXPIRY`]. See those docs for
9699-
/// privacy implications as well as those of the parameterized [`Router`], which implements
9700-
/// [`MessageRouter`].
9701-
///
9702-
/// Also, uses a derived payer id in the refund for payer privacy.
9703-
///
9704-
/// # Limitations
9705-
///
9706-
/// Requires a direct connection to an introduction node in the responding
9707-
/// [`Bolt12Invoice::payment_paths`].
9708-
///
9709-
/// # Errors
9710-
///
9711-
/// Errors if:
9712-
/// - a duplicate `payment_id` is provided given the caveats in the aforementioned link,
9713-
/// - `amount_msats` is invalid, or
9714-
/// - the parameterized [`Router`] is unable to create a blinded path for the refund.
9715-
///
9716-
/// [`Refund`]: crate::offers::refund::Refund
9717-
/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
9718-
/// [`Bolt12Invoice::payment_paths`]: crate::offers::invoice::Bolt12Invoice::payment_paths
9719-
/// [Avoiding Duplicate Payments]: #avoiding-duplicate-payments
9720-
pub fn create_refund_builder(
9721-
&$self, amount_msats: u64, absolute_expiry: Duration, payment_id: PaymentId,
9722-
retry_strategy: Retry, max_total_routing_fee_msat: Option<u64>
9723-
) -> Result<$builder, Bolt12SemanticError> {
9724-
let node_id = $self.get_our_node_id();
9725-
let expanded_key = &$self.inbound_payment_key;
9726-
let entropy = &*$self.entropy_source;
9727-
let secp_ctx = &$self.secp_ctx;
9728-
9729-
let nonce = Nonce::from_entropy_source(entropy);
9730-
let context = OffersContext::OutboundPayment { payment_id, nonce, hmac: None };
9731-
let path = $self.create_blinded_paths_using_absolute_expiry(context, Some(absolute_expiry))
9732-
.and_then(|paths| paths.into_iter().next().ok_or(()))
9733-
.map_err(|_| Bolt12SemanticError::MissingPaths)?;
9734-
9735-
let builder = RefundBuilder::deriving_signing_pubkey(
9736-
node_id, expanded_key, nonce, secp_ctx, amount_msats, payment_id
9737-
)?
9738-
.chain_hash($self.chain_hash)
9739-
.absolute_expiry(absolute_expiry)
9740-
.path(path);
9741-
9742-
let _persistence_guard = PersistenceNotifierGuard::notify_on_drop($self);
9743-
9744-
let expiration = StaleExpiration::AbsoluteTimeout(absolute_expiry);
9745-
$self.pending_outbound_payments
9746-
.add_new_awaiting_invoice(
9747-
payment_id, expiration, retry_strategy, max_total_routing_fee_msat, None,
9748-
)
9749-
.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
9750-
9751-
Ok(builder.into())
9752-
}
9753-
} }
9754-
97559617
impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, MR: Deref, L: Deref> OffersMessageCommons for ChannelManager<M, T, ES, NS, SP, F, R, MR, L>
97569618
where
97579619
M::Target: chain::Watch<<SP::Target as SignerProvider>::EcdsaSigner>,
@@ -9975,6 +9837,13 @@ where
99759837
fn get_chain_hash(&self) -> ChainHash {
99769838
self.chain_hash
99779839
}
9840+
9841+
fn add_new_awaiting_invoice(&self, payment_id: PaymentId, expiration: StaleExpiration, retry_strategy: Retry, max_total_routing_fee_msat: Option<u64>, retryable_invoice_request: Option<RetryableInvoiceRequest>) -> Result<(), ()> {
9842+
let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
9843+
self.pending_outbound_payments.add_new_awaiting_invoice (
9844+
payment_id, expiration, retry_strategy, max_total_routing_fee_msat, retryable_invoice_request,
9845+
)
9846+
}
99789847
}
99799848

99809849
/// Defines the maximum number of [`OffersMessage`] including different reply paths to be sent
@@ -9996,12 +9865,6 @@ where
99969865
MR::Target: MessageRouter,
99979866
L::Target: Logger,
99989867
{
9999-
#[cfg(not(c_bindings))]
10000-
create_refund_builder!(self, RefundBuilder<secp256k1::All>);
10001-
10002-
#[cfg(c_bindings)]
10003-
create_refund_builder!(self, RefundMaybeWithDerivedMetadataBuilder);
10004-
100059868
/// Pays for an [`Offer`] using the given parameters by creating an [`InvoiceRequest`] and
100069869
/// enqueuing it to be sent via an onion message. [`ChannelManager`] will pay the actual
100079870
/// [`Bolt12Invoice`] once it is received.

‎lightning/src/ln/offers_tests.rs

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -452,7 +452,7 @@ fn creates_short_lived_refund() {
452452

453453
let absolute_expiry = bob.node.duration_since_epoch() + MAX_SHORT_LIVED_RELATIVE_EXPIRY;
454454
let payment_id = PaymentId([1; 32]);
455-
let refund = bob.node
455+
let refund = bob.offers_handler
456456
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
457457
.unwrap()
458458
.build().unwrap();
@@ -481,7 +481,7 @@ fn creates_long_lived_refund() {
481481
let absolute_expiry = bob.node.duration_since_epoch() + MAX_SHORT_LIVED_RELATIVE_EXPIRY
482482
+ Duration::from_secs(1);
483483
let payment_id = PaymentId([1; 32]);
484-
let refund = bob.node
484+
let refund = bob.offers_handler
485485
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
486486
.unwrap()
487487
.build().unwrap();
@@ -640,7 +640,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
640640

641641
let absolute_expiry = Duration::from_secs(u64::MAX);
642642
let payment_id = PaymentId([1; 32]);
643-
let refund = david.node
643+
let refund = david.offers_handler
644644
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
645645
.unwrap()
646646
.build().unwrap();
@@ -769,7 +769,7 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
769769

770770
let absolute_expiry = Duration::from_secs(u64::MAX);
771771
let payment_id = PaymentId([1; 32]);
772-
let refund = bob.node
772+
let refund = bob.offers_handler
773773
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
774774
.unwrap()
775775
.build().unwrap();
@@ -878,7 +878,7 @@ fn pays_for_refund_without_blinded_paths() {
878878

879879
let absolute_expiry = Duration::from_secs(u64::MAX);
880880
let payment_id = PaymentId([1; 32]);
881-
let refund = bob.node
881+
let refund = bob.offers_handler
882882
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
883883
.unwrap()
884884
.clear_paths()
@@ -1033,7 +1033,7 @@ fn send_invoice_for_refund_with_distinct_reply_path() {
10331033

10341034
let absolute_expiry = Duration::from_secs(u64::MAX);
10351035
let payment_id = PaymentId([1; 32]);
1036-
let refund = alice.node
1036+
let refund = alice.offers_handler
10371037
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
10381038
.unwrap()
10391039
.build().unwrap();
@@ -1236,7 +1236,7 @@ fn creates_refund_with_blinded_path_using_unannounced_introduction_node() {
12361236

12371237
let absolute_expiry = Duration::from_secs(u64::MAX);
12381238
let payment_id = PaymentId([1; 32]);
1239-
let refund = bob.node
1239+
let refund = bob.offers_handler
12401240
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
12411241
.unwrap()
12421242
.build().unwrap();
@@ -1519,7 +1519,7 @@ fn fails_authentication_when_handling_invoice_for_refund() {
15191519

15201520
let absolute_expiry = Duration::from_secs(u64::MAX);
15211521
let payment_id = PaymentId([1; 32]);
1522-
let refund = david.node
1522+
let refund = david.offers_handler
15231523
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
15241524
.unwrap()
15251525
.build().unwrap();
@@ -1553,7 +1553,7 @@ fn fails_authentication_when_handling_invoice_for_refund() {
15531553
// Send the invoice to David using an invalid blinded path.
15541554
let invalid_path = refund.paths().first().unwrap().clone();
15551555
let payment_id = PaymentId([2; 32]);
1556-
let refund = david.node
1556+
let refund = david.offers_handler
15571557
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
15581558
.unwrap()
15591559
.build().unwrap();
@@ -1680,7 +1680,7 @@ fn fails_creating_refund_or_sending_invoice_without_connected_peers() {
16801680

16811681
let absolute_expiry = david.node.duration_since_epoch() + MAX_SHORT_LIVED_RELATIVE_EXPIRY;
16821682
let payment_id = PaymentId([1; 32]);
1683-
match david.node.create_refund_builder(
1683+
match david.offers_handler.create_refund_builder(
16841684
10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None
16851685
) {
16861686
Ok(_) => panic!("Expected error"),
@@ -1691,7 +1691,7 @@ fn fails_creating_refund_or_sending_invoice_without_connected_peers() {
16911691
args.send_channel_ready = (true, true);
16921692
reconnect_nodes(args);
16931693

1694-
let refund = david.node
1694+
let refund = david.offers_handler
16951695
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
16961696
.unwrap()
16971697
.build().unwrap();
@@ -1749,7 +1749,7 @@ fn fails_sending_invoice_with_unsupported_chain_for_refund() {
17491749

17501750
let absolute_expiry = Duration::from_secs(u64::MAX);
17511751
let payment_id = PaymentId([1; 32]);
1752-
let refund = bob.node
1752+
let refund = bob.offers_handler
17531753
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
17541754
.unwrap()
17551755
.chain(Network::Signet)
@@ -1847,13 +1847,13 @@ fn fails_creating_refund_with_duplicate_payment_id() {
18471847
let absolute_expiry = Duration::from_secs(u64::MAX);
18481848
let payment_id = PaymentId([1; 32]);
18491849
assert!(
1850-
nodes[0].node.create_refund_builder(
1850+
nodes[0].offers_handler.create_refund_builder(
18511851
10_000, absolute_expiry, payment_id, Retry::Attempts(0), None
18521852
).is_ok()
18531853
);
18541854
expect_recent_payment!(nodes[0], RecentPaymentDetails::AwaitingInvoice, payment_id);
18551855

1856-
match nodes[0].node.create_refund_builder(
1856+
match nodes[0].offers_handler.create_refund_builder(
18571857
10_000, absolute_expiry, payment_id, Retry::Attempts(0), None
18581858
) {
18591859
Ok(_) => panic!("Expected error"),
@@ -1973,7 +1973,7 @@ fn fails_sending_invoice_without_blinded_payment_paths_for_refund() {
19731973

19741974
let absolute_expiry = Duration::from_secs(u64::MAX);
19751975
let payment_id = PaymentId([1; 32]);
1976-
let refund = david.node
1976+
let refund = david.offers_handler
19771977
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
19781978
.unwrap()
19791979
.build().unwrap();
@@ -2022,7 +2022,7 @@ fn fails_paying_invoice_more_than_once() {
20222022

20232023
let absolute_expiry = Duration::from_secs(u64::MAX);
20242024
let payment_id = PaymentId([1; 32]);
2025-
let refund = david.node
2025+
let refund = david.offers_handler
20262026
.create_refund_builder(10_000_000, absolute_expiry, payment_id, Retry::Attempts(0), None)
20272027
.unwrap()
20282028
.build().unwrap();

0 commit comments

Comments
 (0)