docs: add anti-abuse bond documentation by Catrya · Pull Request #616 · MostroP2P/mobile

Catrya · 2026-06-15T21:38:48Z

Add docs/architecture/ANTI_ABUSE_BOND.md describing the client side of the anti-abuse bond
Cover node policy discovery, the 5 wire actions, taker/maker bond and payout-claim flows
Document bond-slashed forfeiture notice and the deferred-deletion session lifecycle

Summary by CodeRabbit

Documentation

Added/updated a comprehensive guide for the anti-abuse bond feature, including how bond policy is determined per node, the user payment and payout flows, forfeiture handling and notifications, session lifecycle and restart resilience, routing for bond payouts, and current limitations.

coderabbitai · 2026-06-15T21:39:02Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d6be4304-c349-42cf-b12e-de42d1738987

📥 Commits

Reviewing files that changed from the base of the PR and between 8ba9487 and adea37b.

📒 Files selected for processing (1)

docs/architecture/ANTI_ABUSE_BOND.md

✅ Files skipped from review due to trivial changes (1)

docs/architecture/ANTI_ABUSE_BOND.md

Walkthrough

A new architecture document docs/architecture/ANTI_ABUSE_BOND.md (495 lines) is added, comprehensively documenting the client-side anti-abuse bond feature: bond policy discovery from kind-38385 events, five wire actions, three distinct user flows (taker pays, maker pays via ephemeral session.bondPending, claim slashed share via BondPayoutPhase), session lifecycle/defer-delete rules, order_state.dart guard logic, notification wiring, test coverage, and known limitations.

Changes

Anti-Abuse Bond Architecture Documentation

Layer / File(s)	Summary
Overview, scope, and BondPolicy model `docs/architecture/ANTI_ABUSE_BOND.md`	Adds document scope and client-responsibility overview, feature summary mapping to relevant modules, three-state `BondPolicy` enum (unsupported/disabled/enabled), seven policy tags with parsing/validation rules, and claim-window days client-side defaulting.
Client-visible wire contract `docs/architecture/ANTI_ABUSE_BOND.md`	Enumerates the five supported `Action` values (`pay-bond`, `add-bond-invoice`, payout acks, `bond-slashed`), documents directionality and payload structure expectations, and clarifies the phase-2 limitation that the client does not directly observe solver-directed dispute slashes.
Three user flows `docs/architecture/ANTI_ABUSE_BOND.md`	Documents Flow 1 (taker pays: `waiting-taker-bond` state, pay-bond screen navigation, restart restore behavior), Flow 2 (maker pays: ephemeral in-memory `session.bondPending` flag, `AddOrderNotifier` timing, local abandon on rejection), and Flow 3 (claiming slashed share: `BondPayoutPhase` state machine with timestamp precedence, deadline computation from `slashed_at`, UI badge/button/claim-screen surfacing, submission error handling).
Session lifecycle, forfeiture notices, and retake guard `docs/architecture/ANTI_ABUSE_BOND.md`	Documents `bond-slashed` payload semantics and ordering relative to `canceled`, defer-delete logic for non-user-initiated bonded cancels, 60s grace window and timer reconciliation behavior, restart reconciliation on app relaunch, bond-slashed timer cancellation, and the retake guard preventing stale timers from deleting a refreshed session.
order_state.dart guard, notification wiring, and routing `docs/architecture/ANTI_ABUSE_BOND.md`	Explains the `_resolveStatus` guard preventing bond-related `SmallOrder` payloads with null status from overwriting tracked trade state, in-app-only notification wiring for bond actions, and the routing constraint directing payout to `/bond_payout/:orderId`.
Test suite coverage and known limitations `docs/architecture/ANTI_ABUSE_BOND.md`	Enumerates bond-related test files and their coverage scope (helpers truth tables, order-state guards, maker bond flow, notification tap behavior, session `bondPending`, bond-tag parsing), and lists known open items: push notifications not wired, anti-spam dedup behavior, non-live deadline countdown, and offline correctness dependency.

Sequence Diagram

sequenceDiagram
  participant Taker
  participant MakerClient
  participant Client
  participant Daemon

  Note over Taker,Daemon: Flow 1 — Taker pays bond
  Daemon-->>Taker: pay-bond action
  Taker->>Client: navigate to pay-bond screen
  Taker->>Daemon: pay invoice

  Note over MakerClient,Daemon: Flow 2 — Maker pays on order creation
  MakerClient->>Client: set ephemeral bondPending flag
  Daemon-->>MakerClient: add-bond-invoice action
  MakerClient->>Daemon: pay invoice
  Client->>Client: persist session after confirmation

  Note over Client,Daemon: Flow 3 — Claim slashed share
  Daemon-->>Client: bond-slashed action
  Client->>Client: set BondPayoutPhase, compute deadline from slashed_at
  Client->>Client: render badge/button on screen
  Client->>Daemon: submit payout claim

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

MostroP2P/mobile#608: This architecture doc directly describes the maker anti-abuse bond client flow implemented in that PR, including the ephemeral Session.bondPending flag, payBondInvoice handling, maker-cancel abandon logic, and maker-specific pay-bond screen copy.

Suggested reviewers

ermeme
mostronatorcoder
grunch

Poem

🐇 A bond doc blooms in pages clear,
With flows and guards that all align here.
Three paths to pay, one claim to make,
Session timers and guards awake.
Now architects and devs can peer! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation for the anti-abuse bond feature, which is precisely what the changeset does.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch doc-anti-abuse-bond

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

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/ANTI_ABUSE_BOND.md`:
- Around line 138-152: Add language specifiers to three fenced code blocks in
docs/architecture/ANTI_ABUSE_BOND.md to comply with the Markdown guideline that
requires every fenced code block to have a language specifier. For the flow
diagram blocks at lines 138-152, 187-210, and 236-250, change the opening fence
from three backticks (` ``` `) to ` ```text ` to properly identify these blocks
as text content. Each of the three locations requires the same fix: add "text"
immediately after the opening three backticks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d617e45e-bca1-4771-b611-c5c4bf0a379b

📥 Commits

Reviewing files that changed from the base of the PR and between 741535d and 8ba9487.

📒 Files selected for processing (1)

docs/architecture/ANTI_ABUSE_BOND.md

docs: add anti-abuse bond documentation

8ba9487

coderabbitai Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread docs/architecture/ANTI_ABUSE_BOND.md Outdated

Add language specifiers to fenced code blocks per coding guidelines

adea37b

grunch merged commit 23f1336 into main Jun 16, 2026
2 checks passed

grunch deleted the doc-anti-abuse-bond branch June 16, 2026 14:09

coderabbitai Bot mentioned this pull request Jun 17, 2026

feat(bond): cause-aware bond-slashed handling (dispute vs timeout) #619

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add anti-abuse bond documentation#616

docs: add anti-abuse bond documentation#616
grunch merged 2 commits into
mainfrom
doc-anti-abuse-bond

Catrya commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Catrya commented Jun 15, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Documentation

Uh oh!

coderabbitai Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Catrya commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading