Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Implement a way to do BOLT 12 Proof of Payment #3593

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[RFC] Implement a way to do BOLT 12 Proof of Payment #3593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
265f6c1
Un-cfg-gate StaticInvoices
valentinewallace Feb 6, 2025
f80cd8d
ser: support LengthLimitedRead in impl_writeable_tlv_based_enum
vincenzopalazzo Mar 17, 2025
e2c9570
add the bolt12 invoice to the PaymentSend event
vincenzopalazzo Feb 7, 2025
0f406a2
store static invoice inside the PendingOutboundPayment::StaticInvoice…
vincenzopalazzo Mar 5, 2025
3929d07
meta: fix clippy warning that should not happen
vincenzopalazzo Mar 18, 2025
365548b
fixup! Un-cfg-gate StaticInvoices
vincenzopalazzo Apr 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion lightning/src/events/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -949,6 +949,16 @@ pub enum Event {
///
/// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees
fee_paid_msat: Option<u64>,
/// The BOLT 12 invoice that was paid. `None` if the payment was a non BOLT 12 payment.
///
/// The BOLT 12 invoice is useful for proof of payment because it contains the
/// payment hash. A third party can verify that the payment was made by
/// showing the invoice and confirming that the payment hash matches
/// the hash of the payment preimage.
Comment on lines +954 to +957
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This won't provide proof-of-payment if a static invoice is provided, could amend the docs for that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, this is the docs for the older version - now should be it, let me know how looks like now, and if you want to do some more iteration on it

///
/// However, the [`PaidInvoice`] can also be of type [`crate::offers::static_invoice::StaticInvoice`], which
/// is a special [`Bolt12Invoice`] where proof of payment is not possible.
bolt12_invoice: Option<PaidInvoice>,
},
/// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
/// provide failure information for each path attempt in the payment, including retries.
Expand Down Expand Up @@ -1556,14 +1566,15 @@ impl Writeable for Event {
(13, payment_id, option),
});
},
&Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat } => {
&Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat, ref bolt12_invoice } => {
2u8.write(writer)?;
write_tlv_fields!(writer, {
(0, payment_preimage, required),
(1, payment_hash, required),
(3, payment_id, option),
(5, fee_paid_msat, option),
(7, amount_msat, option),
(9, bolt12_invoice, option),
});
},
&Event::PaymentPathFailed {
Expand Down Expand Up @@ -1898,12 +1909,14 @@ impl MaybeReadable for Event {
let mut payment_id = None;
let mut amount_msat = None;
let mut fee_paid_msat = None;
let mut bolt12_invoice = None;
read_tlv_fields!(reader, {
(0, payment_preimage, required),
(1, payment_hash, option),
(3, payment_id, option),
(5, fee_paid_msat, option),
(7, amount_msat, option),
(9, bolt12_invoice, option),
});
if payment_hash.is_none() {
payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).to_byte_array()));
Expand All @@ -1914,6 +1927,7 @@ impl MaybeReadable for Event {
payment_hash: payment_hash.unwrap(),
amount_msat,
fee_paid_msat,
bolt12_invoice,
}))
};
f()
Expand Down Expand Up @@ -2438,3 +2452,17 @@ impl<T: EventHandler> EventHandler for Arc<T> {
self.deref().handle_event(event)
}
}

/// The BOLT 12 invoice that was paid, surfaced in [`Event::PaymentSent::bolt12_invoice`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum PaidInvoice {
///
Bolt12Invoice(crate::offers::invoice::Bolt12Invoice),
///
StaticInvoice(crate::offers::static_invoice::StaticInvoice),
}

