@forgesworn/moneyer 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [0.1.0] - 2026-08-20
+
+Initial implementation.
+
+- The six LUD-25 endpoints: payRequest, mint address discovery, pay
+  callback, LUD-21 verify (mint and melt sides), informational GET, and
+  the mutating callback (melt, rotate, split, merge).
+- Funding sources: cln (clnrest) and lnd (REST), both with
+  caller-supplied invoice preimages; a fake backend for development and
+  tests, refused outside `--dev`.
+- SQLite store keyed by note id (sha256 of the secret) - secrets are never
+  persisted. Synchronous atomic mutations.
+- In-process note signing with a dedicated mint key, agreeing byte for
+  byte with lnurlcash-kit's verifier.
+- The melt discipline: respond-then-pay, confirm-before-restore,
+  pending-not-guessed, reconciliation at startup and on demand.
+- Passes the lnurlcash-conformance grader, read-only and spending runs;
+  the grader executes inside the test suite.
+- The LUD-25 fee algebra on mutations: base_fee_msat deducted from every
+  split's change (never the requested amount), (n-1) base fees refunded
+  into a merge of n notes, 'insufficient value' when change cannot cover
+  the fee or would land at zero.
+- The mint's own website at GET /: mint a note in the browser (invoice
+  QR, LUD-21 countdown polling, claim-and-immediately-rotate so the
+  verify-exposed preimage dies before the note is shown, offline
+  signature verification in front of the user, scratch-off silver over the QR), check
+  a note (live/spent/unknown/pending in plain words), the terms and the
+  funding node. vite + anime.js + lnurlcash-kit, served from memory by
+  the mint process; falls back to a self-contained zero-script landing
+  page when no web build exists. `MONEYER_WALLET_URL` links minted notes
+  into a companion wallet's claim route.
+- Node statistics (capacity, channels, peers) on the discovery endpoint,
+  best-effort from the funding source.
+- Shared funding sources are a supported deployment: the melt path
+  pre-checks the node's payment history and surfaces the node's
+  "payment already exists" refusal as a distinct, note-restoring
+  outcome, closing the cross-mint melt replay a shared node otherwise
+  allows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheCryptoDonkey
+
+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,133 @@
+# moneyer
+
+> An LNURLcash (LUD-25) mint. A moneyer was the mediaeval craftsman licensed
+> to strike coins; this one strikes Lightning bearer notes.
+
+moneyer is an independent implementation of the LUD-25 draft: paying an
+invoice it issues mints a bearer note whose spend secret is that invoice's
+payment preimage, and a note's holder can rotate, split, merge and melt it
+against the withdraw callback. It passes the full
+[lnurlcash-conformance](https://github.com/TheCryptoDonkey/lnurlcash-conformance)
+grader, including the spending checks, and the grader runs in this repo's
+own test suite.
+
+Reference stack, by dni (MIT): the [LUD-25 draft](https://github.com/lnurl/luds/pull/301),
+[lnurl-mint](https://github.com/dni/lnurl-mint), [lnurl-wallet](https://github.com/dni/lnurl-wallet).
+moneyer shares no code with them; where their behaviour encodes a safety
+lesson, that behaviour is kept deliberately and tested.
+
+## What it is
+
+- TypeScript, ESM, Node 24+. `node:http` and `node:sqlite`; no web
+  framework, no ORM.
+- Funding sources: **cln** (clnrest) and **lnd** (REST), both of which
+  accept a caller-supplied invoice preimage - the capability a LUD-25 mint
+  cannot exist without. phoenixd and NIP-47 `make_invoice` do not offer it,
+  which is why neither can back a mint. A **fake** backend exists for
+  development and tests and refuses to run outside `--dev`.
+- Notes are stored by id, `sha256(k1)` - the store never holds a spend
+  secret. A freshly minted note's preimage lives only with the payer and
+  the funding source.
+- Signs every note it mints with its own mint key (secp256k1, the standard
+  `Lightning Signed Message` construction) for LUD-25 offline verification.
+- The melt discipline: reply OK when the note is reserved, pay in the
+  background, burn only on confirmed payment, restore only on confirmed
+  non-payment, and park everything else as pending for reconciliation -
+  which also runs at startup, so a crash mid-melt never guesses.
+
+## Run
+
+Not on npm yet - build from source, with the sibling repos it links
+against until those publish:
+
+```bash
+git clone https://github.com/TheCryptoDonkey/lnurlcash-kit
+git clone https://github.com/TheCryptoDonkey/lnurlcash-conformance
+git clone https://github.com/forgesworn/moneyer
+(cd lnurlcash-kit && npm install && npm run build)
+cd moneyer && npm install && npm run build && npm run web:build
+```
+
+```bash
+# development: fake funding source, in-memory store, a funded note printed
+node dist/cli.js --dev
+
+# production shape
+MONEYER_BACKEND=cln \
+MONEYER_BACKEND_URL=https://127.0.0.1:3010 \
+MONEYER_BACKEND_RUNE=... \
+MONEYER_SIGNING_KEY=<32 bytes hex> \
+MONEYER_PUBLIC_ORIGIN=https://mint.example \
+MONEYER_DB=/var/lib/moneyer/mint.sqlite \
+node dist/cli.js
+```
+
+The mint is then payable at `mint@mint.example` (and the bare-domain `_`
+alias). Configuration is environment-only; see `src/config.ts` for the
+full `MONEYER_*` set including fees (`MONEYER_BASE_FEE_MSAT`,
+`MONEYER_FEE_PPM`), limits, and `MONEYER_SUNSET` for winding down without
+stranding holders.
+
+## The website
+
+`GET /` serves the mint's own site (`web/`, vite + anime.js, built by
+`npm run web:build` into memory-served static files). It is a wallet-grade
+LNURLcash client in its own right, driven entirely by `lnurlcash-kit`
+against the same endpoints every wallet uses:
+
+- **Mint a note in the browser**: amount in, fee grossed up and shown
+  before the invoice exists, invoice QR (tap opens a wallet), LUD-21
+  polling with a countdown, and on settlement the note is claimed and
+  **immediately rotated** - the preimage any invoice-observer could poll
+  out of verify is dead before the note is shown. The rotated note's
+  signature is verified against the mint's advertised key in front of the
+  user, and the QR arrives under scratch-off silver foil, rubbed away like a scratch card.
+- **Check a note**: live value, spent/unknown/pending classified in plain
+  words, offline signature verification.
+- `MONEYER_WALLET_URL` (optional) links minted notes straight into a
+  companion web wallet's `#/claim` route.
+
+Without a web build the server falls back to a self-contained, zero-script
+landing page, so an npm-installed mint still has a face.
+
+As a library:
+
+```ts
+import {createMoneyer, configFromEnv} from '@forgesworn/moneyer'
+const mint = await createMoneyer(configFromEnv())
+```
+
+## Endpoints
+
+| | |
+| --- | --- |
+| `/.well-known/lnurlp/<user>` | LUD-16 payRequest; paying mints a note |
+| `/.well-known/lnurlw/<user>` | LUD-25 mint address discovery (experimental) |
+| `/p/cb` | LUD-06 pay callback; issues the mint invoice |
+| `/verify/<hash>` | LUD-21 verify, for mint invoices and melt payments |
+| `/w` | LUD-03 informational GET |
+| `/w/cb` | the mutating callback: melt, rotate, split, merge |
+
+## Testing
+
+```bash
+npm test          # vitest: protocol, signing, melt discipline, conformance
+```
+
+The conformance grader runs inside the suite against an in-process mint,
+read-only and spending paths both. The cln and lnd backends are direct
+ports of the reference mint's semantics but have not yet been exercised
+against live nodes; treat them as beta until they have.
+
+## Dogfood
+
+Part of the ForgeSworn LNURLcash stack: built on
+[`lnurlcash-kit`](https://github.com/TheCryptoDonkey/lnurlcash-kit) (fee
+maths, hashing, signature agreement) and
+[`farrier-kit`](https://github.com/forgesworn/farrier-kit) (BOLT-11
+decoding and preimage verification on the melt path). The companion wallet
+is [`@forgesworn/notecase`](https://github.com/forgesworn/notecase).
+
+## Licence
+
+MIT.

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+moneyer moves real money. If you find a way to make it move the wrong way,
+please report it privately.
+
+## Reporting
+
+Open a GitHub security advisory on this repository (Security tab, "Report
+a vulnerability"), or contact the maintainer privately. Please do not open
+a public issue for anything that could cost an operator or a holder funds
+before a fix exists.
+
+Include what you can: the endpoint or flow, a reproduction against
+`moneyer --dev` (never against someone's live mint), and what an attacker
+gains.
+
+## Scope
+
+In scope: anything that burns, mints, restores or reveals a note contrary
+to the rules in THREAT-MODEL.md; anything that makes the melt discipline
+guess; anything that lets a request cross the store's atomicity.
+
+Out of scope: denial of service against an unproxied dev deployment,
+vulnerabilities in the funding source itself, and social engineering.
+
+## Supported versions
+
+Pre-1.0: only the latest release is supported. Pin an exact version; the
+LUD-25 spec is still a draft and wire behaviour may follow it.

package/THREAT-MODEL.md

@@ -0,0 +1,104 @@
+# Threat model
+
+moneyer holds other people's money as bearer liabilities. The store keeps
+note ids (hashes), amounts and states; the spend secrets exist only as
+invoice preimages at the funding source and in holders' wallets.
+
+## Assets
+
+- The outstanding note set: every `outstanding` row is money owed to
+  whoever holds its secret.
+- The funding source credentials (rune or macaroon): full spending power
+  over the mint's liquidity.
+- The mint signing key: whoever holds it can issue "verified" notes.
+
+## Adversaries and defences
+
+**A holder replaying or racing mutations.** Every mutation validates and
+transitions state in one synchronous SQLite transaction with no await
+inside it; two concurrent callbacks for the same k1 cannot both win. A
+burned k1 answers `Invalid or already spent k1.` atomically. And every
+LNURL endpoint answers GET only, so a preflight or any other non-GET
+request carrying a callback's query string cannot mutate anything.
+
+**A holder inflating a merge or split with a repeated k1.** Duplicated k1
+parameters in one request are refused outright; they would otherwise count
+one note's value twice into the output.
+
+**A holder claiming an output id that already exists.** `h`/`h2` may not
+collide with any existing note OR any mint invoice's payment hash, settled
+or not. The invoice case is the subtle one: `/verify` hands a settled mint
+invoice's preimage to its payer, and that preimage is the k1 of whatever
+note carries the hash as its id - minting "over" such an id would point a
+future payer's money at a stranger's note.
+
+**A holder melting into the mint's own invoice.** Refused synchronously:
+paying it would route the funding source's money at itself, which real
+nodes handle inconsistently.
+
+**A holder reusing an invoice across melts.** Refused: the funding source
+dedupes payments by hash, so the second melt would be "confirmed" against
+the first payment and burn a note without moving funds.
+
+**A holder replaying a melt across mints sharing one funding source.**
+Sharing a node between mints is a supported deployment, and it creates a
+dedupe gap no mint's own tables can see: an invoice melted at mint A is
+unknown to mint B, whose confirm-by-hash would read A's completed payment
+as its own success and burn B's note with no funds moving. Closed twice
+over: the melt callback synchronously asks the NODE whether it ever paid
+(or is still paying) the hash and refuses if so, and if the foreign
+payment lands in the race between that check and the send, the node's own
+"payment already exists" refusal is surfaced as a distinct
+PaymentAlreadyKnownError and the note restores - nothing went out on this
+mint's behalf, so nothing is guessed. Do not share a funding source with
+a mint implementation that lacks the equivalent guard: its side of the
+same replay stays open.
+
+**A malicious payee holding a hodl invoice.** A clean failure report from
+the funding source is never trusted on its own: the note restores only
+once `isPaymentComplete` returns a terminal false. A payment stuck
+in-flight leaves the note pending rather than restorable - the alternative
+is letting the holder melt the same value twice.
+
+**A funding source lying about an invoice.** The invoice returned by
+`createInvoice` is decoded and must commit to the preimage moneyer chose
+and the amount requested, or it is never handed out - otherwise a payer's
+money would mint an unclaimable note.
+
+**Process death.** Melts are journalled before payment; reconciliation
+runs at startup and on demand, resolving pending melts by asking the
+funding source, never by assumption.
+
+**The verify endpoint as an oracle.** `/verify` serves bearer material
+(the preimage). It is only served once the funding source reports
+settlement, is fetched live rather than cached, and has a real off switch
+(`MONEYER_VERIFY=0` makes it a 404). Anyone who saw the unpaid invoice can
+poll it, which is why wallets must rotate immediately on claim - stated in
+the spec and enforced by the companion wallet.
+
+## Out of scope
+
+- Compromise of the host or the funding source credentials: at that point
+  the attacker IS the mint.
+- Lightning-level attacks against the funding source (channel jamming,
+  probing) - the node's own concern.
+- TLS termination: moneyer expects a reverse proxy in production and binds
+  to loopback by default.
+
+## Known limitations
+
+- The cln and lnd backends are unexercised against live nodes (direct
+  ports of the reference mint's logic). Run `--dev` traffic and the
+  conformance grader against a staging deployment before taking real money.
+- No rate limiting is built in; put it at the proxy. This matters most for
+  `/p/cb`: each unauthenticated call creates a real invoice at the funding
+  source. moneyer sweeps its own unsettled invoices once their bolt11
+  expiry has passed, but the node's side of that growth is the operator's
+  to bound (cln's autoclean, or an equivalent cron) - and a proxy limit is
+  what keeps the RPC pile-up and the node database from growing at all.
+- A fee-free configuration pays the melt routing-fee floor (0.5% of the
+  amount or 5000 msat) out of its own channel balance, and mint-and-melt
+  cycling costs a griefer nothing. Set `MONEYER_BASE_FEE_MSAT` to cover the
+  floor before taking real traffic.
+- `node:sqlite` is a single-writer store; moneyer is a single-process
+  service by design. Do not run two instances against one database.

package/dist/backends/cln.d.ts

@@ -0,0 +1,5 @@
+import { type LightningBackend } from './types.ts';
+export declare const createClnBackend: (config: {
+    url: string;
+    rune: string;
+}) => LightningBackend;

package/dist/backends/cln.js

@@ -0,0 +1,130 @@
+import { bytesToHex, randomBytes } from '@noble/hashes/utils.js';
+import { verifyPreimage } from 'farrier-kit/preimage';
+import { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } from "./types.js";
+// Core Lightning over the clnrest plugin. cln's `invoice` accepts a
+// caller-supplied preimage, which is the whole reason it can back a mint.
+//
+// Not yet exercised against a live node - the semantics are a direct port
+// of the reference mint's cln backend, which is.
+//
+// TLS: the node's certificate must be one this process trusts. For a
+// self-signed clnrest cert, point NODE_EXTRA_CA_CERTS at it.
+// xpay's documented failure codes.
+const PAY_FAILURE_REASONS = {
+    203: "The invoice's destination permanently rejected this payment.",
+    205: 'Could not find a route to pay this invoice.',
+    207: 'This invoice has expired.',
+    219: 'This invoice has already been paid.'
+};
+export const createClnBackend = (config) => {
+    const call = async (path, body, timeoutMs = 15_000) => {
+        const res = await fetch(`${config.url}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', Rune: config.rune },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        const json = await res.json().catch(() => null);
+        return { ok: res.ok, status: res.status, json };
+    };
+    const mustCall = async (path, body, timeoutMs) => {
+        const res = await call(path, body, timeoutMs);
+        if (!res.ok) {
+            throw new Error(`cln ${path} failed (${res.status}): ${JSON.stringify(res.json)?.slice(0, 200)}`);
+        }
+        return res.json;
+    };
+    return {
+        name: 'cln',
+        async createInvoice({ amountMsat, preimageHex, memo }) {
+            const result = await mustCall('/v1/invoice', {
+                amount_msat: amountMsat,
+                label: bytesToHex(randomBytes(16)),
+                description: memo,
+                preimage: preimageHex
+            });
+            if (typeof result?.bolt11 !== 'string')
+                throw new Error('cln did not return a bolt11 invoice.');
+            return { pr: result.bolt11 };
+        },
+        async payInvoice({ pr, feeLimitMsat }) {
+            // xpay resolves once it stops retrying, which is NOT proof that no
+            // HTLC it already sent remains outstanding - the caller confirms via
+            // isPaymentComplete before restoring anything either way. The
+            // timeout sits above xpay's own default 60s retry_for so a clean
+            // failure response is not turned into an ambiguous one at the wire.
+            const res = await call('/v1/xpay', { invstring: pr, maxfee: feeLimitMsat }, 90_000);
+            if (!res.ok) {
+                const code = res.json?.code;
+                // 219: this node already paid that hash. On a shared node that is
+                // somebody else's payment - nothing went out for THIS call, so it
+                // is a distinct, safely-restorable refusal rather than a failure.
+                if (code === 219) {
+                    throw new PaymentAlreadyKnownError('cln already has a payment for this hash');
+                }
+                const reason = (typeof code === 'number' && PAY_FAILURE_REASONS[code]) ||
+                    res.json?.message ||
+                    `Payment failed (${res.status}).`;
+                throw new PaymentFailedError(reason);
+            }
+            const preimageHex = res.json?.payment_preimage;
+            if (typeof preimageHex !== 'string')
+                throw new Error('cln did not return a payment_preimage.');
+            const amountMsat = res.json?.amount_msat;
+            const amountSentMsat = res.json?.amount_sent_msat;
+            const feeMsat = typeof amountMsat === 'number' && typeof amountSentMsat === 'number'
+                ? amountSentMsat - amountMsat
+                : null;
+            return { preimageHex, feeMsat };
+        },
+        async isPaymentComplete(paymentHashHex) {
+            const result = await mustCall('/v1/listpays', { payment_hash: paymentHashHex });
+            const pays = result?.pays ?? [];
+            // "pending" is not "confirmed not paid" - an HTLC may still be locked
+            // at the final hop.
+            if (pays.some(pay => pay?.status === 'pending')) {
+                throw new PaymentPendingError('cln reports the payment still pending');
+            }
+            return pays.some(pay => pay?.status === 'complete');
+        },
+        async isInvoiceSettled(paymentHashHex) {
+            const result = await mustCall('/v1/listinvoices', { payment_hash: paymentHashHex });
+            const invoices = result?.invoices ?? [];
+            return invoices.length > 0 && invoices[0]?.status === 'paid';
+        },
+        async invoicePreimage(paymentHashHex) {
+            const result = await mustCall('/v1/listinvoices', { payment_hash: paymentHashHex });
+            const invoice = (result?.invoices ?? [])[0];
+            if (!invoice || invoice.status !== 'paid')
+                return null;
+            const preimageHex = invoice.payment_preimage;
+            if (typeof preimageHex !== 'string' || !verifyPreimage(preimageHex, paymentHashHex))
+                return null;
+            return preimageHex;
+        },
+        async paymentPreimage(paymentHashHex) {
+            const result = await mustCall('/v1/listpays', { payment_hash: paymentHashHex });
+            for (const pay of result?.pays ?? []) {
+                if (pay?.status === 'complete' && typeof pay.preimage === 'string')
+                    return pay.preimage;
+            }
+            return null;
+        },
+        async nodeInfo() {
+            const info = await mustCall('/v1/getinfo', {});
+            const id = info?.id;
+            const address = (info?.address ?? [])[0];
+            const uri = id && address?.address && address?.port ? `${id}@${address.address}:${address.port}` : id;
+            const color = typeof info?.color === 'string' ? `#${info.color.replace(/^#/, '')}` : undefined;
+            const numChannels = Number(info?.num_active_channels);
+            const numPeers = Number(info?.num_peers);
+            return {
+                ...(info?.alias ? { alias: info.alias } : {}),
+                ...(uri ? { uri } : {}),
+                ...(color && /^#[0-9a-fA-F]{6}$/.test(color) ? { color } : {}),
+                ...(Number.isSafeInteger(numChannels) ? { numChannels } : {}),
+                ...(Number.isSafeInteger(numPeers) ? { numPeers } : {})
+            };
+        }
+    };
+};

package/dist/backends/fake-bolt11.d.ts

@@ -0,0 +1,6 @@
+export declare const fakeBolt11: (args: {
+    amountMsat: number;
+    paymentHashHex: string;
+    memo?: string;
+    timestamp?: number;
+}) => string;

package/dist/backends/fake-bolt11.js

@@ -0,0 +1,60 @@
+import { bech32 } from '@scure/base';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { hexToBytes, utf8ToBytes, randomBytes } from '@noble/hashes/utils.js';
+// A syntactically COMPLETE BOLT-11 invoice that nothing can ever pay.
+//
+// The conformance mock mint gets away with an HRP and filler because the
+// reference wallet only reads the human-readable part. This stack holds
+// itself to farrier-kit's full decode - checksum, tagged fields, signature
+// layout - so the fake funding source has to emit the real grammar: a
+// mainnet HRP with the exact amount, a p field carrying the true payment
+// hash, s and 9 so modern parsers see a payment secret and its feature
+// bits, d for the memo, and a recoverable signature by a fixed throwaway
+// key that no Lightning node has ever announced. Unpayable by
+// construction; decodable by anything.
+const FAKE_NODE_KEY = hexToBytes('4242424242424242424242424242424242424242424242424242424242424242');
+const fiveToEight = (words) => {
+    let acc = 0;
+    let bits = 0;
+    const out = [];
+    for (const word of words) {
+        acc = (acc << 5) | word;
+        bits += 5;
+        while (bits >= 8) {
+            bits -= 8;
+            out.push((acc >> bits) & 0xff);
+        }
+    }
+    if (bits > 0)
+        out.push((acc << (8 - bits)) & 0xff);
+    return new Uint8Array(out);
+};
+const tagged = (type, data) => [
+    type,
+    data.length >> 5,
+    data.length & 31,
+    ...data
+];
+const amountHrp = (msat) => (msat % 100 === 0 ? `${msat / 100}n` : `${msat * 10}p`);
+export const fakeBolt11 = (args) => {
+    const hrp = `lnbc${amountHrp(args.amountMsat)}`;
+    const words = [];
+    const timestamp = args.timestamp ?? Math.floor(Date.now() / 1000);
+    for (let i = 6; i >= 0; i--)
+        words.push((timestamp / 2 ** (5 * i)) & 31);
+    // p - payment hash
+    words.push(...tagged(1, Array.from(bech32.toWords(hexToBytes(args.paymentHashHex)))));
+    // d - description
+    words.push(...tagged(13, Array.from(bech32.toWords(utf8ToBytes(args.memo ?? 'moneyer fake invoice')))));
+    // s - payment secret (random; nothing will ever present it)
+    words.push(...tagged(16, Array.from(bech32.toWords(randomBytes(32)))));
+    // 9 - features: var_onion_optin (bit 9) and payment_secret (bit 15), both
+    // optional, as 20 bits of 5-bit words
+    words.push(...tagged(5, [1, 0, 16, 0]));
+    const signed = sha256(new Uint8Array([...utf8ToBytes(hrp), ...fiveToEight(words)]));
+    const lead = secp256k1.sign(signed, FAKE_NODE_KEY, { format: 'recovered', prehash: false });
+    const signature = new Uint8Array([...lead.subarray(1), lead[0]]);
+    words.push(...Array.from(bech32.toWords(signature)));
+    return bech32.encode(hrp, words, false);
+};

package/dist/backends/fake.d.ts

@@ -0,0 +1,17 @@
+import { type LightningBackend } from './types.ts';
+export type FakePayMode = 'succeed' | 'fail-clean' | 'fail-then-paid' | 'ambiguous-paid' | 'ambiguous-unpaid' | 'ambiguous-pending';
+export type FakeBackend = LightningBackend & {
+    control: {
+        settleInvoice(paymentHashHex: string): void;
+        setPayMode(mode: FakePayMode): void;
+        resolvePayment(paymentHashHex: string, status: 'complete' | 'failed'): void;
+        registerPaymentPreimage(paymentHashHex: string, preimageHex: string): void;
+        seedForeignPayment(paymentHashHex: string, status?: 'complete' | 'pending'): void;
+        invoiceByHash(paymentHashHex: string): {
+            preimageHex: string;
+            amountMsat: number;
+            settled: boolean;
+        } | undefined;
+    };
+};
+export declare const createFakeBackend: () => FakeBackend;

package/dist/backends/fake.js

@@ -0,0 +1,104 @@
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { hexToBytes } from '@noble/hashes/utils.js';
+import { bolt11PaymentHash } from 'farrier-kit/bolt11';
+import { fakeBolt11 } from "./fake-bolt11.js";
+import { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } from "./types.js";
+export const createFakeBackend = () => {
+    const invoices = new Map();
+    const payments = new Map();
+    const knownPreimages = new Map();
+    let payMode = 'succeed';
+    return {
+        name: 'fake',
+        async createInvoice({ amountMsat, preimageHex, memo }) {
+            const paymentHashHex = bytesToHex(sha256(hexToBytes(preimageHex)));
+            const pr = fakeBolt11({ amountMsat, paymentHashHex, memo });
+            invoices.set(paymentHashHex, { preimageHex, amountMsat, settled: false });
+            return { pr };
+        },
+        async payInvoice({ pr }) {
+            const paymentHashHex = bolt11PaymentHash(pr);
+            if (!paymentHashHex)
+                throw new PaymentFailedError('That is not a decodable invoice.');
+            // Real nodes dedupe sends by payment hash: a hash this node already
+            // holds a payment for is refused, exactly as lnd and cln refuse it.
+            if (payments.has(paymentHashHex)) {
+                throw new PaymentAlreadyKnownError('this node already has a payment for that hash');
+            }
+            const preimageHex = knownPreimages.get(paymentHashHex) ?? null;
+            switch (payMode) {
+                case 'succeed':
+                    payments.set(paymentHashHex, { status: 'complete', preimageHex });
+                    return { preimageHex, feeMsat: 0 };
+                case 'fail-clean':
+                    payments.set(paymentHashHex, { status: 'failed', preimageHex: null });
+                    throw new PaymentFailedError('Could not find a route to pay this invoice.');
+                case 'fail-then-paid':
+                    payments.set(paymentHashHex, { status: 'complete', preimageHex });
+                    throw new PaymentFailedError('Timed out trying to find a route to pay this invoice.');
+                case 'ambiguous-paid':
+                    payments.set(paymentHashHex, { status: 'complete', preimageHex });
+                    throw new Error('connection reset mid-payment');
+                case 'ambiguous-unpaid':
+                    payments.set(paymentHashHex, { status: 'failed', preimageHex: null });
+                    throw new Error('connection reset mid-payment');
+                case 'ambiguous-pending':
+                    payments.set(paymentHashHex, { status: 'pending', preimageHex });
+                    throw new Error('connection reset mid-payment');
+            }
+        },
+        async isPaymentComplete(paymentHashHex) {
+            const payment = payments.get(paymentHashHex);
+            if (!payment)
+                return false;
+            if (payment.status === 'pending') {
+                throw new PaymentPendingError('the payment has no terminal outcome yet');
+            }
+            return payment.status === 'complete';
+        },
+        async isInvoiceSettled(paymentHashHex) {
+            return invoices.get(paymentHashHex)?.settled ?? false;
+        },
+        async invoicePreimage(paymentHashHex) {
+            const invoice = invoices.get(paymentHashHex);
+            return invoice?.settled ? invoice.preimageHex : null;
+        },
+        async paymentPreimage(paymentHashHex) {
+            const payment = payments.get(paymentHashHex);
+            return payment?.status === 'complete' ? payment.preimageHex : null;
+        },
+        async nodeInfo() {
+            return { alias: 'moneyer (fake funding source)', color: '#c9ced8' };
+        },
+        control: {
+            settleInvoice(paymentHashHex) {
+                const invoice = invoices.get(paymentHashHex);
+                if (!invoice)
+                    throw new Error(`no fake invoice for ${paymentHashHex}`);
+                invoice.settled = true;
+            },
+            setPayMode(mode) {
+                payMode = mode;
+            },
+            resolvePayment(paymentHashHex, status) {
+                const payment = payments.get(paymentHashHex);
+                if (!payment)
+                    throw new Error(`no fake payment for ${paymentHashHex}`);
+                payment.status = status;
+            },
+            registerPaymentPreimage(paymentHashHex, preimageHex) {
+                knownPreimages.set(paymentHashHex, preimageHex);
+                const payment = payments.get(paymentHashHex);
+                if (payment?.status === 'complete')
+                    payment.preimageHex = preimageHex;
+            },
+            seedForeignPayment(paymentHashHex, status = 'complete') {
+                payments.set(paymentHashHex, { status, preimageHex: null });
+            },
+            invoiceByHash(paymentHashHex) {
+                return invoices.get(paymentHashHex);
+            }
+        }
+    };
+};

package/dist/backends/lnd.d.ts

@@ -0,0 +1,5 @@
+import { type LightningBackend } from './types.ts';
+export declare const createLndBackend: (config: {
+    url: string;
+    macaroon: string;
+}) => LightningBackend;