Pontmore Custodial Escrow

Standalone NestJS service for Pontmore custodial_escrow operations.

The service owns the custody boundary:

• escrow reference issuance
• funding status
• release and refund execution
• idempotency
• audit trail
• PIP-01 escrow descriptor publication

Minmo or any other swap implementation should call this service instead of talking directly to wallet infrastructure.

Development

npm install
npm run build
npm start

Set ESCROW_SERVICE_API_KEY before using protected endpoints. Protected requests must include:

Authorization: Bearer <ESCROW_SERVICE_API_KEY>

API

Public:

• GET /health
• GET /v1/descriptors/default
• GET /v1/descriptors/:id

Protected:

• POST /v1/escrows
• GET /v1/escrows/:reference
• POST /v1/escrows/:reference/funding/verify
• POST /v1/escrows/:reference/release
• POST /v1/escrows/:reference/refund
• POST /v1/escrows/:reference/dispute-resolution

This implementation uses Postgres through TypeORM for escrow records, idempotency keys, and audit history. Runtime Bitcoin operations use the FMCD adapter by default, matching the integration shape currently used by Minmo's API Bitcoin service. The mock Bitcoin adapter remains available for tests and local contract development.

Database

Set DATABASE_URL before starting the service:

createdb pontmore_escrow
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/pontmore_escrow
export POSTGRES_SYNCHRONIZE=true # local development only
npm run start:dev

POSTGRES_SYNCHRONIZE=true is convenient during early local development. Use migrations before running the service against shared or production databases.

Docker

Build the image:

npm run docker:build

Run the service:

docker run --rm -p 4071:4071 \
  -e PORT=4071 \
  -e ESCROW_SERVICE_API_KEY=replace-with-a-long-random-secret \
  -e ESCROW_WEBHOOK_SECRET=replace-with-a-long-random-secret \
  -e DATABASE_URL=postgres://postgres:postgres@host.docker.internal:5432/pontmore_escrow \
  -e BITCOIN_ADAPTER=fmcd \
  -e FMCD_BASE_URL=http://host.docker.internal:8080 \
  -e FMCD_PASSWORD=replace-with-fmcd-password \
  minmoto/escrow:local

Bitcoin Adapter

The default adapter is FMCD, https://github.com/minmoto/fmcd:

export BITCOIN_ADAPTER=fmcd
export FMCD_BASE_URL=http://localhost:8080
export FMCD_PASSWORD=...
export FEDERATION_ID=...
export GATEWAY_ID=...

The adapter calls:

• POST /v2/ln/invoice
• POST /v2/ln/pay
• POST /v2/admin/operations
• POST /v2/onchain/withdraw

Use BITCOIN_ADAPTER=mock only for local API contract work.