Skip to content

Document solver_pubkey in restore-session response #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BraCR10 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document solver_pubkey in restore-session response #41

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 33 additions & 8 deletions src/restore_session.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
[
Expand Down Expand Up @@ -54,7 +54,16 @@ Mostro will respond with a message containing all non-finalized orders (e.g., st
"order_id": "<Order Id>",
"trade_index": 4,
"status": "initiated",
"initiator": "seller"
"initiator": "seller",
"solver_pubkey": null
},
{
"dispute_id": "<Dispute Id>",
"order_id": "<Order Id>",
"trade_index": 5,
"status": "in-progress",
"initiator": "buyer",
"solver_pubkey": "<Solver Pubkey>"
}
]
}
Expand All @@ -68,16 +77,32 @@ 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.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for ECDH derivation logic related to dispute chat and solver pubkey

# Look for ECDH or key derivation mentions in dispute documentation
rg -n -C5 --type=md 'ECDH|shared.?key|key.?deriv' src/dispute.md

# Search for chat-related dispute messages or encryption details
rg -n -C5 --type=md 'chat|encrypt' src/dispute.md

# Check if there are other docs mentioning dispute chat encryption
fd -e md -x rg -l 'dispute.*chat|chat.*dispute'

Repository: MostroP2P/protocol

Length of output: 126

🏁 Script executed:

cat src/dispute_chat.md

Repository: MostroP2P/protocol

Length of output: 2102

🏁 Script executed:

cat src/restore_session.md | head -100

Repository: MostroP2P/protocol

Length of output: 3634

Remove incorrect ECDH claim from solver_pubkey field description.

The claim that solver_pubkey is "used to derive the ECDH shared key for the dispute chat" is inaccurate. According to dispute_chat.md, the dispute chat ECDH key is derived using the admin's pubkey (sent in the admin-took-dispute message), not the solver's pubkey:

Shared Key = ECDH(tradeKey.private, adminPubkey)

The solver_pubkey identifies the dispute solver but is not involved in the ECDH key derivation. Remove this incorrect claim from the field description.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/restore_session.md` at line 90, Update the `solver_pubkey` field
description in the restore_session.md diff to remove the incorrect claim that it
is "used to derive the ECDH shared key for the dispute chat"; keep that it is
the hex pubkey of the assigned solver (or null) and is set via
`admin-add-solver`, and if needed add a clarifying note that the dispute chat
ECDH shared key is derived from the admin's pubkey (see `admin-took-dispute` /
dispute_chat.md) rather than from `solver_pubkey`.


> **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

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:

Expand All @@ -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": "<Solver Pubkey>" }
]
}
}
Expand Down