NIP-XX: Orders

[pats2sats]

Summary

Adds the marketplace order protocol for creating, negotiating, funding, acknowledging, settling, cancelling, and reviewing orders against NIP-99 listings. The proposal separates private negotiation from public payment/order lifecycle events so clients can coordinate trades without exposing unnecessary participant identity or payment evidence.

What this defines

• kind:32122 order events and deterministic order groups.
• Payment lifecycle events: payment, payment ack, payment settlement, order cancel, and payment nack.
• Private structured-message negotiation using signed child events inside encrypted rumors.
• Temporary trade key participant proofs for privacy-preserving public lifecycle events.
• Commit authorization for negotiated terms.
• Marketplace seed and review event usage.

Scope

This is the order and payment lifecycle layer. Listing semantics come from NIP-99 and the marketplace listing extension; arbiter discovery and settlement policy matching are defined by the arbitration services proposal.

[ericfj2140]

Hey @pats2sats — I reviewed this alongside the existing Gamma Markets/Conduit private order flow and opened #12 to address a related interoperability issue.

As discussed on Signal and the problem we both seem to want to address: Gamma currently uses inner kinds 16 and 17 for order/payment messages, but those collide with NIP-18 Generic Repost and NIP-25 external-content reactions. #12 proposes converging on the kind:1327 Structured Message introduced here, using versioned, named message types rather than Gamma’s numeric types.

The main difference is signed children. I’m proposing that signed children remain optional and type-specific, rather than requiring them for routine invoices, payment confirmations, fulfillment updates, and shipping messages. NIP-59’s signed seal already authenticates those routine messages to their recipients.

#12 also makes payment semantics more explicit:
payment_request
payment_proof
payment_confirmed
payment_rejected
refund_requested
refund_confirmed
payment_settlement

This separates “the buyer says they paid” from “the merchant verified payment,” while leaving payment_settlement available for escrow, release, split, or claim flows.

Idea is to have 1327 to have one compatible base meaning: a versioned private structured-message envelope. #10 could then register distinct named types such as order_commit when a signed child event is required, without changing the payload shape of routine types such as order or payment_confirmed.

Does that preserve what you were trying to achieve with the signed children?

[ericfj2140]

Reviewing this alongside the accommodation profile in #7 and the marketplace extension in #9, the availability model needs an explicit boundary with NIP-52.

This draft uses start/end and confirmed public order groups to compute listing availability. NIP-52 kind 31922 already provides date-based intervals with inclusive start and exclusive end, while kind 31924 can group calendar events. For accommodation listings, seller-authored calendar events could represent blocked or busy ranges without publishing buyer identity, while the order/payment lifecycle remains authoritative for commercial commitment. Kind 31925 RSVP should not, by itself, imply booking acceptance.

Whether this draft adopts NIP-52 or intentionally does not, it should define:

• which events are authoritative for availability;
• interval boundaries and local-date/time-zone handling;
• quantity/capacity reduction across overlapping orders;
• tentative holds and expiration;
• cancellation and release behavior;
• deterministic handling of concurrent commitments.

Without those rules, two clients can derive different availability from the same listing and order history, including double-booking scenarios.