DEV Community: Denver Mtange

Building Pontmore: From Protocol Spec to Working Standalone Escrow POC

Denver Mtange — Thu, 13 Aug 2026 19:56:46 +0000

When I opened PR #12 on the Pontmore protocol repo, I was trying to answer one question: can we define a standard way for applications to invoke an escrow service directly, without routing through a swap state machine? The answer was yes , but the path from spec to working POC to simplified protocol taught me more than I expected about designing interoperable financial infrastructure.

The Problem: PIP-01 Was Discovery-Only

PIP-01 (the Pontmore Escrow Descriptor) initially served a narrow purpose: allow agents to discover compatible escrow mechanisms for fiat-to-Bitcoin swaps. It was a discovery tool, not an execution engine.

A pre-PR #12 descriptor looked like this:

{
  "version": 1,
  "escrow_type": "lightning_hold_invoice",
  "networks": ["bitcoin", "lightning"],
  "funding_rules": { "required_confirmation": "invoice_held" },
  "release_rules": { "release_trigger": "counterparty_fiat_payment_confirmed" },
  "dispute_rules": { "policy": "operator_resolved" }
}

This told an agent "this escrow exists and works with Lightning hold invoices." But it didn't tell a standalone application how to create an escrow, fund it, release it, or cancel it. Those details were implicit in PIP-02's swap state machine , you needed a swap to use an escrow. There was no path for an application to say "I need an escrow between two people, let me create one."

PR #12: The Standalone Service Interface

The driving force was Issue #11: "Define escrow service invocation in PIP-01." The solution was an optional service block in the descriptor that tells applications how to talk to the escrow directly ; endpoints, authentication, operations, funding models, and release decision formats.

The resulting spec defined:

Transport: https as the canonical transport, with room for additional transports
Authentication: nostr_http_auth (NIP-98) , your Nostr pubkey IS your identity, no bearer tokens
Canonical operations: create, funding_instructions, fund_status, release, refund, split, cancel
Funding models: single_funder, two_party, m_of_n
Release decisions: mutual_consent, operator_decision, oracle_signature, application_signed_result, threshold_participant_signatures, split_decision
Wire contract: a schema_url pointing to a normative OpenAPI document

A standalone-sufficient descriptor now carried a full service contract:

{
  "version": 1,
  "escrow_type": "custodial_escrow",
  "networks": ["lightning"],
  "funding_rules": { "required_confirmation": "invoice_paid", "funding_timeout": "86400_seconds" },
  "release_rules": { "release_trigger": "application_signed_result", "refund_trigger": "timeout_or_dispute_refund_decision" },
  "dispute_rules": { "policy": "operator_resolved" },
  "service": {
    "transport": ["https"],
    "interface": "pontmore_escrow_http_v1",
    "endpoint": "https://escrow.example.com/pontmore/v1",
    "auth": ["nostr_http_auth"],
    "operations": ["create", "funding_instructions", "fund_status", "release", "refund", "cancel"],
    "funding_model": ["single_funder", "two_party", "m_of_n"],
    "release_decisions": ["mutual_consent", "operator_decision", "application_signed_result"],
    "schema_url": "https://escrow.example.com/pontmore/v1/openapi/v1.0.0.json"
  }
}

The PR also patched structural loopholes identified during implementation: cross-instance replay protection (oracle/threshold signatures now commit to the stable escrow ID), funding-phase timeout enforcement (cancelling a partially-funded escrow must refund all funded sides), and deadlock prevention (any timeout path using mutual consent must declare a non-consent fallback).

PR #12 was merged on August 11, 2026 , with review feedback that would prove significant.

Review Feedback That Seeded PR #17

During review, okjodom left several comments that revealed a deeper design tension:

"We could simplify this definition by deferring the service, transport and interface version to the declared OpenAPI schema doc."

"Please remove the escrow state machine definition. Implementation details must not be part of the generic PIP-01 spec."

"I'm quite wary of having to define these operational semantics in the escrow descriptor."

