The trade lifecycle and escrow

A trade is the only object in P2P that moves money. Everything about how it is built exists to guarantee one property: a trade's escrow is paid out at most once, no matter which of the six doors settles it.

The state machine

                 buyer confirms          seller releases
   PENDING ──────────────────────► PAYMENT_SENT ──────────────► COMPLETED
      │                                  │
      │ buyer cancels                    │ either party disputes
      ▼                                  ▼
  CANCELLED                          DISPUTED ──► COMPLETED  (admin)
      ▲                                  └──────► CANCELLED  (admin)
      │ payment window elapses
   EXPIRED

The allowed transitions are exactly these — nothing else is accepted:

Opening a trade

The taker chooses an amount and one of the offer's payment methods. Before anything is locked, an unauthenticated pre-flight answers "can this person actually fund it" so a doomed request never takes the offer's write lock.

Then, under a Redis lock on the offer (p2p:initiate:<offerId>:lock, 30 s) and a SERIALIZABLE transaction:

The payment method snapshot matters: trade.paymentDetails is a copy of the name, icon, instructions, processing time and the method's metadata as they were at that instant. If the maker later edits their bank details, the running trade still shows what the buyer agreed to.

Escrow: one authority, one guard

All escrow movement goes through a single settlement function. Six callers use it — the seller's release, user cancellation, the expiry cron, admin trade resolution, admin trade cancellation and admin dispute resolution — and they all share one wallet idempotency namespace, p2p_settle_<tradeId>.

p2pTrade.escrowStatus is the guard, taken under a row lock and flipped to a terminal value in the same transaction as the money:

Four settlement outcomes exist:

Amounts are clamped twice: to the escrow recorded on the trade, and to the seller wallet's real inOrder. A drifted ledger can therefore settle what genuinely exists rather than throwing and stranding the trade.

The fee

One fee exists. There is no maker fee, no taker fee, no dispute fee.

It is computed at trade initiation from the trade amount and stored on the row, then charged at settlement. Three things constrain it:

• It comes out of the buyer's proceeds and can never exceed them.
• It is never charged on a refund — a seller getting their own funds back is not taxed for it.
• A floor of 0.0001 applies, but only while it stays under 5 % of the trade amount. Without that cap, the absolute floor was ten dollars' worth of BTC — enough to equal a legal minimum-size BTC trade, produce a zero buyer credit, be rejected by the wallet service, and leave the escrow permanently stuck.

Sellers who hold Super Admin are exempt from the fee entirely. Collected fees are booked as platform revenue and recorded in p2p_commissions.

The payment window

One definition, used by the expiry cron, the trade view, the WebSocket and the payment-confirmation endpoint. In precedence order:

1. offer.tradeSettings.autoCancel, when it is a finite number ≥ 0. A value of 0 means never auto-cancel and stops here — it does not mean "expire immediately" and does not fall through.
2. offer.tradeSettings.paymentWindow — a legacy alias with the same meaning.
3. The admin setting p2pDefaultPaymentWindow.
4. 30 minutes.

The window is measured from trade.createdAt. The admin switch p2pAutoCancelUnpaidTrades disables trade expiry altogether; it does not affect the stale-payment safety net below.

What the cron does, every minute

Expires unpaid trades. PENDING trades past their window are set to EXPIRED, their escrow returned to the parent offer, and the offer's advertised capacity restored by what settlement actually released. Expiry is recorded on the cancellation columns (cancelledAt, cancellationReason: "Payment window elapsed") — there is no expiredAt column.

Auto-disputes stale payments. A trade sitting in PAYMENT_SENT for more than 24 hours is moved to DISPUTED with a high-priority dispute filed on the buyer's behalf. The escrow deliberately stays held; an admin settles it.

The deadline is anchored on paymentConfirmedAt — the instant the buyer declared payment — not on updatedAt. Every chat message rewrites the trade row, which bumped updatedAt and reset the safety net indefinitely: a seller who kept the conversation alive could hold a buyer's escrow forever.

Expires dead offers. See Offers.

Each scan is capped at 500 rows per tick and drains across ticks. The trade scan is deliberately newest-first: offers with autoCancel: 0 never expire and so never leave the candidate set, and an oldest-first batch would be permanently occupied by exactly those rows.

An admin can trigger the whole handler by hand from the trades screen if a window has clearly lapsed and nothing has happened.

Who may do what

Two of these deserve spelling out to support staff:

• A seller cannot cancel a pending trade. They are told to pause their offer instead. Letting a seller cancel would let them pull out of a trade a buyer is mid-way through paying for.
• Nobody can cancel after PAYMENT_SENT. The buyer cancelling would lose their money; the seller cancelling would be a straight theft — keep the fiat, get the crypto back. Both parties are directed to open a dispute.

A cancellation reason of at least 10 characters is required, and is stored on the trade.

Release

The seller presses release. In one transaction: the escrow settles to the buyer net of the fee, the trade goes COMPLETED with completedAt set, the activity log is written, and the offer's attributed escrow is drawn down.

After the commit: audit entries, notifications, a WebSocket status broadcast, and — if the MLM addon is installed — affiliate rewards for both parties' referrers, calculated from what settlement actually moved rather than a second local fee calculation.

Releasing is idempotent by two independent mechanisms. A Redis key caches the result for an hour, and the escrow authority's escrowStatus guard settles a trade at most once regardless.

Chat and attachments

Every trade has a private conversation between the two parties, stored as MESSAGE entries on the trade timeline and delivered over a WebSocket subscription rather than by polling.

• Messages are capped at 1000 characters and 100 per hour.
• Images can be attached, up to 5 MB each.
• An attachment can be read only by the buyer and the seller of that trade.
• Admins can post into the conversation from the dispute or trade screen; those messages are marked as admin messages and both parties are notified.

Message text is sanitised on the way in: line breaks and tabs survive, control characters and the characters that could open a tag do not. It is rendered as plain text.

Reviews

After a trade completes, each party may review the other. The UI submits a single 1–5 star rating; the storage is three independent 0–100 dimensions — communication, speed and trust — and a star rating is spread across all three. A caller can send the dimensions individually instead.

Feedback text is capped at 2000 characters. Review averages feed the hourly reputation job and the trader cards on the market board.