Expand description
LNURLcash (LUD-25 draft) bearer notes: the money-critical logic, in one place.
A bearer note is an ordinary LUD-03 withdrawRequest link whose k1 IS the
asset:
lnurlw://mint.example/w?k1=<spend>&c=<cs1>Whoever holds the spend controls the sats behind it, like a banknote. Any
amount alongside it is only a claim by whoever encoded the note; the
authoritative value is always maxWithdrawable from an informational GET.
Every note is a BIP-341 taproot output key Q, named cp1<Q>, and a
spend opens it: a 64-hex preimage (the plain bearer note), a ck1 (its
key path) or a cw1 (a leaf of its script tree). See spend.
Every mutating operation is a GET on the callback from that
withdrawRequest, naming each resulting note by its cp1 or, for a bearer
note, its hash h:
callback?k1=X&pr=<bolt11> melt
callback?k1=X&p1=<h or cp1> rotate
callback?k1=X&amount=<msat>&p1=..&p2=.. split
callback?k1=X&k1=Y&p1=<h or cp1> merge§What this crate is for
It exists so there is exactly one audited implementation of the parts that lose money when they are wrong - ambiguous mutations, melt semantics, who generates a replacement secret, which end of a signature carries the recovery id - and so the mobile bindings are a wrapper over that rather than a fifth hand-written port drifting away from a draft spec.
§Amounts
Integers in milli-satoshis, everywhere, with no exceptions.
§Reference implementations
Both by dni, both MIT: lnurl-mint (the service) and lnurl-wallet (the wallet).
Re-exports§
pub use bolt11::decode_bolt11_amount_msat;pub use bolt11::is_bolt11_invoice;pub use bolt11::same_invoice;pub use errors::classify_note_error;pub use errors::Error;pub use errors::Result;pub use fees::apply_mint_fee;pub use fees::describe_mint_fee;pub use fees::format_fee_percent;pub use fees::gross_up_for_mint_fee;pub use fees::parse_mint_fee;pub use fees::MintFee;pub use note::build_note_url;pub use note::check_note_url;pub use note::is_valid_note_input;pub use note::note_declared_amount;pub use note::note_k1;pub use note::note_signature;pub use note::resolve_note_input;pub use note::with_new_k1;pub use note::without_k1;pub use protocol::InvoiceResult;pub use protocol::MeltState;pub use protocol::MintAddressInfo;pub use protocol::MutationResponse;pub use protocol::PayRequestInfo;pub use protocol::Request;pub use protocol::VerifyResult;pub use protocol::WithdrawRequestInfo;pub use protocol::MINT_COMMENT_LENGTH;pub use recoverable::note_id_of;pub use recoverable::note_lookup_of;pub use secrets::generate_note_secret;pub use secrets::hash_k1;pub use secrets::is_preimage;pub use signature::address_proof_digest;pub use signature::address_proof_message;pub use signature::check_note;pub use signature::check_note_certificate;pub use signature::note_signature_digest;pub use signature::note_signature_digest_for_hash;pub use signature::note_signature_message;pub use signature::note_signature_message_for_hash;pub use signature::sign_address_proof;pub use signature::verify_address_proof;pub use signature::verify_note_signature;pub use signature::verify_note_signature_hash;pub use signature::NoteCheck;pub use spend::check_spend;pub use spend::decode_note;pub use spend::decode_spend;pub use spend::spend_domain_of;pub use spend::SpendCheck;pub use spend::SpendVerdict;pub use urls::from_bech32_lnurl;pub use urls::from_lud17;pub use urls::is_allowed_service_url;pub use urls::is_bech32_lnurl;pub use urls::is_lightning_address;pub use urls::lightning_address_username;pub use urls::mint_address_url;pub use urls::resolve_lnurl_input;pub use urls::resolve_mint_input;pub use urls::server_of;pub use urls::to_bech32_lnurl;pub use urls::to_lud17w;
Modules§
- bolt11
- Only what a caller needs to bind a SERVICE’s response to the payment it asked for. No full TLV decode: the amount lives in the human-readable part, and equality is a normalised string compare.
- cash
- The
m/139'BIP-32 walk from a wallet’s seed down to oneSERVICE’s root, as LUD-26’s “Seed & derivation” specifies it: - errors
- The error taxonomy, which is the safety-critical part of this crate.
- fees
- LUD-25 mint fees (optional), and LUD-26’s address fee.
- note
- Note URLs: parsing what a note claims, and building the next one.
- protocol
- The protocol itself, with no I/O in it.
- recoverable
- LUD-25’s bech32m strings, key-path notes, and LUD-26’s seed tree they hang off.
- secrets
- Note secrets: where they come from, and what shape they are.
- signature
- LUD-25 offline verification, and the address-registration proof.
- spend
- LUD-25 spends: what opens a note, and what its signatures sign.
- urls
- Resolving user input to a URL, and deciding which URLs may be fetched.