Add restore session

Author: grunch

src/SUMMARY.md

@@ -24,6 +24,7 @@
 - [Admin Settle order](./admin_settle_order.md)
 - [Admin Cancel order](./admin_cancel_order.md)
 - [Admin Add Solver](./admin_add_solver.md)
+- [Restore session](./restore_session.md)
 - [Actions](./actions.md)
   - [Message suggestions for actions](./message_suggestions_for_actions.md)
 - [P2P Order event. NIP-69](./order_event.md)

src/restore_session.md

@@ -0,0 +1,93 @@
+# Restore Session
+
+To restore a session from the mnemonic seed on a new device (e.g., moving from mobile to desktop), the client sends a `restore-session` message. Mostro will respond with the relevant orders and disputes so the client can rebuild the session state using the same `trade_index` values.
+
+## Request
+
+Client sends a Gift wrap Nostr event to Mostro with the following rumor's content:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "action": "restore-session",
+    "payload": null
+  }
+}
+```
+
+## Response
+
+Mostro will respond with a message containing all non-finalized orders (e.g., statuses such as `pending`, `active`, `fiat-sent`, `waiting-buyer-invoice`, `waiting-payment`, `settled-hold-invoice`) and any active disputes. The response format will be:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "action": "restore-session",
+    "payload": {
+      "orders": [
+        {
+          "id": "<Order Id>",
+          "trade_index": 1,
+          "status": "pending"
+        },
+        {
+          "id": "<Order Id>",
+          "trade_index": 2,
+          "status": "active"
+        },
+        {
+          "id": "<Order Id>",
+          "trade_index": 3,
+          "status": "fiat-sent"
+        }
+      ],
+      "disputes": [
+        {
+          "dispute_id": "<Dispute Id>",
+          "order_id": "<Order Id>",
+          "trade_index": 4,
+          "status": "initiated"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Fields
+
+* `orders`: An array of active or ongoing orders with their `id`, `trade_index`, and current `status`.
+* `disputes`: An array of ongoing disputes with `dispute_id`, the associated `order_id`, and `trade_index`.
+
+## Example Use Case
+
+A user has the following:
+
+* Two `pending` orders (trade index 1 and 2)
+* One `active` order (trade index 3)
+* One active dispute (trade index 4)
+
+When switching to desktop, after restoring the mnemonic, the client sends `restore-session` and receives:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "action": "restore-session",
+    "payload": {
+      "orders": [
+        { "id": "abc-123", "trade_index": 1, "status": "pending" },
+        { "id": "def-456", "trade_index": 2, "status": "pending" },
+        { "id": "ghi-789", "trade_index": 3, "status": "active" },
+        { "id": "xyz-999", "trade_index": 4, "status": "dispute" }
+      ],
+      "disputes": [
+        { "dispute_id": "dis-001", "order_id": "xyz-999", "trade_index": 4, "status": "initiated" }
+      ]
+    }
+  }
+}
+```
+