morphit/docs/adr/0009-phase3c-order-posting.md

# ADR-0009 — Phase 3c order posting + enforcement architecture

**Status:** Accepted
**Date:** 2026-04-19
**Deciders:** project maintainer
**Supersedes:** none
**Superseded by:** none

> **2026-05-12 forward note (Part 120 audit):** the
> "3 minutes" replace-window references throughout this
> ADR describe the value as originally specified.  Updated
> to **15 minutes** in Part 70 per ADR-0001's 2026-05-07
> Amendment.  This ADR is preserved with the original
> 3-minute references for historical accuracy; ADR-0001
> is authoritative for the current window.

## Context

Phase 3b delivered the indexer's **read** path: users can browse
orders that already exist on chain. Phase 3c delivers the **write**
path: a user composes an order in the browser, signs and broadcasts
it to Blurt, and pays the Morphit listing fee.

Several decisions couldn't be made in Phase 3b because they depend
on the compose flow:

1. **Fee payment mechanics.** The PLAN says listing costs "$0.25
   USD-equivalent, 50% off in BLURT." How does the indexer verify
   the user actually paid? What happens if the user underpays?
2. **Transaction composition.** The `morphit_order_v1` op is a
   `custom_json` signed by the posting key. A BLURT transfer is
   signed by the active key. These are different auth levels. Do
   they go in one transaction or two?
3. **Replace-window enforcement.** ADR-0001 mandates 3 minutes.
   Enforced where — on the client (so the UI hides the button),
   on the indexer (so late replaces are ignored), or both?
4. **Sybil fee escalation.** "Orders 1–3 at $0.25, 4–10 at +25%,
   11+ at +50%, resets when old orders cancel or expire" is
   prescriptive but underspecified. What counts as "an order"
   for the purpose of counting? Rolling 24 hours, calendar day, or
   since-last-reset?
5. **Self-trade detection.** "Indexer correlates fee-payment
   patterns" — concretely, which signals?

## Decision

### 1. Fee payment — single Blurt transaction, two active-level operations

Posting an order paid in BLURT is a single Blurt transaction
containing two operations in order:

1. `custom_json` — the `morphit_order_v1` op, declared at **active**
   authority (`required_auths: [signer]`, empty `required_posting_auths`)
2. `transfer` — a BLURT transfer from the signer to the Morphit
   fee-collection account `@morphit-fees`, with a specific memo
   format (active authority, as all transfers are)

Both ops go in **one** signed transaction. This gives atomicity:
either both land on chain or neither does. A user cannot post an
order without paying, nor pay without posting.

**Why the order op is active-level here, not posting (cp407).** A
transfer requires active authority, and Blurt (Graphene) rejects any
transaction that mixes posting-level and active-level operations — it
asserts `required_active.size() == 0` when a posting op is present.
So an order op that shares a transaction with the fee transfer MUST
itself be active-level; the whole transaction is then active-level and
takes a **single active signature**. (The original design signed a
posting-level order op alongside the active transfer, which the chain
rejected on every BLURT-paid order — this was fixed by making the
order op active-level rather than splitting the fee into a second
transaction, which would have broken atomicity and the sibling-op fee
verification below.)

The frontend asks the user to unlock their active key once, signs the
whole transaction with the active key alone, and broadcasts.