The tension was clear: PR #12 had made PIP-01 the source of truth for service behavior ; endpoints, operations, state machines, decision formats. But the reviewer wanted to pull all of that back into the referenced schema, leaving PIP-01 as a lightweight compatibility object. He approved the PR anyway , "this has provably moved us forward by a margin, let's land and iterate" — and opened PR #17 within hours to begin the simplification.

The POC: Building Against PR #12

While the spec was being reviewed, I had to build a working implementation to prove the concept was viable. The result is pontmore-lightning-escrow — a custodial escrow service running on Render with Blink Lightning custody and Supabase persistence. It's live at standalone-escrow.onrender.com and has processed real Lightning escrows during testing.

Architecture

                   Nostr Relays               HTTPS Clients
                  (nos.lol etc)           (rollpot, curl, apps)
                       │                         │
                       │ kind 30361              │ NIP-98 auth header
                       │ descriptor              │ (signed kind 27235 event)
                       ▼                         ▼
              ┌─────────────────────────────────────────┐
              │           Express Server                │
              │           (Render, port 3000)           │
              │                                         │
              │  ┌──────────────┐  ┌────────────────┐   │
              │  │  NIP-98 Auth │  │  Escrow Engine │   │
              │  │  Middleware  │  │   + 5 release  │   │
              │  │              │  │  decision types│   │
              │  └──────────────┘  └────────────────┘   │
              │                                         │
              │            ┌────────────────────────┐   │
              │            │                        │   │
              │            ▼                        ▼   │
              │   ┌──────────────┐           ┌──────────────┐
              │   │   Supabase   │           │    Blink     │
              │   │   (Postgres) │           │  (Lightning) │
              │   │              │           │              │
              │   │ · escrow     │           │ · invoices   │
              │   │   instances  │           │ · payments   │
              │   │ · funders    │           │ · LN address │
              │   │ · state RPC  │           │   payouts    │
              │   └──────────────┘           └──────────────┘
              │
              └─────────────────────────────────────────┘

Express Server handles all PIP-01 operations via NIP-98 authenticated endpoints. Every mutating request carries a signed kind 27235 Nostr event in the Authorization header , the authenticated pubkey IS the participant's identity. No user registration, no session management, no password resets.

Escrow Engine validates state transitions, verifies release/refund Schnorr signatures across five decision formats, manages opaque single-use enrollment tokens, and orchestrates multi-party funding. All state mutations go through a Postgres RPC that atomically checks the current state before transitioning , no application-level locking required.

Supabase provides durable Postgres storage with two tables (escrow_instances for escrow metadata, escrow_funders for per-participant funding state) and a transition_escrow_state RPC that prevents race conditions. If two requests race to transition the same escrow, exactly one succeeds and the other gets a clean conflict error.

Blink is the Lightning custody backend , creates BOLT11 invoices per participant (with per-invoice platform fees), detects payments via polling, and executes Lightning Address payouts on release. Payout idempotency is guaranteed via deterministic keys scoped to the escrow, purpose, and recipient.

The Test Suite and Universal Tester

No automated tests existed when I started , manual curl commands were the only validation. I built a 50-test integration suite targeting the live Render deployment, covering descriptor discovery, NIP-98 auth edge cases (5 failure modes), open enrollment with single-use enforcement, multi-party funding visibility, release decision verification, cancel authorization, idempotency across creators, state machine correctness, and OpenAPI schema compliance against live responses.

All tests use ephemeral secp256k1 keypairs with no shared state between tests. Cleanup is automated via afterAll hooks that cancel any created escrows.

I also built a separate tool , the Escrow Descriptor Tester ; a web UI that queries Nostr relays for kind 30361 events, runs 40+ PIP-01 spec validation checks per descriptor, and executes live service tests against standalone endpoints. It found 18 published descriptors on nos.lol, most of them custodial_escrow with operator_resolved dispute policy. Several had subtle spec violations: empty required_confirmation strings, non-standard funding models, or missing decision signer blocks.

PR #17: The Simplification

