BOLT 12 invoice encoding and building#1926

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

Merged
TheBlueMatt merged 11 commits into from
Jan 23, 2023
Merged

BOLT 12 invoice encoding and building #1926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
bd0040a
Drop AsRef<[u8]> implementation for TlvRecord
jkczyz Dec 22, 2022
6b35354
Define TlvStream::skip_signatures
jkczyz Dec 22, 2022
243f448
Encoding for TLV stream without signature records
jkczyz Dec 22, 2022
e1aa18a
Invoice encoding and parsing
jkczyz Sep 12, 2022
88c5197
Builder for creating invoices for offers
jkczyz Dec 20, 2022
f779bc0
Builder for creating invoices for refunds
jkczyz Dec 20, 2022
7f52d26
Use SystemTime::now() for Invoice creation time
jkczyz Jan 13, 2023
fe83aed
Expand invoice module docs and include an example
jkczyz Jan 18, 2023
bf1147f
Invoice building tests
jkczyz Jan 16, 2023
a452551
Invoice parsing tests
jkczyz Jan 16, 2023
15f1295
Fix unused_imports warning in no-std tests
jkczyz Jan 19, 2023
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
1,565 changes: 1,565 additions & 0 deletions lightning/src/offers/invoice.rs
View file
Open in desktop

Large diffs are not rendered by default.

54 changes: 48 additions & 6 deletions lightning/src/offers/invoice_request.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
pub(super) bytes: Vec<u8>,
contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
payer: PayerContents,
offer: OfferContents,
pub(super) offer: OfferContents,
chain: Option<ChainHash>,
amount_msats: Option<u64>,
features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
self.signature
}

/// Creates an [`Invoice`] for the request with the given required fields.
///
/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
/// is not available.
///
/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment

@valentinewallacevalentinewallaceJan 21, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too

@jkczyzjkczyzJan 21, 2023

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.

/// for the invoice.
///
/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It

@valentinewallacevalentinewallaceJan 21, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here

/// must contain one or more elements.

@valentinewallacevalentinewallaceJan 21, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred

///
/// Errors if the request contains unknown required features.
///
/// [`Duration`]: core::time::Duration
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
pub fn respond_with(
&self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
#[cfg(any(test, not(feature = "std")))]
created_at: core::time::Duration
) -> Result<InvoiceBuilder, SemanticError> {
if self.features().requires_unknown_bits() {
return Err(SemanticError::UnknownRequiredFeatures);
}

#[cfg(all(not(test), feature = "std"))]
let created_at = std::time::SystemTime::now()
.duration_since(std::time::SystemTime::UNIX_EPOCH)
.expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
}

#[cfg(test)]
fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
self.chain.unwrap_or_else(|| self.offer.implied_chain())
}

Expand Down
72 changes: 60 additions & 12 deletions lightning/src/offers/merkle.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
let mut tlv_stream = TlvStream::new(&data[..]).peekable();
let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
let mut engine = sha256::Hash::engine();
engine.input("LnNonce".as_bytes());
engine.input(tlv_stream.peek().unwrap().record_bytes);
engine.input(first_tlv_record.record_bytes);
engine
}));
let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

let mut leaves = Vec::new();
for record in tlv_stream {
if !SIGNATURE_TYPES.contains(&record.r#type) {
leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
}
let tlv_stream = TlvStream::new(&data[..]);
for record in tlv_stream.skip_signatures() {
leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
}

// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
data: io::Cursor::new(data),
}
}

fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
#[inline]
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
let tlv_stream = TlvStream::new(&self.0[..]);
for record in tlv_stream.skip_signatures() {
writer.write_all(record.record_bytes)?;
}
Ok(())
}
}

#[cfg(test)]
mod tests {
use super::{TlvStream, WithoutSignatures};

use bitcoin::hashes::{Hash, sha256};
use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
use core::convert::Infallible;
use crate::offers::offer::{Amount, OfferBuilder};
use crate::offers::invoice_request::InvoiceRequest;
use crate::offers::parse::Bech32Encode;
use crate::util::ser::Writeable;

#[test]
fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
);
}

