docs: add comprehensive order states specification - #11
Merged
Conversation
Member
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Contributor
|
Important Review skippedBot user detected. To trigger a single review, invoke the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughAdds a new comprehensive order lifecycle specification (.specify/v1-reference/ORDER_STATES.md) defining 15 order states, per-role actions and transitions, UI status representations, automatic/timeout behaviors, dispute/admin flows, restoration rules, and implementation/testing guidance; also adds a small i18n requirement to specs/001-mostro-p2p-client/spec.md. Changes
Sequence Diagram(s)sequenceDiagram
participant Buyer
participant Seller
participant System
participant Admin
Buyer->>System: create sell-order
System->>Seller: notify new sell-order
Seller->>Buyer: accept / provide invoice
Buyer->>System: take order / pay (holds invoice)
System->>System: transition to settledHoldInvoice
System->>Seller: notify settlement (seller may see success)
System->>Buyer: notify settledHoldInvoice (later auto->success)
alt dispute by buyer/seller
Buyer->>Admin: create dispute
Admin->>System: review
Admin->>Buyer: settle/cancel/complete -> System transitions to admin terminal state
end
alt payment failed then addInvoice
System->>Buyer: paymentFailed (status preserved)
Buyer->>System: addInvoice -> resume transition
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
.specify/v1-reference/ORDER_STATES.md (2)
26-26: Optional: Add blank lines around transition tables for better markdown formatting.The markdown linter suggests surrounding tables with blank lines for improved readability and compliance with markdown best practices. While this doesn't affect functionality, it improves document formatting consistency.
Example fix for line 26
| `cancel` | Creator | `canceled` | + ---Apply similar spacing to all transition tables throughout the document.
Also applies to: 49-49, 74-74, 99-99, 123-123, 145-145, 165-165, 184-184, 218-218, 240-240
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md at line 26, Add blank lines before and after each markdown transition table to satisfy the linter and improve formatting; locate the tables by the header row "| Action | By | Next State |" (and the other transition tables with the same structure) and ensure there is an empty line above the header and an empty line after the table end for every occurrence throughout the document.
308-308: Optional: Add language identifiers to ASCII diagram code blocks.The fenced code blocks containing ASCII flow diagrams (lines 308, 348, 389) lack language identifiers. While ASCII art doesn't require syntax highlighting, adding a language identifier (e.g.,
textorascii) improves markdown compliance and makes the intent clearer.Example fix
-``` +```text ┌──────────┐ takeSell ┌──────────────────┐ │ PENDING │ ───────────────▶ │ WAITING_BUYER_ │Also applies to: 348-348, 389-389
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md at line 308, The ASCII flow diagram fenced code blocks in ORDER_STATES.md that show states like "PENDING" → "WAITING_BUYER_" (the diagrams around the snippets containing those ASCII labels) are missing language identifiers; update each fenced block (the three diagrams referenced) to use a language tag such as ```text or ```ascii so the blocks become ```text ... ``` (or ```ascii ... ```), ensuring all three ASCII diagrams are annotated consistently to improve markdown correctness and clarity.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.specify/v1-reference/ORDER_STATES.md:
- Around line 218-221: Clarify the cooperative-cancel flow: explicitly define
what "previous state" means (the immediate prior order state before entering
cooperativelyCanceled), state how it is recorded (e.g., persist a previous_state
field when transitioning into cooperativelyCanceled) and list which source
states may transition to cooperativelyCanceled (e.g., Open, Matched,
PendingSettlement) along with the exact transition triggers for
`cooperativeCancelAccepted` and (timeout/ignore) behavior; also document the
difference between `cooperativeCancelAccepted` -> cooperativelyCanceled and the
regular `cancel` -> `canceled` path so readers know when to use
`cooperativelyCanceled` vs `canceled` and how the revert on timeout returns to
the recorded previous_state.
- Around line 346-385: The diagram and the state definitions disagree: update
the spec so transitions for WAITING_PAYMENT, WAITING_BUYER_INVOICE and ACTIVE
are consistent with the buy-order flow by either (A) making the state transition
rules conditional on order type (buy vs sell) and documenting that payInvoice
from WAITING_PAYMENT on a buy order leads to WAITING_BUYER_INVOICE and
addInvoice from WAITING_BUYER_INVOICE on a buy order leads to ACTIVE (update the
WAITING_PAYMENT and WAITING_BUYER_INVOICE definitions accordingly), or (B)
revert the buy order flow diagram to match the existing rules (WAITING_PAYMENT +
payInvoice → ACTIVE and WAITING_BUYER_INVOICE + addInvoice → WAITING_PAYMENT);
also update the state transition table to include an "Order Type" column or
conditional notes indicating which transitions apply to buy vs sell orders and
reference the payInvoice and addInvoice transitions explicitly.
---
Nitpick comments:
In @.specify/v1-reference/ORDER_STATES.md:
- Line 26: Add blank lines before and after each markdown transition table to
satisfy the linter and improve formatting; locate the tables by the header row
"| Action | By | Next State |" (and the other transition tables with the same
structure) and ensure there is an empty line above the header and an empty line
after the table end for every occurrence throughout the document.
- Line 308: The ASCII flow diagram fenced code blocks in ORDER_STATES.md that
show states like "PENDING" → "WAITING_BUYER_" (the diagrams around the snippets
containing those ASCII labels) are missing language identifiers; update each
fenced block (the three diagrams referenced) to use a language tag such as
```text or ```ascii so the blocks become ```text ... ``` (or ```ascii ... ```),
ensuring all three ASCII diagrams are annotated consistently to improve markdown
correctness and clarity.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8ed75a59-445c-4fc4-8f0c-55fd60aa5deb
📒 Files selected for processing (1)
.specify/v1-reference/ORDER_STATES.md
Comment on lines
+218
to
+221
| | Action | By | Next State | | ||
| |--------|----|------------| | ||
| | `cooperativeCancelAccepted` | Counterparty | `canceled` | | ||
| | (timeout/ignore) | - | Returns to previous state | |
Contributor
There was a problem hiding this comment.
Clarify "previous state" behavior for cooperative cancellation.
Line 221 indicates that if a cooperative cancel is ignored or times out, the order "returns to previous state." However, the specification doesn't clarify:
- Which state is considered the "previous state"?
- How is this previous state tracked/determined?
- From which states can an order transition into
cooperativelyCanceled?
The individual state definitions show cancel actions that go directly to canceled (not cooperativelyCanceled), suggesting cooperative cancellation may be a separate action. Consider adding clarification about when cooperative cancellation is used versus regular cancellation, and explicitly documenting the state tracking mechanism.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 218-218: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specify/v1-reference/ORDER_STATES.md around lines 218 - 221, Clarify the
cooperative-cancel flow: explicitly define what "previous state" means (the
immediate prior order state before entering cooperativelyCanceled), state how it
is recorded (e.g., persist a previous_state field when transitioning into
cooperativelyCanceled) and list which source states may transition to
cooperativelyCanceled (e.g., Open, Matched, PendingSettlement) along with the
exact transition triggers for `cooperativeCancelAccepted` and (timeout/ignore)
behavior; also document the difference between `cooperativeCancelAccepted` ->
cooperativelyCanceled and the regular `cancel` -> `canceled` path so readers
know when to use `cooperativelyCanceled` vs `canceled` and how the revert on
timeout returns to the recorded previous_state.
Comment on lines
+346
to
+385
| ### Buy Order Flow (Buyer Creates, Seller Takes) | ||
|
|
||
| ``` | ||
| ┌──────────┐ takeBuy ┌──────────────────┐ | ||
| │ PENDING │ ───────────────▶ │ WAITING_PAYMENT │ | ||
| │ │ │ │ | ||
| └──────────┘ └──────────┬───────┘ | ||
| │ | ||
| │ payInvoice | ||
| ▼ | ||
| ┌──────────────────┐ | ||
| │ WAITING_BUYER_ │ | ||
| │ INVOICE │ | ||
| └──────────┬───────┘ | ||
| │ | ||
| │ (buyer adds invoice) | ||
| ▼ | ||
| ┌──────────────────┐ | ||
| │ ACTIVE │ | ||
| └──────────┬───────┘ | ||
| │ | ||
| │ fiatSent | ||
| ▼ | ||
| ┌──────────────────┐ | ||
| │ FIAT_SENT │ | ||
| └──────────┬───────┘ | ||
| │ | ||
| │ release | ||
| ▼ | ||
| ┌──────────────────┐ | ||
| │ SETTLED_HOLD_ │ | ||
| │ INVOICE │ | ||
| └──────────┬───────┘ | ||
| │ | ||
| │ (auto) | ||
| ▼ | ||
| ┌──────────────────┐ | ||
| │ SUCCESS │ | ||
| └──────────────────┘ | ||
| ``` |
Contributor
There was a problem hiding this comment.
Critical inconsistency: Buy order flow contradicts state definitions and transition table.
The buy order flow diagram shows that after a seller pays the hold invoice in WAITING_PAYMENT state, the order transitions to WAITING_BUYER_INVOICE (lines 354-359), and then after the buyer adds an invoice, it transitions to ACTIVE (lines 361-364).
However, this contradicts:
- WAITING_PAYMENT state definition (line 76): states that
payInvoiceby Seller →active(notwaitingBuyerInvoice) - WAITING_BUYER_INVOICE state definition (line 51): states that
addInvoiceby Buyer →waitingPayment(notactive) - State transition table (line 491): shows
waitingPayment+payInvoice→active
The buy order flow makes logical sense (seller locks sats first, then buyer provides destination invoice), but the state definitions and transition table don't account for order-type-specific transitions. The specification needs to either:
- Add conditional transitions based on order type (buy vs sell), OR
- Correct the buy order flow diagram to match the current state definitions
🔧 Suggested approach to resolve
Option 1: Update state definitions to show order-type-dependent transitions:
WAITING_PAYMENT (line 76):
| Action | By | Next State |
|--------|----|------------|
-| `payInvoice` | Seller | `active` |
+| `payInvoice` | Seller | `active` (sell orders) or `waitingBuyerInvoice` (buy orders) |WAITING_BUYER_INVOICE (line 51):
| Action | By | Next State |
|--------|----|------------|
-| `addInvoice` | Buyer | `waitingPayment` |
+| `addInvoice` | Buyer | `waitingPayment` (sell orders) or `active` (buy orders) |Option 2: Add an "Order Type" column to the state transition table (line 484) to clarify which transitions apply to buy vs sell orders.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 348-348: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specify/v1-reference/ORDER_STATES.md around lines 346 - 385, The diagram
and the state definitions disagree: update the spec so transitions for
WAITING_PAYMENT, WAITING_BUYER_INVOICE and ACTIVE are consistent with the
buy-order flow by either (A) making the state transition rules conditional on
order type (buy vs sell) and documenting that payInvoice from WAITING_PAYMENT on
a buy order leads to WAITING_BUYER_INVOICE and addInvoice from
WAITING_BUYER_INVOICE on a buy order leads to ACTIVE (update the WAITING_PAYMENT
and WAITING_BUYER_INVOICE definitions accordingly), or (B) revert the buy order
flow diagram to match the existing rules (WAITING_PAYMENT + payInvoice → ACTIVE
and WAITING_BUYER_INVOICE + addInvoice → WAITING_PAYMENT); also update the state
transition table to include an "Order Type" column or conditional notes
indicating which transitions apply to buy vs sell orders and reference the
payInvoice and addInvoice transitions explicitly.
Member
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (2)
.specify/v1-reference/ORDER_STATES.md (2)
51-52:⚠️ Potential issue | 🔴 CriticalState transitions are still inconsistent across sections for buy flow.
The buy flow diagram (Lines 346–364) conflicts with the state definitions/table:
- Line 76 says
payInvoice→active- Line 51 says
addInvoice→waitingPayment- Line 491 repeats
waitingPayment+payInvoice→activeThese cannot all be true for buy orders at once.
Also applies to: 76-77, 346-364, 491-491
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md around lines 51 - 52, The ORDER_STATES doc has conflicting buy-flow transitions: reconcile the state transition for invoice/payment so it's consistent across the table and diagram—pick the canonical transition (either addInvoice -> waitingPayment then payInvoice -> active, or addInvoice -> active directly via payInvoice) and update all references (the transitions involving addInvoice, payInvoice, waitingPayment, active, cancel, canceled) so the table rows and the buy flow diagram use the same sequence; ensure the state-table entry for `addInvoice` and the diagram steps that mention `payInvoice`/`waitingPayment` are corrected to match the chosen canonical flow.
210-221:⚠️ Potential issue | 🟠 MajorDefine “previous state” for cooperative cancellation explicitly.
Line 221 still says “Returns to previous state” without defining how that state is recorded/restored or which source states can enter
cooperativelyCanceled. This remains ambiguous for implementers.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md around lines 210 - 221, Clarify what "previous state" means by listing which source states may enter the cooperative-cancel flow and by specifying the recording/restoration mechanism: update ORDER_STATES.md’s cooperative cancellation section to (1) enumerate allowed originating states (e.g., trading, awaitingCounterparty, etc.), (2) state that entering the cooperative-cancel pending state must atomically record the originating state in a field named previousState on the order, and (3) specify that on timeout/ignore the system restores that recorded previousState, while on the `cooperativeCancelAccepted` action the state transitions to `canceled` and the previousState is cleared; reference the `cooperativeCancelAccepted` action and the cooperative-cancel state name in the text and transitions table so implementers know how to record and restore state.
🧹 Nitpick comments (2)
.specify/v1-reference/ORDER_STATES.md (2)
26-31: Add blank lines around tables to satisfy markdownlint MD058.Current table formatting repeatedly violates MD058 and will keep doc lint noisy.
Also applies to: 49-54, 74-80, 99-105, 123-128, 145-149, 165-168, 184-187, 218-221, 240-245
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md around lines 26 - 31, Add a blank line before and after each Markdown table to satisfy MD058; for every table block (e.g., the table that starts with "| Action | By | Next State |") insert one empty line above the table header and one empty line after the table footer so the tables at all noted occurrences are separated from surrounding paragraphs and lists.
308-308: Add language identifiers to fenced code blocks.Markdownlint MD040 is valid here (
```text/```mermaid/```rust/```dartas appropriate) to improve rendering/tooling.Also applies to: 348-348, 389-389, 666-666
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/ORDER_STATES.md at line 308, Several fenced code blocks in ORDER_STATES.md are plain triple-backticks ("```") without language identifiers; update each such fence (the occurrences that currently are just "```") to include the appropriate language tag (e.g., ```text, ```mermaid, ```rust, ```dart) so tooling and rendering can detect the language and format correctly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.specify/v1-reference/ORDER_STATES.md:
- Line 243: The table has conflicting terminal mappings for the action names
adminCancel/adminCanceled: some rows map them to canceledByAdmin and another
maps them to canceled; pick the correct canonical terminal state (either
canceledByAdmin or canceled) and update all occurrences so they are
consistent—replace the mapping in the row(s) referencing
adminCancel/adminCanceled (currently at the three differing rows) to the chosen
target, and ensure the header/description text (where those action names appear)
and any duplicated variants (adminCancel vs adminCanceled) use the same
canonical name to avoid contradictory semantics.
- Line 415: The "active" order status is documented with conflicting colors: one
table lists `active` with hex `#1E3A8A` and token `statusActive`, while another
describes it as "Green"; pick the correct canonical color (hex or named color)
and make both places consistent by updating the other table entry and the
`statusActive` token to match; also search for any spec/test references to
`active` color and update them to the chosen value so UI behavior and tests
align.
- Around line 25-31: The action keys in ORDER_STATES.md (e.g., takeSell,
addInvoice, payInvoice) use camelCase but must match the protocol's kebab-case
action names defined in PROTOCOL.md; update all action identifiers in
ORDER_STATES.md (including the blocks around the shown diff and the ranges
noted: 49-53, 73-79, 601-649) to kebab-case (e.g., take-sell, add-invoice,
pay-invoice) OR implement and document a deterministic normalization step that
converts camelCase to kebab-case before protocol validation; ensure references
to actions like takeSell, addInvoice, payInvoice are consistently replaced or
normalized to the kebab-case equivalents so they match PROTOCOL.md.
---
Duplicate comments:
In @.specify/v1-reference/ORDER_STATES.md:
- Around line 51-52: The ORDER_STATES doc has conflicting buy-flow transitions:
reconcile the state transition for invoice/payment so it's consistent across the
table and diagram—pick the canonical transition (either addInvoice ->
waitingPayment then payInvoice -> active, or addInvoice -> active directly via
payInvoice) and update all references (the transitions involving addInvoice,
payInvoice, waitingPayment, active, cancel, canceled) so the table rows and the
buy flow diagram use the same sequence; ensure the state-table entry for
`addInvoice` and the diagram steps that mention `payInvoice`/`waitingPayment`
are corrected to match the chosen canonical flow.
- Around line 210-221: Clarify what "previous state" means by listing which
source states may enter the cooperative-cancel flow and by specifying the
recording/restoration mechanism: update ORDER_STATES.md’s cooperative
cancellation section to (1) enumerate allowed originating states (e.g., trading,
awaitingCounterparty, etc.), (2) state that entering the cooperative-cancel
pending state must atomically record the originating state in a field named
previousState on the order, and (3) specify that on timeout/ignore the system
restores that recorded previousState, while on the `cooperativeCancelAccepted`
action the state transitions to `canceled` and the previousState is cleared;
reference the `cooperativeCancelAccepted` action and the cooperative-cancel
state name in the text and transitions table so implementers know how to record
and restore state.
---
Nitpick comments:
In @.specify/v1-reference/ORDER_STATES.md:
- Around line 26-31: Add a blank line before and after each Markdown table to
satisfy MD058; for every table block (e.g., the table that starts with "| Action
| By | Next State |") insert one empty line above the table header and one empty
line after the table footer so the tables at all noted occurrences are separated
from surrounding paragraphs and lists.
- Line 308: Several fenced code blocks in ORDER_STATES.md are plain
triple-backticks ("```") without language identifiers; update each such fence
(the occurrences that currently are just "```") to include the appropriate
language tag (e.g., ```text, ```mermaid, ```rust, ```dart) so tooling and
rendering can detect the language and format correctly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 97117bc5-256f-4d40-9b07-3f96d0a13aaf
📒 Files selected for processing (2)
.specify/v1-reference/ORDER_STATES.mdspecs/001-mostro-p2p-client/spec.md
✅ Files skipped from review due to trivial changes (1)
- specs/001-mostro-p2p-client/spec.md
Comment on lines
+25
to
+31
| **Transitions:** | ||
| | Action | By | Next State | | ||
| |--------|----|------------| | ||
| | `takeSell` | Buyer | `waitingBuyerInvoice` | | ||
| | `takeBuy` | Seller | `waitingPayment` | | ||
| | `cancel` | Creator | `canceled` | | ||
|
|
Contributor
There was a problem hiding this comment.
Action naming format conflicts with protocol contract.
This file consistently uses camelCase action keys (e.g., takeSell, addInvoice, payInvoice), while .specify/PROTOCOL.md:38-59 defines protocol actions in kebab-case (e.g., take-sell, add-invoice, pay-invoice). Without an explicit normalization rule, this is error-prone.
Also applies to: 49-53, 73-79, 601-649
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 26-26: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specify/v1-reference/ORDER_STATES.md around lines 25 - 31, The action keys
in ORDER_STATES.md (e.g., takeSell, addInvoice, payInvoice) use camelCase but
must match the protocol's kebab-case action names defined in PROTOCOL.md; update
all action identifiers in ORDER_STATES.md (including the blocks around the shown
diff and the ranges noted: 49-53, 73-79, 601-649) to kebab-case (e.g.,
take-sell, add-invoice, pay-invoice) OR implement and document a deterministic
normalization step that converts camelCase to kebab-case before protocol
validation; ensure references to actions like takeSell, addInvoice, payInvoice
are consistently replaced or normalized to the kebab-case equivalents so they
match PROTOCOL.md.
| | Action | By | Next State | | ||
| |--------|----|------------| | ||
| | `adminSettle` | Admin | `settledByAdmin` | | ||
| | `adminCancel` | Admin | `canceledByAdmin` | |
Contributor
There was a problem hiding this comment.
adminCancel target state is contradictory inside the same spec.
Lines 243 and 501 map adminCancel to canceledByAdmin, but Line 638 maps adminCancel/adminCanceled to canceled. This creates conflicting terminal semantics.
Suggested minimal doc fix
-| `adminCancel` / `adminCanceled` | `canceled` | Admin canceled the order |
+| `adminCancel` / `adminCanceled` | `canceledByAdmin` | Admin canceled the order |Also applies to: 501-501, 638-638
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specify/v1-reference/ORDER_STATES.md at line 243, The table has conflicting
terminal mappings for the action names adminCancel/adminCanceled: some rows map
them to canceledByAdmin and another maps them to canceled; pick the correct
canonical terminal state (either canceledByAdmin or canceled) and update all
occurrences so they are consistent—replace the mapping in the row(s) referencing
adminCancel/adminCanceled (currently at the three differing rows) to the chosen
target, and ensure the header/description text (where those action names appear)
and any duplicated variants (adminCancel vs adminCanceled) use the same
canonical name to avoid contradictory semantics.
| | `waitingBuyerInvoice` | `#7C2D12` (orange-900) | `#FED7AA` (orange-200) | `statusWaiting` | | ||
| | `waitingPayment` | `#7C2D12` (orange-900) | `#FED7AA` (orange-200) | `statusWaiting` | | ||
| | `paymentFailed` | `#1F2937` (gray-800) | `#D1D5DB` (gray-300) | `statusInactive` | | ||
| | `active` | `#1E3A8A` (blue-900) | `#93C5FD` (blue-300) | `statusActive` | |
Contributor
There was a problem hiding this comment.
active status color is inconsistent between tables.
Line 415 defines active as blue (#1E3A8A), but Line 735 says color is “Green”. UI behavior/spec tests will diverge unless one source is corrected.
Also applies to: 735-735
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.specify/v1-reference/ORDER_STATES.md at line 415, The "active" order status
is documented with conflicting colors: one table lists `active` with hex
`#1E3A8A` and token `statusActive`, while another describes it as "Green"; pick
the correct canonical color (hex or named color) and make both places consistent
by updating the other table entry and the `statusActive` token to match; also
search for any spec/test references to `active` color and update them to the
chosen value so UI behavior and tests align.
added 3 commits
March 23, 2026 17:41
![MostronatorCoder[bot]](https://github.githubassets.com/images/gravatars/gravatar-user-420.png){kind=avatar}
Adds complete specification for all 15 order states: - Visual representation with exact color codes - State descriptions and available actions - Transition tables by role (buyer/seller) - Complete flow diagrams for sell and buy orders - My Trades list item layout - Action button requirements by state - Implementation notes for Rust/Flutter split - Testing scenarios with code examples Order States Documented: 1. PENDING - Initial state 2. WAITING_BUYER_INVOICE - Buyer provides invoice 3. WAITING_PAYMENT - Seller pays hold invoice 4. PAYMENT_FAILED - Payment timeout/retry 5. ACTIVE - Fiat exchange in progress 6. FIAT_SENT - Buyer marked fiat sent 7. SETTLED_HOLD_INVOICE - Sats being routed 8. SUCCESS - Trade completed 9. CANCELED - Order canceled 10. COOPERATIVELY_CANCELED - Waiting for cancel agreement 11. DISPUTE - Under admin review 12. SETTLED_BY_ADMIN - Admin resolved for buyer 13. CANCELED_BY_ADMIN - Admin resolved for seller 14. COMPLETED_BY_ADMIN - Admin force-completed 15. EXPIRED - Order timed out
Adds 5 new appendix sections from ORDER_STATUS_HANDLING.md: ## Appendix A: Action-to-Status Mapping - Complete action tables for seller/buyer perspectives - Dispute actions and terminal actions - Status preservation edge cases (paymentFailed + addInvoice) ## Appendix B: Role-Specific Status Display - Seller releases flow diagram (buyer vs seller timeline) - Explanation of why settledHoldInvoice exists ## Appendix C: Restore Flow - Synthesized actions by status for buyer/seller - Critical note on settledHoldInvoice vs success in restore ## Appendix D: Dispute Auto-Closure - Auto-closure rules for terminal states - Dispute action values by closure reason - Rationale for inferring closure vs subscribing to events ## Appendix E: UI Labels Reference - My Trades list compact labels - Order Details descriptive labels Now contains all information from both original documents in one comprehensive spec.
mostronatorcoder
Bot
force-pushed
the
docs/order-states-spec
branch
from
March 23, 2026 17:42
667c4f4 to
ad94cba
Compare
added 4 commits
March 23, 2026 17:47
Fixes (inline): 1. COOPERATIVELY_CANCELED: clarified previous_state concept, source states (active, fiatSent), difference vs canceled (pending vs terminal), and behavior when peer ignores the request 2. WAITING_PAYMENT and WAITING_BUYER_INVOICE: added order-type-dependent transition tables showing: - Sell order: payInvoice → active - Buy order: payInvoice → waitingBuyerInvoice - Sell order: addInvoice → waitingPayment - Buy order: addInvoice → active Flow diagrams were already correct (buy order shows payInvoice → waitingBuyerInvoice). State definitions now match the diagrams. Nitpicks: 3. Added 'text' language tag to all 3 ASCII diagram fenced blocks 4. Added blank lines before/after all transition tables
- Fix COOPERATIVELY_CANCELED: clarified that trade can continue normally from this state (fiatSent, release, dispute) without automatic reversion - Add blank lines before/after transition tables for markdown linting - Verify ASCII diagrams have proper text tags
…tatus The Mostro protocol does NOT change the order status when cooperative cancel is requested. The order stays in its current state (active, fiatSent, etc.). Mostro only sends notification actions. cooperativelyCanceled is a client-side UI state (visual overlay), not a protocol-level status change. Key corrections: - Order remains in current status (active stays active) - Both parties can continue trade normally (fiatSent, release, dispute) - Cancel only completes when counterparty accepts - UI shows 'Canceling' as overlay, not as actual status
Some actions are notifications only (cooperativeCancelInitiatedByYou, cooperativeCancelInitiatedByPeer, disputeInitiatedByPeer) and do NOT change the order status. Appendix A now documents status-changing actions, with a note about notification-only actions.
grunch
approved these changes
Mar 23, 2026
This was referenced Mar 23, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds complete specification for all 15 order states in the Mostro protocol, including visual representation, state transitions, and UI requirements.
Document
.specify/v1-reference/ORDER_STATES.md(~19KB)Content
All 15 Order States
Complete State Machine
My Trades UI Specs
Action Buttons by State
Requirements for each state:
Implementation Notes
Testing
Source
Extracted from v1 implementation:
lib/data/models/enums/status.dartlib/core/mostro_fsm.dartlib/features/trades/widgets/trades_list_item.dartlib/core/app_theme.dartSummary by CodeRabbit