Merge pull request #35 from MostroP2P/docs/update-dispute-chat

Docs/update dispute chat

Author: Catrya

src/SUMMARY.md

@@ -4,12 +4,6 @@
 
 ---
 
-- [User Guide (English)](https://mostro.network/docs-english/)
-- [Guía de Usuario (Español)](https://mostro.network/docs-spanish/)
-- [Run Your Own Node](https://mostro.community/guide)
-
----
-
 - [Keys management](./key_management.md)
 - [Creating a Sell order](./new_sell_order.md)
 - [Creating a Sell range order](./new_sell_range_order.md)
@@ -27,9 +21,9 @@
 - [Release](./release.md)
 - [Rate user](./user_rating.md)
 - [Cancel](./cancel.md)
+- [Peer-to-peer Chat](./chat.md)
 - [Dispute](./dispute.md)
 - [Dispute Chat](./dispute_chat.md)
-- [Peer-to-peer Chat](./chat.md)
 - [List disputes](./list_disputes.md)
 - [Admin Settle order](./admin_settle_order.md)
 - [Admin Cancel order](./admin_cancel_order.md)

src/dispute_chat.md

@@ -1,49 +1,70 @@
 # Dispute Chat
 
-Once an admin takes a dispute, both the admin and the involved parties (buyer and seller) can communicate through an encrypted chat using Gift Wrap messages (NIP-59).
+The dispute chat uses the same shared key encryption scheme as the [Peer-to-peer Chat](./chat.md). Instead of computing a shared key between buyer and seller, each party computes an independent shared key with the admin who took the dispute.
 
-## Sending a message
+## Establishing the shared key
 
-Users and admins send messages using action `send-dm`. The message content is wrapped in a Gift Wrap event (kind 1059) to ensure privacy and encryption.
-
-### User sending a message
-
-Here is an example of a user sending a message to the admin:
+When an admin takes a dispute, Mostro sends an `admin-took-dispute` message to each party (buyer and seller) containing the admin's pubkey:
 
 ```json
 [
   {
-    "dm": {
+    "order": {
       "version": 1,
-      "action": "send-dm",
+      "id": "<Order Id>",
+      "action": "admin-took-dispute",
       "payload": {
-        "text_message": "Hello, I need help with this order"
+        "peer": {
+          "pubkey": "<Admin's pubkey>"
+        }
       }
     }
   },
   null
 ]
 ```
 
-### Admin sending a message
+Upon receiving this message, the client computes the shared key using ECDH:
 
-Admins use the same format to send messages to users:
+```
+Shared Key = ECDH(tradeKey.private, adminPubkey)
+```
+
+The admin computes the same shared key from their side:
+
+```
+Shared Key = ECDH(adminPrivateKey, tradeKey.public)
+```
+
+Each party (buyer and seller) has its own independent shared key with the admin. A session can have both a peer shared key (for the P2P chat) and an admin shared key (for the dispute chat) simultaneously.
+
+## Sending and receiving messages
+
+Messages are wrapped and unwrapped using the same simplified NIP-59 scheme described in [Peer-to-peer Chat](./chat.md#example). The inner event is a kind 1 event signed by the sender's key, encrypted with NIP-44 and placed inside a kind 1059 Gift Wrap event.
+
+The `p` tag in the wrapper event points to the **admin shared key's pubkey**, not the trade key:
 
 ```json
-[
-  {
-    "dm": {
-      "version": 1,
-      "action": "send-dm",
-      "payload": {
-        "text_message": "I'm reviewing the evidence, please wait"
-      }
-    }
-  },
-  null
-]
+{
+  "content": "<Encrypted content>",
+  "kind": 1059,
+  "created_at": 1703021488,
+  "pubkey": "<Ephemeral pubkey>",
+  "id": "<Event Id>",
+  "sig": "<Ephemeral key signature>",
+  "tags": [["p", "<Admin Shared Pubkey>"]]
+}
 ```
 
-## Receiving messages
+## Subscribing to messages
+
+Clients subscribe to kind 1059 events filtered by the admin shared key's pubkey:
+
+```json
+{
+  "kinds": [1059],
+  "#p": ["<Admin Shared Pubkey>"]
+}
+```
 
-Clients must subscribe to kind 1059 events with a `p` tag matching their pubkey. The Gift Wrap protocol (NIP-59) ensures that only the intended recipient can decrypt and read the messages, while preserving the sender's identity through the SEAL layer
+Clients should discard any messages received from pubkeys other than the Mostro node or the dispute solver.

src/overview.md

@@ -1,5 +1,7 @@
 ## Overview
 
+**See also:** [User Guide (English)](https://mostro.network/docs-english/) | [Guía de Usuario (Español)](https://mostro.network/docs-spanish/) | [Run Your Own Node](https://mostro.community/guide)
+
 Mostro uses [Addressable Events](https://github.com/nostr-protocol/nips/blob/master/01.md#kinds) to publish different types of information. Each event type has its own `kind`:
 
 | Event Type | Kind  | Description |