#[test]
fn skips_encoding_signature_tlv_records() {
let secp_ctx = Secp256k1::new();
let recipient_pubkey = {
let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
};
let payer_keys = {
let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
KeyPair::from_secret_key(&secp_ctx, &secret_key)
};

let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
.amount_msats(100)
.build_unchecked()
.request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
.build_unchecked()
.sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
.unwrap();

let mut bytes_without_signature = Vec::new();
WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

assert_ne!(bytes_without_signature, invoice_request.bytes);
assert_eq!(
TlvStream::new(&bytes_without_signature).count(),
TlvStream::new(&invoice_request.bytes).count() - 1,
);
}

impl AsRef<[u8]> for InvoiceRequest {
fn as_ref(&self) -> &[u8] {
&self.bytes
Expand Down
1 change: 1 addition & 0 deletions lightning/src/offers/mod.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down
31 changes: 21 additions & 10 deletions lightning/src/offers/offer.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
/// Whether the offer has expired.
#[cfg(feature = "std")]
pub fn is_expired(&self) -> bool {
match self.absolute_expiry() {
Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
Ok(elapsed) => elapsed > seconds_from_epoch,
Err(_) => false,
},
None => false,
}
self.contents.is_expired()
}

/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

/// The public key used by the recipient to sign invoices.
pub fn signing_pubkey(&self) -> PublicKey {
self.contents.signing_pubkey
self.contents.signing_pubkey()
}

/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
self.chains().contains(&chain)
}

#[cfg(feature = "std")]
pub(super) fn is_expired(&self) -> bool {
match self.absolute_expiry {
Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
Ok(elapsed) => elapsed > seconds_from_epoch,
Err(_) => false,
},
None => false,
}
}

pub fn amount(&self) -> Option<&Amount> {
self.amount.as_ref()
}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
}
}

pub(super) fn signing_pubkey(&self) -> PublicKey {
self.signing_pubkey
}

pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
let (currency, amount) = match &self.amount {
None => (None, None),
Expand Down
10 changes: 10 additions & 0 deletions lightning/src/offers/parse.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
MissingDescription,
/// A signing pubkey was not provided.
MissingSigningPubkey,
/// A signing pubkey was provided but a different one was expected.
InvalidSigningPubkey,
/// A signing pubkey was provided but was not expected.
UnexpectedSigningPubkey,
/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
MissingPayerMetadata,
/// A payer id was expected but was missing.
MissingPayerId,
/// Blinded paths were expected but were missing.
MissingPaths,
/// The blinded payinfo given does not match the number of blinded path hops.
InvalidPayInfo,
/// An invoice creation time was expected but was missing.
MissingCreationTime,
/// An invoice payment hash was expected but was missing.
MissingPaymentHash,
/// A signature was expected but was missing.
MissingSignature,
}
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
BOLT 12 invoice encoding and building#1926

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

 Merged

TheBlueMatt
merged 11 commits into

from

Jan 23, 2023
 Merged


BOLT 12 invoice encoding and building
#1926
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
bd0040a

Drop AsRef<[u8]> implementation for TlvRecord


jkczyz Dec 22, 2022
6b35354

Define TlvStream::skip_signatures


jkczyz Dec 22, 2022
243f448

Encoding for TLV stream without signature records


jkczyz Dec 22, 2022
e1aa18a

Invoice encoding and parsing


jkczyz Sep 12, 2022
88c5197

Builder for creating invoices for offers


jkczyz Dec 20, 2022
f779bc0

Builder for creating invoices for refunds


jkczyz Dec 20, 2022
7f52d26

Use SystemTime::now() for Invoice creation time


jkczyz Jan 13, 2023
fe83aed

Expand invoice module docs and include an example


jkczyz Jan 18, 2023
bf1147f

Invoice building tests


jkczyz Jan 16, 2023
a452551

Invoice parsing tests


jkczyz Jan 16, 2023
15f1295

Fix unused_imports warning in no-std tests


jkczyz Jan 19, 2023

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


