Worked integration · LUD-25 draft

LNURLcash without putting a wallet inside the app.

An LNURLcash note is an LNURL-withdraw link whose secret controls the sats behind it. A browser app can use nwc-kit to ask the user's existing Lightning wallet to pay the mint or receive a melt. The app stays serverless and the wallet keeps its keys.

Open LNURLwallet Read the NWC recipe

Fig. 1. The preimage is the asset. nwc-kit carries the wallet leg only. Whether the preimage matches the invoice, and whether the mint is worth its custody, are both questions the application has to answer for itself. A melt runs the same circuit backwards.

LNURLcash is an experimental draft. Use small amounts, treat each mint as a counterparty, and read the current project status before relying on it.

What actually happens

The note protocol and the wallet connection remain separate. That makes the trust boundary easier to see and much harder to accidentally expand.

i
Mint · wallet to note
1. The app resolves the mint's LUD‑16 payRequest and asks for an invoice in milli-satoshis.
2. The app decodes the invoice and checks the amount before asking the connected wallet to pay.
3. payInvoice() returns the preimage. The app proves it matches the invoice payment hash.
4. The app claims the note and rotates it immediately, because the mint's node saw the original secret first.
ii
Melt · note to wallet
1. The app asks the connected wallet to make an invoice for the note's value.
2. The app gives that invoice and the note secret to the mint's withdraw callback.
3. The mint accepts the melt and pays asynchronously. Acceptance is not settlement.
4. The app polls lookupInvoice() and marks the note spent only when the wallet reports settlement.

Where nwc-kit fits

What it supplies

nwc-kit supplies authenticated NIP‑47 requests over NIP‑44 v2. It lets the application pay a mint invoice, create an invoice for a melt, and look up settlement without receiving the wallet's keys or running a Lightning node of its own.

The NWC connection string is still a spending capability. Keep it in private app-owned storage, give it the smallest useful budget and expiry, and never send it to the mint.

What remains the application's job

nwc-kit does not decode BOLT‑11 invoices, verify payment preimages, implement LNURLcash, store notes or decide whether a mint should be trusted. farrier-kit covers invoice and preimage verification.

Timeout, abort, close and publish failure remain ambiguous after an NWC request starts. Reconcile the original invoice before retrying. A blind retry can pay twice.

A mint custodies the sats behind its notes. That makes it a counterparty, not a verifier, and no amount of protocol care on the wallet leg changes it. Size the note to what you are willing to lose to a mint that stops answering.

Try the pieces

These are separate projects with separate responsibilities. You can use the web wallet and experimental mint now, or inspect and flash the hardware vault if you want note secrets kept off the browser.

LNURLwallet: A serverless wallet for holding, rotating, splitting, combining and melting notes from independent LNURLcash mints. Notes are encrypted before they reach browser storage. Open the wallet ↗ Source
ForgeSworn mint: A live, small-value LNURLcash mint for testing the current draft. The mint custodies the sats behind its notes, so it is a counterparty rather than a verifier. Open the mint ↗ Source
LNURLvault: ESP32 firmware that generates and holds bearer-note secrets, with a physical approval before plaintext export. Check the current hardware status and security model before flashing it. Open the vault installer ↗ Source

Read the protocol and the code

Start with the LUD‑25 draft, then use the nwc-kit recipe for the wallet-facing TypeScript flow. The three projects above are open source, so the claim surface is available to inspect rather than hidden behind the demos.

Back to nwc-kit Run the demo GitHub