lnurlcash-kit 0.1.2 → 0.2.1

package/README.md

@@ -122,6 +122,31 @@ This is not hypothetical: the same hazard broke the
 development, by two different mechanisms, and is now a named scenario in the
 conformance vectors.
 
+Because a retry cannot always be prevented, a mutation refused with the
+input already spent or unknown carries its outputs anyway:
+
+```ts
+try {
+  await rotateNote(callback, oldK1)
+} catch (err) {
+  const secrets = newSecretsOf(err)   // works on both error families
+  if (secrets.length) {
+    await save(secrets)               // first. always.
+    // then ask: is there a note at that secret?
+    const fate = await probeBurnedNote(buildNoteUrl(base, secrets[0]))
+    // 'live' -> the mutation landed and you own the output
+    // 'gone' -> the refusal was honest, discard
+  }
+}
+```
+
+The class does not change: at the wire a retry and a genuine double spend are
+the same answer, and whether your input was live when the request went out is
+something you know and this library does not. So it hands back the secret
+rather than a verdict. A refusal that cannot be a landed mutation, such as a
+mint refusing on policy grounds, carries nothing, and you can discard your
+staged records at once.
+
 **4. A melt's `OK` means "in flight", not "spent".** The service pays
 asynchronously and only burns the note once the payment settles, restoring
 it if the payment fails. A failed melt is never reported back through the
@@ -136,6 +161,12 @@ who saw the unpaid invoice can poll for it — the payment hash travels inside
 the invoice. First rotater wins. A wallet that rotates on settlement wins by
 construction; a human copying a preimage by hand does not.
 
