X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Foffers%2Frefund.rs;h=16014cd3c0b7ac6080a31b1c198b7bb669798219;hb=1d9e541c5766eb03dfaee7844b27b3bc1d60a05e;hp=35c1726c977debf28a06cbf50561a3c3bb159555;hpb=f8c9b092fdeab598431a0d05e4ccb914c2ca0a4f;p=rust-lightning

diff --git a/lightning/src/offers/refund.rs b/lightning/src/offers/refund.rs
index 35c1726c..16014cd3 100644
--- a/lightning/src/offers/refund.rs
+++ b/lightning/src/offers/refund.rs
@@ -18,6 +18,8 @@
 //! [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 //! [`Offer`]: crate::offers::offer::Offer
 //!
+//! # Example
+//!
 //! ```
 //! extern crate bitcoin;
 //! extern crate core;
@@ -28,7 +30,7 @@
 //!
 //! use bitcoin::network::constants::Network;
 //! use bitcoin::secp256k1::{KeyPair, PublicKey, Secp256k1, SecretKey};
-//! use lightning::offers::parse::ParseError;
+//! use lightning::offers::parse::Bolt12ParseError;
 //! use lightning::offers::refund::{Refund, RefundBuilder};
 //! use lightning::util::ser::{Readable, Writeable};
 //!
@@ -40,7 +42,7 @@
 //! # fn create_another_blinded_path() -> BlindedPath { unimplemented!() }
 //! #
 //! # #[cfg(feature = "std")]
-//! # fn build() -> Result<(), ParseError> {
+//! # fn build() -> Result<(), Bolt12ParseError> {
 //! let secp_ctx = Secp256k1::new();
 //! let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32]).unwrap());
 //! let pubkey = PublicKey::from(keys);
@@ -70,11 +72,19 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Note
+//!
+//! If constructing a [`Refund`] for use with a [`ChannelManager`], use
+//! [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`].
+//!
+//! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+//! [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder
 
 use bitcoin::blockdata::constants::ChainHash;
 use bitcoin::network::constants::Network;
 use bitcoin::secp256k1::{PublicKey, Secp256k1, self};
-use core::convert::TryFrom;
+use core::hash::{Hash, Hasher};
 use core::ops::Deref;
 use core::str::FromStr;
 use core::time::Duration;
@@ -82,18 +92,29 @@ use crate::sign::EntropySource;
 use crate::io;
 use crate::blinded_path::BlindedPath;
 use crate::ln::PaymentHash;
+use crate::ln::channelmanager::PaymentId;
 use crate::ln::features::InvoiceRequestFeatures;
 use crate::ln::inbound_payment::{ExpandedKey, IV_LEN, Nonce};
 use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT};
-use crate::offers::invoice::{BlindedPayInfo, DerivedSigningPubkey, ExplicitSigningPubkey, InvoiceBuilder};
+use crate::offers::invoice::BlindedPayInfo;
 use crate::offers::invoice_request::{InvoiceRequestTlvStream, InvoiceRequestTlvStreamRef};
 use crate::offers::offer::{OfferTlvStream, OfferTlvStreamRef};
-use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError};
+use crate::offers::parse::{Bech32Encode, Bolt12ParseError, Bolt12SemanticError, ParsedMessage};
 use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
 use crate::offers::signer::{Metadata, MetadataMaterial, self};
 use crate::util::ser::{SeekReadable, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
 
+#[cfg(not(c_bindings))]
+use {
+	crate::offers::invoice::{DerivedSigningPubkey, ExplicitSigningPubkey, InvoiceBuilder},
+};
+#[cfg(c_bindings)]
+use {
+	crate::offers::invoice::{InvoiceWithDerivedSigningPubkeyBuilder, InvoiceWithExplicitSigningPubkeyBuilder},
+};
+
+#[allow(unused_imports)]
 use crate::prelude::*;
 
 #[cfg(feature = "std")]
@@ -113,17 +134,36 @@ pub struct RefundBuilder<'a, T: secp256k1::Signing> {
 	secp_ctx: Option<&'a Secp256k1<T>>,
 }
 
-impl<'a> RefundBuilder<'a, secp256k1::SignOnly> {
+/// Builds a [`Refund`] for the "offer for money" flow.
+///
+/// See [module-level documentation] for usage.
+///
+/// [module-level documentation]: self
+#[cfg(c_bindings)]
+pub struct RefundMaybeWithDerivedMetadataBuilder<'a> {
+	refund: RefundContents,
+	secp_ctx: Option<&'a Secp256k1<secp256k1::All>>,
+}
+
+macro_rules! refund_explicit_metadata_builder_methods { () => {
 	/// Creates a new builder for a refund using the [`Refund::payer_id`] for the public node id to
 	/// send to if no [`Refund::paths`] are set. Otherwise, it may be a transient pubkey.
 	///
-	/// Additionally, sets the required [`Refund::description`], [`Refund::metadata`], and
+	/// Additionally, sets the required [`Refund::description`], [`Refund::payer_metadata`], and
 	/// [`Refund::amount_msats`].
+	///
+	/// # Note
+	///
+	/// If constructing a [`Refund`] for use with a [`ChannelManager`], use
+	/// [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`].
+	///
+	/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+	/// [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder
 	pub fn new(
 		description: String, metadata: Vec<u8>, payer_id: PublicKey, amount_msats: u64
-	) -> Result<Self, SemanticError> {
+	) -> Result<Self, Bolt12SemanticError> {
 		if amount_msats > MAX_VALUE_MSAT {
-			return Err(SemanticError::InvalidAmount);
+			return Err(Bolt12SemanticError::InvalidAmount);
 		}
 
 		let metadata = Metadata::Bytes(metadata);
@@ -136,9 +176,11 @@ impl<'a> RefundBuilder<'a, secp256k1::SignOnly> {
 			secp_ctx: None,
 		})
 	}
-}
+} }
 
-impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
+macro_rules! refund_builder_methods { (
+	$self: ident, $self_type: ty, $return_type: ty, $return_value: expr, $secp_context: ty $(, $self_mut: tt)?
+) => {
 	/// Similar to [`RefundBuilder::new`] except, if [`RefundBuilder::path`] is called, the payer id
 	/// is derived from the given [`ExpandedKey`] and nonce. This provides sender privacy by using a
 	/// different payer id for each refund, assuming a different nonce is used.  Otherwise, the
@@ -147,18 +189,22 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
 	/// Also, sets the metadata when [`RefundBuilder::build`] is called such that it can be used to
 	/// verify that an [`InvoiceRequest`] was produced for the refund given an [`ExpandedKey`].
 	///
+	/// The `payment_id` is encrypted in the metadata and should be unique. This ensures that only
+	/// one invoice will be paid for the refund and that payments can be uniquely identified.
+	///
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	/// [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey
 	pub fn deriving_payer_id<ES: Deref>(
 		description: String, node_id: PublicKey, expanded_key: &ExpandedKey, entropy_source: ES,
-		secp_ctx: &'a Secp256k1<T>, amount_msats: u64
-	) -> Result<Self, SemanticError> where ES::Target: EntropySource {
+		secp_ctx: &'a Secp256k1<$secp_context>, amount_msats: u64, payment_id: PaymentId
+	) -> Result<Self, Bolt12SemanticError> where ES::Target: EntropySource {
 		if amount_msats > MAX_VALUE_MSAT {
-			return Err(SemanticError::InvalidAmount);
+			return Err(Bolt12SemanticError::InvalidAmount);
 		}
 
 		let nonce = Nonce::from_entropy_source(entropy_source);
-		let derivation_material = MetadataMaterial::new(nonce, expanded_key, IV_BYTES);
+		let payment_id = Some(payment_id);
+		let derivation_material = MetadataMaterial::new(nonce, expanded_key, IV_BYTES, payment_id);
 		let metadata = Metadata::DerivedSigningPubkey(derivation_material);
 		Ok(Self {
 			refund: RefundContents {
@@ -174,17 +220,17 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
 	/// already passed is valid and can be checked for using [`Refund::is_expired`].
 	///
 	/// Successive calls to this method will override the previous setting.
-	pub fn absolute_expiry(mut self, absolute_expiry: Duration) -> Self {
-		self.refund.absolute_expiry = Some(absolute_expiry);
-		self
+	pub fn absolute_expiry($($self_mut)* $self: $self_type, absolute_expiry: Duration) -> $return_type {
+		$self.refund.absolute_expiry = Some(absolute_expiry);
+		$return_value
 	}
 
 	/// Sets the [`Refund::issuer`].
 	///
 	/// Successive calls to this method will override the previous setting.
-	pub fn issuer(mut self, issuer: String) -> Self {
-		self.refund.issuer = Some(issuer);
-		self
+	pub fn issuer($($self_mut)* $self: $self_type, issuer: String) -> $return_type {
+		$self.refund.issuer = Some(issuer);
+		$return_value
 	}
 
 	/// Adds a blinded path to [`Refund::paths`]. Must include at least one path if only connected
@@ -192,18 +238,26 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
 	///
 	/// Successive calls to this method will add another blinded path. Caller is responsible for not
 	/// adding duplicate paths.
-	pub fn path(mut self, path: BlindedPath) -> Self {
-		self.refund.paths.get_or_insert_with(Vec::new).push(path);
-		self
+	pub fn path($($self_mut)* $self: $self_type, path: BlindedPath) -> $return_type {
+		$self.refund.paths.get_or_insert_with(Vec::new).push(path);
+		$return_value
 	}
 
 	/// Sets the [`Refund::chain`] of the given [`Network`] for paying an invoice. If not
 	/// called, [`Network::Bitcoin`] is assumed.
 	///
 	/// Successive calls to this method will override the previous setting.
-	pub fn chain(mut self, network: Network) -> Self {
-		self.refund.chain = Some(ChainHash::using_genesis_block(network));
-		self
+	pub fn chain($self: $self_type, network: Network) -> $return_type {
+		$self.chain_hash(ChainHash::using_genesis_block(network))
+	}
+
+	/// Sets the [`Refund::chain`] of the given [`ChainHash`] for paying an invoice. If not called,
+	/// [`Network::Bitcoin`] is assumed.
+	///
+	/// Successive calls to this method will override the previous setting.
+	pub(crate) fn chain_hash($($self_mut)* $self: $self_type, chain: ChainHash) -> $return_type {
+		$self.refund.chain = Some(chain);
+		$return_value
 	}
 
 	/// Sets [`Refund::quantity`] of items. This is purely for informational purposes. It is useful
@@ -215,60 +269,119 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	/// [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity
 	/// [`Offer`]: crate::offers::offer::Offer
-	pub fn quantity(mut self, quantity: u64) -> Self {
-		self.refund.quantity = Some(quantity);
-		self
+	pub fn quantity($($self_mut)* $self: $self_type, quantity: u64) -> $return_type {
+		$self.refund.quantity = Some(quantity);
+		$return_value
 	}
 
 	/// Sets the [`Refund::payer_note`].
 	///
 	/// Successive calls to this method will override the previous setting.
-	pub fn payer_note(mut self, payer_note: String) -> Self {
-		self.refund.payer_note = Some(payer_note);
-		self
+	pub fn payer_note($($self_mut)* $self: $self_type, payer_note: String) -> $return_type {
+		$self.refund.payer_note = Some(payer_note);
+		$return_value
 	}
 
 	/// Builds a [`Refund`] after checking for valid semantics.
-	pub fn build(mut self) -> Result<Refund, SemanticError> {
-		if self.refund.chain() == self.refund.implied_chain() {
-			self.refund.chain = None;
+	pub fn build($($self_mut)* $self: $self_type) -> Result<Refund, Bolt12SemanticError> {
+		if $self.refund.chain() == $self.refund.implied_chain() {
+			$self.refund.chain = None;
 		}
 
 		// Create the metadata for stateless verification of a Bolt12Invoice.
-		if self.refund.payer.0.has_derivation_material() {
-			let mut metadata = core::mem::take(&mut self.refund.payer.0);
+		if $self.refund.payer.0.has_derivation_material() {
+			let mut metadata = core::mem::take(&mut $self.refund.payer.0);
 
-			if self.refund.paths.is_none() {
+			if $self.refund.paths.is_none() {
 				metadata = metadata.without_keys();
 			}
 
-			let mut tlv_stream = self.refund.as_tlv_stream();
+			let mut tlv_stream = $self.refund.as_tlv_stream();
 			tlv_stream.0.metadata = None;
-			if metadata.derives_keys() {
+			if metadata.derives_payer_keys() {
 				tlv_stream.2.payer_id = None;
 			}
 
-			let (derived_metadata, keys) = metadata.derive_from(tlv_stream, self.secp_ctx);
+			let (derived_metadata, keys) = metadata.derive_from(tlv_stream, $self.secp_ctx);
 			metadata = derived_metadata;
 			if let Some(keys) = keys {
-				self.refund.payer_id = keys.public_key();
+				$self.refund.payer_id = keys.public_key();
 			}
 
-			self.refund.payer.0 = metadata;
+			$self.refund.payer.0 = metadata;
 		}
 
 		let mut bytes = Vec::new();
-		self.refund.write(&mut bytes).unwrap();
+		$self.refund.write(&mut bytes).unwrap();
+
+		Ok(Refund {
+			bytes,
+			#[cfg(not(c_bindings))]
+			contents: $self.refund,
+			#[cfg(c_bindings)]
+			contents: $self.refund.clone(),
+		})
+	}
+} }
 
-		Ok(Refund { bytes, contents: self.refund })
+#[cfg(test)]
+macro_rules! refund_builder_test_methods { (
+	$self: ident, $self_type: ty, $return_type: ty, $return_value: expr $(, $self_mut: tt)?
+) => {
+	#[cfg_attr(c_bindings, allow(dead_code))]
+	pub(crate) fn clear_paths($($self_mut)* $self: $self_type) -> $return_type {
+		$self.refund.paths = None;
+		$return_value
+	}
+
+	#[cfg_attr(c_bindings, allow(dead_code))]
+	fn features_unchecked($($self_mut)* $self: $self_type, features: InvoiceRequestFeatures) -> $return_type {
+		$self.refund.features = features;
+		$return_value
 	}
+} }
+
+impl<'a> RefundBuilder<'a, secp256k1::SignOnly> {
+	refund_explicit_metadata_builder_methods!();
 }
 
-#[cfg(test)]
 impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
-	fn features_unchecked(mut self, features: InvoiceRequestFeatures) -> Self {
-		self.refund.features = features;
-		self
+	refund_builder_methods!(self, Self, Self, self, T, mut);
+
+	#[cfg(test)]
+	refund_builder_test_methods!(self, Self, Self, self, mut);
+}
+
+#[cfg(all(c_bindings, not(test)))]
+impl<'a> RefundMaybeWithDerivedMetadataBuilder<'a> {
+	refund_explicit_metadata_builder_methods!();
+	refund_builder_methods!(self, &mut Self, (), (), secp256k1::All);
+}
+
+#[cfg(all(c_bindings, test))]
+impl<'a> RefundMaybeWithDerivedMetadataBuilder<'a> {
+	refund_explicit_metadata_builder_methods!();
+	refund_builder_methods!(self, &mut Self, &mut Self, self, secp256k1::All);
+	refund_builder_test_methods!(self, &mut Self, &mut Self, self);
+}
+
+#[cfg(c_bindings)]
+impl<'a> From<RefundBuilder<'a, secp256k1::All>>
+for RefundMaybeWithDerivedMetadataBuilder<'a> {
+	fn from(builder: RefundBuilder<'a, secp256k1::All>) -> Self {
+		let RefundBuilder { refund, secp_ctx } = builder;
+
+		Self { refund, secp_ctx }
+	}
+}
+
+#[cfg(c_bindings)]
+impl<'a> From<RefundMaybeWithDerivedMetadataBuilder<'a>>
+for RefundBuilder<'a, secp256k1::All> {
+	fn from(builder: RefundMaybeWithDerivedMetadataBuilder<'a>) -> Self {
+		let RefundMaybeWithDerivedMetadataBuilder { refund, secp_ctx } = builder;
+
+		Self { refund, secp_ctx }
 	}
 }
 
@@ -281,7 +394,6 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> {
 /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 /// [`Offer`]: crate::offers::offer::Offer
 #[derive(Clone, Debug)]
-#[cfg_attr(test, derive(PartialEq))]
 pub struct Refund {
 	pub(super) bytes: Vec<u8>,
 	pub(super) contents: RefundContents,
@@ -319,7 +431,7 @@ impl Refund {
 	///
 	/// If `None`, the refund does not expire.
 	pub fn absolute_expiry(&self) -> Option<Duration> {
-		self.contents.absolute_expiry
+		self.contents.absolute_expiry()
 	}
 
 	/// Whether the refund has expired.
@@ -328,46 +440,51 @@ impl Refund {
 		self.contents.is_expired()
 	}
 
+	/// Whether the refund has expired given the duration since the Unix epoch.
+	pub fn is_expired_no_std(&self, duration_since_epoch: Duration) -> bool {
+		self.contents.is_expired_no_std(duration_since_epoch)
+	}
+
 	/// The issuer of the refund, possibly beginning with `user@domain` or `domain`. Intended to be
 	/// displayed to the user but with the caveat that it has not been verified in any way.
 	pub fn issuer(&self) -> Option<PrintableString> {
-		self.contents.issuer.as_ref().map(|issuer| PrintableString(issuer.as_str()))
+		self.contents.issuer()
 	}
 
 	/// Paths to the sender originating from publicly reachable nodes. Blinded paths provide sender
 	/// privacy by obfuscating its node id.
 	pub fn paths(&self) -> &[BlindedPath] {
-		self.contents.paths.as_ref().map(|paths| paths.as_slice()).unwrap_or(&[])
+		self.contents.paths()
 	}
 
 	/// An unpredictable series of bytes, typically containing information about the derivation of
 	/// [`payer_id`].
 	///
 	/// [`payer_id`]: Self::payer_id
-	pub fn metadata(&self) -> &[u8] {
+	pub fn payer_metadata(&self) -> &[u8] {
 		self.contents.metadata()
 	}
 
 	/// A chain that the refund is valid for.
 	pub fn chain(&self) -> ChainHash {
-		self.contents.chain.unwrap_or_else(|| self.contents.implied_chain())
+		self.contents.chain()
 	}
 
 	/// The amount to refund in msats (i.e., the minimum lightning-payable unit for [`chain`]).
 	///
 	/// [`chain`]: Self::chain
 	pub fn amount_msats(&self) -> u64 {
-		self.contents.amount_msats
+		self.contents.amount_msats()
 	}
 
 	/// Features pertaining to requesting an invoice.
 	pub fn features(&self) -> &InvoiceRequestFeatures {
-		&self.contents.features
+		&self.contents.features()
 	}
 
 	/// The quantity of an item that refund is for.
 	pub fn quantity(&self) -> Option<u64> {
-		self.contents.quantity
+		self.contents.quantity()
 	}
 
 	/// A public node id to send to in the case where there are no [`paths`]. Otherwise, a possibly
@@ -375,14 +492,16 @@ impl Refund {
 	///
 	/// [`paths`]: Self::paths
 	pub fn payer_id(&self) -> PublicKey {
-		self.contents.payer_id
+		self.contents.payer_id()
 	}
 
 	/// Payer provided note to include in the invoice.
 	pub fn payer_note(&self) -> Option<PrintableString> {
-		self.contents.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str()))
+		self.contents.payer_note()
 	}
+}
 
+macro_rules! respond_with_explicit_signing_pubkey_methods { ($self: ident, $builder: ty) => {
 	/// Creates an [`InvoiceBuilder`] for the refund with the given required fields and using the
 	/// [`Duration`] since [`std::time::SystemTime::UNIX_EPOCH`] as the creation time.
 	///
@@ -394,14 +513,14 @@ impl Refund {
 	/// [`Duration`]: core::time::Duration
 	#[cfg(feature = "std")]
 	pub fn respond_with(
-		&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
+		&$self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
 		signing_pubkey: PublicKey,
-	) -> Result<InvoiceBuilder<ExplicitSigningPubkey>, SemanticError> {
+	) -> Result<$builder, Bolt12SemanticError> {
 		let created_at = std::time::SystemTime::now()
 			.duration_since(std::time::SystemTime::UNIX_EPOCH)
 			.expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");
 
-		self.respond_with_no_std(payment_paths, payment_hash, signing_pubkey, created_at)
+		$self.respond_with_no_std(payment_paths, payment_hash, signing_pubkey, created_at)
 	}
 
 	/// Creates an [`InvoiceBuilder`] for the refund with the given required fields.
@@ -427,16 +546,18 @@ impl Refund {
 	///
 	/// [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at
 	pub fn respond_with_no_std(
-		&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
+		&$self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
 		signing_pubkey: PublicKey, created_at: Duration
-	) -> Result<InvoiceBuilder<ExplicitSigningPubkey>, SemanticError> {
-		if self.features().requires_unknown_bits() {
-			return Err(SemanticError::UnknownRequiredFeatures);
+	) -> Result<$builder, Bolt12SemanticError> {
+		if $self.features().requires_unknown_bits() {
+			return Err(Bolt12SemanticError::UnknownRequiredFeatures);
 		}
 
-		InvoiceBuilder::for_refund(self, payment_paths, created_at, payment_hash, signing_pubkey)
+		<$builder>::for_refund($self, payment_paths, created_at, payment_hash, signing_pubkey)
 	}
+} }
 
+macro_rules! respond_with_derived_signing_pubkey_methods { ($self: ident, $builder: ty) => {
 	/// Creates an [`InvoiceBuilder`] for the refund using the given required fields and that uses
 	/// derived signing keys to sign the [`Bolt12Invoice`].
 	///
@@ -447,9 +568,9 @@ impl Refund {
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	#[cfg(feature = "std")]
 	pub fn respond_using_derived_keys<ES: Deref>(
-		&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
+		&$self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
 		expanded_key: &ExpandedKey, entropy_source: ES
-	) -> Result<InvoiceBuilder<DerivedSigningPubkey>, SemanticError>
+	) -> Result<$builder, Bolt12SemanticError>
 	where
 		ES::Target: EntropySource,
 	{
@@ -457,7 +578,7 @@ impl Refund {
 			.duration_since(std::time::SystemTime::UNIX_EPOCH)
 			.expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");
 
-		self.respond_using_derived_keys_no_std(
+		$self.respond_using_derived_keys_no_std(
 			payment_paths, payment_hash, created_at, expanded_key, entropy_source
 		)
 	}
@@ -471,22 +592,36 @@ impl Refund {
 	///
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub fn respond_using_derived_keys_no_std<ES: Deref>(
-		&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
+		&$self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
 		created_at: core::time::Duration, expanded_key: &ExpandedKey, entropy_source: ES
-	) -> Result<InvoiceBuilder<DerivedSigningPubkey>, SemanticError>
+	) -> Result<$builder, Bolt12SemanticError>
 	where
 		ES::Target: EntropySource,
 	{
-		if self.features().requires_unknown_bits() {
-			return Err(SemanticError::UnknownRequiredFeatures);
+		if $self.features().requires_unknown_bits() {
+			return Err(Bolt12SemanticError::UnknownRequiredFeatures);
 		}
 
 		let nonce = Nonce::from_entropy_source(entropy_source);
 		let keys = signer::derive_keys(nonce, expanded_key);
-		InvoiceBuilder::for_refund_using_keys(self, payment_paths, created_at, payment_hash, keys)
+		<$builder>::for_refund_using_keys($self, payment_paths, created_at, payment_hash, keys)
 	}
+} }
 
-	#[cfg(test)]
+#[cfg(not(c_bindings))]
+impl Refund {
+	respond_with_explicit_signing_pubkey_methods!(self, InvoiceBuilder<ExplicitSigningPubkey>);
+	respond_with_derived_signing_pubkey_methods!(self, InvoiceBuilder<DerivedSigningPubkey>);
+}
+
+#[cfg(c_bindings)]
+impl Refund {
+	respond_with_explicit_signing_pubkey_methods!(self, InvoiceWithExplicitSigningPubkeyBuilder);
+	respond_with_derived_signing_pubkey_methods!(self, InvoiceWithDerivedSigningPubkeyBuilder);
+}
+
+#[cfg(test)]
+impl Refund {
 	fn as_tlv_stream(&self) -> RefundTlvStreamRef {
 		self.contents.as_tlv_stream()
 	}
@@ -498,20 +633,49 @@ impl AsRef<[u8]> for Refund {
 	}
 }
 
+impl PartialEq for Refund {
+	fn eq(&self, other: &Self) -> bool {
+		self.bytes.eq(&other.bytes)
+	}
+}
+
+impl Eq for Refund {}
+
+impl Hash for Refund {
+	fn hash<H: Hasher>(&self, state: &mut H) {
+		self.bytes.hash(state);
+	}
+}
+
 impl RefundContents {
 	pub fn description(&self) -> PrintableString {
 		PrintableString(&self.description)
 	}
 
+	pub fn absolute_expiry(&self) -> Option<Duration> {
+		self.absolute_expiry
+	}
+
 	#[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,
-		}
+		SystemTime::UNIX_EPOCH
+			.elapsed()
+			.map(|duration_since_epoch| self.is_expired_no_std(duration_since_epoch))
+			.unwrap_or(false)
+	}
+
+	pub(super) fn is_expired_no_std(&self, duration_since_epoch: Duration) -> bool {
+		self.absolute_expiry
+			.map(|absolute_expiry| duration_since_epoch > absolute_expiry)
+			.unwrap_or(false)
+	}
+
+	pub fn issuer(&self) -> Option<PrintableString> {
+		self.issuer.as_ref().map(|issuer| PrintableString(issuer.as_str()))
+	}
+
+	pub fn paths(&self) -> &[BlindedPath] {
+		self.paths.as_ref().map(|paths| paths.as_slice()).unwrap_or(&[])
 	}
 
 	pub(super) fn metadata(&self) -> &[u8] {
@@ -526,14 +690,37 @@ impl RefundContents {
 		ChainHash::using_genesis_block(Network::Bitcoin)
 	}
 
-	pub(super) fn derives_keys(&self) -> bool {
-		self.payer.0.derives_keys()
+	pub fn amount_msats(&self) -> u64 {
+		self.amount_msats
 	}
 
-	pub(super) fn payer_id(&self) -> PublicKey {
+	/// Features pertaining to requesting an invoice.
+	pub fn features(&self) -> &InvoiceRequestFeatures {
+		&self.features
+	}
+
+	/// The quantity of an item that refund is for.
+	pub fn quantity(&self) -> Option<u64> {
+		self.quantity
+	}
+
+	/// A public node id to send to in the case where there are no [`paths`]. Otherwise, a possibly
+	/// transient pubkey.
+	///
+	/// [`paths`]: Self::paths
+	pub fn payer_id(&self) -> PublicKey {
 		self.payer_id
 	}
 
+	/// Payer provided note to include in the invoice.
+	pub fn payer_note(&self) -> Option<PrintableString> {
+		self.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str()))
+	}
+
+	pub(super) fn derives_keys(&self) -> bool {
+		self.payer.0.derives_payer_keys()
+	}
+
 	pub(super) fn as_tlv_stream(&self) -> RefundTlvStreamRef {
 		let payer = PayerTlvStreamRef {
 			metadata: self.payer.0.as_bytes(),
@@ -606,7 +793,7 @@ impl Bech32Encode for Refund {
 }
 
 impl FromStr for Refund {
-	type Err = ParseError;
+	type Err = Bolt12ParseError;
 
 	fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
 		Refund::from_bech32_str(s)
@@ -614,7 +801,7 @@ impl FromStr for Refund {
 }
 
 impl TryFrom<Vec<u8>> for Refund {
-	type Error = ParseError;
+	type Error = Bolt12ParseError;
 
 	fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error> {
 		let refund = ParsedMessage::<RefundTlvStream>::try_from(bytes)?;
@@ -626,7 +813,7 @@ impl TryFrom<Vec<u8>> for Refund {
 }
 
 impl TryFrom<RefundTlvStream> for RefundContents {
-	type Error = SemanticError;
+	type Error = Bolt12SemanticError;
 
 	fn try_from(tlv_stream: RefundTlvStream) -> Result<Self, Self::Error> {
 		let (
@@ -639,45 +826,45 @@ impl TryFrom<RefundTlvStream> for RefundContents {
 		) = tlv_stream;
 
 		let payer = match payer_metadata {
-			None => return Err(SemanticError::MissingPayerMetadata),
+			None => return Err(Bolt12SemanticError::MissingPayerMetadata),
 			Some(metadata) => PayerContents(Metadata::Bytes(metadata)),
 		};
 
 		if metadata.is_some() {
-			return Err(SemanticError::UnexpectedMetadata);
+			return Err(Bolt12SemanticError::UnexpectedMetadata);
 		}
 
 		if chains.is_some() {
-			return Err(SemanticError::UnexpectedChain);
+			return Err(Bolt12SemanticError::UnexpectedChain);
 		}
 
 		if currency.is_some() || offer_amount.is_some() {
-			return Err(SemanticError::UnexpectedAmount);
+			return Err(Bolt12SemanticError::UnexpectedAmount);
 		}
 
 		let description = match description {
-			None => return Err(SemanticError::MissingDescription),
+			None => return Err(Bolt12SemanticError::MissingDescription),
 			Some(description) => description,
 		};
 
 		if offer_features.is_some() {
-			return Err(SemanticError::UnexpectedFeatures);
+			return Err(Bolt12SemanticError::UnexpectedFeatures);
 		}
 
 		let absolute_expiry = absolute_expiry.map(Duration::from_secs);
 
 		if quantity_max.is_some() {
-			return Err(SemanticError::UnexpectedQuantity);
+			return Err(Bolt12SemanticError::UnexpectedQuantity);
 		}
 
 		if node_id.is_some() {
-			return Err(SemanticError::UnexpectedSigningPubkey);
+			return Err(Bolt12SemanticError::UnexpectedSigningPubkey);
 		}
 
 		let amount_msats = match amount {
-			None => return Err(SemanticError::MissingAmount),
+			None => return Err(Bolt12SemanticError::MissingAmount),
 			Some(amount_msats) if amount_msats > MAX_VALUE_MSAT => {
-				return Err(SemanticError::InvalidAmount);
+				return Err(Bolt12SemanticError::InvalidAmount);
 			},
 			Some(amount_msats) => amount_msats,
 		};
@@ -685,7 +872,7 @@ impl TryFrom<RefundTlvStream> for RefundContents {
 		let features = features.unwrap_or_else(InvoiceRequestFeatures::empty);
 
 		let payer_id = match payer_id {
-			None => return Err(SemanticError::MissingPayerId),
+			None => return Err(Bolt12SemanticError::MissingPayerId),
 			Some(payer_id) => payer_id,
 		};
 
@@ -704,25 +891,36 @@ impl core::fmt::Display for Refund {
 
 #[cfg(test)]
 mod tests {
-	use super::{Refund, RefundBuilder, RefundTlvStreamRef};
+	use super::{Refund, RefundTlvStreamRef};
+	#[cfg(not(c_bindings))]
+	use {
+		super::RefundBuilder,
+	};
+	#[cfg(c_bindings)]
+	use {
+		super::RefundMaybeWithDerivedMetadataBuilder as RefundBuilder,
+	};
 
 	use bitcoin::blockdata::constants::ChainHash;
 	use bitcoin::network::constants::Network;
 	use bitcoin::secp256k1::{KeyPair, Secp256k1, SecretKey};
-	use core::convert::TryFrom;
+
 	use core::time::Duration;
+
 	use crate::blinded_path::{BlindedHop, BlindedPath};
 	use crate::sign::KeyMaterial;
+	use crate::ln::channelmanager::PaymentId;
 	use crate::ln::features::{InvoiceRequestFeatures, OfferFeatures};
 	use crate::ln::inbound_payment::ExpandedKey;
 	use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT};
 	use crate::offers::invoice_request::InvoiceRequestTlvStreamRef;
 	use crate::offers::offer::OfferTlvStreamRef;
-	use crate::offers::parse::{ParseError, SemanticError};
+	use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError};
 	use crate::offers::payer::PayerTlvStreamRef;
 	use crate::offers::test_utils::*;
 	use crate::util::ser::{BigSize, Writeable};
 	use crate::util::string::PrintableString;
+	use crate::prelude::*;
 
 	trait ToBytes {
 		fn to_bytes(&self) -> Vec<u8>;
@@ -745,7 +943,7 @@ mod tests {
 		refund.write(&mut buffer).unwrap();
 
 		assert_eq!(refund.bytes, buffer.as_slice());
-		assert_eq!(refund.metadata(), &[1; 32]);
+		assert_eq!(refund.payer_metadata(), &[1; 32]);
 		assert_eq!(refund.description(), PrintableString("foo"));
 		assert_eq!(refund.absolute_expiry(), None);
 		#[cfg(feature = "std")]
@@ -795,7 +993,7 @@ mod tests {
 	fn fails_building_refund_with_invalid_amount() {
 		match RefundBuilder::new("foo".into(), vec![1; 32], payer_pubkey(), MAX_VALUE_MSAT + 1) {
 			Ok(_) => panic!("expected error"),
-			Err(e) => assert_eq!(e, SemanticError::InvalidAmount),
+			Err(e) => assert_eq!(e, Bolt12SemanticError::InvalidAmount),
 		}
 	}
 
@@ -806,9 +1004,10 @@ mod tests {
 		let expanded_key = ExpandedKey::new(&KeyMaterial([42; 32]));
 		let entropy = FixedEntropy {};
 		let secp_ctx = Secp256k1::new();
+		let payment_id = PaymentId([1; 32]);
 
 		let refund = RefundBuilder
-			::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000)
+			::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000, payment_id)
 			.unwrap()
 			.build().unwrap();
 		assert_eq!(refund.payer_id(), node_id);
@@ -819,7 +1018,10 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(invoice.verify(&expanded_key, &secp_ctx));
+		match invoice.verify(&expanded_key, &secp_ctx) {
+			Ok(payment_id) => assert_eq!(payment_id, PaymentId([1; 32])),
+			Err(()) => panic!("verification failed"),
+		}
 
 		let mut tlv_stream = refund.as_tlv_stream();
 		tlv_stream.2.amount = Some(2000);
@@ -832,7 +1034,7 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(!invoice.verify(&expanded_key, &secp_ctx));
+		assert!(invoice.verify(&expanded_key, &secp_ctx).is_err());
 
 		// Fails verification with altered metadata
 		let mut tlv_stream = refund.as_tlv_stream();
@@ -847,7 +1049,7 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(!invoice.verify(&expanded_key, &secp_ctx));
+		assert!(invoice.verify(&expanded_key, &secp_ctx).is_err());
 	}
 
 	#[test]
@@ -857,6 +1059,7 @@ mod tests {
 		let expanded_key = ExpandedKey::new(&KeyMaterial([42; 32]));
 		let entropy = FixedEntropy {};
 		let secp_ctx = Secp256k1::new();
+		let payment_id = PaymentId([1; 32]);
 
 		let blinded_path = BlindedPath {
 			introduction_node_id: pubkey(40),
@@ -868,7 +1071,7 @@ mod tests {
 		};
 
 		let refund = RefundBuilder
-			::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000)
+			::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000, payment_id)
 			.unwrap()
 			.path(blinded_path)
 			.build().unwrap();
@@ -879,7 +1082,10 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(invoice.verify(&expanded_key, &secp_ctx));
+		match invoice.verify(&expanded_key, &secp_ctx) {
+			Ok(payment_id) => assert_eq!(payment_id, PaymentId([1; 32])),
+			Err(()) => panic!("verification failed"),
+		}
 
 		// Fails verification with altered fields
 		let mut tlv_stream = refund.as_tlv_stream();
@@ -893,7 +1099,7 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(!invoice.verify(&expanded_key, &secp_ctx));
+		assert!(invoice.verify(&expanded_key, &secp_ctx).is_err());
 
 		// Fails verification with altered payer_id
 		let mut tlv_stream = refund.as_tlv_stream();
@@ -908,13 +1114,14 @@ mod tests {
 			.unwrap()
 			.build().unwrap()
 			.sign(recipient_sign).unwrap();
-		assert!(!invoice.verify(&expanded_key, &secp_ctx));
+		assert!(invoice.verify(&expanded_key, &secp_ctx).is_err());
 	}
 
 	#[test]
 	fn builds_refund_with_absolute_expiry() {
 		let future_expiry = Duration::from_secs(u64::max_value());
 		let past_expiry = Duration::from_secs(0);
+		let now = future_expiry - Duration::from_secs(1_000);
 
 		let refund = RefundBuilder::new("foo".into(), vec![1; 32], payer_pubkey(), 1000).unwrap()
 			.absolute_expiry(future_expiry)
@@ -923,6 +1130,7 @@ mod tests {
 		let (_, tlv_stream, _) = refund.as_tlv_stream();
 		#[cfg(feature = "std")]
 		assert!(!refund.is_expired());
+		assert!(!refund.is_expired_no_std(now));
 		assert_eq!(refund.absolute_expiry(), Some(future_expiry));
 		assert_eq!(tlv_stream.absolute_expiry, Some(future_expiry.as_secs()));
 
@@ -934,6 +1142,7 @@ mod tests {
 		let (_, tlv_stream, _) = refund.as_tlv_stream();
 		#[cfg(feature = "std")]
 		assert!(refund.is_expired());
+		assert!(refund.is_expired_no_std(now));
 		assert_eq!(refund.absolute_expiry(), Some(past_expiry));
 		assert_eq!(tlv_stream.absolute_expiry, Some(past_expiry.as_secs()));
 	}
@@ -1064,7 +1273,7 @@ mod tests {
 			.respond_with_no_std(payment_paths(), payment_hash(), recipient_pubkey(), now())
 		{
 			Ok(_) => panic!("expected error"),
-			Err(e) => assert_eq!(e, SemanticError::UnknownRequiredFeatures),
+			Err(e) => assert_eq!(e, Bolt12SemanticError::UnknownRequiredFeatures),
 		}
 	}
 
@@ -1082,7 +1291,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingPayerMetadata));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::MissingPayerMetadata));
 			},
 		}
 	}
@@ -1101,7 +1310,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingDescription));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::MissingDescription));
 			},
 		}
 	}
@@ -1120,7 +1329,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingAmount));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::MissingAmount));
 			},
 		}
 
@@ -1130,7 +1339,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::InvalidAmount));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidAmount));
 			},
 		}
 	}
@@ -1149,7 +1358,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingPayerId));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::MissingPayerId));
 			},
 		}
 	}
