_ Git - rust-lightning/blob - lightning-invoice/src/lib.rs

   1 #![deny(missing_docs)]
   2 #![deny(non_upper_case_globals)]
   3 #![deny(non_camel_case_types)]
   4 #![deny(non_snake_case)]
   5 #![deny(unused_mut)]
   6
   7 #![cfg_attr(feature = "strict", deny(warnings))]
   8
   9 //! This crate provides data structures to represent
  10 //! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)
  11 //! invoices and functions to create, encode and decode these. If you just want to use the standard
  12 //! en-/decoding functionality this should get you started:
  13 //!
  14 //!   * For parsing use `str::parse::<Invoice>(&self)` (see the docs of `impl FromStr for Invoice`)
  15 //!   * For constructing invoices use the `InvoiceBuilder`
  16 //!   * For serializing invoices use the `Display`/`ToString` traits
  17
  18 extern crate bech32;
  19 extern crate bitcoin_hashes;
  20 extern crate lightning;
  21 extern crate num_traits;
  22 extern crate secp256k1;
  23
  24 use bech32::u5;
  25 use bitcoin_hashes::Hash;
  26 use bitcoin_hashes::sha256;
  27 use lightning::ln::features::InvoiceFeatures;
  28 #[cfg(any(doc, test))]
  29 use lightning::routing::network_graph::RoutingFees;
  30 use lightning::routing::router::RouteHintHop;
  31
  32 use secp256k1::key::PublicKey;
  33 use secp256k1::{Message, Secp256k1};
  34 use secp256k1::recovery::RecoverableSignature;
  35 use std::ops::Deref;
  36
  37 use std::iter::FilterMap;
  38 use std::slice::Iter;
  39 use std::time::{SystemTime, Duration, UNIX_EPOCH};
  40 use std::fmt::{Display, Formatter, self};
  41
  42 mod de;
  43 mod ser;
  44 mod tb;
  45
  46 pub use de::{ParseError, ParseOrSemanticError};
  47
  48 // TODO: fix before 2037 (see rust PR #55527)
  49 /// Defines the maximum UNIX timestamp that can be represented as `SystemTime`. This is checked by
  50 /// one of the unit tests, please run them.
  51 const SYSTEM_TIME_MAX_UNIX_TIMESTAMP: u64 = std::i32::MAX as u64;
  52
  53 /// Allow the expiry time to be up to one year. Since this reduces the range of possible timestamps
  54 /// it should be rather low as long as we still have to support 32bit time representations
  55 const MAX_EXPIRY_TIME: u64 = 60 * 60 * 24 * 356;
  56
  57 /// Default expiry time as defined by [BOLT 11].
  58 ///
  59 /// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
  60 const DEFAULT_EXPIRY_TIME: u64 = 3600;
  61
  62 /// Default minimum final CLTV expiry as defined by [BOLT 11].
  63 ///
  64 /// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
  65 const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
  66
  67 /// This function is used as a static assert for the size of `SystemTime`. If the crate fails to
  68 /// compile due to it this indicates that your system uses unexpected bounds for `SystemTime`. You
  69 /// can remove this functions and run the test `test_system_time_bounds_assumptions`. In any case,
  70 /// please open an issue. If all tests pass you should be able to use this library safely by just
  71 /// removing this function till we patch it accordingly.
  72 fn __system_time_size_check() {
  73         // Use 2 * sizeof(u64) as expected size since the expected underlying implementation is storing
  74         // a `Duration` since `SystemTime::UNIX_EPOCH`.
  75         unsafe { std::mem::transmute_copy::<SystemTime, [u8; 16]>(&UNIX_EPOCH); }
  76 }
  77
  78
  79 /// **Call this function on startup to ensure that all assumptions about the platform are valid.**
  80 ///
  81 /// Unfortunately we have to make assumptions about the upper bounds of the `SystemTime` type on
  82 /// your platform which we can't fully verify at compile time and which isn't part of it's contract.
  83 /// To our best knowledge our assumptions hold for all platforms officially supported by rust, but
  84 /// since this check is fast we recommend to do it anyway.
  85 ///
  86 /// If this function fails this is considered a bug. Please open an issue describing your
  87 /// platform and stating your current system time.
  88 ///
  89 /// # Panics
  90 /// If the check fails this function panics. By calling this function on startup you ensure that
  91 /// this wont happen at an arbitrary later point in time.
  92 pub fn check_platform() {
  93     // The upper and lower bounds of `SystemTime` are not part of its public contract and are
  94     // platform specific. That's why we have to test if our assumptions regarding these bounds
  95     // hold on the target platform.
  96     //
  97     // If this test fails on your platform, please don't use the library and open an issue
  98     // instead so we can resolve the situation. Currently this library is tested on:
  99     //   * Linux (64bit)
 100     let fail_date = UNIX_EPOCH + Duration::from_secs(SYSTEM_TIME_MAX_UNIX_TIMESTAMP);
 101     let year = Duration::from_secs(60 * 60 * 24 * 365);
 102
 103     // Make sure that the library will keep working for another year
 104     assert!(fail_date.duration_since(SystemTime::now()).unwrap() > year);
 105
 106     let max_ts = PositiveTimestamp::from_unix_timestamp(
 107         SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME
 108     ).unwrap();
 109     let max_exp = ::ExpiryTime::from_seconds(MAX_EXPIRY_TIME).unwrap();
 110
 111     assert_eq!(
 112         (*max_ts.as_time() + *max_exp.as_duration()).duration_since(UNIX_EPOCH).unwrap().as_secs(),
 113         SYSTEM_TIME_MAX_UNIX_TIMESTAMP
 114     );
 115 }
 116
 117
 118 /// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures
 119 /// that only a semantically and syntactically correct Invoice can be built using it.
 120 ///
 121 /// ```
 122 /// extern crate secp256k1;
 123 /// extern crate lightning_invoice;
 124 /// extern crate bitcoin_hashes;
 125 ///
 126 /// use bitcoin_hashes::Hash;
 127 /// use bitcoin_hashes::sha256;
 128 ///
 129 /// use secp256k1::Secp256k1;
 130 /// use secp256k1::key::SecretKey;
 131 ///
 132 /// use lightning_invoice::{Currency, InvoiceBuilder};
 133 ///
 134 /// # fn main() {
 135 /// let private_key = SecretKey::from_slice(
 136 ///             &[
 137 ///                     0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
 138 ///                     0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
 139 ///             0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
 140 ///     ][..]
 141 ///     ).unwrap();
 142 ///
 143 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
 144 ///
 145 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
 146 ///     .description("Coins pls!".into())
 147 ///     .payment_hash(payment_hash)
 148 ///     .current_timestamp()
 149 ///     .min_final_cltv_expiry(144)
 150 ///     .build_signed(|hash| {
 151 ///             Secp256k1::new().sign_recoverable(hash, &private_key)
 152 ///     })
 153 ///     .unwrap();
 154 ///
 155 /// assert!(invoice.to_string().starts_with("lnbc1"));
 156 /// # }
 157 /// ```
 158 ///
 159 /// # Type parameters
 160 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
 161 /// given field:
 162 ///  * `D`: exactly one `Description` or `DescriptionHash`
 163 ///  * `H`: exactly one `PaymentHash`
 164 ///  * `T`: the timestamp is set
 165 ///
 166 /// (C-not exported) as we likely need to manually select one set of boolean type parameters.
 167 #[derive(Eq, PartialEq, Debug, Clone)]
 168 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> {
 169         currency: Currency,
 170         amount: Option<u64>,
 171         si_prefix: Option<SiPrefix>,
 172         timestamp: Option<PositiveTimestamp>,
 173         tagged_fields: Vec<TaggedField>,
 174         error: Option<CreationError>,
 175
 176         phantom_d: std::marker::PhantomData<D>,
 177         phantom_h: std::marker::PhantomData<H>,
 178         phantom_t: std::marker::PhantomData<T>,
 179         phantom_c: std::marker::PhantomData<C>,
 180 }
 181
 182 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
 183 ///
 184 /// There are three ways to construct an `Invoice`:
 185 ///  1. using `InvoiceBuilder`
 186 ///  2. using `Invoice::from_signed(SignedRawInvoice)`
 187 ///  3. using `str::parse::<Invoice>(&str)`
 188 #[derive(Eq, PartialEq, Debug, Clone)]
 189 pub struct Invoice {
 190         signed_invoice: SignedRawInvoice,
 191 }
 192
 193 /// Represents the description of an invoice which has to be either a directly included string or
 194 /// a hash of a description provided out of band.
 195 ///
 196 /// (C-not exported) As we don't have a good way to map the reference lifetimes making this
 197 /// practically impossible to use safely in languages like C.
 198 #[derive(Eq, PartialEq, Debug, Clone)]
 199 pub enum InvoiceDescription<'f> {
 200         /// Reference to the directly supplied description in the invoice
 201         Direct(&'f Description),
 202
 203         /// Reference to the description's hash included in the invoice
 204         Hash(&'f Sha256),
 205 }
 206
 207 /// Represents a signed `RawInvoice` with cached hash. The signature is not checked and may be
 208 /// invalid.
 209 ///
 210 /// # Invariants
 211 /// The hash has to be either from the deserialized invoice or from the serialized `raw_invoice`.
 212 #[derive(Eq, PartialEq, Debug, Clone)]
 213 pub struct SignedRawInvoice {
 214         /// The rawInvoice that the signature belongs to
 215         raw_invoice: RawInvoice,
 216
 217         /// Hash of the `RawInvoice` that will be used to check the signature.
 218         ///
 219         /// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form,
 220         /// since it's not guaranteed that encoding it again will lead to the same result since integers
 221         /// could have been encoded with leading zeroes etc.
 222         /// * if the `SignedRawInvoice` was constructed manually the hash will be the calculated hash
 223         /// from the `RawInvoice`
 224         hash: [u8; 32],
 225
 226         /// signature of the payment request
 227         signature: InvoiceSignature,
 228 }
 229
 230 /// Represents an syntactically correct Invoice for a payment on the lightning network,
 231 /// but without the signature information.
 232 /// De- and encoding should not lead to information loss but may lead to different hashes.
 233 ///
 234 /// For methods without docs see the corresponding methods in `Invoice`.
 235 #[derive(Eq, PartialEq, Debug, Clone)]
 236 pub struct RawInvoice {
 237         /// human readable part
 238         pub hrp: RawHrp,
 239
 240         /// data part
 241         pub data: RawDataPart,
 242 }
 243
 244 /// Data of the `RawInvoice` that is encoded in the human readable part
 245 ///
 246 /// (C-not exported) As we don't yet support Option<Enum>
 247 #[derive(Eq, PartialEq, Debug, Clone)]
 248 pub struct RawHrp {
 249         /// The currency deferred from the 3rd and 4th character of the bech32 transaction
 250         pub currency: Currency,
 251
 252         /// The amount that, multiplied by the SI prefix, has to be payed
 253         pub raw_amount: Option<u64>,
 254
 255         /// SI prefix that gets multiplied with the `raw_amount`
 256         pub si_prefix: Option<SiPrefix>,
 257 }
 258
 259 /// Data of the `RawInvoice` that is encoded in the data part
 260 #[derive(Eq, PartialEq, Debug, Clone)]
 261 pub struct RawDataPart {
 262         /// generation time of the invoice
 263         pub timestamp: PositiveTimestamp,
 264
 265         /// tagged fields of the payment request
 266         pub tagged_fields: Vec<RawTaggedField>,
 267 }
 268
 269 /// A timestamp that refers to a date after 1 January 1970 which means its representation as UNIX
 270 /// timestamp is positive.
 271 ///
 272 /// # Invariants
 273 /// The UNIX timestamp representing the stored time has to be positive and small enough so that
 274 /// a `EpiryTime` can be added to it without an overflow.
 275 #[derive(Eq, PartialEq, Debug, Clone)]
 276 pub struct PositiveTimestamp(SystemTime);
 277
 278 /// SI prefixes for the human readable part
 279 #[derive(Eq, PartialEq, Debug, Clone, Copy)]
 280 pub enum SiPrefix {
 281         /// 10^-3
 282         Milli,
 283         /// 10^-6
 284         Micro,
 285         /// 10^-9
 286         Nano,
 287         /// 10^-12
 288         Pico,
 289 }
 290
 291 impl SiPrefix {
 292         /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
 293         /// This is effectively 10^12 * the prefix multiplier
 294         pub fn multiplier(&self) -> u64 {
 295                 match *self {
 296                         SiPrefix::Milli => 1_000_000_000,
 297                         SiPrefix::Micro => 1_000_000,
 298                         SiPrefix::Nano => 1_000,
 299                         SiPrefix::Pico => 1,
 300                 }
 301         }
 302
 303         /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
 304         /// multiplier.
 305         ///
 306         /// (C-not exported) As we don't yet support a slice of enums, and also because this function
 307         /// isn't the most critical to expose.
 308         pub fn values_desc() -> &'static [SiPrefix] {
 309                 use SiPrefix::*;
 310                 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
 311                 &VALUES
 312         }
 313 }
 314
 315 /// Enum representing the crypto currencies (or networks) supported by this library
 316 #[derive(Eq, PartialEq, Debug, Clone)]
 317 pub enum Currency {
 318         /// Bitcoin mainnet
 319         Bitcoin,
 320
 321         /// Bitcoin testnet
 322         BitcoinTestnet,
 323
 324         /// Bitcoin regtest
 325         Regtest,
 326
 327         /// Bitcoin simnet/signet
 328         Simnet,
 329 }
 330
 331 /// Tagged field which may have an unknown tag
 332 #[derive(Eq, PartialEq, Debug, Clone)]
 333 pub enum RawTaggedField {
 334         /// Parsed tagged field with known tag
 335         KnownSemantics(TaggedField),
 336         /// tagged field which was not parsed due to an unknown tag or undefined field semantics
 337         UnknownSemantics(Vec<u5>),
 338 }
 339
 340 /// Tagged field with known tag
 341 ///
 342 /// For descriptions of the enum values please refer to the enclosed type's docs.
 343 #[allow(missing_docs)]
 344 #[derive(Eq, PartialEq, Debug, Clone)]
 345 pub enum TaggedField {
 346         PaymentHash(Sha256),
 347         Description(Description),
 348         PayeePubKey(PayeePubKey),
 349         DescriptionHash(Sha256),
 350         ExpiryTime(ExpiryTime),
 351         MinFinalCltvExpiry(MinFinalCltvExpiry),
 352         Fallback(Fallback),
 353         Route(RouteHint),
 354         PaymentSecret(PaymentSecret),
 355         Features(InvoiceFeatures),
 356 }
 357
 358 /// SHA-256 hash
 359 #[derive(Eq, PartialEq, Debug, Clone)]
 360 pub struct Sha256(pub sha256::Hash);
 361
 362 /// Description string
 363 ///
 364 /// # Invariants
 365 /// The description can be at most 639 __bytes__ long
 366 #[derive(Eq, PartialEq, Debug, Clone)]
 367 pub struct Description(String);
 368
 369 /// Payee public key
 370 #[derive(Eq, PartialEq, Debug, Clone)]
 371 pub struct PayeePubKey(pub PublicKey);
 372
 373 /// 256-bit payment secret
 374 #[derive(Eq, PartialEq, Debug, Clone)]
 375 pub struct PaymentSecret(pub [u8; 32]);
 376
 377 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
 378 /// expires
 379 ///
 380 /// # Invariants
 381 /// The number of seconds this expiry time represents has to be in the range
 382 /// `0...(SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)` to avoid overflows when adding it to a
 383 /// timestamp
 384 #[derive(Eq, PartialEq, Debug, Clone)]
 385 pub struct ExpiryTime(Duration);
 386
 387 /// `min_final_cltv_expiry` to use for the last HTLC in the route
 388 #[derive(Eq, PartialEq, Debug, Clone)]
 389 pub struct MinFinalCltvExpiry(pub u64);
 390
 391 // TODO: better types instead onf byte arrays
 392 /// Fallback address in case no LN payment is possible
 393 #[allow(missing_docs)]
 394 #[derive(Eq, PartialEq, Debug, Clone)]
 395 pub enum Fallback {
 396         SegWitProgram {
 397                 version: u5,
 398                 program: Vec<u8>,
 399         },
 400         PubKeyHash([u8; 20]),
 401         ScriptHash([u8; 20]),
 402 }
 403
 404 /// Recoverable signature
 405 #[derive(Eq, PartialEq, Debug, Clone)]
 406 pub struct InvoiceSignature(pub RecoverableSignature);
 407
 408 /// Private routing information
 409 ///
 410 /// # Invariants
 411 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
 412 ///
 413 #[derive(Eq, PartialEq, Debug, Clone)]
 414 pub struct RouteHint(Vec<RouteHintHop>);
 415
 416 /// Tag constants as specified in BOLT11
 417 #[allow(missing_docs)]
 418 pub mod constants {
 419         pub const TAG_PAYMENT_HASH: u8 = 1;
 420         pub const TAG_DESCRIPTION: u8 = 13;
 421         pub const TAG_PAYEE_PUB_KEY: u8 = 19;
 422         pub const TAG_DESCRIPTION_HASH: u8 = 23;
 423         pub const TAG_EXPIRY_TIME: u8 = 6;
 424         pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
 425         pub const TAG_FALLBACK: u8 = 9;
 426         pub const TAG_ROUTE: u8 = 3;
 427         pub const TAG_PAYMENT_SECRET: u8 = 16;
 428         pub const TAG_FEATURES: u8 = 5;
 429 }
 430
 431 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False> {
 432         /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
 433         /// `InvoiceBuilder::build(self)` becomes available.
 434         pub fn new(currrency: Currency) -> Self {
 435                 InvoiceBuilder {
 436                         currency: currrency,
 437                         amount: None,
 438                         si_prefix: None,
 439                         timestamp: None,
 440                         tagged_fields: Vec::new(),
 441                         error: None,
 442
 443                         phantom_d: std::marker::PhantomData,
 444                         phantom_h: std::marker::PhantomData,
 445                         phantom_t: std::marker::PhantomData,
 446                         phantom_c: std::marker::PhantomData,
 447                 }
 448         }
 449 }
 450
 451 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C> {
 452         /// Helper function to set the completeness flags.
 453         fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN> {
 454                 InvoiceBuilder::<DN, HN, TN, CN> {
 455                         currency: self.currency,
 456                         amount: self.amount,
 457                         si_prefix: self.si_prefix,
 458                         timestamp: self.timestamp,
 459                         tagged_fields: self.tagged_fields,
 460                         error: self.error,
 461
 462                         phantom_d: std::marker::PhantomData,
 463                         phantom_h: std::marker::PhantomData,
 464                         phantom_t: std::marker::PhantomData,
 465                         phantom_c: std::marker::PhantomData,
 466                 }
 467         }
 468
 469         /// Sets the amount in pico BTC. The optimal SI prefix is choosen automatically.
 470         pub fn amount_pico_btc(mut self, amount: u64) -> Self {
 471                 let biggest_possible_si_prefix = SiPrefix::values_desc()
 472                         .iter()
 473                         .find(|prefix| amount % prefix.multiplier() == 0)
 474                         .expect("Pico should always match");
 475                 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
 476                 self.si_prefix = Some(*biggest_possible_si_prefix);
 477                 self
 478         }
 479
 480         /// Sets the payee's public key.
 481         pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
 482                 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
 483                 self
 484         }
 485
 486         /// Sets the payment secret
 487         pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> Self {
 488                 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
 489                 self
 490         }
 491
 492         /// Sets the expiry time
 493         pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
 494         match ExpiryTime::from_duration(expiry_time) {
 495             Ok(t) => self.tagged_fields.push(TaggedField::ExpiryTime(t)),
 496             Err(e) => self.error = Some(e),
 497         };
 498                 self
 499         }
 500
 501         /// Adds a fallback address.
 502         pub fn fallback(mut self, fallback: Fallback) -> Self {
 503                 self.tagged_fields.push(TaggedField::Fallback(fallback));
 504                 self
 505         }
 506
 507         /// Adds a private route.
 508         pub fn route(mut self, route: Vec<RouteHintHop>) -> Self {
 509                 match RouteHint::new(route) {
 510                         Ok(r) => self.tagged_fields.push(TaggedField::Route(r)),
 511                         Err(e) => self.error = Some(e),
 512                 }
 513                 self
 514         }
 515
 516         /// Adds a features field which indicates the set of supported protocol extensions which the
 517         /// origin node supports.
 518         pub fn features(mut self, features: InvoiceFeatures) -> Self {
 519                 self.tagged_fields.push(TaggedField::Features(features));
 520                 self
 521         }
 522 }
 523
 524 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, tb::True, C> {
 525         /// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields.
 526         pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
 527
 528                 // If an error occurred at any time before, return it now
 529                 if let Some(e) = self.error {
 530                         return Err(e);
 531                 }
 532
 533                 let hrp = RawHrp {
 534                         currency: self.currency,
 535                         raw_amount: self.amount,
 536                         si_prefix: self.si_prefix,
 537                 };
 538
 539                 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
 540
 541                 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
 542                         RawTaggedField::KnownSemantics(tf)
 543                 }).collect::<Vec<_>>();
 544
 545                 let data = RawDataPart {
 546                         timestamp: timestamp,
 547                         tagged_fields: tagged_fields,
 548                 };
 549
 550                 Ok(RawInvoice {
 551                         hrp: hrp,
 552                         data: data,
 553                 })
 554         }
 555 }
 556
 557 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<tb::False, H, T, C> {
 558         /// Set the description. This function is only available if no description (hash) was set.
 559         pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C> {
 560                 match Description::new(description) {
 561                         Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
 562                         Err(e) => self.error = Some(e),
 563                 }
 564                 self.set_flags()
 565         }
 566
 567         /// Set the description hash. This function is only available if no description (hash) was set.
 568         pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C> {
 569                 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
 570                 self.set_flags()
 571         }
 572 }
 573
 574 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, tb::False, T, C> {
 575         /// Set the payment hash. This function is only available if no payment hash was set.
 576         pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C> {
 577                 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
 578                 self.set_flags()
 579         }
 580 }
 581
 582 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, tb::False, C> {
 583         /// Sets the timestamp.
 584         pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C> {
 585                 match PositiveTimestamp::from_system_time(time) {
 586                         Ok(t) => self.timestamp = Some(t),
 587                         Err(e) => self.error = Some(e),
 588                 }
 589
 590                 self.set_flags()
 591         }
 592
 593         /// Sets the timestamp to the current UNIX timestamp.
 594         pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C> {
 595                 let now = PositiveTimestamp::from_system_time(SystemTime::now());
 596                 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
 597                 self.set_flags()
 598         }
 599 }
 600
 601 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool> InvoiceBuilder<D, H, T, tb::False> {
 602         /// Sets `min_final_cltv_expiry`.
 603         pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True> {
 604                 self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
 605                 self.set_flags()
 606         }
 607 }
 608
 609 impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True> {
 610         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
 611         /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
 612         /// the included payee public key.
 613         pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
 614                 where F: FnOnce(&Message) -> RecoverableSignature
 615         {
 616                 let invoice = self.try_build_signed::<_, ()>(|hash| {
 617                         Ok(sign_function(hash))
 618                 });
 619
 620                 match invoice {
 621                         Ok(i) => Ok(i),
 622                         Err(SignOrCreationError::CreationError(e)) => Err(e),
 623                         Err(SignOrCreationError::SignError(())) => unreachable!(),
 624                 }
 625         }
 626
 627         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
 628         /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
 629         /// if applicable also for the included payee public key.
 630         pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Invoice, SignOrCreationError<E>>
 631                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 632         {
 633                 let raw = match self.build_raw() {
 634                         Ok(r) => r,
 635                         Err(e) => return Err(SignOrCreationError::CreationError(e)),
 636                 };
 637
 638                 let signed = match raw.sign(sign_function) {
 639                         Ok(s) => s,
 640                         Err(e) => return Err(SignOrCreationError::SignError(e)),
 641                 };
 642
 643                 let invoice = Invoice {
 644                         signed_invoice: signed,
 645                 };
 646
 647                 invoice.check_field_counts().expect("should be ensured by type signature of builder");
 648
 649                 Ok(invoice)
 650         }
 651 }
 652
 653
 654 impl SignedRawInvoice {
 655         /// Disassembles the `SignedRawInvoice` into its three parts:
 656         ///  1. raw invoice
 657         ///  2. hash of the raw invoice
 658         ///  3. signature
 659         pub fn into_parts(self) -> (RawInvoice, [u8; 32], InvoiceSignature) {
 660                 (self.raw_invoice, self.hash, self.signature)
 661         }
 662
 663         /// The `RawInvoice` which was signed.
 664         pub fn raw_invoice(&self) -> &RawInvoice {
 665                 &self.raw_invoice
 666         }
 667
 668         /// The hash of the `RawInvoice` that was signed.
 669         pub fn hash(&self) -> &[u8; 32] {
 670                 &self.hash
 671         }
 672
 673         /// InvoiceSignature for the invoice.
 674         pub fn signature(&self) -> &InvoiceSignature {
 675                 &self.signature
 676         }
 677
 678         /// Recovers the public key used for signing the invoice from the recoverable signature.
 679         pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
 680                 let hash = Message::from_slice(&self.hash[..])
 681                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 682
 683                 Ok(PayeePubKey(Secp256k1::new().recover(
 684                         &hash,
 685                         &self.signature
 686                 )?))
 687         }
 688
 689         /// Checks if the signature is valid for the included payee public key or if none exists if it's
 690         /// valid for the recovered signature (which should always be true?).
 691         pub fn check_signature(&self) -> bool {
 692                 let included_pub_key = self.raw_invoice.payee_pub_key();
 693
 694                 let mut recovered_pub_key = Option::None;
 695                 if recovered_pub_key.is_none() {
 696                         let recovered = match self.recover_payee_pub_key() {
 697                                 Ok(pk) => pk,
 698                                 Err(_) => return false,
 699                         };
 700                         recovered_pub_key = Some(recovered);
 701                 }
 702
 703                 let pub_key = included_pub_key.or_else(|| recovered_pub_key.as_ref())
 704                         .expect("One is always present");
 705
 706                 let hash = Message::from_slice(&self.hash[..])
 707                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 708
 709                 let secp_context = Secp256k1::new();
 710                 let verification_result = secp_context.verify(
 711                         &hash,
 712                         &self.signature.to_standard(),
 713                         pub_key
 714                 );
 715
 716                 match verification_result {
 717                         Ok(()) => true,
 718                         Err(_) => false,
 719                 }
 720         }
 721 }
 722
 723 /// Finds the first element of an enum stream of a given variant and extracts one member of the
 724 /// variant. If no element was found `None` gets returned.
 725 ///
 726 /// The following example would extract the first
 727 /// ```
 728 /// use Enum::*
 729 ///
 730 /// enum Enum {
 731 ///     A(u8),
 732 ///     B(u16)
 733 /// }
 734 ///
 735 /// let elements = vec![A(1), A(2), B(3), A(4)]
 736 ///
 737 /// assert_eq!(find_extract!(elements.iter(), Enum::B(ref x), x), Some(3u16))
 738 /// ```
 739 macro_rules! find_extract {
 740     ($iter:expr, $enm:pat, $enm_var:ident) => {
 741         $iter.filter_map(|tf| match *tf {
 742                         $enm => Some($enm_var),
 743                         _ => None,
 744                 }).next()
 745     };
 746 }
 747
 748 #[allow(missing_docs)]
 749 impl RawInvoice {
 750         /// Hash the HRP as bytes and signatureless data part.
 751         fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
 752                 use bech32::FromBase32;
 753
 754                 let mut preimage = Vec::<u8>::from(hrp_bytes);
 755
 756                 let mut data_part = Vec::from(data_without_signature);
 757                 let overhang = (data_part.len() * 5) % 8;
 758                 if overhang > 0 {
 759                         // add padding if data does not end at a byte boundary
 760                         data_part.push(u5::try_from_u8(0).unwrap());
 761
 762                         // if overhang is in (1..3) we need to add u5(0) padding two times
 763                         if overhang < 3 {
 764                                 data_part.push(u5::try_from_u8(0).unwrap());
 765                         }
 766                 }
 767
 768                 preimage.extend_from_slice(&Vec::<u8>::from_base32(&data_part)
 769                         .expect("No padding error may occur due to appended zero above."));
 770
 771                 let mut hash: [u8; 32] = Default::default();
 772                 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
 773                 hash
 774         }
 775
 776         /// Calculate the hash of the encoded `RawInvoice`
 777         pub fn hash(&self) -> [u8; 32] {
 778                 use bech32::ToBase32;
 779
 780                 RawInvoice::hash_from_parts(
 781                         self.hrp.to_string().as_bytes(),
 782                         &self.data.to_base32()
 783                 )
 784         }
 785
 786         /// Signs the invoice using the supplied `sign_function`. This function MAY fail with an error
 787         /// of type `E`. Since the signature of a `SignedRawInvoice` is not required to be valid there
 788         /// are no constraints regarding the validity of the produced signature.
 789         ///
 790         /// (C-not exported) As we don't currently support passing function pointers into methods
 791         /// explicitly.
 792         pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
 793                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 794         {
 795                 let raw_hash = self.hash();
 796                 let hash = Message::from_slice(&raw_hash[..])
 797                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 798                 let signature = sign_method(&hash)?;
 799
 800                 Ok(SignedRawInvoice {
 801                         raw_invoice: self,
 802                         hash: raw_hash,
 803                         signature: InvoiceSignature(signature),
 804                 })
 805         }
 806
 807         /// Returns an iterator over all tagged fields with known semantics.
 808         ///
 809         /// (C-not exported) As there is not yet a manual mapping for a FilterMap
 810         pub fn known_tagged_fields(&self)
 811                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
 812         {
 813                 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
 814                 // function's type signature.
 815                 // TODO: refactor once impl Trait is available
 816                 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
 817                         match *raw {
 818                                 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
 819                                 _ => None,
 820                         }
 821                 }
 822
 823                 self.data.tagged_fields.iter().filter_map(match_raw )
 824         }
 825
 826         pub fn payment_hash(&self) -> Option<&Sha256> {
 827                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
 828         }
 829
 830         pub fn description(&self) -> Option<&Description> {
 831                 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
 832         }
 833
 834         pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
 835                 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
 836         }
 837
 838         pub fn description_hash(&self) -> Option<&Sha256> {
 839                 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
 840         }
 841
 842         pub fn expiry_time(&self) -> Option<&ExpiryTime> {
 843                 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
 844         }
 845
 846         pub fn min_final_cltv_expiry(&self) -> Option<&MinFinalCltvExpiry> {
 847                 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
 848         }
 849
 850         pub fn payment_secret(&self) -> Option<&PaymentSecret> {
 851                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
 852         }
 853
 854         pub fn features(&self) -> Option<&InvoiceFeatures> {
 855                 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
 856         }
 857
 858         /// (C-not exported) as we don't support Vec<&NonOpaqueType>
 859         pub fn fallbacks(&self) -> Vec<&Fallback> {
 860                 self.known_tagged_fields().filter_map(|tf| match tf {
 861                         &TaggedField::Fallback(ref f) => Some(f),
 862                         _ => None,
 863                 }).collect::<Vec<&Fallback>>()
 864         }
 865
 866         pub fn routes(&self) -> Vec<&RouteHint> {
 867                 self.known_tagged_fields().filter_map(|tf| match tf {
 868                         &TaggedField::Route(ref r) => Some(r),
 869                         _ => None,
 870                 }).collect::<Vec<&RouteHint>>()
 871         }
 872
 873         pub fn amount_pico_btc(&self) -> Option<u64> {
 874                 self.hrp.raw_amount.map(|v| {
 875                         v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
 876                 })
 877         }
 878
 879         pub fn currency(&self) -> Currency {
 880                 self.hrp.currency.clone()
 881         }
 882 }
 883
 884 impl PositiveTimestamp {
 885         /// Create a new `PositiveTimestamp` from a unix timestamp in the Range
 886         /// `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
 887         /// `CreationError::TimestampOutOfBounds`.
 888         pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
 889                 if unix_seconds > SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME {
 890                         Err(CreationError::TimestampOutOfBounds)
 891                 } else {
 892                         Ok(PositiveTimestamp(UNIX_EPOCH + Duration::from_secs(unix_seconds)))
 893                 }
 894         }
 895
 896         /// Create a new `PositiveTimestamp` from a `SystemTime` with a corresponding unix timestamp in
 897         /// the Range `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
 898         /// `CreationError::TimestampOutOfBounds`.
 899         pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
 900                 if time
 901                         .duration_since(UNIX_EPOCH)
 902                         .map(|t| t.as_secs() <= SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)
 903                         .unwrap_or(true)
 904                         {
 905                                 Ok(PositiveTimestamp(time))
 906                         } else {
 907                         Err(CreationError::TimestampOutOfBounds)
 908                 }
 909         }
 910
 911         /// Returns the UNIX timestamp representing the stored time
 912         pub fn as_unix_timestamp(&self) -> u64 {
 913                 self.0.duration_since(UNIX_EPOCH)
 914                         .expect("ensured by type contract/constructors")
 915                         .as_secs()
 916         }
 917
 918         /// Returns a reference to the internal `SystemTime` time representation
 919         pub fn as_time(&self) -> &SystemTime {
 920                 &self.0
 921         }
 922 }
 923
 924 impl Into<SystemTime> for PositiveTimestamp {
 925         fn into(self) -> SystemTime {
 926                 self.0
 927         }
 928 }
 929
 930 impl Deref for PositiveTimestamp {
 931         type Target = SystemTime;
 932
 933         fn deref(&self) -> &Self::Target {
 934                 &self.0
 935         }
 936 }
 937
 938 impl Invoice {
 939         /// Transform the `Invoice` into it's unchecked version
 940         pub fn into_signed_raw(self) -> SignedRawInvoice {
 941                 self.signed_invoice
 942         }
 943
 944         /// Check that all mandatory fields are present
 945         fn check_field_counts(&self) -> Result<(), SemanticError> {
 946                 // "A writer MUST include exactly one p field […]."
 947                 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
 948                         TaggedField::PaymentHash(_) => true,
 949                         _ => false,
 950                 }).count();
 951                 if payment_hash_cnt < 1 {
 952                         return Err(SemanticError::NoPaymentHash);
 953                 } else if payment_hash_cnt > 1 {
 954                         return Err(SemanticError::MultiplePaymentHashes);
 955                 }
 956
 957                 // "A writer MUST include either exactly one d or exactly one h field."
 958                 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
 959                         TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
 960                         _ => false,
 961                 }).count();
 962                 if  description_cnt < 1 {
 963                         return Err(SemanticError::NoDescription);
 964                 } else if description_cnt > 1 {
 965                         return  Err(SemanticError::MultipleDescriptions);
 966                 }
 967
 968                 Ok(())
 969         }
 970
 971         /// Check that the invoice is signed correctly and that key recovery works
 972         pub fn check_signature(&self) -> Result<(), SemanticError> {
 973                 match self.signed_invoice.recover_payee_pub_key() {
 974                         Err(secp256k1::Error::InvalidRecoveryId) =>
 975                                 return Err(SemanticError::InvalidRecoveryId),
 976                         Err(_) => panic!("no other error may occur"),
 977                         Ok(_) => {},
 978                 }
 979
 980                 if !self.signed_invoice.check_signature() {
 981                         return Err(SemanticError::InvalidSignature);
 982                 }
 983
 984                 Ok(())
 985         }
 986
 987         /// Constructs an `Invoice` from a `SignedInvoice` by checking all its invariants.
 988         /// ```
 989         /// use lightning_invoice::*;
 990         ///
 991         /// let invoice = "lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp\
 992         ///     l2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d7\
 993         ///     3gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ec\
 994         ///     ky03ylcqca784w";
 995         ///
 996         /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
 997         ///
 998         /// assert!(Invoice::from_signed(signed).is_ok());
 999         /// ```
