feat: support zero-amount BOLT11 invoices (pay cashu/spark, create spark) by orveth · Pull Request #1049 · MakePrisms/agicash

orveth · 2026-05-05T13:05:42Z

Summary

Pay zero-amount from spark (~1 line):

Relax the Continue-button predicate on the send-input screen so that a spark source account can proceed even with an empty amount field — the spark send service already accepts a user-supplied amount and the destination-validation gate already permitted amountless BOLT11 for spark.

Pay zero-amount from cashu (NUT-05 amountless):

Add ExtendedMintInfo.canMeltAmountless() (delegates to cashu-ts supportsAmountless after a NUT-05-disabled gate).
Lift the spark-only gate in send-store.ts into a shared canAccountPayAmountlessBolt11 helper that also unlocks cashu accounts whose mint advertises amountless support.
Drop the "Cashu accounts do not support amountless lightning invoices" guard in cashu-send-quote-service.ts and call wallet.createMeltQuoteBolt11(paymentRequest, amount_msat) for amountless invoices — cashu-ts wraps the options.amountless payload internally when its second arg is set.

Create zero-amount on spark (~3 changes):

Make amount?: Money optional on GetLightningQuoteParams and useCreateSparkReceiveQuote's props; conditionally include amountSats in the BreezSdk.receivePayment call.
receive-spark.tsx: pass amount: undefined when the user-entered amount is zero so the SDK creates an amountless invoice rather than a 0-sat invoice.
receive-input.tsx: drop the zero-input lockout on the Continue button for spark accounts.

Out of scope (intentionally not touched)

Min/max enforcement against mint quote response — the wallet does not enforce mint min/max anywhere today; tracked as a separate workstream.
Cashu zero-amount receive — blocked by NUT-04 spec, deferred.
No UI redesigns, no new flows or components, no refactors beyond what these workstreams require.

Test plan

bun run typecheck clean
bun run check:all clean (only pre-existing vite-env.d.ts warnings)
bun test — 126 / 126 pass (10 new, all green)
- ExtendedMintInfo.canMeltAmountless — NUT-5 disabled, no amountless method, bolt11/sat advertised, unit-mismatched
- validateBolt11 with allowZeroAmount: true — amountless passes, non-bitcoin networks still fail
- CashuSendQuoteService.getLightningQuote — confirms createMeltQuoteBolt11 is called with the user-supplied amount in msat for amountless invoices, without it for amounted invoices
E2E smoke test against a NUT-05-amountless mint and a spark wallet — to be driven by alchemist after this PR is open

Notes for reviewers

A small app/test-setup.ts is registered via bunfig.toml [test] preload. It polyfills window, window.location, and window.localStorage for the bun test environment so service modules that transitively load agicash-db/database.client.ts (which references window at module scope) can be imported in tests. The polyfill is gated by typeof === 'undefined' checks so it is a no-op in any environment that already provides those globals.
canAccountPayAmountlessBolt11 is exported from send-store.ts so the send-input button predicate uses the same gate as the destination validator — cashu and spark behave identically.

vercel · 2026-05-05T13:05:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agicash	Ready	Preview, Comment	Jun 5, 2026 10:17pm

supabase · 2026-05-05T13:05:50Z

This pull request has been ignored for the connected project hrebgkfhjpkbxpztqqke because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

gudnuf · 2026-05-05T20:30:41Z

    ? new Money({ amount: invoice.amountMsat, currency: 'BTC', unit: 'msat' })
-    : (amount as Money<'BTC'>);
+    : ((amount as Money<'BTC'> | undefined) ??
+      new Money({ amount: 0, currency: 'BTC', unit: 'sat' }));


we should make sure that when the quote gets completed the amount paid is properly updated in the encrypted transaction details

or maybe even better to change the type to amount can be undefined

or maybe even better to change the type to amount can be undefined

what do you mean? what would be undefined?

Wired up in cebf851. The actual paid amount from the SDK paymentSucceeded event (payment.amount) is now propagated through useOnSparkReceiveStateChange -> completeReceiveQuote mutation -> SparkReceiveQuoteService.complete(..., paidAmount). The repository re-encrypts quote.amount = paidAmount into the SparkLightningReceiveDbDataSchema, which the existing complete_spark_receive_quote SQL function writes to both spark_receive_quotes.encrypted_data and transactions.encrypted_transaction_details in the same transaction. Same path is used in claim-cashu-token-service.ts (cashu-token-to-spark receive) for consistency.

Took the simpler route per the facilitator decision: keep amount: Money required throughout the wallet code (zero-Money encodes "amountless"), and convert to undefined only at the literal wallet.receivePayment call site via a ternary. See a2a31ef. Push back if you prefer the optional-Money plumbing instead and I will redo it.

That alt is moot now — the design landed in a2a31ef does not propagate undefined at all. Internally amount stays a non-optional Money and the only undefined is at the literal SDK call: amountSats: amount.isZero() ? undefined : amount.toNumber('sat'). Zero-Money encodes the amountless case.

or maybe even better to change the type to amount can be undefined

what do you mean? what would be undefined?

the amount is undefined. The amount is not yet set until the payer chooses how much to send.

gudnuf · 2026-05-05T20:50:16Z

+   * via NUT-05 melt for the given method and unit. NUT-05 must be enabled
+   * and at least one method entry must advertise `options.amountless = true`.
+   */
+  canMeltAmountless(method = 'bolt11', unit = 'sat'): boolean {


I don't think this belongs here its not a. protocol extention. Also, why do we need a new method for it. mintInfo.supportsAmountless(method, unit) is probably sufficient.

Removed in 0273718. The wrapper added no agicash-specific logic; the only consumer (canAccountPayAmountlessBolt11 in send-store.ts) now calls mintInfo.supportsAmountless('bolt11', unit) directly. cashu-ts's supportsAmountless does not check the NUT-05 disabled flag, so I kept that as a single inline guard at the call site. Tests for the gating logic moved from protocol-extensions.test.ts to send-store.test.ts.

jbojcic1 · 2026-05-06T12:46:39Z

-      createQuote({ account, amount });
+      createQuote({
+        account,
+        amount: amount.isZero() ? undefined : amount,


is this needed? would it work if we just pass zero amount instead of undefined?

Simplified per your suggestion in a2a31ef — receive-spark.tsx now passes amount straight through. The amount.isZero() ? undefined : amount.toNumber('sat') ternary lives only at the literal Breez SDK call site in spark-receive-quote-core.ts.

jbojcic1 · 2026-05-06T12:50:14Z

        type: 'bolt11Invoice',
        description: description ?? '',
-        amountSats: amount.toNumber('sat'),
+        ...(amount !== undefined && { amountSats: amount.toNumber('sat') }),


why not amountSats: amount ? amount.toNumber('sat') : undefined?

Applied in a2a31ef. Now: amountSats: amount.isZero() ? undefined : amount.toNumber('sat').

jbojcic1 · 2026-05-06T12:57:08Z

why is this needed?

Investigated and added a docstring in 0402c44. Two module-load failures in agicash-db/database.client.ts make the polyfill necessary:

(window as any).agicashRealtime = agicashRealtimeClient; at module top level (no typeof guard).

createClient(...) triggers a Supabase auth fetch that calls isLoggedIn() -> window.localStorage.getItem(...), also without a typeof guard.

I tried mock.module('~/features/agicash-db/database.client', ...) from inside cashu-send-quote-service.test.ts, but it does not work: bun hoists the static import { CashuSendQuoteService } above any mock.module() call in the same file, so the real database.client.ts evaluates first and throws ReferenceError: window is not defined before the mock can register. Verified by removing the preload and running the test.

Two alternatives to the polyfill, neither obviously better:

Make database.client.ts/auth.ts SSR-safe (guard the window references with typeof window !== 'undefined'). Cleaner long-term but is a non-test runtime change.

Use a separate mock.module() preload file instead of the polyfill. Same shape as today, just a different mechanism.

Kept the polyfill and added a docstring explaining exactly which lines trigger which failure. Happy to take either alternative if you'd prefer one over the other.

jbojcic1 · 2026-05-06T13:09:55Z

    ? new Money({ amount: invoice.amountMsat, currency: 'BTC', unit: 'msat' })
-    : (amount as Money<'BTC'>);
+    : ((amount as Money<'BTC'> | undefined) ??
+      new Money({ amount: 0, currency: 'BTC', unit: 'sat' }));


or maybe even better to change the type to amount can be undefined

what do you mean? what would be undefined?

…ark) Rebased onto post-monorepo master; paths relocated app/ -> apps/web-wallet/app/ (bunfig.toml -> apps/web-wallet/bunfig.toml). 3-way merge; resolved send-input.tsx (master restructured surrounding JSX) + bunfig.toml newline. Original commits: - feat(send): pay amountless BOLT11 invoices from spark accounts - feat(send): pay amountless BOLT11 invoices from cashu accounts (NUT-05 amountless) - feat(receive): create amountless BOLT11 invoices on spark accounts - test: cover canMeltAmountless + amountless melt-quote path - fix(receive-spark): record actual paid amount on quote completion - refactor(receive-spark): keep amount: Money internal, convert at SDK boundary - refactor(cashu): use supportsAmountless directly, drop canMeltAmountless wrapper - chore(test): document why test-setup polyfill is required

vercel Bot deployed to Preview May 5, 2026 13:06 View deployment

jbojcic1 self-assigned this May 5, 2026

orveth assigned gudnuf May 5, 2026

gudnuf reviewed May 5, 2026

View reviewed changes

jbojcic1 reviewed May 6, 2026

View reviewed changes

vercel Bot deployed to Preview May 6, 2026 13:32 View deployment

orveth force-pushed the cashu-zero-amount-invoices branch from 0402c44 to bfffd92 Compare June 5, 2026 22:16

vercel Bot deployed to Preview June 5, 2026 22:17 View deployment

Uh oh!

Conversation

orveth commented May 5, 2026

Summary

Out of scope (intentionally not touched)

Test plan

Notes for reviewers

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

supabase Bot commented May 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented May 5, 2026 •

edited

Loading