@@ -1218,7 +1427,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedMetadata));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedMetadata));
 			},
 		}
 
@@ -1229,7 +1438,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedChain));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedChain));
 			},
 		}
 
@@ -1240,7 +1449,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedAmount));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedAmount));
 			},
 		}
 
@@ -1251,7 +1460,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedFeatures));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedFeatures));
 			},
 		}
 
@@ -1261,7 +1470,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedQuantity));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedQuantity));
 			},
 		}
 
@@ -1272,7 +1481,7 @@ mod tests {
 		match Refund::try_from(tlv_stream.to_bytes()) {
 			Ok(_) => panic!("expected error"),
 			Err(e) => {
-				assert_eq!(e, ParseError::InvalidSemantics(SemanticError::UnexpectedSigningPubkey));
+				assert_eq!(e, Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::UnexpectedSigningPubkey));
 			},
 		}
 	}
@@ -1292,7 +1501,7 @@ mod tests {
 
 		match Refund::try_from(encoded_refund) {
 			Ok(_) => panic!("expected error"),
-			Err(e) => assert_eq!(e, ParseError::Decode(DecodeError::InvalidValue)),
+			Err(e) => assert_eq!(e, Bolt12ParseError::Decode(DecodeError::InvalidValue)),
 		}
 	}
 }