impl_writeable_tlv_based_enum!(PaidInvoice,
{0, Bolt12Invoice} => (),
{2, StaticInvoice} => (),
);
9 changes: 6 additions & 3 deletions lightning/src/ln/async_payments_tests.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ use crate::blinded_path::message::{MessageContext, OffersContext};
use crate::blinded_path::payment::PaymentContext;
use crate::blinded_path::payment::{AsyncBolt12OfferContext, BlindedPaymentTlvs};
use crate::chain::channelmonitor::{HTLC_FAIL_BACK_BUFFER, LATENCY_GRACE_PERIOD_BLOCKS};
use crate::events::{Event, HTLCDestination, PaymentFailureReason};
use crate::events::{Event, HTLCDestination, PaidInvoice, PaymentFailureReason};
use crate::ln::blinded_payment_tests::{fail_blinded_htlc_backwards, get_blinded_route_parameters};
use crate::ln::channelmanager::{PaymentId, RecipientOnionFields};
use crate::ln::functional_test_utils::*;
Expand Down Expand Up @@ -420,7 +420,7 @@ fn async_receive_flow_success() {
.pay_for_offer(&offer, None, Some(amt_msat), None, payment_id, Retry::Attempts(0), params)
.unwrap();
let release_held_htlc_om =
pass_async_payments_oms(static_invoice, &nodes[0], &nodes[1], &nodes[2]).1;
pass_async_payments_oms(static_invoice.clone(), &nodes[0], &nodes[1], &nodes[2]).1;
nodes[0]
.onion_messenger
.handle_onion_message(nodes[2].node.get_our_node_id(), &release_held_htlc_om);
Expand All @@ -441,7 +441,10 @@ fn async_receive_flow_success() {
let args = PassAlongPathArgs::new(&nodes[0], route[0], amt_msat, payment_hash, ev)
.with_payment_preimage(keysend_preimage);
do_pass_along_path(args);
claim_payment_along_route(ClaimAlongRouteArgs::new(&nodes[0], route, keysend_preimage));
let res =
claim_payment_along_route(ClaimAlongRouteArgs::new(&nodes[0], route, keysend_preimage));
assert!(res.is_some());
assert_eq!(res, Some(PaidInvoice::StaticInvoice(static_invoice)));
}

#[cfg_attr(feature = "std", ignore)]
Expand Down
27 changes: 17 additions & 10 deletions lightning/src/ln/functional_test_utils.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
use crate::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen, Watch, chainmonitor::Persist};
use crate::chain::channelmonitor::ChannelMonitor;
use crate::chain::transaction::OutPoint;
use crate::events::{ClaimedHTLC, ClosureReason, Event, HTLCDestination, PathFailure, PaymentPurpose, PaymentFailureReason};
use crate::events::{ClaimedHTLC, ClosureReason, Event, HTLCDestination, PaidInvoice, PathFailure, PaymentFailureReason, PaymentPurpose};
use crate::events::bump_transaction::{BumpTransactionEvent, BumpTransactionEventHandler, Wallet, WalletSource};
use crate::ln::types::ChannelId;
use crate::types::payment::{PaymentPreimage, PaymentHash, PaymentSecret};
Expand Down Expand Up @@ -2294,7 +2294,7 @@ macro_rules! expect_payment_claimed {
pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM=CM>>(node: &H,
expected_payment_preimage: PaymentPreimage, expected_fee_msat_opt: Option<Option<u64>>,
expect_per_path_claims: bool, expect_post_ev_mon_update: bool,
) {
) -> Option<PaidInvoice> {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like we don't currently check that this is set for any static invoices, could you add a check in one of the calls to claim_payment_along_route in async_payments_tests.rs`?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch thanks

let events = node.node().get_and_clear_pending_events();
let expected_payment_hash = PaymentHash(
bitcoin::hashes::sha256::Hash::hash(&expected_payment_preimage.0).to_byte_array());
Expand All @@ -2306,8 +2306,11 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM=CM>>(node: &H,
if expect_post_ev_mon_update {
check_added_monitors(node, 1);
}
// We return the invoice because some test may want to check the invoice details.
#[allow(unused_assignments)]
let mut invoice = None;
let expected_payment_id = match events[0] {
Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat } => {
Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat, ref bolt12_invoice } => {
assert_eq!(expected_payment_preimage, *payment_preimage);
assert_eq!(expected_payment_hash, *payment_hash);
assert!(amount_msat.is_some());
Expand All @@ -2316,6 +2319,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM=CM>>(node: &H,
} else {
assert!(fee_paid_msat.is_some());
}
invoice = bolt12_invoice.clone();
payment_id.unwrap()
},
_ => panic!("Unexpected event"),
Expand All @@ -2331,19 +2335,20 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM=CM>>(node: &H,
}
}
}
invoice
}

#[macro_export]
macro_rules! expect_payment_sent {
($node: expr, $expected_payment_preimage: expr) => {
$crate::expect_payment_sent!($node, $expected_payment_preimage, None::<u64>, true);
$crate::expect_payment_sent!($node, $expected_payment_preimage, None::<u64>, true)
};
($node: expr, $expected_payment_preimage: expr, $expected_fee_msat_opt: expr) => {
$crate::expect_payment_sent!($node, $expected_payment_preimage, $expected_fee_msat_opt, true);
$crate::expect_payment_sent!($node, $expected_payment_preimage, $expected_fee_msat_opt, true)
};
($node: expr, $expected_payment_preimage: expr, $expected_fee_msat_opt: expr, $expect_paths: expr) => {
$crate::ln::functional_test_utils::expect_payment_sent(&$node, $expected_payment_preimage,
$expected_fee_msat_opt.map(|o| Some(o)), $expect_paths, true);
$expected_fee_msat_opt.map(|o| Some(o)), $expect_paths, true)
}
}

