lnurlcash-kit 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
+may carry breaking changes; pin an exact version.
+
+## 0.1.0 - 2026-08-20
+
+First release. The protocol layer of
+[lnurl-wallet](https://github.com/dni/lnurl-wallet) (MIT, dni), extracted as
+a standalone library.
+
+### Changes made on extraction
+
+**No globals.** The wallet's `offlineMode()` global became an `offline`
+option, and `fetch`, `timeoutMs` and `randomSecret` joined it. Nothing reads
+ambient state, so a caller can be certain what a call will and will not do.
+`createClient(options)` binds one set for callers who would otherwise thread
+the same object everywhere.
+
+**No DOM or storage assumptions.** Only `fetch`, `URL` and `crypto` are
+required, all substitutable.
+
+### Behavioural fixes
+
+Both were found by the conformance vectors, and both exist in the source
+this was extracted from.
+
+**A reasonless service error is no longer reported as an unknown note.**
+`{"status":"ERROR"}` with no `reason` had a friendly default substituted
+before classification, and that default — "Unknown service error" — matched
+the rule for "unknown note". A service that said nothing was therefore
+reported as denying the note exists, and through `probeBurnedNote` that
+reads as "the burn landed": a conclusion about somebody's money drawn from a
+blank. The reason is now carried through exactly as sent, empty included.
+
+**`grossUpForMintFee` returns the true minimum, and cannot be stalled.** It
+estimated linearly then walked one msat at a time, bounded by a guard. At a
+99.9999% fee the walk is around a million steps, so the guard tripped and
+the answer came back non-minimal — and the fee is chosen by the service, so
+that input is reachable on purpose. It is now a binary search, which is
+exact and bounded for every fee.
+
+**The proportional fee term no longer overflows.** `gross * ppm / 1_000_000`
+exceeds 64-bit unsigned at realistic amounts — 21M BTC is 2.1e15 msat, times
+999_999 ppm is about 2.1e21 — and exceeds a double's exact range too. It is
+computed split. This changes nothing in TypeScript at ordinary amounts, and
+matters a great deal to the ports.
+
+### Additions
+
+**A mutation naming no note is refused** before it reaches the network,
+rather than sent as a callback with no `k1` for a service to interpret
+generously.
+
+**`mint@localhost:8000` resolves.** A Lightning Address needs a dot to be a
+domain, so a bare local host was rejected even though the resolution below
+it already handled the port and the cleartext scheme such a host needs. The
+strict `isLightningAddress` is unchanged; only the resolvers are more
+generous, and only for hosts that are already treated as insecure.

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 dni
+Copyright (c) 2026 TheCryptoDonkey
+
+This library's protocol layer was extracted from lnurl-wallet
+(https://github.com/dni/lnurl-wallet), the LNURLcash reference wallet, which
+is MIT licensed and authored by dni. Subsequent changes are TheCryptoDonkey's.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# lnurlcash-kit
+
+LNURLcash ([LUD-25 draft](https://github.com/lnurl/luds/pull/301)) bearer
+notes for TypeScript: mint, rotate, split, merge, melt, and verify a note
+offline.
+
+```bash
+npm install lnurlcash-kit
+```
+
+This is an early `0.x` release tracking a **draft** spec. Pin an exact
+version.
+
+## What a bearer note is
+
+An ordinary [LUD-03](https://github.com/lnurl/luds/blob/luds/03.md)
+withdrawRequest link whose `k1` **is** the asset:
+
+```
+lnurlw://mint.example/w?k1=<secret>&amount=<msat>
+```
+
+Whoever knows the `k1` controls the sats behind it, like a banknote. The
+`amount` alongside it is only a claim by whoever encoded the note; the
+authoritative value is always `maxWithdrawable` from an informational GET.
+
+No new endpoint and no new encoding, so a wallet that has never heard of
+LNURLcash sees a normal withdraw link and can still cash it out. Every
+mutating operation is a GET on the `callback` from that withdrawRequest:
+
+| Request | Result |
+| --- | --- |
+| `callback?k1=X&pr=<bolt11>` | **melt**: X burned once `pr` settles |
+| `callback?k1=X&h=<sha256(X')>` | **rotate**: X burned, a note keyed by `h` minted |
+| `callback?k1=X&amount=<msat>&h=..&h2=..` | **split**: X burned, notes keyed by `h` and `h2` minted |
+| `callback?k1=X&k1=Y&h=<sha256(Z)>` | **merge**: all burned, one note keyed by `h` minted |
+
+## Usage
+
+```ts
+import {
+  resolveNoteInput,
+  fetchNoteInfo,
+  rotateNote,
+  splitNote,
+  meltNote,
+  verifyNoteSignature
+} from 'lnurlcash-kit'
+
+// accepts a bech32 LNURL, an lnurlw:// URL, or a plain https one
+const url = resolveNoteInput(scanned)
+if (!url) throw new Error('not a note')
+
+// what is it actually worth? Only the service can say.
+const info = await fetchNoteInfo(url)
+console.log(info.maxWithdrawable, 'msat')
+
+// that GET put the secret on the wire, so rotate it
+const fresh = await rotateNote(info.callback, info.k1)
+
+// and check the mint really issued it, without asking anyone
+if (info.mintPubkey && fresh.signature) {
+  verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature, info.mintPubkey)
+}
+```
+
+Every request function takes options last — `fetch`, `timeoutMs`, `offline`,
+`randomSecret`. `createClient(options)` binds one set once:
+
+```ts
+const client = createClient({timeoutMs: 10_000})
+await client.rotateNote(callback, k1)
+```
+
+## The five things that will cost you money
+
+Everything below is a bug class this library exists to close. If you write
+your own client instead, write these first.
+
+**1. Never let the service generate a replacement secret.** On rotate, split
+and merge the *wallet* draws a fresh 32 bytes and discloses only
+`sha256(secret)` as `h`. A service-issued replacement has, structurally,
+been seen by that service — so a "rotate" that accepts one closes no
+exposure at all. This library generates them and ignores any `k1` a
+non-compliant service tries to hand back.
+
+**2. A failed mutation is not a failure.** If a rotate times out, the
+service may already have burned your input and minted the output. The fresh
+secret in your process is then the only copy of that money in existence.
+Every mutating call raises `AmbiguousMutationError` carrying `newSecrets` —
+**persist them before doing anything else**, then use `probeBurnedNote` to
+find out what happened:
+
+```ts
+try {
+  const {k1} = await rotateNote(callback, oldK1)
+} catch (err) {
+  if (err instanceof AmbiguousMutationError) {
+    await save(err.newSecrets)                    // first. always.
+    const fate = await probeBurnedNote(noteUrl)
+    // 'live'    -> nothing landed, the saved secrets are worthless
+    // 'gone'    -> the burn landed, the saved secrets ARE the note
+    // 'unknown' -> keep everything and try again later
+  }
+}
+```
+
+`RequestRefusedError` is the opposite and safe: nothing left the process.
+
+**3. Your HTTP stack must not retry.** Every mutation is a GET, HTTP treats GET
+as idempotent, and an LNURLcash mutation is not — the first attempt burns the
+input. A retried mutation is answered "already spent", which reads as a
+*definitive* rejection, so the fresh secret gets discarded along with the note
+the service just minted. Node's `fetch` does not retry on its own, but a
+browser will resend an idempotent request that failed on a stale pooled
+connection, and any retry wrapper, service worker or proxy in front of this
+will do the same. If you pass your own `fetch`, do not make it retry these.
+
+This is not hypothetical: the same hazard broke the
+[Kotlin](https://github.com/TheCryptoDonkey/lnurlcash-kotlin) and
+[Go](https://github.com/TheCryptoDonkey/lnurlcash-go) siblings during
+development, by two different mechanisms, and is now a named scenario in the
+conformance vectors.
+
+**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
+callback — it is only observable as the note becoming spendable again. Other
+operations on that `k1` raise `PendingNoteError` meanwhile; retry, never
+read it as spent.
+
+**5. Rotate the instant you claim a minted note.** The preimage that mints a
+note is generated by the service, and if it serves
+[LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) `verify`, *anyone*
+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.
+
+## Offline verification
+
+A service may sign each note with its Lightning node identity key, so a
+holder can confirm issuer and amount with nothing but the note:
+
+```
+message = "LNURLcash:" || amount_msat || ":" || hex(sha256(k1))
+digest  = sha256(sha256("Lightning Signed Message:" || message))
+sig     = 65 bytes, r || s || recovery_id
+```
+
+`verifyNoteSignature` recovers the pubkey and compares it to `mintPubkey`.
+It accepts the recovery id at either end, because lnurl-mint once emitted
+the reverse layout and other implementations may still; trying both is safe,
+since the wrong ordering recovers an unrelated key that cannot match.
+
+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.
+
+## Scope
+
+This library speaks the protocol. It does not store notes, hold keys, manage
+a balance, pay invoices, or decide anything about your UI. Storage and key
+management are yours, and they are where most of the remaining risk lives —
+see [THREAT-MODEL.md](THREAT-MODEL.md).
+
+Amounts are integers in **milli-satoshis**, everywhere, with no exceptions.
+
+## Provenance
+
+The protocol layer was extracted from
+[lnurl-wallet](https://github.com/dni/lnurl-wallet), the LNURLcash reference
+wallet by dni, rather than reimplemented — that code has been exercised
+against a real mint and an adversarial mock, and a fresh rewrite would have
+thrown that away to no one's benefit.
+
+The reference implementations, both dni's, both MIT:
+
+- [lnurl-mint](https://github.com/dni/lnurl-mint) — the reference service
+- [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
+
+Changes made on extraction are listed in [CHANGELOG.md](CHANGELOG.md); two
+are behavioural fixes worth reading if you are porting from that code.
+
+## Conformance
+
+Tested against [lnurlcash-conformance](https://github.com/TheCryptoDonkey/lnurlcash-conformance):
+language-neutral vectors plus a mock mint that can be told to misbehave —
+drop a connection mid-mutation, sign in the wrong byte order, lie about a
+note's value, never settle a melt. If you are writing an LNURLcash
+implementation in any language, run those vectors before you run real sats
+through it.
+
+```bash
+npm test
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE) for the attribution.

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security policy
+
+## Supported versions
+
+`0.x` tracks a draft spec ([LUD-25](https://github.com/lnurl/luds/pull/301)).
+Only the latest `0.x` release is supported. Pin an exact version.
+
+## Reporting a vulnerability
+
+Report privately through GitHub's advisory form:
+
+<https://github.com/TheCryptoDonkey/lnurlcash-kit/security/advisories/new>
+
+Please do not open a public issue for anything that could be used to take
+somebody's notes.
+
+Include what you can: affected version, a reproduction, and what an attacker
+gets out of it. A rough report today beats a polished one next month.
+
+Expect an acknowledgement within a few days. This is maintained by one
+person, so timelines are best-effort rather than contractual.
+
+## Scope
+
+**In scope**: anything in this library that could lose or leak a note —
+secrets on the wire, a mutation misclassified as definitive, verification
+that accepts a signature it should not, URL admission bypasses, a fee or
+amount calculation that can be steered by a hostile mint.
+
+**Out of scope**: how a calling application stores secrets, weak RNG
+substituted through `randomSecret`, the behaviour of any particular mint, and
+the LUD-25 draft itself — spec concerns belong on
+[the PR](https://github.com/lnurl/luds/pull/301), where they help everyone
+rather than just this library.
+
+If a finding affects the protocol rather than this implementation, it is
+worth telling the reference implementations too:
+[lnurl-mint](https://github.com/dni/lnurl-mint) and
+[lnurl-wallet](https://github.com/dni/lnurl-wallet).

package/THREAT-MODEL.md

@@ -0,0 +1,158 @@
+# Threat model
+
+What this library defends against, what it cannot, and what it hands to you.
+
+## What it is
+
+A protocol client for LNURLcash bearer notes. It builds requests, classifies
+responses, generates replacement note secrets, and verifies mint signatures
+offline. It holds no state between calls.
+
+## Assets
+
+**Note secrets (`k1`).** Bearer instruments. Whoever holds one can spend it,
+with no further authentication, from anywhere. Compromise is theft, and it
+is silent and irreversible: the money is gone before the previous holder has
+any way to notice.
+
+**Replacement secrets awaiting confirmation.** After a mutation whose outcome
+is unknown, the secrets generated in-process may be the only copies of notes
+a service has already minted. Losing them destroys the money exactly as
+thoroughly as leaking them gives it away.
+
+**Mint pubkeys.** Not secret, but a wrong one makes offline verification
+meaningless.
+
+## Trust boundaries
+
+| Party | Trusted for |
+| --- | --- |
+| the SERVICE (mint) | custody of the sats, and honest accounting. Nothing else. |
+| the caller's storage | confidentiality and durability of secrets. This library provides neither. |
+| the caller's RNG | unpredictability of replacement secrets. Substitutable, and load-bearing. |
+| the network | nothing. |
+
+A mint is trusted with custody by construction — it holds the funds. It is
+*not* trusted to describe them accurately, which is why value comes from
+`maxWithdrawable` rather than from a note URL's own `amount`, and why a
+signed note can be checked against a key the mint published earlier.
+
+## What this library defends against
+
+**A service that keeps a copy of your note.** Rotate, split and merge disclose
+only `sha256(secret)`. The service registers the note under that hash and
+never sees the secret. This is the difference between a bearer note and a
+receipt, and it is why a service-generated replacement is refused even when
+offered (`serverGeneratedSecrets` in the mock mint exercises exactly this).
+
+**A mutation whose outcome is unknown.** Timeouts, dropped connections,
+unreadable bodies and unconfirmed 200s are all raised as
+`AmbiguousMutationError` carrying the fresh secrets, never as failure.
+Requests that provably never left — offline mode, a refused URL, an
+unparseable callback — are raised as `RequestRefusedError` instead, which is
+safe to treat as "nothing happened".
+
+**A note that answers its own questions.** Every URL fetched, whether scanned
+by a user or supplied by a service in its own response, must be https, or
+http to loopback or `.onion`. A `data:` URL carrying withdrawRequest JSON
+would otherwise mint a self-contained fake note that verifies against
+nothing. Redirects are followed by hand, each hop re-admitted against the
+same rule, so an https endpoint cannot pass a request - and the k1 a
+callback URL carries - off to cleartext or another scheme mid-chain. And
+every response body is read with a size cap, so one hostile answer cannot
+exhaust the caller's memory.
+
+**A service that inflates a note.** With offline verification configured, the
+signature commits to the amount. A service reporting more than it signed
+fails verification, without the holder contacting anyone.
+
+**A service that swaps your note.** The informational GET checks that the
+echoed `k1` is the one queried. A different one means either a non-compliant
+service or a note redeemed by somebody else.
+
+**A secret leaking through a query string.** `sig` is stripped before the
+informational GET, since the service already knows what it signed.
+
+**A hostile fee advertisement.** Fees of 100% or more are refused at parse
+time, and the gross-up search is a binary search rather than a walk — so a
+service cannot stall a caller with an extreme fee.
+
+**Integer overflow on realistic amounts.** The proportional fee term is
+computed split, because 21M BTC in msat times a high ppm exceeds 64-bit
+unsigned. Ports that multiply naively pass every small test and mangle large
+ones; the conformance vectors include a case that catches it.
+
+## What it does not defend against
+
+**Storage compromise.** This library never persists anything. If your
+storage is readable — an unencrypted database, a synced folder, a debugger,
+a crash dump — every note in it is spendable by whoever reads it. Encrypt at
+rest, and treat backups as the same exposure.
+
+**A weak RNG.** `randomSecret` is replaceable, which means it can be replaced
+badly. A predictable secret is a note anyone can mint themselves. Use the
+platform CSPRNG, or a hardware RNG, and nothing else.
+
+**Secrets in logs.** A note URL carries its secret in a query string. A
+request logger, an error reporter, a crash handler or an analytics SDK that
+records URLs records bearer money. This library never logs; what wraps it
+might.
+
+**A malicious or compromised mint.** It holds the funds. It can refuse to
+honour a note, vanish, or inflate its liabilities. Offline verification
+proves what it *said*, which is useful for exposing it afterwards, and is
+not custody.
+
+**The mint-time preimage race.** A freshly minted note's secret is the
+invoice preimage, so the service has necessarily seen it, and anyone who saw
+the unpaid invoice can poll LUD-21 `verify` for it the moment it settles.
+Rotating immediately wins that race; a slow manual flow does not. Do not
+publish unpaid mint invoices.
+
+**Traffic analysis.** Every operation reaches the mint directly. The mint
+learns your IP, your timing, and which notes move together. Notes are bearer
+instruments, not private ones — merging several notes tells the mint they
+had one holder. Route over Tor if that matters.
+
+**Anything about the sats themselves.** No custody, no channel management,
+no payment routing.
+
+## The retry hazard
+
+Every LNURLcash mutation is an HTTP GET, and HTTP treats GET as idempotent, so
+a stack may resend one when a connection fails mid-flight. An LNURLcash
+mutation is not idempotent: the first attempt burns the input.
+
+A retried mutation is therefore answered "already spent", which classifies as a
+definitive rejection — so a caller concludes nothing happened and discards the
+fresh secret that was the only copy of the note the service just minted.
+
+This library never retries, and the `fetch` it uses by default does not either
+in Node. It cannot control what wraps it: a browser resending an idempotent
+request on a stale pooled connection, a service worker, a retry interceptor, a
+proxy or a mesh with automatic retries would all reintroduce it. A caller
+passing its own `fetch` owns this.
+
+The hazard is real rather than theoretical — it broke the Kotlin and Go
+siblings during development, by two different mechanisms — and is a named
+scenario in the conformance vectors.
+
+## Deliberate design choices
+
+**Both signature recovery-id orderings are accepted.** The wire format is
+`r || s || recovery_id`; lnurl-mint once emitted the reverse. Trying both is
+not a weakening: recovering under the wrong ordering yields an unrelated
+pubkey, which cannot match the expected one.
+
+**Errors are typed by whether the request could have been processed**, not by
+transport detail. That distinction is the whole safety model, and message
+text is not a stable interface — never branch on it.
+
+**No global state.** Offline mode, fetch, timeout and RNG are parameters. A
+caller that wants certainty nothing reaches the network sets `offline` and
+gets a refusal, rather than trusting that no code path happens to make a
+request.
+
+## Reporting
+
+See [SECURITY.md](SECURITY.md).

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+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 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 MintFee = {
+    baseFeeMsat: number;
+    feePpm: number;
+};
+declare const parseMintFee: (metadata: string) => MintFee | null;
+declare const applyMintFee: (grossMsat: number, fee: MintFee) => number;
+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;
+    k1: string;
+    minWithdrawable: number;
+    maxWithdrawable: number;
+    defaultDescription?: string;
+    mintPubkey?: string;
+};
+declare const fetchNoteInfo: (url: string, options?: LnurlcashOptions) => Promise<WithdrawRequestInfo>;
+declare const probeBurnedNote: (url: string, options?: LnurlcashOptions) => Promise<"live" | "gone" | "unknown">;
+type MintAddressInfo = {
+    tag: 'withdrawRequest';
+    callback: string;
+    minWithdrawable: number;
+    maxWithdrawable: number;
+    defaultDescription?: string;
+    nodePubkey?: string;
+    payLink: string;
+    nodeAlias?: string;
+    nodeUri?: string;
+    nodeColor?: string;
+    nodeCapacityMsat?: number;
+    nodeNumChannels?: number;
+    nodeNumPeers?: number;
+};
+declare const fetchMintAddress: (url: string, options?: LnurlcashOptions) => Promise<MintAddressInfo>;
+type WithdrawSuccessResponse = {
+    status: 'OK';
+    sig?: string;
+    sig2?: string;
+    pr?: string;
+    verify?: string;
+};
+type MeltResult = {
+    verify?: string;
+    pr?: string;
+};
+declare const meltNote: (callback: string, k1: string, pr: string, options?: LnurlcashOptions) => Promise<MeltResult>;
+type HashedMutationResult = {
+    signature?: string;
+};
+declare const rotateNoteWithHash: (callback: string, k1: string, h: string, options?: LnurlcashOptions) => Promise<HashedMutationResult>;
+type HashedSplitResult = {
+    signature?: string;
+    changeSignature?: string;
+};
+declare const splitNoteWithHash: (callback: string, k1s: string[], amountMsat: number, h: string, h2: string, options?: LnurlcashOptions) => Promise<HashedSplitResult>;
+declare const mergeNotesWithHash: (callback: string, k1s: string[], h: string, options?: LnurlcashOptions) => Promise<HashedMutationResult>;
+type RotateResult = {
+    k1: string;
+    signature?: string;
+};
+declare const rotateNote: (callback: string, k1: string, options?: LnurlcashOptions) => Promise<RotateResult>;
+type SplitResult = {
+    k1: string;
+    signature?: string;
+    change: string;
+    changeSignature?: string;
+};
+declare const splitNote: (callback: string, k1s: string[], amountMsat: number, options?: LnurlcashOptions) => Promise<SplitResult>;
+declare const mergeNotes: (callback: string, k1s: string[], options?: LnurlcashOptions) => Promise<RotateResult>;
+type SettledNote = {
+    k1: string;
+    amountMsat: number;
+    signature?: string;
+    callback: string;
+};
+declare const settleNote: (baseUrl: string, k1: string, expectedAmountMsat: number, signature: string | undefined, options?: LnurlcashOptions) => Promise<SettledNote>;
+type PayRequestInfo = {
+    tag: 'payRequest';
+    callback: string;
+    minSendable: number;
+    maxSendable: number;
+    metadata: string;
+    withdrawLink?: string;
+    mintPubkey?: string;
+    mintFee?: MintFee;
+};
+declare const fetchPayRequest: (url: string, options?: LnurlcashOptions) => Promise<PayRequestInfo>;
+type InvoiceResult = {
+    pr: string;
+    verify?: string;
+    disposable: boolean;
+};
+declare const requestInvoice: (payCallback: string, amountMsat: number, options?: LnurlcashOptions) => Promise<InvoiceResult>;
+type VerifyResult = {
+    settled: boolean;
+    preimage: string | null;
+    pr: string;
+};
+declare const fetchInvoiceVerification: (verifyUrl: string, options?: LnurlcashOptions) => Promise<VerifyResult>;
+
+declare const createClient: (options?: LnurlcashOptions) => {
+    fetchNoteInfo: (url: string) => Promise<WithdrawRequestInfo>;
+    probeBurnedNote: (url: string) => Promise<"live" | "gone" | "unknown">;
+    fetchMintAddress: (url: string) => Promise<MintAddressInfo>;
+    meltNote: (callback: string, k1: string, pr: string) => Promise<MeltResult>;
+    rotateNote: (callback: string, k1: string) => Promise<RotateResult>;
+    rotateNoteWithHash: (callback: string, k1: string, h: string) => Promise<HashedMutationResult>;
+    splitNote: (callback: string, k1s: string[], amountMsat: number) => Promise<SplitResult>;
+    splitNoteWithHash: (callback: string, k1s: string[], amountMsat: number, h: string, h2: string) => Promise<HashedSplitResult>;
+    mergeNotes: (callback: string, k1s: string[]) => Promise<RotateResult>;
+    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>;
+    fetchInvoiceVerification: (verifyUrl: string) => Promise<VerifyResult>;
+};
+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, 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, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withoutK1 };