lexe_payment_uri_core/lib.rs
1//! Core types and logic required to permissively parse Bitcoin / lightning
2//! payment addresses and URIs. For actually *resolving* a [`PaymentUri`] into a
3//! [`PaymentMethod`], which frequently requires accessing a network, see the
4//! `lexe-payment-uri` crate.
5//!
6//! # Permissive parsing
7//!
8//! This crate parses various BTC-related payment methods permissively.
9//! That means we accept inputs that are not strictly well-formed.
10//!
11//! Other wallet parsers for comparison:
12//! + [ACINQ/phoenix - Parser](https://github.com/ACINQ/phoenix/blob/master/phoenix-shared/src/commonMain/kotlin/fr.acinq.phoenix/utils/Parser.kt)
13//! + [breez/breez-sdk - input_parser.rs](https://github.com/breez/breez-sdk-greenlight/blob/main/libs/sdk-common/src/input_parser.rs)
14//! + [MutinyWallet/bitcoin_waila (unmaintained)](https://github.com/MutinyWallet/bitcoin-waila/blob/master/waila/src/lib.rs)
15//!
16//! # Prompts
17//!
18//! ```md
19//! Please read these URI parser impls:
20//! - `~/lexe/github/breez-sdk-greenlight/libs/sdk-common/src/input_parser.rs`
21//! - `~/lexe/github/phoenix/phoenix-shared/src/commonMain/kotlin/fr.acinq.phoenix/utils/Parser.kt` (and files nearby)
22//! - `~/lexe/github/bitcoin-waila/waila/src/lib.rs`
23//! ```
24//!
25//! [`PaymentUri`]: payment_uri::PaymentUri
26//! [`PaymentMethod`]: payment_method::PaymentMethod
27
28// `proptest_derive::Arbitrary` issue. This will hard-error for edition 2024 so
29// hopefully it gets fixed soon...
30// See: <https://github.com/proptest-rs/proptest/issues/447>
31#![allow(non_local_definitions)]
32
33use std::{
34 borrow::Cow,
35 fmt::{self, Display},
36};
37
38use lexe_api_core::types::{invoice, offer};
39
40/// Export all public types so they are accessible via the crate root.
41/// The containing modules are used only for internal organization, and are
42/// intentionally private so crate users have a simple, flat namespace.
43pub use crate::{
44 bip321_uri::Bip321Uri,
45 email_like::EmailLikeAddress,
46 lexe_link::{LexePayUrl, LexeUri},
47 lightning_uri::LightningUri,
48 lnurl::{
49 Lnurl, LnurlAuthAction, LnurlAuthRequest, LnurlScheme, LnurlTag,
50 LnurlWithdrawRequest, LnurlWithdrawRequestTag,
51 LnurlWithdrawRequestWire,
52 },
53 payment_method::{
54 AuthMethod, BestPaymentUriMethods, ClaimMethod, PaymentMethod,
55 PaymentUriMethod, PaymentUriMethods, PermittedMethods, Resolvable,
56 },
57 payment_uri::PaymentUri,
58};
59
60/// Helper functions and utilities; some of these are public.
61pub mod helpers;
62
63/// BIP321 / BIP21 parsing and formatting.
64mod bip321_uri;
65/// Email-like payment URIs, including Lightning Addresses and BIP353.
66mod email_like;
67/// Lexe links, which open a payment code directly in the Lexe app.
68mod lexe_link;
69/// "lightning:" URIs, containing a BOLT 11 invoice or BOLT12 offer.
70mod lightning_uri;
71/// LNURLs.
72mod lnurl;
73/// `PaymentMethod` and subtypes, representing a resolved payment method.
74mod payment_method;
75/// Top level `PaymentUri` representing a parsed payment URI or address.
76mod payment_uri;
77
78#[derive(Clone, Debug, PartialEq)]
79pub enum Error {
80 /// [`PaymentUri`] parsing errors.
81 InvalidPaymentUri(Cow<'static, str>),
82 /// [`Bip321Uri`] parsing errors.
83 InvalidBip321Uri(Cow<'static, str>),
84 /// [`LightningUri`] parsing errors.
85 InvalidLightningUri(Cow<'static, str>),
86 InvalidUri(lexe_uri::ParseError),
87 /// [`EmailLikeAddress`] parsing errors.
88 InvalidEmailLike(Cow<'static, str>),
89 InvalidLnurl(Cow<'static, str>),
90 InvalidLexeConnect(lexe_connect::request::RequestError),
91 InvalidInvoice(invoice::ParseError),
92 InvalidOffer(offer::ParseError),
93 InvalidBtcAddress(bitcoin::address::ParseError),
94}
95
96impl std::error::Error for Error {}
97
98impl From<lexe_uri::ParseError> for Error {
99 fn from(err: lexe_uri::ParseError) -> Self {
100 Self::InvalidUri(err)
101 }
102}
103
104impl fmt::Display for Error {
105 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
106 match self {
107 Self::InvalidUri(err) => err.fmt(f),
108 Self::InvalidPaymentUri(msg) =>
109 write!(f, "Invalid payment URI: {msg}"),
110 Self::InvalidBip321Uri(msg) =>
111 write!(f, "Invalid 'bitcoin:' URI: {msg}"),
112 Self::InvalidLightningUri(msg) =>
113 write!(f, "Invalid 'lightning:' URI: {msg}"),
114 Self::InvalidEmailLike(msg) =>
115 write!(f, "Invalid BIP353 / Lightning Address: {msg}"),
116 Self::InvalidLnurl(msg) => write!(f, "Invalid LNURL: {msg}"),
117 Self::InvalidLexeConnect(err) =>
118 write!(f, "Invalid LexeConnect request: {err}"),
119 Self::InvalidInvoice(err) => Display::fmt(err, f),
120 Self::InvalidOffer(err) => Display::fmt(err, f),
121 Self::InvalidBtcAddress(err) =>
122 write!(f, "Invalid on-chain address: {err}"),
123 }
124 }
125}