While the POC was running against the PR #12 spec, okjodom opened PR #17 — a cleanup that recasts PIP-01 from a "descriptor-defined standalone service interface" into a "compatibility/discovery object with a schema pointer." The motivation, in his words: "PIP-01 had started to carry too many responsibilities."

The key changes:

Before (PR #12)	After (PR #17)
10+ `service` fields: transport, interface, endpoint, auth, operations, funding_model, release_decisions, decision_signers, schema_url	One field: `service.schema { type, url }`
Named funding models: single_funder, two_party, m_of_n	`funding_threshold` / `participant_count` cardinality (m-of-n)
Descriptor-level `release_rules` with triggers and fallbacks	Removed; release and refund behavior belongs to schema_url
Canonical state machine defined in PIP-01	Removed; swap lifecycle to PIP-02, service behavior to schema
Subtype-specific field lists (implementations, custody_authority, release_authority, refund_authority)	Trimmed to purpose, compatibility invariants, and public/private boundary

The new minimal descriptor, as defined in the upstream spec:

{
  "version": 1,
  "escrow_type": "custodial_escrow",
  "networks": ["bitcoin", "lightning"],
  "funding_rules": {
    "funding_threshold": 1,
    "participant_count": 1,
    "required_confirmation": "invoice_paid",
    "funding_timeout": "funding timeout"
  },
  "dispute_rules": {
    "policy": "operator_resolved",
    "timeout_fallback": "operator_decision"
  },
  "reference_format": "bolt11_or_custodial_escrow_reference",
  "service": {
    "schema": {
      "type": "openapi",
      "url": "https://escrow.example.com/pontmore-escrow.openapi.json"
    }
  },
  "updated_at": 1775559028
}

The migration path is clear but disruptive. The live standalone-escrow.onrender.com deployment still serves the PR #12 descriptor shape. Rollpot (the reference client) currently reads descriptor.service.endpoint and descriptor.service.funding_model directly. Under PR #17, it should instead fetch service.schema.url, validate the referenced OpenAPI document, and discover servers, paths, security schemes, and operation metadata from the schema. The OpenAPI document already carries most of the behavior PR #17 removes from PIP-01.

What I Learned

Protocol design is iterative. The spec went from discovery-only (pre-PR #12) to rich service interface (PR #12) to minimal compatibility object (PR #17) in the span of three weeks. Building while the spec evolves means accepting that some code will be thrown away but the discarded code teaches you what the protocol actually needs. Every field we removed from the descriptor was a field we learned didn't belong there.

The descriptor is a commitment, not documentation. Publishing a kind 30361 event on Nostr relays is a public declaration. Changing it means broadcasting a kind 5 deletion event and republishing. This creates healthy pressure to get the descriptor right before publishing and makes the published event a useful signal for clients who want to verify an operator keeps their promises.

Multi-party accounting compounds. Per-participant invoices, per-funder funding status, aggregate payout calculation across funded sides, proportional refunds on timeout cancellation , the edge cases multiply with each additional participant. A separate escrow_funders table was essential; the alternative of cramming everything into a single escrow row would have been unmaintainable.

The public/private boundary is the protocol's backbone. Wallet IDs, custody backend identifiers, API keys, and bearer secrets do not belong in a public Nostr event. PR #17 enforces this boundary by making PIP-01 a compatibility object whose only service field is a schema pointer. The schema_url is where implementation details live and where they stay out of the public relay.

The POC: github.com/mk-Denver/pontmore-lightning-escrow

The tester: github.com/mk-Denver/escrow-tester

The protocol: github.com/pontmore/protocol ,website

PR #12 (merged): pontmore/protocol#12

PR #17 (simplification): pontmore/protocol#17

Protocol discussion: Open Bitcoin Africa

Learning by Building: Rust for Bitcoiners 1.0

Denver Mtange — Sun, 05 Jul 2026 10:36:26 +0000

When diving into Bitcoin development, reading protocol specifications and documentation will only get you so far. At some point, you have to get your hands dirty. I recently decided to tackle learning Rust the gold standard language for modern Bitcoin infrastructure by building a raw Bitcoin keypair and address generator from scratch.

I quickly discovered that combining Rust's notoriously strict compiler with Bitcoin's unforgiving cryptography is the ultimate trial by fire. Here is what I learned during "Version 1.0" of my journey, the challenges I ran into, and how compiler-driven development helped me overcome them.

The Goal: A From-Scratch Legacy Wallet

The mission was simple on paper: generate 32 bytes of secure randomness (a private key), derive the public key using Elliptic Curve cryptography, hash it down, and encode it into a human-readable legacy Bitcoin address.

Setting up the project with cargo new was straightforward. I also quickly learned Rust's core philosophy of safety: variables are immutable by default (like a mined block) unless explicitly marked with mut. But the real lessons started when I tried to pull in external tools to do the math.

Challenge 1: The Bleeding Edge of Rust and Traits

To get 32 bytes of entropy, I added the rand crate to my project. Following standard tutorials, I wrote rand::thread_rng().gen(). The compiler immediately threw a wall of text at me: expected identifier, found reserved keyword 'gen'.

How I Overcame It: I had stumbled right into a modern Rust ecosystem update. In the new Rust 2024 Edition, gen was made a reserved keyword for a new language feature. The rand crate authors had to rename their method to random(), and thread_rng() to simply rng().

But fixing the names wasn't enough. The compiler then complained it couldn't find .random(). This taught me about Rust Traits. Functions don't just float in the void; they belong to specific toolbelts (Traits). The compiler acted like a senior developer sitting next to me, explicitly suggesting I add use rand::RngExt; to the top of my file. Once I brought the trait into scope, I successfully generated my 32-byte array: my raw private key.

Challenge 2: Elliptic Curves and The `Result` Enum

Next, I needed to derive a compressed Public Key using the secp256k1 crate. I passed my 32 bytes into the cryptography engine expecting a clean public key to pop out. Instead, I got a mismatched types error: expected reference &SecretKey, found reference &Result<SecretKey, Error>.

How I Overcame It:
This taught me two crucial concepts at once:

Rust's Result Enum: Rust doesn't use standard exceptions that crash your program unpredictably. Functions that might fail return a Result box containing either the success data or an error. I had to use .expect() to unwrap the box and explicitly tell the program what to do if the math failed.
The Bitcoin Curve Order: But why would an exact 32-byte array fail? Because of Bitcoin's math. The secp256k1 curve has a maximum limit. There is an infinitesimally small chance (less than 1 in 10^38) that 32 random bytes generate a number mathematically "too big" for the curve. Rust forced me to acknowledge and handle this edge case before my code was legally allowed to compile.

Challenge 3: Hashing and Feature Flags

After successfully deriving my public key (and learning why modern keys start with a 02 prefix to indicate an even Y-coordinate to save blockchain space), I put it through the standard Hash160 pipeline (SHA-256 followed by RIPEMD-160).

The final step was converting this raw 20-byte payload into a readable address using the bs58 crate. I wrote the code to apply the 0x00 mainnet version byte and the double-SHA256 checksum. The compiler threw one last hurdle: no method named 'with_check_version' found.

How I Overcame It:
I learned about Cargo Feature Flags. Because Rust is obsessed with making compiled programs as tiny as possible, crate authors often hide heavy code behind optional flags. The Base58Check algorithm is heavy, so it was turned off by default. Without changing a single line of Rust code, I ran cargo add bs58 --features check in my terminal. The compiler was happy, and my terminal printed a flawless, valid legacy Bitcoin address.

Conclusion: Why Rust is Perfect for Bitcoin

Building this simple generator taught me that the Rust compiler is not your enemy; it is your incredibly pedantic pair-programmer.

Next up in my journey: adapting this tool to connect to a local Signet node and upgrading the engine to generate modern Native SegWit (Bech32) addresses.

you can check the code at https://github.com/mk-Denver/btc_wallet

Learning by building continues.