1,565 changes: 1,565 additions & 0 deletions
lightning/src/offers/invoice.rs

View file


Open in desktop


Large diffs are not rendered by default.


54 changes: 48 additions & 6 deletions
lightning/src/offers/invoice_request.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,12 @@
//!
//! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is
//! typically constructed by a customer and sent to the merchant who had published the corresponding
//! offer. The recipient of the request responds with an `Invoice`.
//! offer. The recipient of the request responds with an [`Invoice`].
//!
//! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
//! precursor, see [`Refund`].
//!
//! [`Invoice`]: crate::offers::invoice::Invoice
//! [`Refund`]: crate::offers::refund::Refund
//!
//! ```ignore
Expand DownExpand Up@@ -57,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
use bitcoin::secp256k1::schnorr::Signature;
use core::convert::TryFrom;
use crate::io;
use crate::ln::PaymentHash;
use crate::ln::features::InvoiceRequestFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
use crate::util::string::PrintableString;

Expand DownExpand Up@@ -239,24 +243,27 @@ impl<'a> UnsignedInvoiceRequest<'a> {
	}
}

/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
///
/// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
/// specifies these such that its recipient can send an invoice for payment.
///
/// [`Invoice`]: crate::offers::invoice::Invoice
/// [`Offer`]: crate::offers::offer::Offer
#[derive(Clone, Debug)]
pub struct InvoiceRequest {
	pub(super) bytes: Vec<u8>,
	contents: InvoiceRequestContents,
pub(super) contents: InvoiceRequestContents,
	signature: Signature,
}

