Skip to content

docs(protocol): propose private structured commerce messages#12

Draft
ericfj2140 wants to merge 1 commit into
codex/spec-refactor-transpositionfrom
docs/commerce-message-envelope-v2
Draft

docs(protocol): propose private structured commerce messages#12
ericfj2140 wants to merge 1 commit into
codex/spec-refactor-transpositionfrom
docs/commerce-message-envelope-v2

Conversation

@ericfj2140

Copy link
Copy Markdown

Summary

Proposes a collision-free private structured commerce message envelope using inner rumor kind 1327, versioned named message types, and explicit payment semantics.

This PR is stacked on #1 and remains experimental. It does not rewrite the current compatibility snapshot.

Why

The inherited marketplace specification assigns kind 16 to private order messages and kind 17 to payment receipts. Those values now conflict with NIP-18 Generic Repost and NIP-25 external content reactions.

The inherited numeric message types also collapse distinct states. In particular, payment proof, merchant verification, fulfillment, cancellation, and refund outcomes need separate meanings.

What changed

  • Added an experimental private structured commerce message proposal.
  • Proposed kind 1327 as the versioned NIP-59 inner rumor envelope.
  • Replaced numeric message types with named types.
  • Distinguished payment_request, payment_proof, payment_confirmed, payment_rejected, refund, fulfillment, and shipping operations.
  • Kept ordinary conversation on kind 14.
  • Made signed child events optional and type-specific for portable authorization rather than mandatory for routine private messages.
  • Added strict legacy kind 16/17 dual-read guidance.
  • Documented how this proposal should converge with the draft Orders work in NIP-XX: Orders #10.
  • Recorded the inherited collisions in the compatibility notes without changing SPEC.md.

Validation

  • git diff --check
  • Verified every relative Markdown link in the four affected files resolves.
  • Confirmed SPEC.md, all pillar files, and all lane files are unchanged from Reorganize specification navigation #1.
  • Reviewed the kind inventory and every normative MUST/SHOULD/MAY statement added by the proposal.
  • Compared the proposed 1327 role with the structured-message and payment lifecycle definitions in NIP-XX: Orders #10.

Runtime or visual evidence

Documentation-only proposal; no runtime or visual surface changes.

Risks and follow-ups

  • Kind 1327 still requires upstream coordination and registration before normative adoption.
  • Exact version 1 JSON payload schemas remain an explicit review question.
  • NIP-XX: Orders #10 currently requires every 1327 payload to be a signed child event. If both proposals advance, NIP-XX: Orders #10 should consume this envelope and register distinct signed-child message types instead of defining an incompatible second 1327 format.
  • Implementations will need a strict dual-read migration before they stop reading legacy kinds 16 and 17.
  • This PR depends on Reorganize specification navigation #1 and should be retargeted to main after Reorganize specification navigation #1 merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant