Two proposals for a trade index synch message

[arkanoider]

@grunch @Catrya @AndreaDiazCorreia ,

This PR introduces two approaches to add a message for synchronizing the user's last trade index between clients and Mostrod. Such synchronization is useful in several scenarios:

• Missed Messages: If either Mostrod or the client misses a message that should increment the trade index, Mostrod can refuse new order or take order messages until a valid trade index is provided.
• Switching Instances: When a user switches to another instance (pubkey) of Mostrod, this ensures that new order or take order messages are accepted.
• Session Restoration: If the user restores their session on another device (e.g., a new phone), aligning the client and daemon trade index is good practice.

These are the two options i propose, both are considered restore messages:

• The first option create a new payload LastTradeIndex with a null value in the request, mostro in the response will send last trade index as the value inside new payload answer

Request
{
  "restore": {
    "version": 1,
    "action": "restore-session",
    "payload": {
      "last_trade_index": null
    }
  }
}

Response
{
  "restore": {
    "version": 1,
    "action": "restore-session",
    "payload": {
      "last_trade_index": 42
    }
  }
}

• The second option create a new action LastTradeIndex with a null payload as request, mostro in the response will send last trade index inside trade index field.

Request
{
  "restore": {
    "version": 1,
    "action": "last-trade-index",
    "payload": null
  }
}

Response
{
  "restore": {
    "version": 1,
    "action": "last-trade-index",
    "trade_index": 42,
    "payload": null
  }
}

In my opinion, probably, a new action is the more linear approach, more similar to other messages and we can leverage the trade_index inside MessageKind struct to get the index without adding other fields

pub struct MessageKind {
    /// Message version
    pub version: u8,
    /// Request_id for test on client
    pub request_id: Option<u64>,
    /// Trade key index
    pub trade_index: Option<i64>,
    /// Message id is not mandatory
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<Uuid>,
    /// Action to be taken
    pub action: Action,
    /// Payload of the Message
    pub payload: Option<Payload>,
}

Now tell me your opinion about...

Summary by CodeRabbit

• Documentation
  • Added a user-facing guide for the "last-trade-index" action describing request/response shape (protocol version 1, action name, null payload) and semantics.
  • Clarified default behavior when no trades exist (returns trade_index = 1) and field meanings.
  • Included example request/response payloads (including trade_index = 7) and added a navigation entry for the guide.

[coderabbitai]

Walkthrough

Adds protocol documentation for a new restore action "last-trade-index" (version 1): client sends a Gift-wrapped Nostr event with payload: null; service responds with restore.trade_index (u32, default 1) and payload: null. Includes field definitions and examples.

Changes

Cohort / File(s)	Summary
Docs: last-trade-index action src/last_trade_index.md	New documentation describing restore.action "last-trade-index", request JSON (restore.version: 1, restore.action: "last-trade-index", payload: null), response JSON (restore.trade_index as u32, default 1, and payload: null), field explanations and examples.
Navigation update src/SUMMARY.md	Added new navigation entry "Last Trade Index" to documentation summary.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor C as Client
  participant R as Nostr Relay
  participant S as Restore Service

  Note over C: Build Gift-wrapped event<br/>`restore.version: 1`<br/>`restore.action: "last-trade-index"`<br/>`payload: null`
  C->>R: Publish request event
  R->>S: Deliver request
  rect rgba(232,245,233,0.6)
    Note over S: Lookup user's last trade index
    alt Trades exist
      S-->>R: Response event<br/>`restore.version: 1`<br/>`restore.trade_index = N`<br/>`payload: null`
    else No trades
      S-->>R: Response event<br/>`restore.version: 1`<br/>`restore.trade_index = 1`<br/>`payload: null`
    end
  end
  R-->>C: Relay response event
  Note over C: Consume `trade_index` (next trade should use `trade_index + 1`)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears and count each hop,
A tiny index, never stop.
If none exist, we start at one,
If seven's seen, then eight's begun.
I hop through docs and leave a trail—🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the main change by highlighting that the pull request introduces two different proposals for synchronizing the trade index, which matches the objectives and content of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2988035 and 8d67cb3.

📒 Files selected for processing (1)

• src/SUMMARY.md (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (3)

src/restore_trade_index.md (1)

37-43: Tighten normative statements and forward‑compat guidance

Add that unknown fields MUST be ignored and response MUST echo version/action for robustness and evolvability.

Suggested additions:

• Response MUST echo the same restore.version and restore.action.
• Receivers MUST ignore unknown fields in restore and payload for forward compatibility.
• Validation: request MUST contain payload.last_trade_index: null; any other non‑null value SHOULD be rejected with an error.

src/restore_trade_index_second_option.md (2)

1-3: Normalize action naming: “sync” vs “synch” and align with examples

Header says “Sync”, description says “synch‑trade‑index”, fields/examples use last-trade-index. Use a single action name; per examples, prefer last-trade-index, and drop “synch”.

Apply this diff:

-# Sync Trade Index
-
-Defines the `synch-trade-index` action used to retrieve the user's last `trade_index`.
+# Last Trade Index
+
+Defines the `last-trade-index` action used to retrieve the user's last `trade_index`.

-* `restore.action`: Must be `last-trade-index`.
+* `restore.action`: MUST be `last-trade-index`.

Also applies to: 35-37

---

40-52: Consider returning both last and next to eliminate client ambiguity

Optional: include next_trade_index in the response to avoid client off‑by‑one mistakes and document the source of truth.

Example:

{
  "restore": {
    "version": 1,
    "action": "last-trade-index",
    "trade_index": 7,
    "next_trade_index": 8,
    "payload": null
  }
}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ab52b99 and ee5a7b3.

📒 Files selected for processing (2)

• src/restore_trade_index.md (1 hunks)
• src/restore_trade_index_second_option.md (1 hunks)

🔇 Additional comments (1)

src/restore_trade_index.md (1)

7-7: Consistent naming: “Mostro” vs “Mostrod”

The PR text references “Mostrod”, while this doc uses “Mostro”. Pick one term and use it consistently in all docs/specs.

Would you confirm the canonical name and update accordingly?

Also applies to: 23-23

[grunch]

great proposal, let's go with the last-trade-index new action

[grunch]

great add it to the index in overview.md

[grunch]

LGTM