Expand Down Expand Up @@ -3106,20 +3111,22 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {

expected_total_fee_msat
}
pub fn claim_payment_along_route(args: ClaimAlongRouteArgs) {
pub fn claim_payment_along_route(args: ClaimAlongRouteArgs) -> Option<PaidInvoice> {
let origin_node = args.origin_node;
let payment_preimage = args.payment_preimage;
let skip_last = args.skip_last;
let expected_total_fee_msat = do_claim_payment_along_route(args);
if !skip_last {
expect_payment_sent!(origin_node, payment_preimage, Some(expected_total_fee_msat));
expect_payment_sent!(origin_node, payment_preimage, Some(expected_total_fee_msat))
} else {
None
}
}

pub fn claim_payment<'a, 'b, 'c>(origin_node: &Node<'a, 'b, 'c>, expected_route: &[&Node<'a, 'b, 'c>], our_payment_preimage: PaymentPreimage) {
pub fn claim_payment<'a, 'b, 'c>(origin_node: &Node<'a, 'b, 'c>, expected_route: &[&Node<'a, 'b, 'c>], our_payment_preimage: PaymentPreimage) -> Option<PaidInvoice> {
claim_payment_along_route(
ClaimAlongRouteArgs::new(origin_node, &[expected_route], our_payment_preimage)
);
)
}

pub const TEST_FINAL_CLTV: u32 = 70;
Expand Down
30 changes: 17 additions & 13 deletions lightning/src/ln/offers_tests.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ use crate::blinded_path::IntroductionNode;
use crate::blinded_path::message::BlindedMessagePath;
use crate::blinded_path::payment::{Bolt12OfferContext, Bolt12RefundContext, PaymentContext};
use crate::blinded_path::message::OffersContext;
use crate::events::{ClosureReason, Event, HTLCDestination, PaymentFailureReason, PaymentPurpose};
use crate::events::{ClosureReason, Event, HTLCDestination, PaidInvoice, PaymentFailureReason, PaymentPurpose};
use crate::ln::channelmanager::{Bolt12PaymentError, MAX_SHORT_LIVED_RELATIVE_EXPIRY, PaymentId, RecentPaymentDetails, RecipientOnionFields, Retry, self};
use crate::types::features::Bolt12InvoiceFeatures;
use crate::ln::functional_test_utils::*;
Expand Down Expand Up @@ -167,7 +167,7 @@ fn route_bolt12_payment<'a, 'b, 'c>(
}

fn claim_bolt12_payment<'a, 'b, 'c>(
node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext
node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext, invoice: &Bolt12Invoice
) {
let recipient = &path[path.len() - 1];
let payment_purpose = match get_event!(recipient, Event::PaymentClaimable) {
Expand All @@ -187,7 +187,11 @@ fn claim_bolt12_payment<'a, 'b, 'c>(
},
_ => panic!("Unexpected payment purpose: {:?}", payment_purpose),
}
claim_payment(node, path, payment_preimage);
if let Some(inv) = claim_payment(node, path, payment_preimage) {
assert_eq!(inv, PaidInvoice::Bolt12Invoice(invoice.to_owned()));
} else {
panic!("Expected PaidInvoice::Bolt12Invoice");
};
}

fn extract_offer_nonce<'a, 'b, 'c>(node: &Node<'a, 'b, 'c>, message: &OnionMessage) -> Nonce {
Expand Down Expand Up @@ -591,7 +595,7 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
expect_recent_payment!(david, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice);
expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -674,7 +678,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
expect_recent_payment!(david, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice);
expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -741,7 +745,7 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -797,7 +801,7 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -851,7 +855,7 @@ fn pays_for_offer_without_blinded_paths() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -894,7 +898,7 @@ fn pays_for_refund_without_blinded_paths() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -1132,7 +1136,7 @@ fn creates_and_pays_for_offer_with_retry() {
}
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -1203,7 +1207,7 @@ fn pays_bolt12_invoice_asynchronously() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);

assert_eq!(
Expand Down Expand Up @@ -1283,7 +1287,7 @@ fn creates_offer_with_blinded_path_using_unannounced_introduction_node() {
route_bolt12_payment(bob, &[alice], &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);

claim_bolt12_payment(bob, &[alice], payment_context);
claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down Expand Up @@ -2139,7 +2143,7 @@ fn fails_paying_invoice_more_than_once() {
assert!(david.node.get_and_clear_pending_msg_events().is_empty());

// Complete paying the first invoice
claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice1);
expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
}

Expand Down
Loading
Loading