1000         pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
1001                 let invoice = Invoice {
1002                         signed_invoice: signed_invoice,
1003                 };
1004                 invoice.check_field_counts()?;
1005                 invoice.check_signature()?;
1006
1007                 Ok(invoice)
1008         }
1009
1010         /// Returns the `Invoice`'s timestamp (should equal it's creation time)
1011         pub fn timestamp(&self) -> &SystemTime {
1012                 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1013         }
1014
1015         /// Returns an iterator over all tagged fields of this Invoice.
1016         ///
1017         /// (C-not exported) As there is not yet a manual mapping for a FilterMap
1018         pub fn tagged_fields(&self)
1019                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1020                 self.signed_invoice.raw_invoice().known_tagged_fields()
1021         }
1022
1023         /// Returns the hash to which we will receive the preimage on completion of the payment
1024         pub fn payment_hash(&self) -> &sha256::Hash {
1025                 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1026         }
1027
1028         /// Return the description or a hash of it for longer ones
1029         ///
1030         /// (C-not exported) because we don't yet export InvoiceDescription
1031         pub fn description(&self) -> InvoiceDescription {
1032                 if let Some(ref direct) = self.signed_invoice.description() {
1033                         return InvoiceDescription::Direct(direct);
1034                 } else if let Some(ref hash) = self.signed_invoice.description_hash() {
1035                         return InvoiceDescription::Hash(hash);
1036                 }
1037                 unreachable!("ensured by constructor");
1038         }
1039
1040         /// Get the payee's public key if one was included in the invoice
1041         pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1042                 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1043         }
1044
1045         /// Get the payment secret if one was included in the invoice
1046         pub fn payment_secret(&self) -> Option<&PaymentSecret> {
1047                 self.signed_invoice.payment_secret()
1048         }
1049
1050         /// Get the invoice features if they were included in the invoice
1051         pub fn features(&self) -> Option<&InvoiceFeatures> {
1052                 self.signed_invoice.features()
1053         }
1054
1055         /// Recover the payee's public key (only to be used if none was included in the invoice)
1056         pub fn recover_payee_pub_key(&self) -> PublicKey {
1057                 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1058         }
1059
1060         /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1061         pub fn expiry_time(&self) -> Duration {
1062                 self.signed_invoice.expiry_time()
1063                         .map(|x| x.0)
1064                         .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1065         }
1066
1067         /// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
1068         /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
1069         pub fn min_final_cltv_expiry(&self) -> u64 {
1070                 self.signed_invoice.min_final_cltv_expiry()
1071                         .map(|x| x.0)
1072                         .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
1073         }
1074
1075         /// Returns a list of all fallback addresses
1076         ///
1077         /// (C-not exported) as we don't support Vec<&NonOpaqueType>
1078         pub fn fallbacks(&self) -> Vec<&Fallback> {
1079                 self.signed_invoice.fallbacks()
1080         }
1081
1082         /// Returns a list of all routes included in the invoice
1083         pub fn routes(&self) -> Vec<&RouteHint> {
1084                 self.signed_invoice.routes()
1085         }
1086
1087         /// Returns the currency for which the invoice was issued
1088         pub fn currency(&self) -> Currency {
1089                 self.signed_invoice.currency()
1090         }
1091
1092         /// Returns the amount if specified in the invoice as pico <currency>.
1093         pub fn amount_pico_btc(&self) -> Option<u64> {
1094                 self.signed_invoice.amount_pico_btc()
1095         }
1096 }
1097
1098 impl From<TaggedField> for RawTaggedField {
1099         fn from(tf: TaggedField) -> Self {
1100                 RawTaggedField::KnownSemantics(tf)
1101         }
1102 }
1103
1104 impl TaggedField {
1105         /// Numeric representation of the field's tag
1106         pub fn tag(&self) -> u5 {
1107                 let tag = match *self {
1108                         TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1109                         TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1110                         TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1111                         TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1112                         TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1113                         TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY,
1114                         TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1115                         TaggedField::Route(_) => constants::TAG_ROUTE,
1116                         TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1117                         TaggedField::Features(_) => constants::TAG_FEATURES,
1118                 };
1119
1120                 u5::try_from_u8(tag).expect("all tags defined are <32")
1121         }
1122 }
1123
1124 impl Description {
1125
1126         /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1127         /// returns `CreationError::DescriptionTooLong` otherwise
1128         ///
1129         /// Please note that single characters may use more than one byte due to UTF8 encoding.
1130         pub fn new(description: String) -> Result<Description, CreationError> {
1131                 if description.len() > 639 {
1132                         Err(CreationError::DescriptionTooLong)
1133                 } else {
1134                         Ok(Description(description))
1135                 }
1136         }
1137
1138         /// Returns the underlying description `String`
1139         pub fn into_inner(self) -> String {
1140                 self.0
1141         }
1142 }
1143
1144 impl Into<String> for Description {
1145         fn into(self) -> String {
1146                 self.into_inner()
1147         }
1148 }
1149
1150 impl Deref for Description {
1151         type Target = str;
1152
1153         fn deref(&self) -> &str {
1154                 &self.0
1155         }
1156 }
1157
1158 impl From<PublicKey> for PayeePubKey {
1159         fn from(pk: PublicKey) -> Self {
1160                 PayeePubKey(pk)
1161         }
1162 }
1163
1164 impl Deref for PayeePubKey {
1165         type Target = PublicKey;
1166
1167         fn deref(&self) -> &PublicKey {
1168                 &self.0
1169         }
1170 }
1171
1172 impl ExpiryTime {
1173         /// Construct an `ExpiryTime` from seconds. If there exists a `PositiveTimestamp` which would
1174         /// overflow on adding the `EpiryTime` to it then this function will return a
1175         /// `CreationError::ExpiryTimeOutOfBounds`.
1176         pub fn from_seconds(seconds: u64) -> Result<ExpiryTime, CreationError> {
1177                 if seconds <= MAX_EXPIRY_TIME {
1178                         Ok(ExpiryTime(Duration::from_secs(seconds)))
1179                 } else {
1180                         Err(CreationError::ExpiryTimeOutOfBounds)
1181                 }
1182         }
1183
1184         /// Construct an `ExpiryTime` from a `Duration`. If there exists a `PositiveTimestamp` which
1185         /// would overflow on adding the `EpiryTime` to it then this function will return a
1186         /// `CreationError::ExpiryTimeOutOfBounds`.
1187         pub fn from_duration(duration: Duration) -> Result<ExpiryTime, CreationError> {
1188                 if duration.as_secs() <= MAX_EXPIRY_TIME {
1189                         Ok(ExpiryTime(duration))
1190                 } else {
1191                         Err(CreationError::ExpiryTimeOutOfBounds)
1192                 }
1193         }
1194
1195         /// Returns the expiry time in seconds
1196         pub fn as_seconds(&self) -> u64 {
1197                 self.0.as_secs()
1198         }
1199
1200         /// Returns a reference to the underlying `Duration` (=expiry time)
1201         pub fn as_duration(&self) -> &Duration {
1202                 &self.0
1203         }
1204 }
1205
1206 impl RouteHint {
1207         /// Create a new (partial) route from a list of hops
1208         pub fn new(hops: Vec<RouteHintHop>) -> Result<RouteHint, CreationError> {
1209                 if hops.len() <= 12 {
1210                         Ok(RouteHint(hops))
1211                 } else {
1212                         Err(CreationError::RouteTooLong)
1213                 }
1214         }
1215
1216         /// Returrn the underlying vector of hops
1217         pub fn into_inner(self) -> Vec<RouteHintHop> {
1218                 self.0
1219         }
1220 }
1221
1222 impl Into<Vec<RouteHintHop>> for RouteHint {
1223         fn into(self) -> Vec<RouteHintHop> {
1224                 self.into_inner()
1225         }
1226 }
1227
1228 impl Deref for RouteHint {
1229         type Target = Vec<RouteHintHop>;
1230
1231         fn deref(&self) -> &Vec<RouteHintHop> {
1232                 &self.0
1233         }
1234 }
1235
1236 impl Deref for InvoiceSignature {
1237         type Target = RecoverableSignature;
1238
1239         fn deref(&self) -> &RecoverableSignature {
1240                 &self.0
1241         }
1242 }
1243
1244 impl Deref for SignedRawInvoice {
1245         type Target = RawInvoice;
1246
1247         fn deref(&self) -> &RawInvoice {
1248                 &self.raw_invoice
1249         }
1250 }
1251
1252 /// Errors that may occur when constructing a new `RawInvoice` or `Invoice`
1253 #[derive(Eq, PartialEq, Debug, Clone)]
1254 pub enum CreationError {
1255         /// The supplied description string was longer than 639 __bytes__ (see [`Description::new(…)`](./struct.Description.html#method.new))
1256         DescriptionTooLong,
1257
1258         /// The specified route has too many hops and can't be encoded
1259         RouteTooLong,
1260
1261         /// The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`
1262         TimestampOutOfBounds,
1263
1264         /// The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`
1265         ExpiryTimeOutOfBounds,
1266 }
1267
1268 impl Display for CreationError {
1269         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1270                 match self {
1271                         CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1272                         CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1273                         CreationError::TimestampOutOfBounds => f.write_str("The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`"),
1274                         CreationError::ExpiryTimeOutOfBounds => f.write_str("The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`"),
1275                 }
1276         }
1277 }
1278
1279 impl std::error::Error for CreationError { }
1280
1281 /// Errors that may occur when converting a `RawInvoice` to an `Invoice`. They relate to the
1282 /// requirements sections in BOLT #11
1283 #[derive(Eq, PartialEq, Debug, Clone)]
1284 pub enum SemanticError {
1285         /// The invoice is missing the mandatory payment hash
1286         NoPaymentHash,
1287
1288         /// The invoice has multiple payment hashes which isn't allowed
1289         MultiplePaymentHashes,
1290
1291         /// No description or description hash are part of the invoice
1292         NoDescription,
1293
1294         /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1295         MultipleDescriptions,
1296
1297         /// The recovery id doesn't fit the signature/pub key
1298         InvalidRecoveryId,
1299
1300         /// The invoice's signature is invalid
1301         InvalidSignature,
1302 }
1303
1304 impl Display for SemanticError {
1305         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1306                 match self {
1307                         SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1308                         SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1309                         SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1310                         SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1311                         SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1312                         SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1313                 }
1314         }
1315 }
1316
1317 impl std::error::Error for SemanticError { }
1318
1319 /// When signing using a fallible method either an user-supplied `SignError` or a `CreationError`
1320 /// may occur.
1321 ///
1322 /// (C-not exported) As we don't support unbounded generics
1323 #[derive(Eq, PartialEq, Debug, Clone)]
1324 pub enum SignOrCreationError<S> {
1325         /// An error occurred during signing
1326         SignError(S),
1327
1328         /// An error occurred while building the transaction
1329         CreationError(CreationError),
1330 }
1331
1332 impl<S> Display for SignOrCreationError<S> {
1333         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1334                 match self {
1335                         SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1336                         SignOrCreationError::CreationError(err) => err.fmt(f),
1337                 }
1338         }
1339 }
1340
1341 #[cfg(test)]
1342 mod test {
1343         use bitcoin_hashes::hex::FromHex;
1344         use bitcoin_hashes::sha256;
1345
1346         #[test]
1347         fn test_system_time_bounds_assumptions() {
1348                 ::check_platform();
1349
1350         assert_eq!(
1351             ::PositiveTimestamp::from_unix_timestamp(::SYSTEM_TIME_MAX_UNIX_TIMESTAMP + 1),
1352             Err(::CreationError::TimestampOutOfBounds)
1353         );
1354
1355         assert_eq!(
1356             ::ExpiryTime::from_seconds(::MAX_EXPIRY_TIME + 1),
1357             Err(::CreationError::ExpiryTimeOutOfBounds)
1358         );
1359         }
1360
1361         #[test]
1362         fn test_calc_invoice_hash() {
1363                 use ::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1364                 use ::TaggedField::*;
1365
1366                 let invoice = RawInvoice {
1367                         hrp: RawHrp {
1368                                 currency: Currency::Bitcoin,
1369                                 raw_amount: None,
1370                                 si_prefix: None,
1371                         },
1372                         data: RawDataPart {
1373                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1374                                 tagged_fields: vec![
1375                                         PaymentHash(::Sha256(sha256::Hash::from_hex(
1376                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1377                                         ).unwrap())).into(),
1378                                         Description(::Description::new(
1379                                                 "Please consider supporting this project".to_owned()
1380                                         ).unwrap()).into(),
1381                                 ],
1382                         },
1383                 };
1384
1385                 let expected_hash = [
1386                         0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1387                         0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1388                         0xd5, 0x18, 0xe1, 0xc9
1389                 ];
1390
1391                 assert_eq!(invoice.hash(), expected_hash)
1392         }
1393
1394         #[test]
1395         fn test_check_signature() {
1396                 use TaggedField::*;
1397                 use secp256k1::Secp256k1;
1398                 use secp256k1::recovery::{RecoveryId, RecoverableSignature};
1399                 use secp256k1::key::{SecretKey, PublicKey};
1400                 use {SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
1401                          PositiveTimestamp};
1402
1403                 let invoice = SignedRawInvoice {
1404                         raw_invoice: RawInvoice {
1405                                 hrp: RawHrp {
1406                                         currency: Currency::Bitcoin,
1407                                         raw_amount: None,
1408                                         si_prefix: None,
1409                                 },
1410                                 data: RawDataPart {
1411                                         timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1412                                         tagged_fields: vec ! [
1413                                                 PaymentHash(Sha256(sha256::Hash::from_hex(
1414                                                         "0001020304050607080900010203040506070809000102030405060708090102"
1415                                                 ).unwrap())).into(),
1416                                                 Description(
1417                                                         ::Description::new(
1418                                                                 "Please consider supporting this project".to_owned()
1419                                                         ).unwrap()
1420                                                 ).into(),
1421                                         ],
1422                                 },
1423                         },
1424                         hash: [
1425                                 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1426                                 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1427                                 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1428                         ],
1429                         signature: InvoiceSignature(RecoverableSignature::from_compact(
1430                                 & [
1431                                         0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1432                                         0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1433                                         0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1434                                         0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1435                                         0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1436                                         0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1437                                 ],
1438                                 RecoveryId::from_i32(0).unwrap()
1439                         ).unwrap()),
1440                 };
1441
1442                 assert!(invoice.check_signature());
1443
1444                 let private_key = SecretKey::from_slice(
1445                         &[
1446                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1447                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1448                                 0x3b, 0x2d, 0xb7, 0x34
1449                         ][..]
1450                 ).unwrap();
1451                 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1452
1453                 assert_eq!(invoice.recover_payee_pub_key(), Ok(::PayeePubKey(public_key)));
1454
1455                 let (raw_invoice, _, _) = invoice.into_parts();
1456                 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1457                         Ok(Secp256k1::new().sign_recoverable(hash, &private_key))
1458                 }).unwrap();
1459
1460                 assert!(new_signed.check_signature());
1461         }
1462
1463         #[test]
1464         fn test_builder_amount() {
1465                 use ::*;
1466
1467                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1468                         .description("Test".into())
1469                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1470                         .current_timestamp();
1471
1472                 let invoice = builder.clone()
1473                         .amount_pico_btc(15000)
1474                         .build_raw()
1475                         .unwrap();
1476
1477                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1478                 assert_eq!(invoice.hrp.raw_amount, Some(15));
1479
1480
1481                 let invoice = builder.clone()
1482                         .amount_pico_btc(1500)
1483                         .build_raw()
1484                         .unwrap();
1485
1486                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1487                 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1488         }
1489
1490         #[test]
1491         fn test_builder_fail() {
1492                 use ::*;
1493                 use std::iter::FromIterator;
1494                 use secp256k1::key::PublicKey;
1495
1496                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1497                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1498                         .current_timestamp()
1499                         .min_final_cltv_expiry(144);
1500
1501                 let too_long_string = String::from_iter(
1502                         (0..1024).map(|_| '?')
1503                 );
1504
1505                 let long_desc_res = builder.clone()
1506                         .description(too_long_string)
1507                         .build_raw();
1508                 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
1509
1510                 let route_hop = RouteHintHop {
1511                         src_node_id: PublicKey::from_slice(
1512                                         &[
1513                                                 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
1514                                                 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
1515                                                 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
1516                                         ][..]
1517                                 ).unwrap(),
1518                         short_channel_id: 0,
1519                         fees: RoutingFees {
1520                                 base_msat: 0,
1521                                 proportional_millionths: 0,
1522                         },
1523                         cltv_expiry_delta: 0,
1524                         htlc_minimum_msat: None,
1525                         htlc_maximum_msat: None,
1526                 };
1527                 let too_long_route = vec![route_hop; 13];
1528                 let long_route_res = builder.clone()
1529                         .description("Test".into())
1530                         .route(too_long_route)
1531                         .build_raw();
1532                 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
1533
1534                 let sign_error_res = builder.clone()
1535                         .description("Test".into())
1536                         .try_build_signed(|_| {
1537                                 Err("ImaginaryError")
1538                         });
1539                 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
1540         }
1541
1542         #[test]
1543         fn test_builder_ok() {
1544                 use ::*;
1545                 use secp256k1::Secp256k1;
1546                 use secp256k1::key::{SecretKey, PublicKey};
1547                 use std::time::{UNIX_EPOCH, Duration};
1548
1549                 let secp_ctx = Secp256k1::new();
1550
1551                 let private_key = SecretKey::from_slice(
1552                         &[
1553                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1554                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1555                                 0x3b, 0x2d, 0xb7, 0x34
1556                         ][..]
1557                 ).unwrap();
1558                 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
1559
1560                 let route_1 = vec![
1561                         RouteHintHop {
1562                                 src_node_id: public_key.clone(),
1563                                 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
1564                                 fees: RoutingFees {
1565                                         base_msat: 2,
1566                                         proportional_millionths: 1,
1567                                 },
1568                                 cltv_expiry_delta: 145,
1569                                 htlc_minimum_msat: None,
1570                                 htlc_maximum_msat: None,
1571                         },
1572                         RouteHintHop {
1573                                 src_node_id: public_key.clone(),
1574                                 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
1575                                 fees: RoutingFees {
1576                                         base_msat: 3,
1577                                         proportional_millionths: 2,
1578                                 },
1579                                 cltv_expiry_delta: 146,
1580                                 htlc_minimum_msat: None,
1581                                 htlc_maximum_msat: None,
1582                         }
1583                 ];
1584
1585                 let route_2 = vec![
1586                         RouteHintHop {
1587                                 src_node_id: public_key.clone(),
1588                                 short_channel_id: 0,
1589                                 fees: RoutingFees {
1590                                         base_msat: 4,
1591                                         proportional_millionths: 3,
1592                                 },
1593                                 cltv_expiry_delta: 147,
1594                                 htlc_minimum_msat: None,
1595                                 htlc_maximum_msat: None,
1596                         },
1597                         RouteHintHop {
1598                                 src_node_id: public_key.clone(),
1599                                 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
1600                                 fees: RoutingFees {
1601                                         base_msat: 5,
1602                                         proportional_millionths: 4,
1603                                 },
1604                                 cltv_expiry_delta: 148,
1605                                 htlc_minimum_msat: None,
1606                                 htlc_maximum_msat: None,
1607                         }
1608                 ];
1609
1610                 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
1611                         .amount_pico_btc(123)
1612                         .timestamp(UNIX_EPOCH + Duration::from_secs(1234567))
1613                         .payee_pub_key(public_key.clone())
1614                         .expiry_time(Duration::from_secs(54321))
1615                         .min_final_cltv_expiry(144)
1616                         .fallback(Fallback::PubKeyHash([0;20]))
1617                         .route(route_1.clone())
1618                         .route(route_2.clone())
1619                         .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
1620                         .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap());
1621
1622                 let invoice = builder.clone().build_signed(|hash| {
1623                         secp_ctx.sign_recoverable(hash, &private_key)
1624                 }).unwrap();
1625
1626                 assert!(invoice.check_signature().is_ok());
1627                 assert_eq!(invoice.tagged_fields().count(), 8);
1628
1629                 assert_eq!(invoice.amount_pico_btc(), Some(123));
1630                 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
1631                 assert_eq!(
1632                         invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1633                         1234567
1634                 );
1635                 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
1636                 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
1637                 assert_eq!(invoice.min_final_cltv_expiry(), 144);
1638                 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
1639                 assert_eq!(invoice.routes(), vec![&RouteHint(route_1), &RouteHint(route_2)]);
1640                 assert_eq!(
1641                         invoice.description(),
1642                         InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
1643                 );
1644                 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
1645
1646                 let raw_invoice = builder.build_raw().unwrap();
1647                 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
1648         }
1649
1650         #[test]
1651         fn test_default_values() {
1652                 use ::*;
1653                 use secp256k1::Secp256k1;
1654                 use secp256k1::key::SecretKey;
1655
1656                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
1657                         .description("Test".into())
1658                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1659                         .current_timestamp()
1660                         .build_raw()
1661                         .unwrap()
1662                         .sign::<_, ()>(|hash| {
1663                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
1664                                 let secp_ctx = Secp256k1::new();
1665                                 Ok(secp_ctx.sign_recoverable(hash, &privkey))
1666                         })
1667                         .unwrap();
1668                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
1669
1670                 assert_eq!(invoice.min_final_cltv_expiry(), DEFAULT_MIN_FINAL_CLTV_EXPIRY);
1671                 assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
1672         }
1673 }