402-mcp 4.1.2 → 4.2.1

package/build/wallet/lnurlcash-ops.d.ts

@@ -0,0 +1,91 @@
+import type { LnurlcashNoteStore, StoredNote, SettledMelt } from '../store/lnurlcash-notes.js';
+/** What a reconcile pass turned up that a caller may want to act on. */
+export interface ReconcileReport {
+    /**
+     * Melts that had already settled by the time we asked again, with the
+     * preimage recovered. Empty on a quiet pass. Each one is also written to
+     * the store, so nothing depends on the caller reading this.
+     */
+    recovered: SettledMelt[];
+}
+/**
+ * Note operations shared by the wallet provider (which melts a note to pay a
+ * BOLT-11 invoice) and the lnurlcash HTTP rail (which hands a note straight to
+ * a paywall). Both need the same crash-safe split and the same reconciliation,
+ * and two copies of that would drift.
+ */
+/** LUD-03/LUD-25 responses are either a success object or `{status:'ERROR'}`. */
+export interface LnurlError {
+    status: 'ERROR';
+    reason?: string;
+}
+export interface WithdrawRequest {
+    status?: string;
+    tag?: string;
+    callback?: string;
+    k1?: string;
+    minWithdrawable?: number;
+    maxWithdrawable?: number;
+}
+export interface CallbackOk {
+    status?: string;
+    verify?: string;
+    pr?: string;
+    reason?: string;
+}
+export declare function isError(res: unknown): res is LnurlError;
+/**
+ * Mint responses are the only thing safe to surface. Anything thrown by the
+ * HTTP layer may carry a URL, and our URLs carry note secrets in the query
+ * string, so exceptions are never stringified outward.
+ */
+export declare class MintRefused extends Error {
+}
+/**
+ * The mint doesn't recognise a note we thought we held. Expected, not
+ * exceptional: a bearer note can be spent by anyone holding a copy, so every
+ * local balance is a cache and the mint is the only authority. Signals "drop
+ * this one and try the next", never "fail the payment".
+ */
+export declare class NoteGone extends Error {
+}
+export interface NoteOpsOptions {
+    /** Per-request HTTP timeout. */
+    httpTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** SSRF guard, matching farrier-kit's verifyLud21 hook. */
+    urlGuard?: (url: URL) => void | Promise<void>;
+}
+export interface ResolvedNote {
+    amountMsat: number;
+    callback: string;
+}
+/**
+ * `refused` is the mint saying it does not honour this note: unknown, already
+ * spent, or pending another operation. `unreachable` is the mint saying
+ * nothing at all. The difference matters because a note is only safe to drop
+ * on the first: a bearer note is money, and a flaky network must never destroy
+ * it.
+ */
+export type NoteProbe = {
+    ok: true;
+    note: ResolvedNote;
+} | {
+    ok: false;
+    reason: 'refused' | 'unreachable';
+};
+export interface NoteOps {
+    probeNote(mint: string, secret: string): Promise<NoteProbe>;
+    resolveNote(mint: string, secret: string): Promise<ResolvedNote | null>;
+    reconcile(): Promise<ReconcileReport>;
+    split(parent: StoredNote, amountMsat: number): Promise<StoredNote>;
+}
+/** Appends params to a callback URL that may already carry some. */
+export declare function callbackUrl(base: string, params: Record<string, string>): string;
+/**
+ * The note as a LUD-25 withdraw URL: the secret as `k1`, its value alongside.
+ * This is the form a wallet shows and the form a paywall is handed. The
+ * `amount` is only a claim; the mint's `maxWithdrawable` is authoritative.
+ */
+export declare function noteUrl(note: Pick<StoredNote, 'mint' | 'secret' | 'amountMsat'>): string;
+export declare function createNoteOps(store: LnurlcashNoteStore, options?: NoteOpsOptions): NoteOps;

package/build/wallet/lnurlcash-ops.js

