Skip to main content

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}