#![deny(non_camel_case_types)]
#![deny(non_snake_case)]
#![deny(unused_mut)]
+#![deny(broken_intra_doc_links)]
#![cfg_attr(feature = "strict", deny(warnings))]
/// it should be rather low as long as we still have to support 32bit time representations
const MAX_EXPIRY_TIME: u64 = 60 * 60 * 24 * 356;
+/// Default expiry time as defined by [BOLT 11].
+///
+/// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
+const DEFAULT_EXPIRY_TIME: u64 = 3600;
+
+/// Default minimum final CLTV expiry as defined by [BOLT 11].
+///
+/// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
+const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
+
/// This function is used as a static assert for the size of `SystemTime`. If the crate fails to
/// compile due to it this indicates that your system uses unexpected bounds for `SystemTime`. You
/// can remove this functions and run the test `test_system_time_bounds_assumptions`. In any case,
/// .description("Coins pls!".into())
/// .payment_hash(payment_hash)
/// .current_timestamp()
+/// .min_final_cltv_expiry(144)
/// .build_signed(|hash| {
/// Secp256k1::new().sign_recoverable(hash, &private_key)
/// })
///
/// (C-not exported) as we likely need to manually select one set of boolean type parameters.
#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool> {
+pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> {
currency: Currency,
amount: Option<u64>,
si_prefix: Option<SiPrefix>,
phantom_d: std::marker::PhantomData<D>,
phantom_h: std::marker::PhantomData<H>,
phantom_t: std::marker::PhantomData<T>,
+ phantom_c: std::marker::PhantomData<C>,
+ phantom_s: std::marker::PhantomData<S>,
}
/// Represents a syntactically and semantically correct lightning BOLT11 invoice.
pub const TAG_FEATURES: u8 = 5;
}
-impl InvoiceBuilder<tb::False, tb::False, tb::False> {
+impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False> {
/// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
/// `InvoiceBuilder::build(self)` becomes available.
pub fn new(currrency: Currency) -> Self {
phantom_d: std::marker::PhantomData,
phantom_h: std::marker::PhantomData,
phantom_t: std::marker::PhantomData,
+ phantom_c: std::marker::PhantomData,
+ phantom_s: std::marker::PhantomData,
}
}
}
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool> InvoiceBuilder<D, H, T> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S> {
/// Helper function to set the completeness flags.
- fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN> {
- InvoiceBuilder::<DN, HN, TN> {
+ fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN> {
+ InvoiceBuilder::<DN, HN, TN, CN, SN> {
currency: self.currency,
amount: self.amount,
si_prefix: self.si_prefix,
phantom_d: std::marker::PhantomData,
phantom_h: std::marker::PhantomData,
phantom_t: std::marker::PhantomData,
+ phantom_c: std::marker::PhantomData,
+ phantom_s: std::marker::PhantomData,
}
}
self
}
- /// Sets the payment secret
- pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> Self {
- self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
- self
- }
-
/// Sets the expiry time
pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
match ExpiryTime::from_duration(expiry_time) {
self
}
- /// Sets `min_final_cltv_expiry`.
- pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> Self {
- self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
- self
- }
-
/// Adds a fallback address.
pub fn fallback(mut self, fallback: Fallback) -> Self {
self.tagged_fields.push(TaggedField::Fallback(fallback));
}
self
}
-
- /// Adds a features field which indicates the set of supported protocol extensions which the
- /// origin node supports.
- pub fn features(mut self, features: InvoiceFeatures) -> Self {
- self.tagged_fields.push(TaggedField::Features(features));
- self
- }
}
-impl<D: tb::Bool, H: tb::Bool> InvoiceBuilder<D, H, tb::True> {
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S> {
/// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields.
pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
}
}
-impl<H: tb::Bool, T: tb::Bool> InvoiceBuilder<tb::False, H, T> {
+impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S> {
/// Set the description. This function is only available if no description (hash) was set.
- pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T> {
+ pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S> {
match Description::new(description) {
Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
Err(e) => self.error = Some(e),
}
/// Set the description hash. This function is only available if no description (hash) was set.
- pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T> {
+ pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S> {
self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
self.set_flags()
}
}
-impl<D: tb::Bool, T: tb::Bool> InvoiceBuilder<D, tb::False, T> {
+impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
/// Set the payment hash. This function is only available if no payment hash was set.
- pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T> {
+ pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S> {
self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
self.set_flags()
}
}
-impl<D: tb::Bool, H: tb::Bool> InvoiceBuilder<D, H, tb::False> {
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
/// Sets the timestamp.
- pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True> {
+ pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
match PositiveTimestamp::from_system_time(time) {
Ok(t) => self.timestamp = Some(t),
Err(e) => self.error = Some(e),
}
/// Sets the timestamp to the current UNIX timestamp.
- pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True> {
+ pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
let now = PositiveTimestamp::from_system_time(SystemTime::now());
self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
self.set_flags()
}
}
-impl InvoiceBuilder<tb::True, tb::True, tb::True> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
+ /// Sets `min_final_cltv_expiry`.
+ pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
+ self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
+ self.set_flags()
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False> {
+ /// Sets the payment secret and relevant features.
+ pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True> {
+ let features = InvoiceFeatures::empty()
+ .set_variable_length_onion_required()
+ .set_payment_secret_required();
+ self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
+ self.tagged_fields.push(TaggedField::Features(features));
+ self.set_flags()
+ }
+}
+
+impl<S: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, S> {
/// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
/// and MUST produce a recoverable signature valid for the given hash and if applicable also for
/// the included payee public key.
};
invoice.check_field_counts().expect("should be ensured by type signature of builder");
+ invoice.check_feature_bits().expect("should be ensured by type signature of builder");
Ok(invoice)
}
Ok(())
}
+ /// Check that feature bits are set as required
+ fn check_feature_bits(&self) -> Result<(), SemanticError> {
+ // "If the payment_secret feature is set, MUST include exactly one s field."
+ let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
+ TaggedField::PaymentSecret(_) => true,
+ _ => false,
+ }).count();
+ if payment_secret_count > 1 {
+ return Err(SemanticError::MultiplePaymentSecrets);
+ }
+
+ // "A writer MUST set an s field if and only if the payment_secret feature is set."
+ let has_payment_secret = payment_secret_count == 1;
+ let features = self.tagged_fields().find(|&tf| match *tf {
+ TaggedField::Features(_) => true,
+ _ => false,
+ });
+ match features {
+ None if has_payment_secret => Err(SemanticError::InvalidFeatures),
+ None => Ok(()),
+ Some(TaggedField::Features(features)) => {
+ if features.supports_payment_secret() && has_payment_secret {
+ Ok(())
+ } else if has_payment_secret {
+ Err(SemanticError::InvalidFeatures)
+ } else if features.supports_payment_secret() {
+ Err(SemanticError::InvalidFeatures)
+ } else {
+ Ok(())
+ }
+ },
+ Some(_) => unreachable!(),
+ }
+ }
+
/// Check that the invoice is signed correctly and that key recovery works
pub fn check_signature(&self) -> Result<(), SemanticError> {
match self.signed_invoice.recover_payee_pub_key() {
signed_invoice: signed_invoice,
};
invoice.check_field_counts()?;
+ invoice.check_feature_bits()?;
invoice.check_signature()?;
Ok(invoice)
self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
}
- /// Returns the invoice's expiry time if present
+ /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
pub fn expiry_time(&self) -> Duration {
self.signed_invoice.expiry_time()
.map(|x| x.0)
- .unwrap_or(Duration::from_secs(3600))
+ .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
}
- /// Returns the invoice's `min_cltv_expiry` time if present
- pub fn min_final_cltv_expiry(&self) -> Option<u64> {
- self.signed_invoice.min_final_cltv_expiry().map(|x| x.0)
+ /// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
+ /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
+ pub fn min_final_cltv_expiry(&self) -> u64 {
+ self.signed_invoice.min_final_cltv_expiry()
+ .map(|x| x.0)
+ .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
}
/// Returns a list of all fallback addresses
/// The invoice contains multiple descriptions and/or description hashes which isn't allowed
MultipleDescriptions,
+ /// The invoice contains multiple payment secrets
+ MultiplePaymentSecrets,
+
+ /// The invoice's features are invalid
+ InvalidFeatures,
+
/// The recovery id doesn't fit the signature/pub key
InvalidRecoveryId,
SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
+ SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
+ SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
}
let builder = InvoiceBuilder::new(Currency::Bitcoin)
.payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
- .current_timestamp();
+ .current_timestamp()
+ .min_final_cltv_expiry(144);
let too_long_string = String::from_iter(
(0..1024).map(|_| '?')
.payee_pub_key(public_key.clone())
.expiry_time(Duration::from_secs(54321))
.min_final_cltv_expiry(144)
- .min_final_cltv_expiry(143)
.fallback(Fallback::PubKeyHash([0;20]))
.route(route_1.clone())
.route(route_2.clone())
}).unwrap();
assert!(invoice.check_signature().is_ok());
- assert_eq!(invoice.tagged_fields().count(), 9);
+ assert_eq!(invoice.tagged_fields().count(), 8);
assert_eq!(invoice.amount_pico_btc(), Some(123));
assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
);
assert_eq!(invoice.payee_pub_key(), Some(&public_key));
assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
- assert_eq!(invoice.min_final_cltv_expiry(), Some(144));
+ assert_eq!(invoice.min_final_cltv_expiry(), 144);
assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
assert_eq!(invoice.routes(), vec![&RouteHint(route_1), &RouteHint(route_2)]);
assert_eq!(
let raw_invoice = builder.build_raw().unwrap();
assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
}
+
+ #[test]
+ fn test_default_values() {
+ use ::*;
+ use secp256k1::Secp256k1;
+ use secp256k1::key::SecretKey;
+
+ let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
+ .description("Test".into())
+ .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
+ .current_timestamp()
+ .build_raw()
+ .unwrap()
+ .sign::<_, ()>(|hash| {
+ let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
+ let secp_ctx = Secp256k1::new();
+ Ok(secp_ctx.sign_recoverable(hash, &privkey))
+ })
+ .unwrap();
+ let invoice = Invoice::from_signed(signed_invoice).unwrap();
+
+ assert_eq!(invoice.min_final_cltv_expiry(), DEFAULT_MIN_FINAL_CLTV_EXPIRY);
+ assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
+ }
}