From 18ab96d9a740945e2f89410a6a43d100ec240e47 Mon Sep 17 00:00:00 2001 From: bracr10 Date: Sat, 25 Apr 2026 13:08:49 -0600 Subject: [PATCH] Refines `restore-session` dispute representation Clarifies that orders currently in dispute are reported solely through the `disputes` array, not `orders`. Introduces the `solver_pubkey` field to the dispute object, indicating the assigned solver for a dispute and its use for chat key derivation. Updates field descriptions and examples to accurately reflect the new structure and the `solver_pubkey` field. --- src/restore_session.md | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/src/restore_session.md b/src/restore_session.md index 2e98be6..76ef044 100644 --- a/src/restore_session.md +++ b/src/restore_session.md @@ -21,7 +21,7 @@ Client sends a Gift wrap Nostr event to Mostro with the following rumor's conten ## 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: +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`) and any active disputes. Orders currently under dispute are not included in `orders`; their information is reported through the `disputes` array instead. The response format will be: ```json [ @@ -54,7 +54,16 @@ Mostro will respond with a message containing all non-finalized orders (e.g., st "order_id": "", "trade_index": 4, "status": "initiated", - "initiator": "seller" + "initiator": "seller", + "solver_pubkey": null + }, + { + "dispute_id": "", + "order_id": "", + "trade_index": 5, + "status": "in-progress", + "initiator": "buyer", + "solver_pubkey": "" } ] } @@ -68,8 +77,23 @@ Mostro will respond with a message containing all non-finalized orders (e.g., st ### Fields * `restore_data`: Wrapper object that contains the session recovery data. -* `restore_data.orders`: An array of active or ongoing orders with their `order_id`, `trade_index`, and current `status`. -* `restore_data.disputes`: An array of ongoing disputes with `dispute_id`, the associated `order_id`, `trade_index`, current `status`, and `initiator` (`"buyer"`, `"seller"`, or `null` if unknown). +* `restore_data.orders`: An array of active or ongoing orders. Each entry contains: + * `order_id`: unique identifier of the order. + * `trade_index`: user's trade index for the order. Used with the mnemonic seed to derive the trade key pair subscribed to it. + * `status`: current order state (e.g., `pending`, `active`, `fiat-sent`, `waiting-buyer-invoice`, `waiting-payment`). +* `restore_data.disputes`: An array of ongoing disputes. Each entry contains: + * `dispute_id`: unique identifier of the dispute. + * `order_id`: id of the order in dispute. + * `trade_index`: trade index of that order. Used with the mnemonic seed to derive the same trade key pair already subscribed to it. + * `status`: current state of the dispute (e.g., `initiated`, `in-progress`). + * `initiator`: party that opened the dispute (`buyer` or `seller`). Tells the client whether the user or the counterparty started it. + * `solver_pubkey`: hex pubkey of the assigned solver, or `null` if none yet. Set once an admin assigns one via `admin-add-solver`. Also used to derive the ECDH shared key for the dispute chat. + +> **Note:** When an order is in dispute it does not appear in `orders`, it appears in `disputes`. In each dispute entry: +> +> * `trade_index` is the order's `trade_index`. +> * `order_id` is the id of that order. +> * The order's `status` is implicitly `dispute`. ## Example Use Case @@ -77,7 +101,8 @@ 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) +* One dispute just opened, still waiting for a solver (trade index 4) +* One dispute already taken by a solver (trade index 5) When switching to desktop, after restoring the mnemonic, the client sends `restore-session` and receives: @@ -92,11 +117,11 @@ When switching to desktop, after restoring the mnemonic, the client sends `resto "orders": [ { "order_id": "abc-123", "trade_index": 1, "status": "pending" }, { "order_id": "def-456", "trade_index": 2, "status": "pending" }, - { "order_id": "ghi-789", "trade_index": 3, "status": "active" }, - { "order_id": "xyz-999", "trade_index": 4, "status": "dispute" } + { "order_id": "ghi-789", "trade_index": 3, "status": "active" } ], "disputes": [ - { "dispute_id": "dis-001", "order_id": "xyz-999", "trade_index": 4, "status": "initiated", "initiator": "seller" } + { "dispute_id": "dis-001", "order_id": "xyz-999", "trade_index": 4, "status": "initiated", "initiator": "seller", "solver_pubkey": null }, + { "dispute_id": "dis-002", "order_id": "uvw-555", "trade_index": 5, "status": "in-progress", "initiator": "buyer", "solver_pubkey": "" } ] } }