[Draft/RFC] Escrow & dispute extension for the marketplace order flow (market-spec / NIP-99)

[Colabonate]

This is a request for design feedback, not a merge request. I've converted it to a draft.
I'd rather get the model right than get it merged fast.

What this is

The GammaMarkets market-spec already standardizes the NIP-99 order/payment/status flow
(kind:16 order, kind:17 payment receipt) — nicely. The one thing it explicitly leaves
out is escrow and dispute resolution.

That gap is exactly what I've built and run in production: Lightning hold-invoice escrow
with a third-party-resolvable dispute path. This proposes those two pieces as an
extension on top of market-spec, not a competing order model.

I previously opened this PR with a much larger scope (identity levels, reputation, DAO
governance, a token, and my own order kinds). That was a mistake — the order layer is
already covered by market-spec, and the rest are product concerns, not protocol concerns.
I've cut it down to the genuinely missing, generically useful piece.

The two events

Both reference an existing market-spec order via its order id.

Escrow State — tracks held funds: HELD → RELEASED | REFUNDED | DISPUTED.
Dispute — a public, neutral claim against an order: OPEN → IN_REVIEW → RESOLVED.

(Full schemas in the file diff.)

One honest architectural note up front

market-spec orders are NIP-17 encrypted DMs. My escrow and dispute events are
public addressable events — deliberately, because a third-party arbitrator and an
escrow holder both need to read a record that isn't private to buyer+seller. So this is
vocabulary-compatible with market-spec, not wire-compatible. I'd like feedback on whether
that asymmetry is acceptable or a dealbreaker.

Design questions I'd genuinely like input on

1. Escrow as a new kind vs. an extra type on market-spec kind:16? The Gamma
   collective may prefer escrow to live as a new type value on the existing order kind.

2. Public escrow/dispute vs. encrypted orders — is the visibility asymmetry above
   workable, or should escrow records be reachable some other way?

3. Who signs the escrow event — the hold-invoice provider, or either party?

4. Does a generic "marketplace dispute" belong in this NIP, in a separate
   resolver-agnostic NIP that escrow merely points to, or is it client-defined?

5. Listing reference — escrow/dispute reference the listing via market-spec's item
   tag (["item", "30402:<pubkey>:<d>", "<qty>"]), matching how kind:16 orders reference
   products. Consistent with market-spec, or is repeating it on the escrow event redundant?

Reference implementation

Running in production (currently with bespoke public ticket kinds, being aligned to
market-spec vocabulary — see ADR-142/143 in the repo):
https://github.com/Colabonate/Colabonate-App

• Server: apps/server/services/nostr-relay.ts
• Kind constants: apps/server/services/kind-mapping.ts

I'd love for the Gamma collective (Shopstr, Cypher, Plebeian, Conduit) to sanity-check
whether escrow/dispute should live here or inside market-spec itself.

Author

Deniz Yilmaz · npub12sr83yw7psyjt9j96sdh8qq4w3qjls0phhazhs3vgcs6wwtf2lysgwgdku