mdk-cloudflare

Lightning payments for Cloudflare Workers via a SQLite-backed Durable Object.

mdk-cloudflare is the backend package in this repo. It gives you:

• LightningNode, a Durable Object class that runs LDK compiled to WASM
• Worker-safe checkout, payment, and node APIs
• createUnifiedHandler(), an upstream-style /api/mdk route for MoneyDevKit checkout flows

Documentation:

• Repo README: https://github.com/johncantrell97/mdk-cloudflare/blob/main/README.md
• Integration docs: https://github.com/johncantrell97/mdk-cloudflare/blob/main/HOSTED_CHECKOUT_SETUP.md
• Architecture guide: https://github.com/johncantrell97/mdk-cloudflare/blob/main/ARCHITECTURE.md
• Agent integration guide: https://github.com/johncantrell97/mdk-cloudflare/blob/main/llms.txt

Install

npm install mdk-cloudflare

Current public support: mainnet only.

Quick Start

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "strict": true,
    "noEmit": true,
    "types": ["@cloudflare/workers-types"]
  }
}

wrangler.toml

compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

[[durable_objects.bindings]]
name = "LIGHTNING_NODE"
class_name = "LightningNode"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["LightningNode"]

Important:

• Use new_sqlite_classes, not new_classes.
• Re-export LightningNode from your Worker entry.

worker.ts

import { LightningNode, createUnifiedHandler } from 'mdk-cloudflare'

export { LightningNode }

interface Env {
  LIGHTNING_NODE: DurableObjectNamespace<LightningNode>
  MDK_ACCESS_TOKEN: string
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url)
    const node = env.LIGHTNING_NODE.get(env.LIGHTNING_NODE.idFromName('default'))

    if (url.pathname === '/api/mdk') {
      return createUnifiedHandler({
        node,
        accessToken: env.MDK_ACCESS_TOKEN,
      })(request)
    }

    return new Response('Not found', { status: 404 })
  },
}

Secrets:

wrangler secret put MNEMONIC
wrangler secret put MDK_ACCESS_TOKEN

For local development with wrangler dev, put those values in .dev.vars next to wrangler.toml.

/api/mdk uses MDK_ACCESS_TOKEN for inbound secret-authenticated MDK server requests. MoneyDevKit Standard Webhooks for app-level events are a separate integration and should use their own endpoint and whsec_... signing secret.

What /api/mdk Supports

createUnifiedHandler() handles:

• create_checkout
• get_checkout
• confirm_checkout
• list_products
• get_customer
• signed GET /api/mdk?action=createCheckout...
• webhook forwarding with secret auth

API Shape

All node methods are called through DO RPC on the stub returned by env.LIGHTNING_NODE.get(...).

const checkout = await node.createCheckout({ amount: 1000, currency: 'SAT' })
const confirmed = await node.confirmCheckout({ checkoutId: checkout.id })
const current = await node.getCheckout(checkout.id)
const products = await node.listProducts()
const customer = await node.getCustomer({ email: 'buyer@example.com' })
const payment = await node.pay('lnbc10u1p...')
const nodeId = await node.getNodeId()
const info = await node.getNodeInfo()
const debug = await node.debug()

Utilities are also exported:

import {
  createCheckoutUrl,
  createUnifiedHandler,
  resolveDestinationToInvoice,
  parseBolt11AmountMsat,
  setLogLevel,
} from 'mdk-cloudflare'

Pairing With React Checkout

If you also want drop-in buyer-facing checkout pages, install:

npm install mdk-cloudflare-react

Then keep your Worker serving /api/mdk and mount the React package in your frontend.

Docs:

• React package docs: https://github.com/johncantrell97/mdk-cloudflare/blob/main/packages/checkout-react/README.md
• React package source: https://github.com/johncantrell97/mdk-cloudflare/tree/main/packages/checkout-react

Examples

• Basic Worker: https://github.com/johncantrell97/mdk-cloudflare/tree/main/examples/basic-worker
• React + Vite hosted checkout: https://github.com/johncantrell97/mdk-cloudflare/tree/main/examples/react-vite-worker
• React Router hosted checkout: https://github.com/johncantrell97/mdk-cloudflare/tree/main/examples/react-router-worker