@@ -0,0 +1,198 @@
+import { generatePreimage, computePaymentHash, fetchJson, verifyLud21 } from 'farrier-kit';
+export function isError(res) {
+    return typeof res === 'object' && res !== null && res.status === 'ERROR';
+}
+/**
+ * Mint responses are the only thing safe to surface. Anything thrown by the
+ * HTTP layer may carry a URL, and our URLs carry note secrets in the query
+ * string, so exceptions are never stringified outward.
+ */
+export class MintRefused extends Error {
+}
+/**
+ * The mint doesn't recognise a note we thought we held. Expected, not
+ * exceptional: a bearer note can be spent by anyone holding a copy, so every
+ * local balance is a cache and the mint is the only authority. Signals "drop
+ * this one and try the next", never "fail the payment".
+ */
+export class NoteGone extends Error {
+}
+const DEFAULT_HTTP_TIMEOUT_MS = 8_000;
+/** Appends params to a callback URL that may already carry some. */
+export function callbackUrl(base, params) {
+    const url = new URL(base);
+    for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, v);
+    return url.toString();
+}
+/**
+ * The note as a LUD-25 withdraw URL: the secret as `k1`, its value alongside.
+ * This is the form a wallet shows and the form a paywall is handed. The
+ * `amount` is only a claim; the mint's `maxWithdrawable` is authoritative.
+ */
+export function noteUrl(note) {
+    const url = new URL('/w', note.mint);
+    url.searchParams.set('k1', note.secret);
+    url.searchParams.set('amount', String(note.amountMsat));
+    return url.toString();
+}
+export function createNoteOps(store, options = {}) {
+    const httpTimeoutMs = options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    const get = async (url) => fetchJson(url, { timeoutMs: httpTimeoutMs, fetchImpl: options.fetchImpl });
+    /** Reads a note's current value from the mint, keeping why it failed. */
+    async function probeNote(mint, secret) {
+        let res;
+        try {
+            res = await get(callbackUrl(new URL('/w', mint).toString(), { k1: secret }));
+        }
+        catch {
+            return { ok: false, reason: 'unreachable' };
+        }
+        if (isError(res) || typeof res.maxWithdrawable !== 'number' || typeof res.callback !== 'string') {
+            return { ok: false, reason: 'refused' };
+        }
+        return { ok: true, note: { amountMsat: res.maxWithdrawable, callback: res.callback } };
+    }
+    /**
+     * Reads a note's current value from the mint. `null` means the mint doesn't
+     * recognise it: unknown, already spent, or pending another operation.
+     */
+    async function resolveNote(mint, secret) {
+        const probe = await probeNote(mint, secret);
+        return probe.ok ? probe.note : null;
+    }
+    /**
+     * Settles notes left in an indeterminate state by an earlier crash, a melt
+     * whose outcome never came back, or a note handed to a paywall that may or
+     * may not have rotated it. A provisional note the mint knows about means its
+     * split landed; one it doesn't means the split never happened. A melting note
+     * the mint still honours means the spend failed and the mint restored it.
+     */
+    async function reconcile() {
+        const recovered = [];
+        for (const note of store.byState('provisional')) {
+            const resolved = await resolveNote(note.mint, note.secret);
+            if (resolved) {
+                store.confirm(note.secret, resolved.amountMsat);
+                // A landed split burned its parent, whatever our local copy says.
+                if (note.parent)
+                    store.remove(note.parent);
+            }
+            else {
+                store.remove(note.secret);
+            }
+        }
+        // A melting note is asked about in a different order, and the order is
+        // the whole fix. Previously the mint was asked whether it still had the
+        // note, and a "no" meant remove: but "no" is exactly what a SETTLED melt
+        // looks like, because settling burns the note. The preimage the payment
+        // bought went in the bin with it.
+        //
+        // So the verify URL is consulted FIRST, while the note is still on disk.
+        // Only once settlement has been ruled out is the note's own fate asked
+        // about, and even then an unrecognised note with an unsettled verify URL
+        // is left alone rather than dropped: that is a melt still in flight.
+        for (const note of store.byState('melting')) {
+            if (note.verifyUrl && note.paymentHashHex) {
+                let result;
+                try {
+                    result = await verifyLud21({
+                        verifyUrl: note.verifyUrl,
+                        paymentHashHex: note.paymentHashHex,
+                        fetchImpl: options.fetchImpl,
+                        timeoutMs: httpTimeoutMs,
+                        ...(options.urlGuard ? { urlGuard: options.urlGuard } : {}),
+                    });
+                }
+                catch {
+                    // The mint said nothing. Nothing said is not a verdict, and this
+                    // note is holding a payment that may have landed.
+                    continue;
+                }
+                if (result?.settled) {
+                    if (result.verified && result.preimage) {
+                        const melt = {
+                            paymentHashHex: note.paymentHashHex,
+                            preimage: result.preimage,
+                            amountMsat: note.amountMsat,
+                            mint: note.mint,
+                            settledAt: new Date().toISOString(),
+                        };
+                        store.recordSettledMelt(melt);
+                        recovered.push(melt);
+                    }
+                    // Settled either way, so the note is spent and must not come back.
+                    store.remove(note.secret);
+                    continue;
+                }
+                // Not settled. If the mint still has the note the melt failed and it
+                // is spendable again; if it does not, the payment is still in flight
+                // and this note stays put with its URL for the next pass.
+                const resolved = await resolveNote(note.mint, note.secret);
+                if (resolved)
+                    store.confirm(note.secret, resolved.amountMsat);
+                continue;
+            }
+            // No proof to consult - an older record, or a mint that offered no
+            // verify URL. Nothing better than the previous behaviour is available.
+            const resolved = await resolveNote(note.mint, note.secret);
+            if (resolved)
+                store.confirm(note.secret, resolved.amountMsat);
+            else
+                store.remove(note.secret);
+        }
+        return { recovered };
+    }
+    /**
+     * Splits `parent` into a note worth exactly `amountMsat` plus change, and
+     * returns the exact-value note. A melt invoice must match the note value
+     * exactly and a paywall must not be overpaid, so this is how an arbitrary
+     * amount gets covered.
+     */
+    async function split(parent, amountMsat) {
+        const resolved = await resolveNote(parent.mint, parent.secret);
+        if (!resolved) {
+            store.remove(parent.secret);
+            throw new NoteGone('note not recognised by the mint');
+        }
+        const paySecret = generatePreimage();
+        const changeSecret = generatePreimage();
+        const addedAt = new Date().toISOString();
+        // Persisted BEFORE the request, deliberately. The mint keys the new notes
+        // to hashes of these secrets and never learns the secrets themselves, so a
+        // crash between its swap and our write would destroy the value outright.
+        store.addMany([
+            { secret: paySecret, mint: parent.mint, amountMsat, state: 'provisional', parent: parent.secret, addedAt },
+            { secret: changeSecret, mint: parent.mint, amountMsat: 0, state: 'provisional', parent: parent.secret, addedAt },
+        ]);
+        let res;
+        try {
+            res = await get(callbackUrl(resolved.callback, {
+                k1: parent.secret,
+                amount: String(amountMsat),
+                h: computePaymentHash(paySecret),
+                h2: computePaymentHash(changeSecret),
+            }));
+        }
+        catch {
+            // Outcome unknown. Leave both children provisional; reconcile() decides
+            // on the next call, once the mint can be asked again.
+            throw new MintRefused('Split outcome unknown; it will be reconciled on the next attempt');
+        }
+        if (isError(res)) {
+            // A refusal is synchronous and burns nothing, so the children are dead.
+            store.removeMany([paySecret, changeSecret]);
+            throw new MintRefused(res.reason ?? 'Mint refused the split');
+        }
+        store.remove(parent.secret);
+        store.confirm(paySecret, amountMsat);
+        const change = await resolveNote(parent.mint, changeSecret);
+        if (change)
+            store.confirm(changeSecret, change.amountMsat);
+        else
+            store.remove(changeSecret);
+        return store.find(paySecret);
+    }
+    return { probeNote, resolveNote, reconcile, split };
+}
+//# sourceMappingURL=lnurlcash-ops.js.map