/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`].
///
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct InvoiceRequestContents {
	payer: PayerContents,
	offer: OfferContents,
pub(super) offer: OfferContents,
	chain: Option<ChainHash>,
	amount_msats: Option<u64>,
	features: InvoiceRequestFeatures,
Expand DownExpand Up@@ -315,6 +322,41 @@ impl InvoiceRequest {
 self.signature
	}

	/// Creates an [`Invoice`] for the request with the given required fields.
	///
	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
	/// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
	/// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
	/// is not available.
	///
	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

lightning-invoice has links to ChannelManager::create_inbound_payment*, may want some here too
@jkczyzjkczyzJan 21, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

We'll wait until the code is used in onion message handling before documenting. For Offers that code will construct the payment hash, though responding to a Refund may need some utility.
	/// for the invoice.
	///
	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

I think this could use more details about why it's required even when you're using a public node id. Maybe could live on Invoice::payment_paths with a docs link here
	/// must contain one or more elements.
@valentinewallacevalentinewallaceJan 21, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Should also note that these should be specified in order of most preferred to least preferred
	///
	/// Errors if the request contains unknown required features.
	///
	/// [`Duration`]: core::time::Duration
	/// [`Invoice`]: crate::offers::invoice::Invoice
	/// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
	pub fn respond_with(
 &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
 #[cfg(any(test, not(feature = "std")))]
 created_at: core::time::Duration
	) -> Result<InvoiceBuilder, SemanticError> {
 if self.features().requires_unknown_bits() {
 return Err(SemanticError::UnknownRequiredFeatures);
 }

 #[cfg(all(not(test), feature = "std"))]
 let created_at = std::time::SystemTime::now()
 .duration_since(std::time::SystemTime::UNIX_EPOCH)
 .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");

 InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
	}

	#[cfg(test)]
	fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
 let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =
Expand All@@ -327,7 +369,7 @@ impl InvoiceRequest {
}

impl InvoiceRequestContents {
	fn chain(&self) -> ChainHash {
pub(super) fn chain(&self) -> ChainHash {
 self.chain.unwrap_or_else(|| self.offer.implied_chain())
	}

Expand Down

72 changes: 60 additions & 12 deletions
lightning/src/offers/merkle.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
use bitcoin::secp256k1::schnorr::Signature;
use crate::io;
use crate::util::ser::{BigSize, Readable};
use crate::util::ser::{BigSize, Readable, Writeable, Writer};

use crate::prelude::*;

Expand DownExpand Up@@ -75,22 +75,21 @@ fn message_digest(tag: &str, bytes: &[u8]) -> Message {
/// Computes a merkle root hash for the given data, which must be a well-formed TLV stream
/// containing at least one TLV record.
fn root_hash(data: &[u8]) -> sha256::Hash {
	let mut tlv_stream = TlvStream::new(&data[..]).peekable();
	let nonce_tag = tagged_hash_engine(sha256::Hash::from_engine({
 let first_tlv_record = TlvStream::new(&data[..]).next().unwrap();
 let mut engine = sha256::Hash::engine();
 engine.input("LnNonce".as_bytes());
 engine.input(tlv_stream.peek().unwrap().record_bytes);
 engine.input(first_tlv_record.record_bytes);
 engine
	}));
	let leaf_tag = tagged_hash_engine(sha256::Hash::hash("LnLeaf".as_bytes()));
	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));

	let mut leaves = Vec::new();
	for record in tlv_stream {
 if !SIGNATURE_TYPES.contains(&record.r#type) {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
 }
	let tlv_stream = TlvStream::new(&data[..]);
	for record in tlv_stream.skip_signatures() {
 leaves.push(tagged_hash_from_engine(leaf_tag.clone(), &record.record_bytes));
 leaves.push(tagged_hash_from_engine(nonce_tag.clone(), &record.type_bytes));
	}

	// Calculate the merkle root hash in place.
Expand DownExpand Up@@ -154,6 +153,10 @@ impl<'a> TlvStream<'a> {
 data: io::Cursor::new(data),
 }
	}

	fn skip_signatures(self) -> core::iter::Filter<TlvStream<'a>, fn(&TlvRecord) -> bool> {
 self.filter(|record| !SIGNATURE_TYPES.contains(&record.r#type))
	}
}

/// A slice into a [`TlvStream`] for a record.
Expand All@@ -164,10 +167,6 @@ struct TlvRecord<'a> {
	record_bytes: &'a [u8],
}

impl AsRef<[u8]> for TlvRecord<'_> {
	fn as_ref(&self) -> &[u8] { &self.record_bytes }
}

impl<'a> Iterator for TlvStream<'a> {
	type Item = TlvRecord<'a>;

Expand DownExpand Up@@ -195,14 +194,33 @@ impl<'a> Iterator for TlvStream<'a> {
	}
}

/// Encoding for a pre-serialized TLV stream that excludes any signature TLV records.
///
/// Panics if the wrapped bytes are not a well-formed TLV stream.
pub(super) struct WithoutSignatures<'a>(pub &'a Vec<u8>);

impl<'a> Writeable for WithoutSignatures<'a> {
	#[inline]
	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 let tlv_stream = TlvStream::new(&self.0[..]);
 for record in tlv_stream.skip_signatures() {
 writer.write_all(record.record_bytes)?;
 }
 Ok(())
	}
}

#[cfg(test)]
mod tests {
	use super::{TlvStream, WithoutSignatures};

	use bitcoin::hashes::{Hash, sha256};
	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
	use core::convert::Infallible;
	use crate::offers::offer::{Amount, OfferBuilder};
	use crate::offers::invoice_request::InvoiceRequest;
	use crate::offers::parse::Bech32Encode;
	use crate::util::ser::Writeable;

	#[test]
	fn calculates_merkle_root_hash() {
Expand DownExpand Up@@ -254,6 +272,36 @@ mod tests {
 );
	}

	#[test]
	fn skips_encoding_signature_tlv_records() {
 let secp_ctx = Secp256k1::new();
 let recipient_pubkey = {
 let secret_key = SecretKey::from_slice(&[41; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key).public_key()
 };
 let payer_keys = {
 let secret_key = SecretKey::from_slice(&[42; 32]).unwrap();
 KeyPair::from_secret_key(&secp_ctx, &secret_key)
 };

 let invoice_request = OfferBuilder::new("foo".into(), recipient_pubkey)
 .amount_msats(100)
 .build_unchecked()
 .request_invoice(vec![0; 8], payer_keys.public_key()).unwrap()
 .build_unchecked()
 .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &payer_keys)))
 .unwrap();

 let mut bytes_without_signature = Vec::new();
 WithoutSignatures(&invoice_request.bytes).write(&mut bytes_without_signature).unwrap();

 assert_ne!(bytes_without_signature, invoice_request.bytes);
 assert_eq!(
 TlvStream::new(&bytes_without_signature).count(),
 TlvStream::new(&invoice_request.bytes).count() - 1,
 );
	}

	impl AsRef<[u8]> for InvoiceRequest {
 fn as_ref(&self) -> &[u8] {
 &self.bytes
Expand Down

1 change: 1 addition & 0 deletions
lightning/src/offers/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -12,6 +12,7 @@
//!
//! Offers are a flexible protocol for Lightning payments.

pub mod invoice;
pub mod invoice_request;
mod merkle;
pub mod offer;
Expand Down

31 changes: 21 additions & 10 deletions
lightning/src/offers/offer.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -232,7 +232,7 @@ impl OfferBuilder {
/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
///
/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
/// customer may request an `Invoice` for a specific quantity and using an amount sufficient to
/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to
/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
///
/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
Expand All@@ -241,6 +241,7 @@ impl OfferBuilder {
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub struct Offer {
	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
Expand All@@ -249,9 +250,10 @@ pub struct Offer {
	pub(super) contents: OfferContents,
}

/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
/// [`Invoice`]: crate::offers::invoice::Invoice
#[derive(Clone, Debug)]
pub(super) struct OfferContents {
	chains: Option<Vec<ChainHash>>,
Expand DownExpand Up@@ -319,13 +321,7 @@ impl Offer {
	/// Whether the offer has expired.
	#[cfg(feature = "std")]
	pub fn is_expired(&self) -> bool {
 match self.absolute_expiry() {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
 self.contents.is_expired()
	}

	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
Expand DownExpand Up@@ -359,7 +355,7 @@ impl Offer {

	/// The public key used by the recipient to sign invoices.
	pub fn signing_pubkey(&self) -> PublicKey {
 self.contents.signing_pubkey
 self.contents.signing_pubkey()
	}

	/// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
Expand DownExpand Up@@ -410,6 +406,17 @@ impl OfferContents {
 self.chains().contains(&chain)
	}

	#[cfg(feature = "std")]
	pub(super) fn is_expired(&self) -> bool {
 match self.absolute_expiry {
 Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
 Ok(elapsed) => elapsed > seconds_from_epoch,
 Err(_) => false,
 },
 None => false,
 }
	}

	pub fn amount(&self) -> Option<&Amount> {
 self.amount.as_ref()
	}
Expand DownExpand Up@@ -473,6 +480,10 @@ impl OfferContents {
 }
	}

	pub(super) fn signing_pubkey(&self) -> PublicKey {
 self.signing_pubkey
	}

	pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
 let (currency, amount) = match &self.amount {
 None => (None, None),
Expand Down

10 changes: 10 additions & 0 deletions
lightning/src/offers/parse.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -147,6 +147,8 @@ pub enum SemanticError {
	MissingDescription,
	/// A signing pubkey was not provided.
	MissingSigningPubkey,
	/// A signing pubkey was provided but a different one was expected.
	InvalidSigningPubkey,
	/// A signing pubkey was provided but was not expected.
	UnexpectedSigningPubkey,
	/// A quantity was expected but was missing.
Expand All@@ -159,6 +161,14 @@ pub enum SemanticError {
	MissingPayerMetadata,
	/// A payer id was expected but was missing.
	MissingPayerId,
	/// Blinded paths were expected but were missing.
	MissingPaths,
	/// The blinded payinfo given does not match the number of blinded path hops.
	InvalidPayInfo,
	/// An invoice creation time was expected but was missing.
	MissingCreationTime,
	/// An invoice payment hash was expected but was missing.
	MissingPaymentHash,
	/// A signature was expected but was missing.
	MissingSignature,
}
Expand Down
Loading