Orders whose fee is **waived** or paid **externally** (BTC/XMR) carry
no `transfer`, so they remain a lone posting-level `custom_json`. The
indexer therefore accepts an active-level order op for exactly the
fee-bearing op ids (`morphit_order_v1`, `morphit_feature_bid_v1`,
`morphit_stranger_fee_v1`) and stays posting-only for every other op
(see the indexer's `extractSigner`).

The transfer memo format is:

```
morphit-fee:<permlink>
```

This ties the fee to the specific order. The indexer's order
handler looks for a matching transfer op in the same transaction,
with the correct amount (±1% tolerance for price-feed drift) and
recipient. If not found, the order is marked `rejected:fee_missing`
and invisible in the orderbook.

### 2. Fee currency and amount calculation

BLURT-only in Phase 3c. Paying in BTC or XMR would require
waiting for confirmations before the order goes live —
unreasonable for a listing that may only be up for 24h anyway.
The $0.25 ✕ 50% BLURT discount nets to **$0.125 USD-equivalent in
BLURT**, which at the fallback price of $0.002/BLURT is 62.5
BLURT. A round-up to 63 BLURT is what the compose UI quotes; the
indexer accepts anything in 62.5..65 BLURT to allow for price-feed
drift (see below).

The frontend fetches the current BLURT price, computes the fee,
and displays it in three ways simultaneously:

- The USD-equivalent number ($0.125 at list; more for escalation
  tiers)
- The BLURT amount the user will actually pay
- The fresh-ness of the price (per ADR-0004 "prices updated X
  seconds ago" indicator)

The indexer also fetches BLURT prices, but its verification
allows a **±1% tolerance** around the expected fee amount to
absorb the mismatch between the price the frontend saw and the
price the indexer sees one block later.

### 3. Replace-window enforcement — indexer is authoritative

The 3-minute edit window is enforced at the **indexer**, per
ADR-0001. The client also respects it (hides the Edit button
after 3 minutes) but only as a UX courtesy — a misbehaving or
out-of-sync client cannot bypass the rule because the indexer
silently drops late `morphit_order_replace_v1` ops.

This means the client computes the window from *block time* of
the original order, not local wall-clock time. The indexer uses
block time too. The `orderReplace` handler checks:

```
current_block_time - original.created_at <= 3 minutes
```

If exceeded: `rejected:replace_window_expired`. The original
order remains on chain, unchanged.

### 4. Sybil fee escalation — 24h rolling window, per account

The listing fee escalates as an account posts more orders in a
rolling 24-hour window. "Orders posted" means orders that are
currently `live` OR that were created in the last 24h (even if
since cancelled/expired). Cancellation does not retroactively
reduce the fee for the cancelled order, but it removes that
order from the *count* so the *next* order pays less.

Concretely, at the moment of posting, the indexer computes:

```
n = count of orders where:
      account = signer AND
      (status = 'live' OR created_at >= now - 24h)
```

The expected fee for the nth order is:

| n        | Multiplier | Expected USD |
|----------|-----------|--------------|
| 1, 2, 3  | 1.00×     | $0.125       |
| 4        | 1.25×     | $0.156       |
| 5        | 1.56×     | $0.195       |
| 6        | 1.95×     | $0.244       |
| 7        | 2.44×     | $0.305       |
| 8        | 3.05×     | $0.381       |
| 9        | 3.81×     | $0.477       |
| 10       | 4.77×     | $0.596       |
| 11+      | 1.50× per additional, compounding on top of tier-10 |

These numbers grow fast by design: an honest user rarely posts
more than 3 orders a day; a spammer pays real BLURT in
escalating amounts. A user who posts and cancels, posts and
cancels, still pays escalating fees as long as they're doing it
within a 24h window.

The compose UI shows the user which tier they're in and what the
fee is, before they sign. No surprises.

### 5. Self-trade detection — two signals

An indexer cannot prove two accounts belong to the same person,
but it can flag patterns that strongly suggest it:

**Signal A — fee-address timing.** Two accounts that:
- Post orders within 5 minutes of each other
- Have never previously broadcast to chain before their
  respective `morphit_profile_v1` ops
- Have their `account_create` ops signed by the same creator
  account

→ flagged as `related_accounts`. Feedback between flagged pairs
is weighted to zero in their reputation totals.

**Signal B — feedback reciprocity.** Two accounts that:
- Exchange ≥3 mutual 5-star reviews within 7 days
- Have no other feedback from third parties

→ flagged as `suspicious_reciprocity`. Same weighting treatment.

Both signals are advisory, not dispositive. Flagged pairs are
publicly visible on their profile pages so other users can judge
for themselves. No automated penalties beyond the feedback
weighting.

## Schema changes

Three new indexer tables:

- `fee_transfers` — records of observed BLURT transfers to
  `@morphit-fees` with parsed memo. Indexed on `memo_permlink`
  and on `signer` for the Sybil counting query.
- `related_accounts` — self-trade Signal A output. Rows written
  when the pattern is detected; never deleted.
- `suspicious_reciprocity` — Signal B output. Same write-once
  semantics.

And one new field on `orders`:

- `fee_status` — one of `unverified`, `verified`, `missing`,
  `underpaid`. Set by the order handler based on what it finds
  in `fee_transfers`.

Migration version bumps to 2 in `src/db/migrations.ts`.

## Alternatives considered

### Two separate transactions for order + fee

- **Pros:** simpler crypto ceremony — one op per signature.
- **Cons:** race conditions (fee paid but order broadcast fails;
  order broadcast but fee payment times out). No atomicity.
- **Rejected.**

### BTC or XMR fees accepted

- **Pros:** user doesn't need to hold BLURT to list.
- **Cons:** waiting for BTC/XMR confirmations (10+ minutes for
  BTC) makes listing unusable for the "post now while I'm
  grocery shopping" case. Also creates an on-chain feedback
  loop: the indexer would need to watch BTC/XMR networks too.
- **Rejected for Phase 3c.** Revisit if BLURT price crashes and
  the fee becomes prohibitive on a per-listing basis.

### Client-only replace window

- **Pros:** no server-side state to track.
- **Cons:** a misbehaving client bypasses the rule entirely, and
  the chain would accumulate replacement ops that the indexer has
  to silently swallow anyway. Better to make the indexer
  authoritative and have the client match.
- **Rejected.**

### Calendar-day Sybil window instead of rolling 24h

- **Pros:** simpler to reason about.
- **Cons:** a spammer posts their 11th, 12th, 13th orders at
  23:55, then 11th, 12th, 13th again at 00:05. Calendar-day
  window lets them pay tier-1 fees for all 20.
- **Rejected.**

## Consequences

### Positive

- A user who honestly posts 1-3 orders per day pays exactly
  $0.125 per order, every time, forever. No surprises.
- A spammer faces steeply escalating costs within a 24h window.
- The "edit a typo" case works for 3 minutes after posting, which
  is plenty of time for the user to notice the typo during their
  own "did I spell everything right?" review.
- The fee payment and order posting are atomic. No "I paid but
  my order isn't showing up" scenarios.

### Negative

- BLURT price volatility means the USD-equivalent fee shifts.
  A user fetching the price at T=0 and broadcasting at T=30s may
  be ±0.5% off the indexer's later price; we absorb this with the
  1% tolerance band.
- The fee-collection account (`@morphit-fees`) is a centralised
  point. Compromise of this account's owner keys lets an
  attacker divert fees. Mitigation: owner/active keys are cold-
  stored, posting key used only for public announcements.
- A user who pays the fee but whose order is rejected for
  *other* reasons (malformed payload, for example) loses the
  BLURT. This is acceptable: the fee is a cost of trying to
  post, not a refundable prepayment.

### Neutral

- The Sybil escalation table is tunable via config without
  schema changes. If real-world usage shows the numbers are
  too aggressive or too lenient, adjust and redeploy.

## Non-goals (explicit, for future phases)

- Featured-slot auction (Phase 3c is "minimum viable orderbook";
  featured slots are Phase 4+).
- Multi-currency fee acceptance (Phase 3c is BLURT-only).
- Automated chargeback or refund mechanism for rejected orders
  (Phase 5 at earliest).
- Email notification when an order's fee is rejected (Phase 5;
  the UI shows the fee_status inline on the user's own orders
  page).

## Amendment — 2026-05-07 (Part 70)

The replace-window referenced throughout this ADR ("3 minutes")
was extended to **15 minutes** in Part 70. The full rationale,
threat-model re-analysis, and complete list of updated call
sites lives in `docs/adr/0001-custom-json-replacement.md`
under "Amendments → 2026-05-07."

This ADR's enforcement-point claim still holds: the window is
indexer-enforced, the client respects it as a UX courtesy, and
a misbehaving or out-of-sync client cannot bypass the rule.
Only the numeric value changed. References in the body of
this document to "3 minutes" should be read as "the
replace-window value, now 15 minutes per the 2026-05-07
amendment."

---

## Part 113 amendment (2026-05-10) — Signal C + cited-order fee_status gate

### Reputation attack surface enumerated

A from-scratch audit of every way someone's
reputation score can be **faked** (inflation) or
**hurt** (deflation) caught two real gaps in the
pre-Part-113 defenses.

**Vector A5 — feedback citing an order whose
`fee_status` is NOT 'verified'.**  The feedback
handler's cited-order check (added per Finding R17)
only required that the order exists and belongs to
the subject.  An order with `fee_status='missing'`
or `'underpaid'` — meaning the listing fee was
never paid — was still a valid citation target.
An attacker could broadcast many `morphit_order_v1`
ops without paying any fee and use those rows as
free citation targets for fake feedback from sock
puppets.  Forging a citation target was effectively
free (sub-BLURT op-broadcast cost).

**Vector B3 — coordinated low-rating pile-on.**
Signal A catches same-creator close-timed clusters
(reputation inflation via tightly-related sock
puppets).  Signal B catches mutual 5-star exchange
clusters (inflation via reciprocal sock-puppet
reviews).  Neither catches the deflation case: a
malicious actor coordinates 3+ sock-puppet accounts
from different creators to leave 1-2 star reviews
on a victim's orders, cratering their visible
average rating.

### Fixes shipped in Part 113

**Fix #1 — fee_status='verified' on cited orders.**
The feedback handler's order EXISTS check now
includes `AND fee_status = 'verified'`.  Rejection
reason renamed `order_permlink_not_found` →
`order_permlink_not_found_or_unverified` to make
the distinction explicit.

Economic effect: forging a citation target now
costs the actual listing fee (~$0.25 in
BLURT/BTC/XMR equivalent).  An attacker
provisioning 5 sock puppets to leave reviews about
themselves now pays $1.25 in real fees just for
the citation targets, plus the cost of provisioning
the sock accounts.  Reputation inflation is no
longer free.

### Signal C — one-way pile-on

**Trigger criteria (all must hold):**

1. ≥3 distinct reviewers targeting the same subject
2. Each reviewer's avg rating to that subject ≤2 stars
3. All reviews posted within a 7-day window
4. All reviewer `first_activity_at` clusters within
   a 14-day window (newly-active cluster vs
   varied-history real users)
5. Each reviewer's `distinct_subjects` in last 30
   days ≤2 (focused on the target, not diversified
   across the marketplace)

→ flagged as `one_way_pile_on`. Same advisory-not-
dispositive treatment as Signals A and B: feedback
from flagged reviewer→subject pairs is excluded
from the reputation summary aggregate but still
appears on the subject's public profile list.

**False-positive guard:**  Criterion 5 is the
backbone.  A real user reviewing five different
counterparties in the last month and giving one a
1-star has `distinct_subjects=5` and isn't
flagged.  A sock-puppet whose only Morphit activity
is a few low-star reviews on one target has
`distinct_subjects=1`.  Criterion 4 (clustered
first-activity timing) is the secondary guard
against patient-attacker sock puppets that activate
spread out over months.

### New schema (migration v31)

```sql
CREATE TABLE IF NOT EXISTS one_way_pile_on (
    id              BIGSERIAL PRIMARY KEY,
    subject         TEXT NOT NULL,
    detected_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    detection_date  DATE NOT NULL DEFAULT CURRENT_DATE,
    attacking_reviewers JSONB NOT NULL,
    avg_rating      NUMERIC(3, 2) NOT NULL,
    review_count    INTEGER NOT NULL,
    review_window_days INTEGER NOT NULL,
    activity_cluster_days INTEGER NOT NULL,
    UNIQUE (subject, detection_date)
);
```

UNIQUE (subject, detection_date) means same-day re-
runs don't insert duplicate rows; an expanding
attack appears as a new row the next day with the
larger attacker set.

### Aggregate exclusion

Both summary aggregates that drive user-visible
"reputation" — the per-account
`/v1/accounts/:account/feedback` summary and the
orderbook `weighted_rating` column — now filter out
rows where the (reviewer, subject) pair appears in
ANY of:

- `suspicious_reciprocity` (Signal B)
- `related_accounts` (Signal A)
- `one_way_pile_on` attacking_reviewers JSONB array
  (Signal C — new)

The list view (`/v1/accounts/:account/feedback`
list response) still returns the suppressed rows
so the subject can see what's been said about
them; only the aggregate excludes them.

### Priority-lens evaluation

- **Privacy (#1)**: zero new on-chain data; uses
  existing `feedback` + `accounts` tables.
  Detector runs locally on each indexer; results
  are local DB state, not federated.
- **Decentralization (#2)**: each operator's
  indexer runs the detectors independently.
  Different operators may flag different subsets
  if their indexers see different chain ranges
  (e.g. operator started later, missed early
  history) — that's expected and acceptable.
- **Grandma-friendliness (#3)**: end-user visible
  behavior is "the rating average ignores
  obviously-coordinated review clusters."  No new
  UX, no new operator config.

### What's NOT done (deferred)

- **Per-row "this review excluded by Signal C"
  badge in the list view.**  Filed as future UX
  improvement.  Currently the subject sees the
  flagged review in their list but no indicator
  that it's excluded from the aggregate.  Reviewing
  attackers via the database directly works for
  operators.

- **Display name-only "Signal A/B/C flagged"
  badge on profile.**  ADR-0009 says flagged
  pairs are "publicly visible on their profile
  pages."  Currently this is implicit — the
  rating is suppressed but the profile doesn't
  say "this account was flagged."  Filed as
  future UX work.

- **Time-decay of reputation.**  Old reviews
  weighted same as recent ones.  Acceptable per
  the FAQ design ("permanent and public").

- **A6 — verifying the reviewer was a counterparty
  on the trade.**  Structurally undecidable
  (Morphit trade settlement is off-chain).
  Acknowledged limitation.