Skip to main content

Crate lnurlcash_core

Crate lnurlcash_core 

Source
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 one SERVICE’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.