+That is a race, and the way to win a race is not to enter it. Where a mint
+advertises `mintToHash`, name the note you are buying and the preimage is
+not its secret at all: see
+[Minting a note you named yourself](#minting-a-note-you-named-yourself).
+The rule above stands for every mint that does not offer it.
+
 ## Offline verification
 
 A service may sign each note with its Lightning node identity key, so a
@@ -156,6 +187,289 @@ The signature commits to the note's *hash*, not its secret — so you can
 prove a mint issued a note, to expose one that will not honour it, without
 handing over what would let anyone spend it.
 
+### When a mint rotates its signing key
+
+Rotating invalidates nothing. The notes already issued are still genuine and
+their signatures still verify, but only against the key that made them, so a
+wallet holding the new key alone would suddenly read every outstanding note
+as forged. A mint publishes the keys it has retired as `previousPubkeys` on
+its mint address, and verification takes the whole set:
+
+```ts
+const {mintPubkey, previousPubkeys = []} = await fetchMintAddress(addressUrl)
+const check = verifyNoteSignatureAgainst(k1, amountMsat, sig, [
+  mintPubkey,
+  ...previousPubkeys
+])
+// check.pubkey names the key that signed. A note that verifies only against
+// a retired one is worth rotating: the mint re-signs it under the current key.
+```
+
+`verifyNoteSignature` takes the same one-or-many argument and returns a plain
+boolean. An empty list is a rejection, not a pass.
+
+### What else a mint says about itself
+
+`mintPubkey` is the key note signatures verify against, and it is *not* the
+Lightning node's key: that one is embedded in `nodeUri`, and every other
+`node*` field really is about the node. Verifying a note against the key
+pulled out of `nodeUri` fails, and the failure says nothing about why.
+`nodePubkey` is a deprecated alias for the same value, kept for one release.
+
+`fetchMintAddress` reads the experimental discovery endpoint, and a mint may
+publish a `name`, a `description`, `contact` details, a `tosUrl`, a `motd`,
+its structured `fees` and its software `version` there. All optional, all
+absent on most mints, and none of it is needed to spend a note. Surface the
+MOTD when it changes: it is how an operator announces maintenance, a fee
+change or a sunset date, and there is no other channel to a bearer holder.
+The endpoint carries no LUD number, so treat a rejection as "no extra
+information" and fall back to `fetchPayRequest`.
+
+## Secrets
+
+A note's `k1` is generated by the wallet, and LUD-25 says nothing about how.
+Draw it from a CSPRNG and the note lives only in your wallet file: the mint
+holds `sha256(k1)` and cannot tell you apart from a stranger, so a lost file
+is lost money. Derive it from a seed instead and the wallet restores from
+words alone.
+
+```
+root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed)
+k1_i = HMAC-SHA256(key = root,                      msg = utf8(host + ":" + index))
+```
+
+`seed` is raw bytes. A 64-byte BIP39 seed is what wallets use in practice,
+but nothing here depends on BIP39, so a device with its own entropy store
+derives the same way and no consumer carries a wordlist it does not need.
+`host` is the mint host exactly as `serverOf` spells it, lowercase and with
+the port where there is one, so `127.0.0.1:8899` and `mint.example` never
+collide. `index` is decimal ASCII from 0. The output is 32 bytes of hex, the
+size of a payment preimage, and the mint sees nothing different: it only
+ever receives `sha256(k1)`.
+
+Because the scheme is written down here rather than invented per wallet, the
+same words restore the same notes in a *different* wallet. That
+cross-wallet portability is the point of putting it in the kit, with
+[a conformance vector](https://github.com/TheCryptoDonkey/lnurlcash-conformance)
+for the ports.
+
+```ts
+import {deriveNoteRoot, derivedSecretSource, restoreNotes} from 'lnurlcash-kit'
+
+const root = deriveNoteRoot(seed)          // seed: Uint8Array, yours to keep safe
+const source = derivedSecretSource(root, 'mint.example', counter)
+
+// hand it to any mutating call and the fresh secrets come from the seed
+const {k1, change} = await splitNote(callback, [note], 40_000, {randomSecret: source})
+saveCounter('mint.example', source.index())  // a split consumed two indices
+```
+
+Persist that counter in the **same write that stages the new records**, and
+do it **before** the hash goes on the wire. A crash between the bump and the
+request wastes an index, which costs nothing. A crash the other way round
+re-derives a secret the mint has already seen, and the second note minted at
+it collides with the first. This is the rule wallets get wrong.
+
+Restoring walks the indices and asks the mint what each derived secret is
+worth:
+
+```ts
+const {found, next} = await restoreNotes('https://mint.example/w', root, 'mint.example')
+```
+
+A live note is recorded, a spent index still counts as used (re-deriving it
+would mint a duplicate), an unknown one counts towards the gap, and the walk
+stops after 20 consecutive unknowns. `next` is the counter to resume from.
+Restoring puts every `k1` it walks on the wire and a restored note carries no
+signature, so rotate each one straight after: that closes the exposure and
+gets the signature in the same call.
+
+The seed is bearer material for every note the wallet will ever hold. Store
+it the way you store the notes, and never log it.
+
+## Minting a note you named yourself
+
+By default the secret of a freshly minted note is the invoice's payment
+preimage, which means the money is a thing two sets of people learn without
+being trusted. Every routing node on the payment path sees it, because that
+is how HTLC settlement works. And anyone who merely saw the unpaid invoice
+can poll LUD-21 `verify` with the payment hash inside it and take the
+preimage the moment it settles, which is what a QR code on a desktop screen
+hands out.
+
+A mint can instead bind the note to a hash you supply, the same `h` you
+already send on every rotate, split and merge. Then you chose the secret,
+nobody else ever had it, and the preimage is an ordinary payment proof.
+
+```ts
+import {
+  fetchPayRequest, requestInvoice, claimMintedNote,
+  deriveNoteRoot, deriveNoteSecret, hashK1
+} from 'lnurlcash-kit'
+
+const pay = await fetchPayRequest(payUrl)      // a Lightning Address resolves here
+if (!pay.mintToHash) { /* preimage path, rotate on claim */ }
+
+const root = deriveNoteRoot(seed)
+const k1 = deriveNoteSecret(root, 'mint.example', nextIndex)
+await persist({k1, index: nextIndex})          // BEFORE the invoice. always.
+
+const {pr} = await requestInvoice(pay.callback, 21_000, {h: hashK1(k1)})
+
+// pay `pr`, then poll. No verify, because you already know the secret.
+const claim = await claimMintedNote(pay.withdrawLink!, k1)
+// 'unminted' -> not settled yet, ask again
+// 'minted'   -> claim.amountMsat is what it is worth, claim.callback melts it
+```
+
+Ask before you buy. `mintToHash` is how a mint says it accepts the parameter,
+and reading it first is the difference between naming your own note and paying
+for one whose secret three other parties can learn. It turns up in three
+places, saying three different things:
+
+| Where | What it means |
+| --- | --- |
+| `PayRequestInfo.mintToHash` | "I accept an `h`." **Decide from this one.** |
+| `MintAddressInfo.mintToHash` | the same fact on the experimental discovery document |
+| `InvoiceResult.mintToHash` | "I bound *this quote* to the hash you named" |
+
+Prefer the payRequest: it is the only endpoint every mint has, it is where
+your wallet already is when it is about to mint, and it sits next to the
+`withdrawLink` the draft already hangs there for LNURLcash's sake. Fall back
+to `fetchMintAddress` for a mint that only advertises on that document. A mint
+that says it in neither place ignores the `h`, keys the note by the preimage
+as it always has, and the verify path is unchanged. Anything that is not
+exactly `true` is a no, everywhere, and `false` on the invoice result is
+silence rather than a refusal, so decide from the advertisement and claim by
+probing.
+
+**Persist the secret before you ask for the invoice.** Paying for a note and
+then losing the secret is the one way this is worse than the preimage scheme,
+and persisting first removes it. Derive it rather than drawing it at random
+and there is a second reason: the note is then seed-derived *from birth*, so
+`restoreNotes` finds it without any rotate having happened. Under the preimage
+scheme a minted note lives outside your derivation until the immediate rotate
+pulls it in, and a wallet that crashes in that window cannot recover the note
+from its words.
+
+No rotate follows a bound claim. The preimage scheme needs one because the
+mint made the secret and hands it out; here the mint never had it, so the note
+is yours from the moment it exists. The claim GET does show the secret to the
+mint it is a claim on, which is a different thing from showing it to whoever
+scanned the QR, and you can still rotate if you want the offline signature.
+
+## Asking to be paid
+
+"Send me 500 sat" today means handing over a Lightning Address, which is a
+mint-and-zap round trip through the mint's node for something neither party
+needed a node for. A payment request names the amount, the mints the payee
+will accept and where to deliver, and the payer's wallet splits a note and
+sends it straight across. Wallet to wallet; the mint only ever sees a split.
+
+```ts
+import {encodePaymentRequest, decodePaymentRequest, paymentRequestAmountMsat} from 'lnurlcash-kit'
+
+const encoded = encodePaymentRequest({
+  v: 1,
+  id: '0123456789abcdef',            // 8 random bytes, hex
+  amount: '500',                     // whole sats, decimal string
+  currency: 'sat',
+  methodDetails: {mints: ['mint.example']},
+  to: 'npub1...',                    // or alice@mint.example
+  memo: 'lunch'
+})
+// lnurlcashreq1eyJhbW91bnQiOiI1MDAiLCJjdXJyZW5jeSI6InNhdCIsImlkIjoiMDEy...
+
+const request = decodePaymentRequest(scanned)   // throws ProtocolError if it is not one
+const owed = paymentRequestAmountMsat(request)  // 500_000
+```
+
+The encoding is `lnurlcashreq1` followed by base64url of the request as
+[JCS](https://www.rfc-editor.org/rfc/rfc8785)-canonical JSON, which is
+NUT-18's `creqA` idiom with our own prefix. Canonical because a request is a
+thing people copy, quote back and match against a record of what they asked
+for: two encodings of the same request must be the same string, or none of
+that works. It stays short enough for one static QR.
+
+The object is the same charge request an HTTP 402 lnurlcash rail serves,
+plus the transport fields a wallet-to-wallet send needs, so one encoder
+covers both. Validation is strict in both directions, including an
+unrecognised field: quietly paying a request you did not fully understand is
+how you pay the wrong person.
+
+`amount` is in **sat**, and it is the one exception to this library's
+msat-everywhere rule. That is deliberate: the field is shared with the 402
+rail and the Cashu payment method, both of which count in whole units. Use
+`paymentRequestAmountMsat` rather than multiplying by hand.
+
+An expired request will not decode, because paying one is always wrong. At
+the expiry counts as expired, not merely past it, so a payer whose clock is a
+second behind the payee's does not send a note against a request the payee
+has already written off. `isPaymentRequest` still returns true for it, so a
+scanner routes it to the pay screen and the user is told it lapsed rather
+than that their input was gibberish; `decodePaymentRequest(input, {now: 0})`
+returns it for display.
+
+`to` is checked, not merely shape-matched: an npub has to survive its bech32
+checksum, because a request naming a destination nobody can route to is a
+request nobody can pay.
+
+**`lnurlcashreq1` means this schema and nothing else.** An earlier HTTP 402
+rail emitted a shorter object under the same prefix (`{"a": 21, "m":
+["mint.example"], "u": "sat"}`: amount as a number, no version, no id). Two
+schemas under one prefix cannot both be right, and this is the one the
+vectors pin. The decoder reads the short form anyway, because refusing a
+string it can plainly understand helps nobody, and gives it a deterministic
+id derived from its own bytes. Nothing here ever emits it.
+
+## Taking a note as payment
+
+A server that accepts bearer notes for something makes the same decisions
+every time, in this order, and `settleNoteForValue` is that order written
+once:
+
+```ts
+import {settleNoteForValue, InsufficientValueError} from 'lnurlcash-kit'
+
+try {
+  const {note, newUrl} = await settleNoteForValue(offered, {
+    mints: ['mint.example'],   // hosts this server accepts. An empty list accepts nothing.
+    minMsat: 21_000,           // the price
+    requireSignature: false    // demand offline proof of issuance first
+  })
+  grantAccess()                // note.k1 is yours now; newUrl is a note to store or melt
+} catch (err) {
+  if (err instanceof InsufficientValueError) refuse(err.amountMsat, err.minMsat)
+  else refuse()
+}
+```
+
+1. the input parses as a note at all
+2. its mint is one this server accepts (checked before any round trip, so an
+   unaccepted mint is never contacted)
+3. an informational GET for the **authoritative** value and the mint's key
+4. the signature, where the server demands one, over the value the mint
+   stated rather than the one the URL claims
+5. that value covers the price
+6. **rotate**
+
+Step 6 is the settlement, not bookkeeping after it. Rotating burns the
+secret the payer handed over and mints a replacement only this server knows,
+in one atomic request: it transfers ownership and rejects a replay in the
+same call, because a second presentation of the same note finds it spent. A
+server that checks a note's value and grants access without rotating has
+verified a photograph of a banknote.
+
+Refusals are typed, and nothing is burned by any of them: `ServiceRejectedError`
+for an unaccepted mint or a signature that will not verify,
+`InsufficientValueError` (carrying both amounts) for a note worth too
+little, `NoteSpentError` for one already spent or presented twice,
+`PendingNoteError` for one with a melt in flight, which is worth retrying
+rather than refusing outright. `AmbiguousMutationError` from the rotate is
+the case to handle with care: persist `err.newSecrets` before anything else,
+because if the request landed then that secret is the money and it is now
+this server's.
+
 ## Scope
 
 This library speaks the protocol. It does not store notes, hold keys, manage

package/dist/index.d.ts

@@ -1,34 +1,19 @@
-declare const isBech32Lnurl: (data: string) => boolean;
-declare const toBech32Lnurl: (url: string) => string;
-declare const fromBech32Lnurl: (data: string) => string | null;
-declare const isAllowedServiceUrl: (value: string) => boolean;
-declare const fromLud17: (url: string) => string;
-declare const toLud17w: (url: string) => string;
-declare const isLightningAddress: (value: string) => boolean;
-declare const resolveMintInput: (value: string) => string | null;
-declare const mintAddressUrl: (payUrl: string) => string | null;
-declare const lightningAddressUsername: (payUrl: string) => string | null;
-declare const resolveLnurlInput: (value: string) => string | null;
-declare const serverOf: (url: string) => string;
-
-declare const noteK1: (url: string) => string | null;
-declare const requireNoteK1: (url: string) => string;
-declare const noteDeclaredAmount: (url: string) => number | null;
-declare const noteSignature: (url: string) => string | null;
-declare const resolveNoteInput: (value: string) => string | null;
-declare const isValidNoteInput: (value: string) => boolean;
-declare const buildNoteUrl: (withdrawLink: string, k1: string, amountMsat?: number) => string;
-declare const withNewK1: (url: string, k1: string, amountMsat: number, signature?: string) => string;
-declare const withoutK1: (url: string, amountMsat: number, signature?: string) => string;
-
 declare const hashK1: (k1: string) => string;
 type RandomSecret = () => string;
 declare const defaultRandomSecret: RandomSecret;
 declare const isPreimage: (value: string) => boolean;
+declare const deriveNoteRoot: (seed: Uint8Array) => Uint8Array;
+declare const deriveNoteSecret: (root: Uint8Array, host: string, index: number) => string;
+declare const derivedSecretSource: (root: Uint8Array, host: string, start?: number) => RandomSecret & {
+    index: () => number;
+};
 
-declare const noteSignatureMessage: (k1: string, amountMsat: number) => string;
-declare const noteSignatureDigest: (k1: string, amountMsat: number) => Uint8Array;
-declare const verifyNoteSignature: (k1: string, amountMsat: number, signatureHex: string, mintPubkeyHex: string) => boolean;
+type LnurlcashOptions = {
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    offline?: boolean;
+    randomSecret?: RandomSecret;
+};
 
 type MintFee = {
     baseFeeMsat: number;
@@ -46,45 +31,6 @@ declare const grossUpForMintFee: (netMsat: number, fee: MintFee) => number;
 declare const formatFeePercent: (ppm: number) => string;
 declare const describeMintFee: (fee: MintFee) => string;
 
-declare const isBolt11Invoice: (value: string) => boolean;
-declare const sameInvoice: (a: string, b: string) => boolean;
-declare const decodeBolt11AmountMsat: (pr: string) => number | null;
-
-declare class LnurlcashError extends Error {
-    constructor(message: string);
-}
-declare class RequestRefusedError extends LnurlcashError {
-}
-declare class ProtocolError extends LnurlcashError {
-}
-declare class ServiceRejectedError extends LnurlcashError {
-    readonly reason: string;
-    constructor(reason: string);
-}
-declare class PendingNoteError extends ServiceRejectedError {
-    constructor(reason?: string);
-}
-declare class NoteSpentError extends ServiceRejectedError {
-    constructor(reason: string);
-}
-declare class NoteUnknownError extends ServiceRejectedError {
-    constructor(reason: string);
-}
-declare class AmbiguousMintError extends LnurlcashError {
-}
-declare class AmbiguousMutationError extends AmbiguousMintError {
-    readonly newSecrets: string[];
-    constructor(message: string, newSecrets: string[]);
-}
-declare const classifyNoteError: (reason: string) => ServiceRejectedError;
-
-type LnurlcashOptions = {
-    fetch?: typeof globalThis.fetch;
-    timeoutMs?: number;
-    offline?: boolean;
-    randomSecret?: RandomSecret;
-};
-
 type WithdrawRequestInfo = {
     tag: 'withdrawRequest';
     callback: string;
@@ -93,15 +39,22 @@ type WithdrawRequestInfo = {
     maxWithdrawable: number;
     defaultDescription?: string;
     mintPubkey?: string;
+    payLink?: string;
 };
 declare const fetchNoteInfo: (url: string, options?: LnurlcashOptions) => Promise<WithdrawRequestInfo>;
 declare const probeBurnedNote: (url: string, options?: LnurlcashOptions) => Promise<"live" | "gone" | "unknown">;
+type MintContact = {
+    nostr?: string;
+    email?: string;
+    url?: string;
+};
 type MintAddressInfo = {
     tag: 'withdrawRequest';
     callback: string;
     minWithdrawable: number;
     maxWithdrawable: number;
     defaultDescription?: string;
+    mintPubkey?: string;
     nodePubkey?: string;
     payLink: string;
     nodeAlias?: string;
@@ -110,6 +63,15 @@ type MintAddressInfo = {
     nodeCapacityMsat?: number;
     nodeNumChannels?: number;
     nodeNumPeers?: number;
+    name?: string;
+    description?: string;
+    contact?: MintContact;
+    tosUrl?: string;
+    motd?: string;
+    fees?: MintFee;
+    version?: string;
+    previousPubkeys?: string[];
+    mintToHash?: boolean;
 };
 declare const fetchMintAddress: (url: string, options?: LnurlcashOptions) => Promise<MintAddressInfo>;
 type WithdrawSuccessResponse = {
@@ -163,20 +125,156 @@ type PayRequestInfo = {
     withdrawLink?: string;
     mintPubkey?: string;
     mintFee?: MintFee;
+    mintToHash?: boolean;
 };
 declare const fetchPayRequest: (url: string, options?: LnurlcashOptions) => Promise<PayRequestInfo>;
 type InvoiceResult = {
     pr: string;
     verify?: string;
     disposable: boolean;
+    mintToHash: boolean;
+};
+type InvoiceRequestOptions = LnurlcashOptions & {
+    h?: string;
 };
-declare const requestInvoice: (payCallback: string, amountMsat: number, options?: LnurlcashOptions) => Promise<InvoiceResult>;
+declare const requestInvoice: (payCallback: string, amountMsat: number, options?: InvoiceRequestOptions) => Promise<InvoiceResult>;
 type VerifyResult = {
     settled: boolean;
     preimage: string | null;
     pr: string;
 };
 declare const fetchInvoiceVerification: (verifyUrl: string, options?: LnurlcashOptions) => Promise<VerifyResult>;
+type MintClaim = {
+    state: 'minted' | 'unminted' | 'pending' | 'spent';
+    k1: string;
+    amountMsat: number | null;
+    callback: string | null;
+};
+declare const claimMintedNote: (withdrawLink: string, k1: string, options?: LnurlcashOptions) => Promise<MintClaim>;
+
+type SettleForValueOptions = {
+    mints: string[];
+    minMsat: number;
+    requireSignature?: boolean;
+};
+type SettledForValue = {
+    note: SettledNote;
+    newUrl: string;
+};
+declare const settleNoteForValue: (noteUrl: string, { mints, minMsat, requireSignature }: SettleForValueOptions, options?: LnurlcashOptions) => Promise<SettledForValue>;
+
+type RestoredNote = {
+    index: number;
+    k1: string;
+    amountMsat: number | null;
+    state: 'live' | 'pending';
+};
+type RestoreResult = {
+    found: RestoredNote[];
+    next: number;
+};
+type RestoreOptions = {
+    gap?: number;
+    start?: number;
+};
+declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
+
+declare const isBech32Lnurl: (data: string) => boolean;
+declare const toBech32Lnurl: (url: string) => string;
+declare const fromBech32Lnurl: (data: string) => string | null;
+declare const isAllowedServiceUrl: (value: string) => boolean;
+declare const fromLud17: (url: string) => string;
+declare const toLud17w: (url: string) => string;
+declare const isLightningAddress: (value: string) => boolean;
+declare const resolveMintInput: (value: string) => string | null;
+declare const mintAddressUrl: (payUrl: string) => string | null;
+declare const lightningAddressUsername: (payUrl: string) => string | null;
+declare const resolveLnurlInput: (value: string) => string | null;
+declare const serverOf: (url: string) => string;
+
+declare const noteK1: (url: string) => string | null;
+declare const requireNoteK1: (url: string) => string;
+declare const noteDeclaredAmount: (url: string) => number | null;
+declare const noteSignature: (url: string) => string | null;
+declare const resolveNoteInput: (value: string) => string | null;
+declare const isValidNoteInput: (value: string) => boolean;
+declare const buildNoteUrl: (withdrawLink: string, k1: string, amountMsat?: number) => string;
+declare const withNewK1: (url: string, k1: string, amountMsat: number, signature?: string) => string;
+declare const withoutK1: (url: string, amountMsat: number, signature?: string) => string;
+
+declare const PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
+type PaymentRequestMethodDetails = {
+    mints: string[];
+    mintPubkeys?: string[];
+};
+type PaymentRequest = {
+    v: 1;
+    id: string;
+    amount: string;
+    currency: 'sat';
+    methodDetails: PaymentRequestMethodDetails;
+    to?: string;
+    memo?: string;
+    expires?: number;
+};
+declare const paymentRequestAmountMsat: (request: PaymentRequest) => number;
+declare const encodePaymentRequest: (request: PaymentRequest) => string;
+type DecodeOptions = {
+    now?: number;
+};
+declare const decodePaymentRequest: (value: string, { now }?: DecodeOptions) => PaymentRequest;
+declare const isPaymentRequest: (value: string) => boolean;
+
+declare const noteSignatureMessage: (k1: string, amountMsat: number) => string;
+declare const noteSignatureDigest: (k1: string, amountMsat: number) => Uint8Array;
+type SignatureCheck = {
+    valid: true;
+    pubkey: string;
+} | {
+    valid: false;
+    pubkey: null;
+};
+declare const verifyNoteSignatureAgainst: (k1: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => SignatureCheck;
+declare const verifyNoteSignature: (k1: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => boolean;
+
+declare const isBolt11Invoice: (value: string) => boolean;
+declare const sameInvoice: (a: string, b: string) => boolean;
+declare const decodeBolt11AmountMsat: (pr: string) => number | null;
+
+declare class LnurlcashError extends Error {
+    constructor(message: string);
+}
+declare class RequestRefusedError extends LnurlcashError {
+}
+declare class ProtocolError extends LnurlcashError {
+}
+declare class ServiceRejectedError extends LnurlcashError {
+    readonly reason: string;
+    newSecrets?: string[];
+    constructor(reason: string);
+}
+declare class PendingNoteError extends ServiceRejectedError {
+    constructor(reason?: string);
+}
+declare class NoteSpentError extends ServiceRejectedError {
+    constructor(reason: string);
+}
+declare class NoteUnknownError extends ServiceRejectedError {
+    constructor(reason: string);
+}
+declare class AmbiguousMintError extends LnurlcashError {
+}
+declare class AmbiguousMutationError extends AmbiguousMintError {
+    readonly newSecrets: string[];
+    constructor(message: string, newSecrets: string[]);
+}
+declare class InsufficientValueError extends ServiceRejectedError {
+    readonly amountMsat: number;
+    readonly minMsat: number;
+    constructor(amountMsat: number, minMsat: number);
+}
+declare const newSecretsOf: (err: unknown) => string[];
+declare const classifyNoteError: (reason: string) => ServiceRejectedError;
 
 declare const createClient: (options?: LnurlcashOptions) => {
     fetchNoteInfo: (url: string) => Promise<WithdrawRequestInfo>;
@@ -191,9 +289,12 @@ declare const createClient: (options?: LnurlcashOptions) => {
     mergeNotesWithHash: (callback: string, k1s: string[], h: string) => Promise<HashedMutationResult>;
     settleNote: (baseUrl: string, k1: string, expectedAmountMsat: number, signature?: string) => Promise<SettledNote>;
     fetchPayRequest: (url: string) => Promise<PayRequestInfo>;
-    requestInvoice: (payCallback: string, amountMsat: number) => Promise<InvoiceResult>;
+    requestInvoice: (payCallback: string, amountMsat: number, h?: string) => Promise<InvoiceResult>;
     fetchInvoiceVerification: (verifyUrl: string) => Promise<VerifyResult>;
+    claimMintedNote: (withdrawLink: string, k1: string) => Promise<MintClaim>;
+    restoreNotes: (baseUrl: string, root: Uint8Array, host: string, restoreOptions?: RestoreOptions) => Promise<RestoreResult>;
+    settleNoteForValue: (noteUrl: string, terms: SettleForValueOptions) => Promise<SettledForValue>;
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type HashedMutationResult, type HashedSplitResult, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintFee, type MintFeeBand, NoteSpentError, NoteUnknownError, type PayRequestInfo, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RotateResult, ServiceRejectedError, type SettledNote, type SplitResult, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, type DecodeOptions, type HashedMutationResult, type HashedSplitResult, InsufficientValueError, type InvoiceRequestOptions, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintClaim, type MintContact, type MintFee, type MintFeeBand, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, ServiceRejectedError, type SettleForValueOptions, type SettledForValue, type SettledNote, type SignatureCheck, type SplitResult, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, verifyNoteSignatureAgainst, withNewK1, withinMintFeeBand, withoutK1 };