morphit/docs/adr/0039-self-sovereign-pricing.md

# ADR-0039 — Self-sovereign price derivation (morphit_native): tiered anchor architecture with cross-stablecoin depeg detection (cp127)

**Status:** Accepted (shipped 2026-05; pre-launch hardening campaign)

**Date:** 2026-05-23
**Deciders:** project maintainer (Ken)
**Related:** ADR-0011 (fee-collection design, where BTC/XMR fees came from); §F.11 BLURT-native fee refactor (which removed price-source dependency from fee verification); cp123-cp125 reputation hardening (whose Sybil-signal tables this design reuses).

## Context

Pre-cp127, Morphit's BLURT/USD price feed used a composite source
that tried external upstreams (Klingex → Coingecko) before falling
back to an operator-set static floor (default `$0.002`).  This worked
during phases 3-4 when BLURT price was relatively flat, but had
several structural problems:

1. **External-source dependency**: every instance phoning home to
   Klingex or Coingecko makes Morphit's price visibility a function
   of external services that can be compromised, rate-limit us, or
   shut down entirely.  LocalBitcoins disappeared in 2023; LocalMonero
   in 2024; Klingex is regionally hosted and subject to its own
   regulatory environment.  Depending on external sources for
   anything "important" is the opposite of Morphit's decentralization
   priority (priority #2 per the standing rules).

2. **Static fallback drifts from reality**: the operator-set
   `$0.002` floor was a snapshot of BLURT price at one moment.  Over
   weeks-to-months it drifts from real market price, leaving the
   USD echo (visible to users alongside listing-fee BLURT amounts)
   meaningfully wrong when external sources are unavailable.

3. **No transparency**: users had to take the indexer's word for the
   price.  An operator could manipulate the static floor with no
   external check; a compromised Klingex value would be served as
   truth.

Ken's cp127 request: derive a self-sovereign price from on-platform
trade data, eventually reducing reliance on Klingex/Coingecko as
on-platform volume grows.  Subsequent discussion expanded the scope
to handle scenarios where stablecoins themselves shut down, USD
itself gets replaced, or various adversarial conditions emerge.

## Decision

A new price-source upstream, `morphit_native`, that derives the
displayed asset/fiat rate from on-platform verified-fee orders.
Slotted between Coingecko and the static floor in the composite
chain (Klingex → Coingecko → **morphit_native** → static floor).
Opt-in via `MORPHIT_INDEXER_PRICE_FEED_NATIVE_ENABLED=true`.

### Tiered anchor architecture

`morphit_native` resolves a price through three tiers, in priority
order:

**Tier 1 — USD-fiat-direct anchor (PRIMARY)**.  Orders where the
asset trades directly against the denomination fiat (typically USD)
via any payment method — bank transfer, cash in person, cash by
mail, Venmo, PayPal, etc.  The fiat side is stated explicitly by
the trader.  **Survives**: all stablecoin shutdowns, single-payment-
method failures, brand-new-fiat replacement of USD (via the
`denominationFiat` factory parameter).

**Tier 2 — Stablecoin-anchored supplement**.  Orders where the
asset trades against stablecoins via `payment_methods` keys
(`pay_usdt`/`pay_usdc`/`pay_dai`).  Each stablecoin's contribution
is gated by the cross-stablecoin depeg detector — only "pegged" or
"unknown" stablecoins count.  **Survives**: single-stablecoin
shutdown (tier skipped entirely when <2 stablecoins available;
Tier 1 covers).

**Tier 3 — Hybrid combined pool**.  When Tier 1 and Tier 2 each
independently fail to meet thresholds, combine into one pool.
Useful during bootstrap or post-shutdown degraded operation.

Each tier requires ≥3 distinct verified-fee traders with clean
Sybil-signal records.  Each trader contributes their own median
order price (one vote per trader, regardless of order count).  The
tier's final price is the median across trader medians.

### Cross-stablecoin depeg detection

A companion module (`stablecoinDepegDetector.ts`) computes
cross-stablecoin ratios from on-platform orders where stablecoins
trade against each other (USDT-vs-USDC, USDT-vs-DAI, USDC-vs-DAI,
etc.).  If all ratios are near 1.0, all stablecoins are pegged.
If one stablecoin's ratios consistently diverge from 1.0 by more
than the threshold (default 3%), that stablecoin is "depegged" —
the median deviation across all pairs involving that coin is the
classifier.

The detector is **self-anchored** — it doesn't require external
knowledge of "what USD is worth."  It only requires the assumption
that **the MAJORITY of stablecoins are correctly pegged at any
given moment**.  This is a much weaker and more defensible
assumption than "USDT = $1 always."

When fewer than 2 stablecoins are available (one or zero
stablecoins remain), cross-ratio detection cannot run.  All
stablecoins are reported as "unknown".  Tier 2 is skipped in this
state; Tier 1 USD-direct covers the derivation.

### Hardened against the cp127 black-hat scenarios

The design explicitly defends against the conspiracy-theorist
attack scenarios surfaced in pre-implementation discussion:

| # | Attack | Defense (built into the code) |
|---|---|---|
| A | Sock-puppet whale | Proportional contribution cap via per-trader median (one trader = one vote) |
| B | Slow-drift attack ("frog in boiling water") | Long-term drift monitor with 7-day exponential baseline; alert on 25% sustained divergence |
| C | Klingex compromise undetected | Cross-source disagreement detector; opt-in priority flip env var |
| D | Post-and-cancel race | 10-minute order-age grace period before order qualifies; live status re-checked at query time |
| E | Operator-config envelope widening | Hardcoded outer plausibility bounds (`HARDCODED_OUTER_MIN_USD = 0.00001`, `HARDCODED_OUTER_MAX_USD = 10_000_000`) that operator config can only TIGHTEN, never widen |
| F | Cross-instance federation manipulation | Peer disagreement detector — implemented cp129 (ADR-0041); surfaces on `/v1/health` as of cp233 |
| G | Patient sock-puppet evading Sybil filters | Price-derivation receipt endpoint `/v1/price/morphit-native/receipt` for after-the-fact forensics |
| H | Downstream oracle abuse | NOT-AN-ORACLE warning in receipt payload + listing-fee payload + ADR + FAQ |

Additional structural defenses:

- **Spread-model echo defense**: only `kind: 'fixed'` orders count.
  `kind: 'spread'` orders price against an external market
  reference; including them would create a circular dependency.
- **Multi-method double-count defense**: each Tier 2 order
  contributes via its FIRST eligible stablecoin only, regardless
  of how many stablecoin payment methods it accepts.
- **Cold-start floor**: each contributing account must have ≥1
  prior verified-fee completed order.  Same protection as the
  `is_new_trader` orderbook badge.
- **Sybil-table filters**: reuses cp123-cp125 reputation tables
  (`suspicious_reciprocity`, `related_accounts`,
  `one_way_pile_on`, `review_concentration`).  Price manipulation
  requires the same level of sophistication as reputation
  manipulation — high bar by design.

### Resilience scenarios

**One stablecoin shuts down** → Tier 2 runs in degraded mode (cross-
ratio detector returns "unknown" for the lone remaining; we treat
"unknown" as eligible; effectively the single remaining stablecoin
is assumed to be $1).  Tier 1 unaffected.

**Two or three stablecoins shut down** → Tier 2 skipped entirely
(`< NATIVE_MIN_STABLECOIN_COUNT_TIER2 = 2` eligible stablecoins).
Tier 1 still works.  Tier 3 falls back to Tier 1 alone.

**Brand new world currency replaces USD** → operator changes the
`denominationFiat` factory parameter (currently hardcoded to 'USD'
in the cp127 factory call site, but the module is parameterized).
Same factory works with new fiat code; no schema change needed
since `orders.fiat_currency` is already a generic TEXT field.

**External sources go completely dark** → composite chain falls
through Klingex → Coingecko → morphit_native → static floor in
order.  morphit_native picks up the slack when traders have generated
enough on-platform data.

### What this design DOESN'T solve (honest limitations)

- **Regulatory capture of all operators in a jurisdiction** —
  federation-level structural limit; users in affected jurisdictions
  use cross-jurisdiction instances via Tor/I2P/Lokinet.
- **State-actor forced account filtering** — operators can locally
  filter accounts; users compare across instances per
  `OPERATOR-TRUST-DESIGN.md`.
- **51%-of-legitimate-trade-volume by a single entity** — if one
  entity legitimately runs >50% of volume, they ARE the market by
  definition.  Not a bug.
- **Patient sock-puppet long-game (months of building reputation
  before activation)** — the cp123-cp125 Sybil filters catch
  concentration patterns at intake, but a patient diversified
  attacker can evade.  Defense G (receipt endpoint) makes
  post-hoc forensics easy; anticipation is the deterrent.
- **Klingex-Coingecko aggregation overlap** — Coingecko aggregates
  many sources including possibly Klingex.  Two-source check might
  effectively be one source displayed twice.  Documented honestly;
  no clean fix.
- **CBDC stealth via "USD" payment methods** — out of scope for
  the price-source design but relevant for broader privacy.

## Operator action required

- **None mandatory.**  Schema migration adds one new table
  (`price_drift_baseline`) idempotently via `CREATE TABLE IF NOT
  EXISTS`.  Existing instances pick this up on next indexer restart.
- **Optional**: operators can enable the native fetcher via
  `MORPHIT_INDEXER_PRICE_FEED_NATIVE_ENABLED=true` when they trust
  their platform's trade volume to support self-sovereign pricing.
- **Optional**: operators with mature data can flip
  `MORPHIT_INDEXER_PRICE_PREFER_NATIVE_WHEN_DISAGREEING=true` to
  prefer the native price over external sources during sustained
  disagreement.

## Performance posture

- **Per-refresh cost**: 3-6 SQL queries (one per tier + depeg
  detector cross-pair queries).  Each query is bounded by the
  8-hour window + Sybil-table filters.  Cheap relative to the
  composite source's 5-min refresh cadence.
- **Drift baseline update**: one INSERT-or-UPDATE per refresh per
  (asset, fiat) pair.  Trivial.
- **Receipt endpoint**: O(N) in qualifying orders + cross-pair
  data.  60s ETag caching mitigates repeat-call cost.

## Privacy posture

Per priority #1:

1. **No new on-chain data.**  All changes operate on already-chain-
   anchored orders + locally-derived signal tables.  No new custom
   JSON op types.
2. **Receipt endpoint reveals which accounts contributed to a price**
   — but this is already publicly inferable from the orderbook.  No
   new privacy leak.
3. **Cross-stablecoin depeg detector reads existing tables only.**
   No new chain-data inputs.

## Decentralization posture

Per priority #2:

- **Per-instance signal-table + baseline state** is the same posture
  as the pre-existing Signals A-D.  Two indexers can show slightly-
  different prices based on their local data.  The disagreement
  monitor + receipt endpoint surface this disagreement explicitly.
- **No new federation-wide constants** beyond the hardcoded outer
  envelope (which is a SAFETY floor, not a coordination point).
- **No new operator-mandatory config**.  Existing operators
  upgrade and the migration applies automatically.

## Future work

Tracked as REVISIT items for cp128+:

- ~~**Defense F (cross-instance peer disagreement detector)**~~ —
  **Done, cp129 (ADR-0041).**  Samples peer instances' receipts and
  alerts on sustained cross-instance divergence.
- **Per-asset wiring for BTC/USD, XMR/USD**: the factory is generic;
  wire additional asset/fiat instances when needed for the
  listing-fee USD-echo extension to BTC/XMR fees.
- **USD-equivalent display in orderbook**: per-asset native price
  surfaces in the orderbook UI for cross-order comparison.
- **denominationFiat parameterization at the call-site level**:
  today the factory hardcodes `denominationFiat: 'USD'`.  Wire it
  to an operator config field so non-USD operator instances can use
  morphit_native too.

## Update — cp233 (runtime wiring of B + C; `/v1/health` surfacing for B + C + F)

Defenses **B** (slow-drift) and **C** (cross-source disagreement)
were *built* in cp127 (modules + contract smokes) but were not yet
invoked in the live price-refresh path — only **F** (cp129) was
runtime-wired.  cp233 closes that gap and makes all three observable:

- **B** runs on every successful price refresh
  (`compositeSource.refreshOnce` → `updateAndCheckDrift`, per-asset),
  persisting its moving baseline to the `price_drift_baseline`
  table.  Peer-independent.
- **C** runs as a per-asset background monitor
  (`startDisagreementMonitor`) that cross-checks the published
  external price against a freshly-derived `morphit_native` price
  each cycle.  In-process, no table.  It treats the published price
  as an external reference **only** when it came from a real
  external market source (klingex/coingecko) — never the static
  floor or the native fallback — so it cannot false-alarm while
  external sources are briefly unreachable.  On by default whenever
  native pricing is enabled.  Peer-independent.
- **All three (B, C, F)** now surface on `/v1/health?verbose=1`
  under `price.drift`, `price.disagreement`, and `price.peer`, and
  each log-alerts on a sustained breach.
- The wiring is pinned by `price-source-hardening-smoke.ts`
  (`BW-*`, `CW-*`, `FS-*` scenarios) so a future refactor cannot
  silently unwire any of it.

Net effect: a lone early-beta instance with no federation peers
still gets slow-drift (B) and source-disagreement (C) protection; F
additionally activates once ≥3 peers are reachable.

## Related

- `apps/indexer/src/indexer/price/morphitNativeFetcher.ts` — generic
  factory + tiered anchor implementation
- `apps/indexer/src/indexer/price/stablecoinDepegDetector.ts` —
  cross-stablecoin ratio analysis
- `apps/indexer/src/indexer/price/driftMonitor.ts` — long-term drift
  sanity check (defense B)
- `apps/indexer/src/indexer/price/disagreementMonitor.ts` —
  cross-source disagreement detector (defense C)
- `apps/indexer/src/api/priceReceipt.ts` — `/v1/price/morphit-native/receipt`
  endpoint (defense G)
- `apps/indexer/scripts/stablecoin-depeg-detector-smoke.ts` —
  6 structural scenarios
- `apps/indexer/scripts/morphit-native-fetcher-smoke.ts` — 10
  structural scenarios (one per defense + contract checks)
- `apps/indexer/scripts/price-source-hardening-smoke.ts` — 14
  scenarios across receipt + drift + disagreement + factory wiring