package/build/wallet/lnurlcash-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnurlcash-ops.js","sourceRoot":"","sources":["../../src/wallet/lnurlcash-ops.ts"],"names":[],"mappings":"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"}

package/build/wallet/lnurlcash.js

@@ -1,40 +1,22 @@
-import { tryDecodeBolt11, bolt11AmountMsats, generatePreimage, computePaymentHash, verifyLud21, fetchJson, } from 'farrier-kit';
+import { tryDecodeBolt11, bolt11AmountMsats, verifyLud21, fetchJson, } from 'farrier-kit';
+import { createNoteOps, callbackUrl, isError, MintRefused, NoteGone, } from './lnurlcash-ops.js';
 const METHOD = 'lnurlcash';
 const DEFAULTS = {
     meltTimeoutMs: 60_000,
     meltPollMs: 1_000,
     httpTimeoutMs: 8_000,
 };
-function isError(res) {
-    return typeof res === 'object' && res !== null && res.status === 'ERROR';
-}
-/**
- * Mint responses are the only thing safe to surface. Anything thrown by the
- * HTTP layer may carry a URL, and our URLs carry note secrets in the query
- * string, so exceptions are never stringified outward.
- */
-class MintRefused extends Error {
-}
-/**
- * The mint doesn't recognise a note we thought we held. Expected, not
- * exceptional: a bearer note can be spent by anyone holding a copy, so every
- * local balance is a cache and the mint is the only authority. Signals "drop
- * this one and try the next", never "fail the payment".
- */
-class NoteGone extends Error {
-}
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
-/** Appends params to a callback URL that may already carry some. */
-function callbackUrl(base, params) {
-    const url = new URL(base);
-    for (const [k, v] of Object.entries(params))
-        url.searchParams.set(k, v);
-    return url.toString();
-}
 export function createLnurlcashWallet(store, options = {}, lock) {
     const cfg = { ...DEFAULTS, ...options };
+    const ops = createNoteOps(store, {
+        httpTimeoutMs: cfg.httpTimeoutMs,
+        fetchImpl: cfg.fetchImpl,
+        // reconcile polls verify URLs of its own now, so the guard has to reach it
+        ...(cfg.urlGuard ? { urlGuard: cfg.urlGuard } : {}),
+    });
     let internalLock = Promise.resolve();
     const defaultLock = (fn) => {
         const result = internalLock.catch(() => { }).then(() => fn());
@@ -46,95 +28,9 @@ export function createLnurlcashWallet(store, options = {}, lock) {
         timeoutMs: cfg.httpTimeoutMs,
         fetchImpl: cfg.fetchImpl,
     });
-    /**
-     * Reads a note's current value from the mint. `null` means the mint doesn't
-     * recognise it: unknown, already spent, or pending another operation.
-     */
-    async function resolveNote(mint, secret) {
-        let res;
-        try {
-            res = await get(callbackUrl(new URL('/w', mint).toString(), { k1: secret }));
-        }
-        catch {
-            return null;
-        }
-        if (isError(res) || typeof res.maxWithdrawable !== 'number' || typeof res.callback !== 'string')
-            return null;
-        return { amountMsat: res.maxWithdrawable, callback: res.callback };
-    }
-    /**
-     * Settles notes left in an indeterminate state by an earlier crash or a melt
-     * whose outcome never came back. A provisional note the mint knows about
-     * means its split landed; one it doesn't means the split never happened. A
-     * melting note the mint still honours means the payment failed and the mint
-     * restored it.
-     */
-    async function reconcile() {
-        for (const note of [...store.byState('provisional'), ...store.byState('melting')]) {
-            const resolved = await resolveNote(note.mint, note.secret);
-            if (resolved) {
-                store.confirm(note.secret, resolved.amountMsat);
-                // A landed split burned its parent, whatever our local copy says.
-                if (note.parent)
-                    store.remove(note.parent);
-            }
-            else {
-                store.remove(note.secret);
-            }
-        }
-    }
-    /**
-     * Splits `parent` into a note worth exactly `amountMsat` plus change, and
-     * returns the exact-value note. The mint requires a melt invoice to match
-     * the note value exactly, so this is how an arbitrary invoice gets paid.
-     */
-    async function split(parent, amountMsat) {
-        const resolved = await resolveNote(parent.mint, parent.secret);
-        if (!resolved) {
-            store.remove(parent.secret);
-            throw new NoteGone('note not recognised by the mint');
-        }
-        const paySecret = generatePreimage();
-        const changeSecret = generatePreimage();
-        const addedAt = new Date().toISOString();
-        // Persisted BEFORE the request, deliberately. The mint keys the new notes
-        // to hashes of these secrets and never learns the secrets themselves, so a
-        // crash between its swap and our write would destroy the value outright.
-        store.addMany([
-            { secret: paySecret, mint: parent.mint, amountMsat, state: 'provisional', parent: parent.secret, addedAt },
-            { secret: changeSecret, mint: parent.mint, amountMsat: 0, state: 'provisional', parent: parent.secret, addedAt },
-        ]);
-        let res;
-        try {
-            res = await get(callbackUrl(resolved.callback, {
-                k1: parent.secret,
-                amount: String(amountMsat),
-                h: computePaymentHash(paySecret),
-                h2: computePaymentHash(changeSecret),
-            }));
-        }
-        catch {
-            // Outcome unknown. Leave both children provisional; reconcile() decides
-            // on the next call, once the mint can be asked again.
-            throw new MintRefused('Split outcome unknown; it will be reconciled on the next attempt');
-        }
-        if (isError(res)) {
-            // A refusal is synchronous and burns nothing, so the children are dead.
-            store.removeMany([paySecret, changeSecret]);
-            throw new MintRefused(res.reason ?? 'Mint refused the split');
-        }
-        store.remove(parent.secret);
-        store.confirm(paySecret, amountMsat);
-        const change = await resolveNote(parent.mint, changeSecret);
-        if (change)
-            store.confirm(changeSecret, change.amountMsat);
-        else
-            store.remove(changeSecret);
-        return store.find(paySecret);
-    }
     /** Melts `note` against `invoice` and waits for cryptographic settlement proof. */
     async function melt(note, invoice, paymentHashHex) {
-        const resolved = await resolveNote(note.mint, note.secret);
+        const resolved = await ops.resolveNote(note.mint, note.secret);
         if (!resolved) {
             store.remove(note.secret);
             throw new NoteGone('note not recognised by the mint');
@@ -169,6 +65,12 @@ export function createLnurlcashWallet(store, options = {}, lock) {
                 reason: 'Mint accepted the melt but offers no LUD-21 verify URL, so settlement cannot be proven.',
             };
         }
+        // Persisted before the first poll, not after the last one. A melt that
+        // settles late still spends the note, and the verify URL is the only
+        // route back to the preimage it bought. Keeping it in a local variable
+        // meant a timeout - or a crash, or the process being killed - threw the
+        // credential away while the sats were already gone.
+        store.setMeltProof(note.secret, res.verify, paymentHashHex);
         const deadline = Date.now() + cfg.meltTimeoutMs;
         for (;;) {
             let result;
@@ -185,10 +87,20 @@ export function createLnurlcashWallet(store, options = {}, lock) {
                 result = undefined;
             }
             if (result?.settled) {
-                store.remove(note.secret);
                 if (result.verified && result.preimage) {
+                    // Recorded before the note goes, so a crash between the two lines
+                    // cannot lose what the payment bought.
+                    store.recordSettledMelt({
+                        paymentHashHex,
+                        preimage: result.preimage,
+                        amountMsat: note.amountMsat,
+                        mint: note.mint,
+                        settledAt: new Date().toISOString(),
+                    });
+                    store.remove(note.secret);
                     return { paid: true, preimage: result.preimage, method: METHOD };
                 }
+                store.remove(note.secret);
                 // Settled per the mint, but unproven. Same stance as the NWC provider:
                 // the note is spent either way, so it must not go back in the store.
                 return {
@@ -203,7 +115,8 @@ export function createLnurlcashWallet(store, options = {}, lock) {
                     paid: false,
                     method: METHOD,
                     outcome: 'unknown',
-                    reason: 'Melt did not settle before the timeout. The note is held pending and will be reconciled before the next payment.',
+                    verifyUrl: res.verify,
+                    reason: 'Melt did not settle before the timeout. The note is held with its verify URL, so a later reconcile can still recover the preimage if the payment lands.',
                 };
             }
             await sleep(cfg.meltPollMs);
@@ -220,8 +133,20 @@ export function createLnurlcashWallet(store, options = {}, lock) {
         if (needMsat === null) {
             return { paid: false, method: METHOD, reason: 'Amountless BOLT-11 invoices require an explicit amount and are refused' };
         }
+        // A reconcile can turn up a payment that landed after an earlier attempt
+        // gave up on it. That preimage is a credential somebody paid for, so it
+        // is said out loud here rather than only filed: the caller is a wallet
+        // asking to spend, and "by the way, that payment you wrote off did go
+        // through" changes what they do next.
+        let recoveredNote = '';
         try {
-            await reconcile();
+            const report = await ops.reconcile();
+            if (report.recovered.length > 0) {
+                const each = report.recovered
+                    .map(m => `${m.paymentHashHex.slice(0, 12)}… preimage ${m.preimage}`)
+                    .join('; ');
+                recoveredNote = ` Also recovered ${report.recovered.length} earlier melt(s) that settled after being written off: ${each}.`;
+            }
         }
         catch { /* best effort; selection below simply sees fewer notes */ }
         const live = store.live();
@@ -239,8 +164,11 @@ export function createLnurlcashWallet(store, options = {}, lock) {
             try {
                 const exact = candidate.amountMsat === needMsat
                     ? candidate
-                    : await split(candidate, needMsat);
-                return await melt(exact, invoice, decoded.paymentHashHex);
+                    : await ops.split(candidate, needMsat);
+                const result = await melt(exact, invoice, decoded.paymentHashHex);
+                return recoveredNote
+                    ? { ...result, reason: `${result.reason ?? 'Paid.'}${recoveredNote}` }
+                    : result;
             }
             catch (error) {
                 if (error instanceof NoteGone) {
@@ -259,7 +187,7 @@ export function createLnurlcashWallet(store, options = {}, lock) {
         return {
             paid: false,
             method: METHOD,
-            reason: `No note large enough: need ${needMsat} msat, largest available is ${best} msat${staleNote}`,
+            reason: `No note large enough: need ${needMsat} msat, largest available is ${best} msat${staleNote}${recoveredNote}`,
         };
     }
     return {

package/build/wallet/lnurlcash.js.map

@@ -1 +1 @@
-{"version":3,"file":"lnurlcash.js","sourceRoot":"","sources":["../../src/wallet/lnurlcash.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lnurlcash.js","sourceRoot":"","sources":["../../src/wallet/lnurlcash.ts"],"names":[],"mappings":"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"}

package/build/wallet/types.d.ts

@@ -9,6 +9,12 @@ export interface PaymentResult {
     reason?: string;
     /** The request may have executed but settlement could not be proven. */
     outcome?: 'unknown';
+    /**
+     * Where settlement can still be proven later, for an `unknown` outcome
+     * that has one. A caller holding this can ask again rather than treating
+     * the payment as lost; reconcile also polls it on its own.
+     */
+    verifyUrl?: string;
 }
 export interface WalletProvider {
     method: WalletMethod;

package/build/xlnurlcash/parse.d.ts

@@ -0,0 +1,27 @@
+export interface LnurlcashChallenge {
+    /** Price in sats. */
+    amount: number;
+    unit: 'sat';
+    /** Mints whose notes the server will accept, as hosts or URLs. */
+    mints: string[];
+}
+/** Detects whether a 402 response carries an lnurlcash challenge. */
+export declare function isLnurlcashChallenge(headers: Headers): boolean;
+/**
+ * Parses an lnurlcash payment request from the X-LNURLcash header value:
+ * `lnurlcashreq1` followed by unpadded base64url of the request's RFC 8785
+ * canonical JSON.
+ *
+ * The request is `{ v, id, amount, currency, methodDetails: { mints } }`,
+ * with the amount a decimal STRING of whole sats. That is the shape the
+ * conformance vectors pin and `lnurlcash-kit` encodes.
+ *
+ * A shorter object, `{ a: number, u, m }`, briefly went out under the same
+ * prefix before the format settled. It is still read here, because a decoder
+ * that returns nothing on a string it can plainly understand helps no one,
+ * and because the kit's own decoder accepts it too. Nothing emits it.
+ *
+ * Only `sat` exists today; anything else returns null rather than guessing at
+ * a denomination.
+ */
+export declare function parseLnurlcashChallenge(header: string): LnurlcashChallenge | null;