Inspiration

P2P Bitcoin trading is how most Africans actually buy and sell Bitcoin — WhatsApp groups, Telegram channels, in-person cash meets. But the tools are broken in three ways:

  1. Custodial platforms hold your keys. If they rug, you lose everything.
  2. Manual OTC has no escrow. Every trade is counterparty risk — send first and pray.
  3. Lightning wallets like Phoenix auto-claim preimages, so you can't do a hold-invoice escrow even if you wanted to.

We needed a way to do escrow on Lightning that is non-custodial (no one holds your funds), trust-minimised (settlement is enforced by math and the protocol chain, not a middleman), and works for small trades (the infrastructure cost can't exceed the trade value). A trade too small to justify a $50/mo VPS still needs escrow.

What it does

PontHTLC is a non-custodial Lightning escrow for P2P Bitcoin trades. Three parties coordinate without trusting each other:

  1. Seller originates a 32-byte preimage $P$, splits it 2-of-3 Shamir, and publishes $H = \text{sha256}(P)$ via Nostr.
  2. Buyer registers $H$ on a Lightning hold invoice (without knowing $P$) and signs a BOLT11 invoice.
  3. Seller funds the invoice; the HTLC stays in-flight. The buyer's node sees PaymentClaimable { preimage: None } — hold verified.
  4. Settlement: buyer reconstructs $P$ from two Shamir shares, calls claim_funds(P), and the seller auto-discovers $P$ from the PaymentSent event.
  5. Dispute: if buyer and seller disagree, either can open a dispute. The daemon (node operator) holds $s_3$ as the resolver — the seller submits it after funding via POST /api/escrow/:id/arb-share. During dispute resolution the daemon releases $s_3$ so the buyer can reconstruct $P$.
  6. Expiry: if the claim_deadline passes, LDK auto-fails the HTLC back to the seller.

The key: no single party can settle alone. Two of three shares are needed to reconstruct $P$. The buyer holds $s_1$, the seller holds $s_2$, and the daemon holds $s_3$. Not the buyer, not the seller, not even the daemon acting alone.

How we built it

Week 1: De-risking spike

We started by proving the core LDK primitive works on regtest. The spike (crates/spike) spins up two LDK nodes (buyer + seller) against a bitcoind regtest container and runs three scenarios:

  • Happy: seller funds → buyer reconstructs $P$ → claim_funds(P) → seller sees PaymentSent.
  • Fail: buyer calls fail_htlc_backwards → seller sees PaymentFailed.
  • Hold: mine past claim_deadline → LDK auto-fails.

All three pass against lightning 0.2.7 on regtest.

Hosted node architecture

The spike proved the primitive, but requiring every trader to run an LDK node is uneconomical. So we pivoted to a hosted node service:

  • A service provider runs one ponthtlc daemon (LDK + bitcoind) serving hundreds of users.
  • Users interact via a browser SPA (Svelte) + Nostr (NIP-59 gift-wrapped messages for share delivery).
  • The preimage is reconstructed client-side in the browser — the hosted node never stores $P$, only passes it through to claim_funds(P).

Non-custodiality survives without running your own node: the host holds $s_3$ but cannot reconstruct $P$ from it alone (it needs $s_1$ or $s_2$). API calls are identified by X-Nostr-Pubkey (not a signature by default), with opt-in NIP-98-style signed authentication (--require-auth). The daemon signs through the protocol reducer (apply_action) before any money move, and the HTLC fails back to the seller if the host rugs.

Event-driven relay model

The relay is the coordination surface, not a notification afterthought. On startup the daemon fetches kind 7300/7301 event chains for every known escrow and reconciles local state (reconcile_all_from_relay). HTTP endpoints are thin wrappers: they sign an action event, persist it locally, publish it to the relay, and return the reconstructed state. The POST /api/escrow/:id/action endpoint accepts client-signed kind 7301 events so a browser holding the user's Nostr key can submit swap/fiat_sent and core/accept without the daemon re-signing. Publish failures retry (3 attempts with backoff).

Durable intent and event observation

Money moves (claim, fail, resolve) persist the full event chain and mark a durable claim_pending / fail_pending intent before calling the LDK node. The auto-payout observer promotes the status to settled / refunded only when PaymentSent / PaymentFailed is observed on the LDK event stream. On restart, pending fail intents are re-submitted (claim intents rely on LDK retaining the pending claim).

The 2-of-3 Shamir split

The preimage $P$ is split using GF($2^8$) Shamir secret sharing:

$$P = \text{combine}(s_i, s_j) \quad \text{for any } i \neq j \in {1, 2, 3}$$

  • $s_1 \to$ Buyer (delivered via Nostr at originate time, before the hold invoice is created)
  • $s_2 \to$ Seller (self-kept)
  • $s_3 \to$ Daemon / node operator (submitted by the seller after funding via POST /api/escrow/:id/arb-share)

No single share reveals anything. Any two reconstruct $P$. The daemon cannot reconstruct $P$ from $s_3$ alone — it needs $s_1$ (buyer) or $s_2$ (seller).

Pontmore protocol conformance

We conform to the existing pontmore/swap@1 profile (Experimental, PIP-02 v2). The profile already defines the full escrow kernel — core/secure, core/settle, core/refund, core/authorize_settlement, core/authorize_refund, core/open_dispute, core/resolve_dispute, core/expire. Our Shamir split is an implementation-private extension within the swap profile's private-payload boundary; it does not alter the public root or action schema.

LDK primitive pontmore/swap@1 action
create_inbound_payment_for_hash(H) (setup)
pay_for_bolt11_invoice(...) core/secure
claim_funds(P) core/authorize_settlement + core/settle
fail_htlc_backwards(H) core/authorize_refund + core/refund
mine past claim_deadline core/expire
daemon releases $s_3$ core/open_dispute + core/resolve_dispute

Challenges we ran into

LDK 0.2.7 API drift

The spike took 5+ compile-fix iterations because lightning resolved to 0.2.7 (not 0.2.0), and the API had drifted from the sample code:

  • get_and_clear_pending_events() is #[cfg(test)]-only — not available in production builds. Switched to process_pending_events_async(handler).
  • process_pending_htlc_forwards() is a separate method that fires PaymentClaimable — without it, the event never arrives.
  • peer_manager.process_events() drains pending_msg_events — without it, the SendOpenChannel message never reaches the peer and the channel handshake stalls silently.
  • KVStoreSyncWrapper is required to bridge FilesystemStore (sync) to the async persister.
  • lightning-invoice ships with empty default features — current_timestamp() is behind #[cfg(feature = "std")].

Each took a debugging cycle to discover, but the spike passing was the moment we knew the architecture was sound.

Channel capacity vs. trade size

The default max_htlc_value_in_flight_msat is ~10% of channel value. A 200,000-sat channel can only carry 20,000-sat HTLCs — too small for a 50,000-msat trade. We had to increase the channel value to 1,000,000 sats.

Non-custodiality without your own node

The hardest design question: how do you stay non-custodial when the user doesn't run their own node? The answer is client-side preimage reconstruction — the browser reconstructs $P$ from Shamir shares and POSTs it to the API. The hosted node is a pass-through, not a custodian. The daemon holds $s_3$ as the resolver but cannot reconstruct $P$ from it alone. Same trust model as a payment processor seeing a card number in transit: they can't use it to authorize a different transfer.

Reducer-gated money moves

A critical bug discovered during the audit: the daemon signed events after calling node.claim / node.fail, meaning a crash between the LDK call and the event append left the HTLC settled but the chain behind. We fixed this by introducing apply_action (which enforces prev == tip and advances the chain), persisting the full event batch atomically before the LDK call, and marking a durable claim_pending / fail_pending intent that the auto-payout observer promotes to terminal only when the LDK event is observed.

Accomplishments that we're proud of

  • All three spike scenarios pass against lightning 0.2.7 on regtest — the core non-custodial hold-invoice primitive is proven.
  • 61 tests across all crates: 15 GF($2^8$) Shamir math, 8 escrow bridge + Shamir, 14 protocol state machine + offers, 24 HTTP API + escrow store + auth + dispute + resolve, plus 3 integration tests (api_happy, restart) and 15 frontend vitest.
  • Conformance to pontmore/swap@1 — we didn't invent a new protocol. We implemented the existing one and extended it privately.
  • The hosted node architecture — solving the "small trade economics" problem without sacrificing non-custodiality via client-side preimage reconstruction.
  • Event-driven relay model — the daemon reconciles event chains from the relay on startup, accepts client-signed kind 7301 events, and publishes with retry. The relay is the coordination surface, not a notification afterthought.
  • The LDK-to-kernel action mapping — a clean table showing how each LDK primitive maps to a Pontmore protocol action.

What we learned

The core insight came from the Pontmore protocol: pontmore/swap@1 already defines the escrow kernel for PIP-02 coordination event chains. We didn't need to invent a new protocol; we needed to implement the existing one on LDK.

The key technical discovery was that Lightning hold invoices (where the payee registers a payment hash without knowing the preimage) give you non-custodial escrow for free:

$$\text{Settlement requires } P \text{, and } P = \text{combine}(s_1, s_2)$$

where $s_1, s_2, s_3$ are 2-of-3 Shamir shares held by the buyer, seller, and daemon respectively. No single party can reconstruct $P$. The Lightning HTLC enforces the rest: claim with $P$, or fail back. The math is the escrow agent.

We also learned that LDK's create_inbound_payment_for_hash is the right primitive — it registers a hash without storing the preimage, so the node can't auto-claim. The PaymentClaimable event arrives with payment_preimage: None, which is the hold semantics we need.

The hardest design lesson was that the event chain must be the source of truth, not HTTP call sequences. The daemon must persist signed events before moving money, reconcile from the relay on startup, and accept client-signed events so users don't depend on the daemon re-signing on their behalf.

What's next for PontHTLC

The spike and MVP are done — all issues (#1–#5, #11, #23–#47) are merged. The hosted daemon, PIP stack, REST API, browser UI, multi-node topology, Docker Compose, event-driven relay model, and security hardening are live. Post-MVP:

  1. Multi-relay support — query more than one relay before the deadline, wait for EOSE, treat no reply as unknown.
  2. Full browser-side signing — user signs swap/fiat_sent and core/accept with their own key via the POST /api/escrow/:id/action endpoint, no daemon re-signing.
  3. Attestation oracles / reversal bonds — tie fiat payment to a verifiable reference, not just the Lightning payment hash.
  4. pontmored integration — wire PontHTLC's LDK node as an economic connector in a pontmore/pontmore deployment.
  5. CI/CD, monitoring, production deployment, mobile-responsive UI, i18n.

The architecture is proven. The protocol is implemented. Now it's scaling.

Built With

  • axum
  • bitcoin
  • docker
  • ldk
  • lightning-block-sync
  • lightning-invoice
  • lightning-net-tokio
  • lightning-persister
  • nostr
  • pontmore-protocol
  • pontmore/pontmore
  • rust
  • svelte
Share this project:

Updates

Submission history