{"id":"92f7bd6e2cb14d64f834a7c061bc9fa5c7ae1464b728a5d34148e20fc3fc2f6d","pubkey":"da19f1cd34beca44be74da4b306d9d1dd86b6343cef94ce22c49c6f59816e5bd","created_at":1774618257,"kind":30817,"tags":[["title","NIP-DISPUTES: Dispute Resolution Protocol"],["k","7543"],["k","30545"],["d","nip-disputes"]],"content":"NIP-DISPUTES\n==============\n\nDispute Resolution Protocol\n------------------------------\n\n`draft` `optional`\n\nTwo event kinds for structured dispute resolution on Nostr: claim filing and resolution.\n\n> **Standalone.** This NIP works independently on any Nostr application.\n\n## Motivation\n\nNIP-56 provides content reporting (flagging notes for moderation), but Nostr has no protocol for resolving disputes between parties. When a marketplace purchase goes wrong, a group governance decision is contested, a freelance job is abandoned, or content is wrongly removed, there is no standardised way to:\n\n- **File a structured complaint** referencing a specific event, with typed categories and optional mediator assignment\n- **Resolve the complaint** with a transparent, signed ruling\n\nThis NIP defines two event kinds: a dispute claim and a dispute resolution. They work with any Nostr interaction that produces an event: marketplace transactions (NIP-15), classified listings (NIP-99), group moderation (NIP-29), content publishing, or any custom application.\n\n## Relationship to Existing NIPs\n\n### NIP-56 (Reporting)\n\nNIP-56 handles content and user reporting for moderation. Dispute Claims (`kind:7543`) are structured complaints between parties with typed dispute categories, optional financial amounts, and optional mediator assignment. The two serve different purposes: NIP-56 is unilateral reporting to relays; NIP-DISPUTES is bilateral dispute resolution between parties.\n\nApplications MAY implement reputation consequences based on dispute history. For example, an application that detects patterns of at-fault rulings against the same pubkey MAY publish NIP-56 reports with structured `report` tags. This keeps abuse reporting at the application layer where pattern detection logic belongs.\n\n### NIP-EVIDENCE (kind 30578)\n\nDispute evidence SHOULD be submitted as [NIP-EVIDENCE](NIP-EVIDENCE.md) records (`kind:30578`). The `e` tag references the dispute claim event. Evidence types (photo, video, screenshot, receipt, etc.) map directly to NIP-EVIDENCE's `evidence_type` vocabulary. This composability means dispute evidence is discoverable alongside other evidence records and benefits from NIP-EVIDENCE's file hash verification, geolocation, and capture timestamp metadata.\n\nSee [Composing with NIP-EVIDENCE](#composing-with-nip-evidence) for concrete examples.\n\n### NIP-94 / Blossom\n\nFor media attachments (photos, videos, documents), use NIP-94 file metadata or Blossom (BUD-01) uploads, referenced from NIP-EVIDENCE records via `file_hash` and URL tags. Media upload is a generic file management concern, not dispute-specific.\n\n### NIP-APPROVAL\n\nFor multi-party dispute panels (e.g. three-mediator arbitration), compose with [NIP-APPROVAL](NIP-APPROVAL.md) gates. Each panel member publishes an approval event; the dispute resolution is published once the required threshold is met.\n\n## Kinds\n\n| kind | description | type |\n| ----- | ------------------- | ----------- |\n| 7543 | Dispute Claim | regular |\n| 30545 | Dispute Resolution | addressable |\n\nClaims are regular events (NIP-01); once published, they cannot be replaced at the relay level (regular events have no addressable replacement semantics). NIP-09 deletion requests may be issued but relays MAY ignore them; the cryptographic signature on the original event remains independently verifiable. Resolutions are addressable events; the resolver may correct a ruling before settlement.\n\n---\n\n## Dispute Claim (`kind:7543`)\n\nFiled by a complainant against another party. Immutable: as a regular event, the claim cannot be replaced or retracted at the relay level. It can only be resolved via a `kind:30545` resolution.\n\n```json\n{\n \"kind\": 7543,\n \"pubkey\": \"\",\n \"created_at\": 1698770000,\n \"tags\": [\n [\"p\", \"\"],\n [\"e\", \"\"],\n [\"alt\", \"Dispute claim: quality issue in freelance engagement\"],\n [\"dispute_type\", \"quality\"],\n [\"resolution_model\", \"mediator\"],\n [\"mediator\", \"\"],\n [\"domain\", \"freelance\"],\n [\"t\", \"domain:freelance\"],\n [\"amount_disputed\", \"25000\"],\n [\"currency\", \"SAT\"]\n ],\n \"content\": \"Deliverables did not match the agreed specification. Three of five requirements were not addressed.\"\n}\n```\n\nTags:\n\n* `p` (REQUIRED): Accused party's pubkey.\n* `e` (REQUIRED): References the event being disputed.\n* `dispute_type` (REQUIRED): Application-defined dispute category. Common examples include `no_show`, `quality`, `pricing`, `damage`, `safety`, `fraud`, `moderation`, `governance`, but applications MAY define any value appropriate to their domain.\n* `resolution_model` (REQUIRED): Application-defined resolution model. Common models include `mediator` (designated party reviews and rules), `mutual` (parties negotiate directly), and `automated` (rule-based auto-resolution), but applications MAY define any value.\n* `mediator` (OPTIONAL): Nominated mediator's pubkey. How the mediator is selected (marketplace-assigned, mutually agreed, random from pool) is application-defined.\n* `domain` (OPTIONAL): Category of the disputed interaction (e.g. `freelance`, `delivery`, `marketplace`, `moderation`, `governance`). This is a multi-letter tag; relays cannot filter on it. Clients MUST post-filter by `domain` after retrieval.\n* `t` (RECOMMENDED when `domain` is present): `[\"t\", \"domain:\"]` (e.g. `[\"t\", \"domain:freelance\"]`). Enables relay-side discovery by domain via `#t` filters. The `domain` tag remains the canonical source; the `t` tag is a relay-filterable mirror.\n* `amount_disputed` (OPTIONAL): Financial amount in dispute, in smallest currency unit.\n* `currency` (OPTIONAL): Currency code (e.g. `GBP`, `USD`, `EUR`, `SAT`).\n\nFiling deadlines, resolution timeframes, and escalation rules are application concerns. Applications SHOULD document their dispute policies separately.\n\n### REQ Filters\n\n```jsonc\n// Subscribe to all disputes involving a specific pubkey (as accused)\n[\"REQ\", \"disputes\", {\"kinds\": [7543], \"#p\": [\"\"]}]\n\n// Subscribe to all disputes filed by a specific pubkey\n[\"REQ\", \"my-disputes\", {\"kinds\": [7543], \"authors\": [\"\"]}]\n\n// Subscribe to disputes for a specific event\n[\"REQ\", \"event-disputes\", {\"kinds\": [7543], \"#e\": [\"\"]}]\n```\n\n### Appeals\n\nApplications MAY implement appeal workflows by publishing additional Dispute Claim events referencing the original resolution.\n\n> **Privacy:** This event MUST be delivered via NIP-59 gift wrap. See [Privacy](#privacy).\n\n---\n\n## Dispute Resolution (`kind:30545`)\n\nThe resolution of a dispute claim. Addressable: the resolver may update the ruling before settlement.\n\n```json\n{\n \"kind\": 30545,\n \"pubkey\": \"\",\n \"created_at\": 1698775000,\n \"tags\": [\n [\"d\", \"resolution_\"],\n [\"e\", \"\"],\n [\"alt\", \"Dispute resolution: partial refund of 15000 SAT\"],\n [\"ruling\", \"partial_refund\"],\n [\"resolution_model\", \"mediator\"],\n [\"at_fault\", \"\"],\n [\"refund_amount\", \"15000\"],\n [\"refund_currency\", \"SAT\"],\n [\"resolved_at\", \"1698775000\"]\n ],\n \"content\": \"After reviewing submitted evidence, the deliverables met 2 of 5 requirements. A 60% refund is awarded to the complainant.\"\n}\n```\n\nTags:\n\n* `d` (REQUIRED): Format `resolution_`. The `` is the SHA-256 event ID from the `e` tag referencing the claim. Using the event ID (a globally unique SHA-256 hash) guarantees uniqueness without requiring application-level identifiers.\n* `e` (REQUIRED): References the Dispute Claim event (`kind:7543`).\n* `ruling` (REQUIRED): One of:\n * `full_refund` - complainant receives full refund\n * `partial_refund` - complainant receives partial refund\n * `no_refund` - accused party keeps payment\n * `respondent_compensated` - accused party awarded additional compensation\n * `mutual_release` - both parties agree to walk away\n * `voided` - interaction voided entirely\n* `resolution_model` (REQUIRED): Model used (matches the claim's `resolution_model`).\n* `at_fault` (OPTIONAL): Pubkey of the party found at fault.\n* `refund_amount`, `refund_currency` (OPTIONAL): Refund details. Amount in smallest currency unit.\n* `resolved_at` (REQUIRED): Unix timestamp when the ruling was made.\n\n`content`: Reasoning and explanation for the ruling. Signed by the resolver's key.\n\n### REQ Filters\n\n```jsonc\n// Subscribe to resolutions for a specific dispute\n[\"REQ\", \"resolution\", {\"kinds\": [30545], \"#e\": [\"\"]}]\n\n// Subscribe to all resolutions by a specific resolver\n[\"REQ\", \"resolver-rulings\", {\"kinds\": [30545], \"authors\": [\"\"]}]\n```\n\n> **Privacy:** This event MUST be delivered via NIP-59 gift wrap. See [Privacy](#privacy).\n\n---\n\n## OPTIONAL Composition with NIP-ESCROW\n\nWhen disputes involve escrowed funds, applications MAY include stake outcome tags in the resolution event:\n\n* `complainant_stake_outcome` (OPTIONAL): Outcome of the complainant's escrowed stake. Example values: `released`, `partial_forfeit`, `full_forfeit`.\n* `accused_stake_outcome` (OPTIONAL): Outcome of the accused party's escrowed stake. Example values: `released`, `partial_forfeit`, `full_forfeit`.\n\nA resolution MAY trigger settlement (Lock to Settlement with `release_reason: dispute_resolved`). When a `kind:30545` resolution includes a refund ruling, the escrow system can use the resolution event as authorisation to release or forfeit funds. See [NIP-ESCROW](NIP-ESCROW.md).\n\n---\n\n## Composing with NIP-EVIDENCE\n\nDispute evidence SHOULD be submitted as [NIP-EVIDENCE](NIP-EVIDENCE.md) records (`kind:30578`). The `e` tag on the evidence record references the dispute claim event, linking evidence to the dispute.\n\n### Submitting Dispute Evidence\n\nA complainant submitting photographic evidence of a quality dispute:\n\n```json\n{\n \"kind\": 30578,\n \"pubkey\": \"\",\n \"created_at\": 1698771000,\n \"tags\": [\n [\"d\", \":evidence:photo_01\"],\n [\"t\", \"evidence-record\"],\n [\"e\", \"\"],\n [\"evidence_type\", \"photo\"],\n [\"captured_at\", \"1698770500\"],\n [\"file_hash\", \"sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\"],\n [\"g\", \"gcpuuz\"],\n [\"p\", \"\"],\n [\"p\", \"\"]\n ],\n \"content\": \"Photo of delivered item showing visible damage to left panel. Compare with agreed specification in the original listing.\"\n}\n```\n\nAn accused party submitting a screenshot of the agreed terms:\n\n```json\n{\n \"kind\": 30578,\n \"pubkey\": \"\",\n \"created_at\": 1698772000,\n \"tags\": [\n [\"d\", \":evidence:screenshot_01\"],\n [\"t\", \"evidence-record\"],\n [\"e\", \"\"],\n [\"evidence_type\", \"screenshot\"],\n [\"captured_at\", \"1698772000\"],\n [\"file_hash\", \"sha256:b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3\"],\n [\"p\", \"\"],\n [\"p\", \"\"]\n ],\n \"content\": \"Screenshot of original agreement showing the five deliverables. Items 1 and 2 were delivered as specified.\"\n}\n```\n\nA receipt submission for a pricing dispute:\n\n```json\n{\n \"kind\": 30578,\n \"pubkey\": \"\",\n \"created_at\": 1698771500,\n \"tags\": [\n [\"d\", \":evidence:receipt_01\"],\n [\"t\", \"evidence-record\"],\n [\"e\", \"\"],\n [\"evidence_type\", \"receipt\"],\n [\"captured_at\", \"1698771500\"],\n [\"file_hash\", \"sha256:c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\"],\n [\"p\", \"\"],\n [\"p\", \"\"]\n ],\n \"content\": \"Payment receipt showing 25000 SAT charged. The agreed price was 18000 SAT per the original quote.\"\n}\n```\n\n### Evidence `d` Tag Convention\n\nFor dispute evidence, the recommended `d` tag format is:\n\n```\n:evidence: