feat(moneydevkit.com, sdk): waitForPayoutResult handler + SDK helper (#777)

mdk.com side:
- New checkout.waitForPayoutResult oRPC handler that blocks until the
  programmatic_payout / withdrawal row identified by idempotencyKey or
  paymentId reaches a terminal Lightning state. Two-path wake strategy:
  fast in-process waiter on the live WS session (when on this task),
  with a 2s DB poll as the cross-task backstop. On timeout the response
  is {status:'REQUESTED'} so SDK callers can loop without try/catch.
- Refactors payment-waiters to Map<paymentId, Set<waiter>> so the
  autopayout retry loop and an SDK caller can both subscribe to the
  same paymentId outcome without one stealing it from the other. Each
  waiter owns its own timer; one expiring doesn't disturb the others.

SDK (mdk-checkout/packages/core):
- waitForPayoutResult() export: server-only, loops the underlying RPC
  when the caller's total budget exceeds the 25s per-call cap.
- programmaticPayout.amountSats is now optional: the SDK decodes the
  amount locally for fixed-amount BOLT11 destinations. amountless
  BOLT11, LNURL, lightning addresses, and BOLT12 still require an
  explicit amountSats. Caller passing an amountSats that disagrees
  with the BOLT11 is rejected up-front because lightning-js's
  FixedAmount branch silently pays the BOLT11 amount.
- New bolt11.ts amount parser (msat-precise, sat-granular only).

Depends on @moneydevkit/api-contract@0.1.32 (PR #776). Until that is
published, package.json points at a local tarball; before final merge
this needs to swap back to "0.1.32" and the lockfile regenerated.

Includes 16 BOLT11 unit tests, 9 SDK waitForPayoutResult tests, 7
multi-subscriber waiter tests, 10 mdk.com handler tests, and the
existing payout/autopayout test suites still pass.

Author: martinsaposnic

packages/core/src/bolt11.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal BOLT11 amount parser. Extracts the invoice amount in sats from the
+ * human-readable part of a BOLT11 string. Returns `null` for an amountless
+ * invoice or for input that doesn't look like a BOLT11 we recognize.
+ *
+ * Recognized HRP prefixes (case-insensitive):
+ *   lnbc    Bitcoin mainnet
+ *   lntb    Bitcoin testnet
+ *   lntbs   Bitcoin signet
+ *   lnsb    Bitcoin signet (alternate)
+ *   lnbcrt  Bitcoin regtest
+ *
+ * Multiplier rules per BOLT 11 (value = pico-BTC * 10^decimal-shift):
+ *   m (milli): X * 100_000 sats
+ *   u (micro): X * 100 sats
+ *   n (nano):  X / 10 sats           (must be divisible by 10)
+ *   p (pico):  X / 10_000 sats       (must be divisible by 10_000)
+ *   (none):    X * 100_000_000 sats  (X is whole-BTC)
+ *
+ * Sub-sat amounts (e.g. lnbc1p... = 0.0001 sats) return null because the
+ * caller is comparing to a sat-precision cap.
+ *
+ * No bech32 / signature validation. Mints from a healthy L402 server are
+ * well-formed; this is amount extraction only.
+ */
+export function decodeBolt11AmountSats(invoice: string): number | null {
+  if (typeof invoice !== 'string') return null
+  // Strip optional URI prefix and leading whitespace.
+  const trimmed = invoice.trim().replace(/^lightning:/i, '')
+  const match = trimmed.match(/^ln(?:bcrt|bc|tbs|tb|sb)(\d+)?([munp])?1/i)
+  if (!match) return null
+  const digits = match[1]
+  const mult = match[2]?.toLowerCase()
+  // Amountless invoice: HRP ends at the bech32 separator with no integer part.
+  if (!digits) return null
+  const amount = Number(digits)
+  if (!Number.isFinite(amount) || amount <= 0) return null
+
+  switch (mult) {
+    case 'm':
+      return amount * 100_000
+    case 'u':
+      return amount * 100
+    case 'n':
+      return amount % 10 === 0 ? amount / 10 : null
+    case 'p':
+      return amount % 10_000 === 0 ? amount / 10_000 : null
+    case undefined:
+      // No multiplier: amount is in whole BTC.
+      return amount * 100_000_000
+    default:
+      return null
+  }
+}

packages/core/src/server.ts

@@ -6,17 +6,30 @@ import {
   contract,
   type GetBalanceResult,
   type ProgrammaticPayoutResult,
+  type WaitForPayoutResultOutput,
 } from '@moneydevkit/api-contract'
 
+import { decodeBolt11AmountSats } from './bolt11'
 import { MAINNET_MDK_BASE_URL } from './mdk-config'
 import { failure, success, type MdkError, type Result } from './types'
 
 /**
  * Options accepted by the server-only programmatic payout helper.
+ *
+ * `amountSats` is optional: when the destination is a fixed-amount BOLT11 the
+ * SDK decodes the amount locally. Variable-amount destinations (LNURL,
+ * lightning address, amountless BOLT11, BOLT12 invreq) still require an
+ * explicit `amountSats`. If both are supplied and a fixed BOLT11 says
+ * otherwise, the call is rejected before it hits the wire so a misconfigured
+ * caller can't pay a different amount than they think they are paying.
  */
 export type ProgrammaticPayoutOptions = {
-  /** Amount to send, in sats. */
-  amountSats: number
+  /**
+   * Amount to send, in sats. Optional when the destination is a fixed-amount
+   * BOLT11; required for amountless BOLT11, LNURL, lightning addresses, and
+   * BOLT12 destinations.
+   */
+  amountSats?: number
   /** Lightning destination to pay from this server-side request. */
   destination: string
   /**
@@ -28,6 +41,24 @@ export type ProgrammaticPayoutOptions = {
   idempotencyKey: string
 }
 
+/**
+ * Options accepted by the server-only waitForPayoutResult helper. Caller
+ * identifies the payout by EITHER the idempotencyKey used at dispatch OR the
+ * paymentId returned by the dispatch. Exactly one is required.
+ */
+export type WaitForPayoutResultOptions = {
+  /** The idempotencyKey passed to programmaticPayout, if known. */
+  idempotencyKey?: string
+  /** The paymentId returned by programmaticPayout, if known. */
+  paymentId?: string
+  /**
+   * Total wait budget in milliseconds. Defaults to 15s. Values above 25s are
+   * split into multiple back-to-back RPC calls so each individual call stays
+   * inside common edge-proxy idle timeouts.
+   */
+  timeoutMs?: number
+}
+
 /**
  * Errors the SDK classifies as definitely-retryable. The same call with the
  * same idempotency key can safely be sent again; mdk.com will dedupe.
@@ -114,13 +145,6 @@ export async function programmaticPayout(
     })
   }
 
-  if (!Number.isInteger(options.amountSats) || options.amountSats <= 0) {
-    return failure({
-      code: 'invalid_amount',
-      message: 'Enter a positive whole-sat amount before triggering a payout.',
-      retryable: false,
-    })
-  }
   const destination = options.destination.trim()
   if (!destination || destination.length > 4096) {
     return failure({
@@ -145,6 +169,44 @@ export async function programmaticPayout(
     })
   }
 
+  // Resolve the effective amount AFTER cheap input rejections.
+  //   1. Caller passed amountSats: validate it. If destination is a
+  //      fixed-amount BOLT11 with a different amount, reject - the user
+  //      almost certainly has a bug, and lightning-js's FixedAmount branch
+  //      would silently pay the BOLT11 amount and ignore the caller.
+  //   2. Caller omitted amountSats and destination is fixed-amount BOLT11:
+  //      decode the amount locally and use it.
+  //   3. Caller omitted amountSats and destination is variable (LNURL,
+  //      lightning address, amountless BOLT11, BOLT12): reject.
+  const bolt11AmountSats = decodeBolt11AmountSats(destination)
+  let effectiveAmountSats: number
+  if (typeof options.amountSats === 'number') {
+    if (!Number.isInteger(options.amountSats) || options.amountSats <= 0) {
+      return failure({
+        code: 'invalid_amount',
+        message: 'Enter a positive whole-sat amount before triggering a payout.',
+        retryable: false,
+      })
+    }
+    if (bolt11AmountSats !== null && bolt11AmountSats !== options.amountSats) {
+      return failure({
+        code: 'amount_mismatch',
+        message: `BOLT11 invoice amount (${bolt11AmountSats} sats) does not match the amountSats passed (${options.amountSats}). Remove amountSats or pass the matching value.`,
+        retryable: false,
+      })
+    }
+    effectiveAmountSats = options.amountSats
+  } else if (bolt11AmountSats !== null) {
+    effectiveAmountSats = bolt11AmountSats
+  } else {
+    return failure({
+      code: 'amount_required',
+      message:
+        'amountSats is required for amountless BOLT11, LNURL, lightning address, and BOLT12 destinations.',
+      retryable: false,
+    })
+  }
+
   const accessToken = process.env.MDK_ACCESS_TOKEN
   if (!accessToken) {
     return failure({
@@ -164,7 +226,7 @@ export async function programmaticPayout(
     })
     const client: ContractRouterClient<typeof contract> = createORPCClient(link)
     const result = await client.checkout.programmaticPayout({
-      amountSats: options.amountSats,
+      amountSats: effectiveAmountSats,
       destination,
       idempotencyKey: options.idempotencyKey,
     })
@@ -258,3 +320,102 @@ export async function getBalance(): Promise<Result<GetBalanceResult>> {
     })
   }
 }
+
+/** Per-RPC timeout cap. Matches the contract's server-side ceiling. */
+const WAIT_FOR_PAYOUT_RPC_MAX_MS = 25_000
+
+/** Default total wait budget when the caller does not specify timeoutMs. */
+const WAIT_FOR_PAYOUT_DEFAULT_MS = 15_000
+
+/**
+ * Block until a previously-dispatched programmatic payout reaches a terminal
+ * Lightning outcome (SUCCESS or FAILED), or the wait budget is exhausted.
+ *
+ * Pass EITHER the idempotencyKey used at dispatch OR the paymentId returned
+ * by it. Exactly one is required.
+ *
+ * If the call returns `status: 'REQUESTED'` the merchant node has not yet
+ * observed paymentSent / paymentFailed for this payment. Callers can re-invoke
+ * to keep waiting; idempotency keys / paymentIds are stable across retries.
+ *
+ * `timeoutMs` over 25s is split into multiple back-to-back RPC calls so each
+ * individual call stays inside common edge-proxy idle timeouts. The function
+ * itself stops at the total budget.
+ */
+export async function waitForPayoutResult(
+  options: WaitForPayoutResultOptions,
+): Promise<Result<WaitForPayoutResultOutput>> {
+  if (typeof window !== 'undefined') {
+    return failure({
+      code: 'server_only',
+      message: 'waitForPayoutResult() can only be called from a server function.',
+      retryable: false,
+    })
+  }
+
+  const hasIdempotencyKey =
+    typeof options.idempotencyKey === 'string' && options.idempotencyKey.length > 0
+  const hasPaymentId = typeof options.paymentId === 'string' && options.paymentId.length > 0
+  if (hasIdempotencyKey === hasPaymentId) {
+    return failure({
+      code: 'invalid_arguments',
+      message: 'Pass exactly one of idempotencyKey or paymentId.',
+      retryable: false,
+    })
+  }
+
+  const totalBudgetMs = Math.max(options.timeoutMs ?? WAIT_FOR_PAYOUT_DEFAULT_MS, 1)
+  const accessToken = process.env.MDK_ACCESS_TOKEN
+  if (!accessToken) {
+    return failure({
+      code: 'missing_access_token',
+      message: 'Set MDK_ACCESS_TOKEN in your environment before waiting on a payout.',
+      retryable: false,
+    })
+  }
+  const baseUrl = process.env.MDK_API_BASE_URL ?? MAINNET_MDK_BASE_URL
+
+  const link = new RPCLink({
+    url: baseUrl,
+    headers: () => ({ 'x-api-key': accessToken }),
+  })
+  const client: ContractRouterClient<typeof contract> = createORPCClient(link)
+
+  const deadline = Date.now() + totalBudgetMs
+
+  // Loop the underlying RPC until terminal or until our budget runs out. Each
+  // RPC carries at most WAIT_FOR_PAYOUT_RPC_MAX_MS of wait. A REQUESTED reply
+  // means the server-side timer elapsed without a terminal event; we
+  // re-attempt with the remaining budget.
+  let lastResult: WaitForPayoutResultOutput | undefined
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now()
+    const sliceMs = Math.min(remaining, WAIT_FOR_PAYOUT_RPC_MAX_MS)
+    try {
+      const result = await client.checkout.waitForPayoutResult({
+        idempotencyKey: options.idempotencyKey,
+        paymentId: options.paymentId,
+        timeoutMs: sliceMs,
+      })
+      lastResult = result
+      if (result.status !== 'REQUESTED') {
+        return success(result)
+      }
+      // Still pending: loop with the remaining budget if any.
+    } catch (err) {
+      if (err instanceof ORPCError) {
+        return failure(classifyOrpcError(err))
+      }
+      return failure({
+        code: 'wait_for_payout_result_failed',
+        message: err instanceof Error ? err.message : String(err),
+        retryable: true,
+      })
+    }
+  }
+
+  // Budget exhausted. Return the last observed snapshot (REQUESTED) so the
+  // caller can decide whether to loop or give up. The shape mirrors a normal
+  // server response.
+  return success(lastResult ?? { status: 'REQUESTED' })
+}

packages/core/tests/bolt11.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { decodeBolt11AmountSats } from '../src/bolt11'
+
+test('decodes a typical milli-bitcoin mainnet invoice (lnbc10m...)', () => {
+  // 10 milli-BTC = 0.01 BTC = 1_000_000 sats
+  assert.equal(decodeBolt11AmountSats('lnbc10m1pdummyrest'), 1_000_000)
+})
+
+test('decodes a typical micro-bitcoin mainnet invoice (lnbc1500u...)', () => {
+  // 1500 micro-BTC = 150_000 sats
+  assert.equal(decodeBolt11AmountSats('lnbc1500u1pdummyrest'), 150_000)
+})
+
+test('decodes a nano-bitcoin invoice that is a whole-sat amount (lnbc2500n...)', () => {
+  // 2500 nano-BTC = 250 sats
+  assert.equal(decodeBolt11AmountSats('lnbc2500n1pdummyrest'), 250)
+})
+
+test('returns null for a nano-bitcoin invoice that is sub-sat granular', () => {
+  // 25 nano-BTC = 2.5 sats; not representable in sats.
+  assert.equal(decodeBolt11AmountSats('lnbc25n1pdummyrest'), null)
+})
+
+test('returns null for any pico-bitcoin invoice below 10000p (sub-sat)', () => {
+  // 1000 pico-BTC = 0.1 sats. Reject.
+  assert.equal(decodeBolt11AmountSats('lnbc1000p1pdummyrest'), null)
+})
+
+test('decodes a pico-bitcoin invoice that is sat-granular (lnbc10000p...)', () => {
+  // 10000 pico-BTC = 1 sat.
+  assert.equal(decodeBolt11AmountSats('lnbc10000p1pdummyrest'), 1)
+})
+
+test('decodes a no-multiplier invoice as whole BTC', () => {
+  // lnbc11... -> 1 BTC = 100_000_000 sats
+  assert.equal(decodeBolt11AmountSats('lnbc11pdummyrest'), 100_000_000)
+})
+
+test('returns null for an amountless invoice (lnbc1...)', () => {
+  assert.equal(decodeBolt11AmountSats('lnbc1pdummyrest'), null)
+})
+
+test('recognizes the testnet HRP prefix (lntb)', () => {
+  assert.equal(decodeBolt11AmountSats('lntb500u1pdummyrest'), 50_000)
+})
+
+test('recognizes the regtest HRP prefix (lnbcrt) BEFORE the mainnet prefix', () => {
+  // The regtest prefix shares the lnbc stem; if matched non-greedily this
+  // would erroneously parse `lnbcrt500u...` as mainnet with amount=rt500u.
+  // The regex puts lnbcrt before lnbc to win the precedence race.
+  assert.equal(decodeBolt11AmountSats('lnbcrt500u1pdummyrest'), 50_000)
+})
+
+test('recognizes the signet HRP prefix (lntbs)', () => {
+  assert.equal(decodeBolt11AmountSats('lntbs100u1pdummyrest'), 10_000)
+})
+
+test('strips the lightning: URI scheme before parsing', () => {
+  assert.equal(decodeBolt11AmountSats('lightning:lnbc1500u1pdummy'), 150_000)
+})
+
+test('trims surrounding whitespace before parsing', () => {
+  assert.equal(decodeBolt11AmountSats('   lnbc1500u1pdummy   '), 150_000)
+})
+
+test('case-insensitive HRP and multiplier (uppercase BOLT11 form)', () => {
+  // BOLT11 can be uppercase (e.g. QR codes); the wire form is normally lower
+  // but the spec allows uppercase as long as it isn't mixed.
+  assert.equal(decodeBolt11AmountSats('LNBC1500U1PDUMMY'), 150_000)
+})
+
+test('rejects garbage input', () => {
+  assert.equal(decodeBolt11AmountSats('not an invoice'), null)
+  assert.equal(decodeBolt11AmountSats(''), null)
+  // @ts-expect-error - explicitly testing wrong-type guard
+  assert.equal(decodeBolt11AmountSats(null), null)
+})
+
+test('rejects amount=0 (BOLT11 forbids; treat as malformed)', () => {
+  assert.equal(decodeBolt11AmountSats('lnbc0u1pdummyrest'), null)
+})