lnurlcash_core/lib.rs
1//! LNURLcash ([LUD-25 draft](https://github.com/lnurl/luds/pull/301)) bearer
2//! notes: the money-critical logic, in one place.
3//!
4//! A bearer note is an ordinary LUD-03 withdrawRequest link whose `k1` IS the
5//! asset:
6//!
7//! ```text
8//! lnurlw://mint.example/w?k1=<spend>&c=<cs1>
9//! ```
10//!
11//! Whoever holds the spend controls the sats behind it, like a banknote. Any
12//! `amount` alongside it is only a claim by whoever encoded the note; the
13//! authoritative value is always `maxWithdrawable` from an informational GET.
14//!
15//! Every note is a BIP-341 taproot output key `Q`, named `cp1<Q>`, and a
16//! spend opens it: a 64-hex preimage (the plain bearer note), a `ck1` (its
17//! key path) or a `cw1` (a leaf of its script tree). See [`spend`].
18//!
19//! Every mutating operation is a GET on the `callback` from that
20//! withdrawRequest, naming each resulting note by its `cp1` or, for a bearer
21//! note, its hash `h`:
22//!
23//! ```text
24//! callback?k1=X&pr=<bolt11> melt
25//! callback?k1=X&p1=<h or cp1> rotate
26//! callback?k1=X&amount=<msat>&p1=..&p2=.. split
27//! callback?k1=X&k1=Y&p1=<h or cp1> merge
28//! ```
29//!
30//! # What this crate is for
31//!
32//! It exists so there is exactly one audited implementation of the parts that
33//! lose money when they are wrong - ambiguous mutations, melt semantics, who
34//! generates a replacement secret, which end of a signature carries the
35//! recovery id - and so the mobile bindings are a wrapper over that rather than
36//! a fifth hand-written port drifting away from a draft spec.
37//!
38//! # Amounts
39//!
40//! Integers in milli-satoshis, everywhere, with no exceptions.
41//!
42//! # Reference implementations
43//!
44//! Both by dni, both MIT:
45//! [lnurl-mint](https://github.com/dni/lnurl-mint) (the service) and
46//! [lnurl-wallet](https://github.com/dni/lnurl-wallet) (the wallet).
47
48#![forbid(unsafe_code)]
49#![warn(missing_debug_implementations)]
50
51pub mod bolt11;
52pub mod cash;
53#[cfg(feature = "client")]
54pub mod client;
55pub mod errors;
56#[cfg(feature = "ffi")]
57pub mod ffi;
58
59// The UniFFI scaffolding has to be generated at the crate root, so it lives
60// here even though everything it exports is defined in `ffi`.
61#[cfg(feature = "ffi")]
62uniffi::setup_scaffolding!();
63pub mod fees;
64mod long_bech32;
65pub mod note;
66pub mod protocol;
67pub mod recoverable;
68pub mod secrets;
69pub mod signature;
70pub mod spend;
71pub mod urls;
72
73pub use bolt11::{decode_bolt11_amount_msat, is_bolt11_invoice, same_invoice};
74pub use errors::{classify_note_error, Error, Result};
75pub use fees::{
76 apply_mint_fee, describe_mint_fee, format_fee_percent, gross_up_for_mint_fee, parse_mint_fee,
77 MintFee,
78};
79pub use note::{
80 build_note_url, check_note_url, is_valid_note_input, note_declared_amount, note_k1,
81 note_signature, resolve_note_input, with_new_k1, without_k1,
82};
83pub use protocol::{
84 InvoiceResult, MeltState, MintAddressInfo, MutationResponse, PayRequestInfo, Request,
85 VerifyResult, WithdrawRequestInfo, MINT_COMMENT_LENGTH,
86};
87pub use recoverable::{note_id_of, note_lookup_of};
88pub use secrets::{generate_note_secret, hash_k1, is_preimage};
89pub use signature::{
90 address_proof_digest, address_proof_message, check_note, check_note_certificate,
91 note_signature_digest, note_signature_digest_for_hash, note_signature_message,
92 note_signature_message_for_hash, sign_address_proof, verify_address_proof,
93 verify_note_signature, verify_note_signature_hash, NoteCheck,
94};
95pub use spend::{
96 check_spend, decode_note, decode_spend, spend_domain_of, SpendCheck, SpendVerdict,
97};
98pub use urls::{
99 from_bech32_lnurl, from_lud17, is_allowed_service_url, is_bech32_lnurl, is_lightning_address,
100 lightning_address_username, mint_address_url, resolve_lnurl_input, resolve_mint_input,
101 server_of, to_bech32_lnurl, to_lud17w,
102};
103
104#[cfg(feature = "client")]
105pub use client::{Client, ClientConfig, NoteFate};