Add BIP21 Unified QR Code Support (#302)

* Add `UnifiedQrPayment` module for BIP21 URIs

Firstly, I thought I staged and made commits for `unified_qr.rs`
so sorry if this is out of order!

But in `unified_qr.rs` I
  - I introduced the `UnifiedQrPayment` struct to handle creating
    and paying BIP21 URIs
  - `receive` generates a URI with an on-chain address and BOLT11
     invoice and returns the URI as a string
  - `send` will parse a given URI string and attempt to send the
    BOLT12 offer, BOLT11 invoice, then if those fail the fallback
    on-chain address will be paid to.
  - Then I included tests for URI generation and URI parsing
  - Also has logging and error handling for payment operations

* Add `unified_qr_payment` payment handler to `Node`

  - implement unified_qr_payment method to create the
    Unified QR  payment handler
  - Includes conditional UniFFI features and updates docs
    with BIP21 and BOLT11 links

* Add support for `unified_qr` in payment mod

  - Included unified_qr in payment module
  - Added `PaymentResult` and `UnifiedQrPayment`
    from unified_qr for public use

* Add bip21 crate to handle BIP21 URIs

* Add `UnifiedQrPayment` and `PaymentResult` to `ldk_node.udl`

  - Introduced `UnifiedQrPayment` method to `Node` interface
  - Add `UnifiedQrPayment` interface with `receieve and
    `send` methods
  - Add `PaymentResult` interface (enum) with `Onchain`,
    `Bolt11` and `Bolt12` fields

These changes add support for our UniFFI bindings and enable
the use of `unified_qr_payment` payment handler in Swift,
and Kotlin.

* Update `Error` enum with URI related errors

  - Add `UriParameterFailed` and `InvalidUri` fields to
    the `Error` enum
  - Added related error  messages in the Display impl for
    the new fields

* Add `PaymentResult` import for UniFFI bindings

  - Added `PaymentResult` so the .udl could access
    the enum
  - Added comment to explain the need to import any
    re-exported items to enure they're accessible in
    UniFFI. (becasue rustc says to add them in `lib.rs`

* Add Unified QR `send`/`receive` integration tests

  - Added `unified_qr_send_receive` test to verify the `UnifedQrPayment`
    functionality
  - Added logic to handle paying a `BOLT12` offer, `BOLT11` invoice,
    and if those fail `On-chain` tx from a URI.
  - Validated each payments successful event
  - Ensured the off-chain and on-chain balacnes reflected the payment
    attempts

* Update PR with optimizations and nit fixups

The changes include:
  - Fixed a handful of nits for better readability in
    docs and simple grammar errors and made various name
    changes that affected the committed files.
  - Added a helper function in unified_qr.rs called
    capitalize_qr_params to format the lightning param in
    the receive method
  - Removed the optional message in the receive method and
    made it a required &str
  - Adjusted UDL formatting to use tabs instead of spaces

These changes were made to improve code quality and
maintainability based on the review feedback

* Refactor URI parsing and add Bolt12 offer in receive

Changes include:
  - Modified serialize_params to serialize both invoices and offers
  - Refactored deserialize_temp by removing the code that was
    parsing based on the lightning invoice/offer prefix. I instead
    used for loop to iterate over each lightning parameter,
    attempting to parse the string as an offer first, and then as an
    invoice. May need to log an error if neither succeeds
  - Added support for Bolt12 offers in the receive method
  - Updated capitalize_params function to handle multiple lightning
    parameters
  - Added a generate_bip21_uri test to show what the uri looks
    like in integration_tests_rust
  - Adjusted integration tests. Still needs work

Still trying to figure out a bug related to Bolt12 offers being
"paid" when it should fall back to an on-chain tx

* Update BOLT12 offer to use `lno` key

In this commit:
  - In serialize_params, BOLT12 offers were changed
    to be serialized with the `lno` key rather than
    the `lightning` key
  - During deserializing, I had to make the same update.
    Used a match to check whether it was a `lightning`
    or `lno` key and then parsed accordingly.
  - Next, a small name change: capitalize_qr_params to
    format_uri. Previously I changed the value after
    "&lightning" to all caps, but the "&lno=" value
    wasn't being changed. So, added a helper method inside
    format_uri to capitalize the values given the key!
  - Updated corresponding tests with `lno` update

Small nits:
  - Updated QrPaymentResult with more thorough docs
  - Added a parsing test with an offer

* Refactor for clarity and improve error handling

This commit fixes a handful of minor comments/nits
that include:
  - Updates to set the `bip21`  crates default-features to false,
    to minimize dependencies.
  - Enable the `std` feature since we use/benefit from it.

  - In `receive` return `InvoiceCreationFailed` or `OfferCreationFailed`
    when creating an invoice or offer. Rather than silently logging the
    error.
  - Also in `receive` we first check if an amount is specified, and if
    not, return an error and abort.
  - Pass in `Config` to `UnifiedQrPayment` struct to use the users config
    network.
  - In `send` instead of checking each network for the `NetworkChecked`
    URI, we pass in the `Config::Network`.
  - Simplifed param parsing in `deserialize_temp` by directly finding
    the key and parsing the corresponding value.

  - General documentation fixes.
  - In parsing tests, moved longer invoice/offer strings into.
    variables that start with expected_ for clarity.

* Fix docs for clarity

Cleaned up the docs so they are easier to understand for the
user. Also changed the message param in receive to description.

Author: slanesuke

Cargo.toml

@@ -61,6 +61,7 @@ reqwest = { version = "0.11", default-features = false, features = ["json", "rus
 rusqlite = { version = "0.28.0", features = ["bundled"] }
 bitcoin = "0.30.2"
 bip39 = "2.0.0"
+bip21 = { version = "0.3.1", features = ["std"], default-features = false }
 
 rand = "0.8.5"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }

bindings/ldk_node.udl

@@ -63,6 +63,7 @@ interface Node {
 	Bolt12Payment bolt12_payment();
 	SpontaneousPayment spontaneous_payment();
 	OnchainPayment onchain_payment();
+	UnifiedQrPayment unified_qr_payment();
 	[Throws=NodeError]
 	void connect(PublicKey node_id, SocketAddress address, boolean persist);
 	[Throws=NodeError]
@@ -148,6 +149,13 @@ interface OnchainPayment {
 	Txid send_all_to_address([ByRef]Address address);
 };
 
+interface UnifiedQrPayment {
+    [Throws=NodeError]
+    string receive(u64 amount_sats, [ByRef]string message, u32 expiry_sec);
+    [Throws=NodeError]
+    QrPaymentResult send([ByRef]string uri_str);
+};
+
 [Error]
 enum NodeError {
 	"AlreadyRunning",
@@ -175,6 +183,7 @@ enum NodeError {
 	"GossipUpdateFailed",
 	"GossipUpdateTimeout",
 	"LiquidityRequestFailed",
+	"UriParameterParsingFailed",
 	"InvalidAddress",
 	"InvalidSocketAddress",
 	"InvalidPublicKey",
@@ -191,6 +200,7 @@ enum NodeError {
 	"InvalidRefund",
 	"InvalidChannelId",
 	"InvalidNetwork",
+	"InvalidUri",
 	"DuplicatePayment",
 	"UnsupportedCurrency",
 	"InsufficientFunds",
@@ -276,6 +286,13 @@ interface PaymentKind {
 	Spontaneous(PaymentHash hash, PaymentPreimage? preimage);
 };
 
+[Enum]
+interface QrPaymentResult {
+    Onchain(Txid txid);
+    Bolt11(PaymentId payment_id);
+    Bolt12(PaymentId payment_id);
+};
+
 enum PaymentDirection {
 	"Inbound",
 	"Outbound",

src/error.rs

@@ -53,6 +53,8 @@ pub enum Error {
 	GossipUpdateTimeout,
 	/// A liquidity request operation failed.
 	LiquidityRequestFailed,
+	/// Parsing a URI parameter has failed.
+	UriParameterParsingFailed,
 	/// The given address is invalid.
 	InvalidAddress,
 	/// The given network address is invalid.
@@ -85,6 +87,8 @@ pub enum Error {
 	InvalidChannelId,
 	/// The given network is invalid.
 	InvalidNetwork,
+	/// The given URI is invalid.
+	InvalidUri,
 	/// A payment with the given hash has already been initiated.
 	DuplicatePayment,
 	/// The provided offer was denonminated in an unsupported currency.
@@ -131,6 +135,7 @@ impl fmt::Display for Error {
 			Self::GossipUpdateFailed => write!(f, "Failed to update gossip data."),
 			Self::GossipUpdateTimeout => write!(f, "Updating gossip data timed out."),
 			Self::LiquidityRequestFailed => write!(f, "Failed to request inbound liquidity."),
+			Self::UriParameterParsingFailed => write!(f, "Failed to parse a URI parameter."),
 			Self::InvalidAddress => write!(f, "The given address is invalid."),
 			Self::InvalidSocketAddress => write!(f, "The given network address is invalid."),
 			Self::InvalidPublicKey => write!(f, "The given public key is invalid."),
@@ -147,6 +152,7 @@ impl fmt::Display for Error {
 			Self::InvalidRefund => write!(f, "The given refund is invalid."),
 			Self::InvalidChannelId => write!(f, "The given channel ID is invalid."),
 			Self::InvalidNetwork => write!(f, "The given network is invalid."),
+			Self::InvalidUri => write!(f, "The given URI is invalid."),
 			Self::DuplicatePayment => {
 				write!(f, "A payment with the given hash has already been initiated.")
 			},

src/lib.rs

@@ -133,7 +133,10 @@ use gossip::GossipSource;
 use graph::NetworkGraph;
 use liquidity::LiquiditySource;
 use payment::store::PaymentStore;
-use payment::{Bolt11Payment, Bolt12Payment, OnchainPayment, PaymentDetails, SpontaneousPayment};
+use payment::{
+	Bolt11Payment, Bolt12Payment, OnchainPayment, PaymentDetails, SpontaneousPayment,
+	UnifiedQrPayment,
+};
 use peer_store::{PeerInfo, PeerStore};
 use types::{
 	Broadcaster, BumpTransactionEventHandler, ChainMonitor, ChannelManager, DynStore, FeeEstimator,
@@ -1072,6 +1075,40 @@ impl Node {
 		))
 	}
 
+	/// Returns a payment handler allowing to create [BIP 21] URIs with an on-chain, [BOLT 11],
+	/// and [BOLT 12] payment options.
+	///
+	/// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
+	/// [BOLT 12]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md
+	/// [BIP 21]: https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
+	#[cfg(not(feature = "uniffi"))]
+	pub fn unified_qr_payment(&self) -> UnifiedQrPayment {
+		UnifiedQrPayment::new(
+			self.onchain_payment().into(),
+			self.bolt11_payment().into(),
+			self.bolt12_payment().into(),
+			Arc::clone(&self.config),
+			Arc::clone(&self.logger),
+		)
+	}
+
+	/// Returns a payment handler allowing to create [BIP 21] URIs with an on-chain, [BOLT 11],
+	/// and [BOLT 12] payment options.
+	///
+	/// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
+	/// [BOLT 12]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md
+	/// [BIP 21]: https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
+	#[cfg(feature = "uniffi")]
+	pub fn unified_qr_payment(&self) -> Arc<UnifiedQrPayment> {
+		Arc::new(UnifiedQrPayment::new(
+			self.onchain_payment(),
+			self.bolt11_payment(),
+			self.bolt12_payment(),
+			Arc::clone(&self.config),
+			Arc::clone(&self.logger),
+		))
+	}
+
 	/// Retrieve a list of known channels.
 	pub fn list_channels(&self) -> Vec<ChannelDetails> {
 		self.channel_manager.list_channels().into_iter().map(|c| c.into()).collect()

src/payment/mod.rs

@@ -5,9 +5,11 @@ mod bolt12;
 mod onchain;
 mod spontaneous;
 pub(crate) mod store;
+mod unified_qr;
 
 pub use bolt11::Bolt11Payment;
 pub use bolt12::Bolt12Payment;
 pub use onchain::OnchainPayment;
 pub use spontaneous::SpontaneousPayment;
 pub use store::{LSPFeeLimits, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus};
+pub use unified_qr::{QrPaymentResult, UnifiedQrPayment};