morphit/docs/adr/0041-cross-instance-peer-disagreement.md

ADR-0041 — Cross-instance peer price disagreement detector (cp129 Defense F)

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

Date: 2026-05-23 Deciders: project maintainer (Ken) Related: ADR-0039 (self-sovereign pricing — designed 8 black-hat defenses A-H; Defense F was deferred from cp127 to "future work"; cp129 implements it). ADR-0040 (denomination configurability — the same-denomination filter in Defense F builds on this).

Context

ADR-0039 designed the morphit_native price fetcher with eight specific manipulation defenses (A through H). Seven shipped in cp127. Defense F — cross-instance peer disagreement detector — was deferred because it required federation-aware code that ADR-0039's scope didn't cover.

The threat Defense F addresses: what if THIS indexer is the one being manipulated?

All other cp127 defenses assume the indexer's own code paths are correct and the manipulation happens at the trader / data-source level (sock-puppet whales, slow-drift attacks, post-and-cancel races, etc.). But what if an operator is compromised — pressured by a regulator, bribed, captured — and starts patching their indexer to report a fake derived price? None of the in-indexer defenses can catch this; the indexer IS the source of truth for its own derivation.

Cross-instance peer disagreement DOES catch it. If my indexer reports BLURT/USD = $0.005 while every other indexer reports $0.002, that disagreement is suspicious by construction. An alert surfaces; the operator can investigate; users get a warning surface on /v1/health.

Decision

Ship a new background module — peerPriceMonitor.ts — that periodically samples peer instances' /v1/price/morphit-native/receipt endpoint, stores observations to a dedicated DB table, computes the peer median over a recent window, and compares against the indexer's own derived price. Sustained disagreement above threshold fires an alert.

Module

apps/indexer/src/indexer/price/peerPriceMonitor.ts (~480 lines including doc-comment). Exports:

• runPeerPriceSampleCycle(cfg, now?) — one sample cycle (query peers + store + compare + maybe alert). Returns a PeerSampleCycleResult for testability.
• startPeerPriceMonitor(cfg, intervalMinutes?) — schedules recurring cycles via setInterval; returns a stop function.
• fetchPeerReceipt(origin, asset, denomination_fiat, timeoutMs?) — single-peer HTTP query with short timeout + graceful failure.
• median(values) — pure-function median (sort-invariant, resists single outlier).
• disagreementExceedsThreshold(myPrice, peerMedian, threshold) — pure-function comparison.
• shouldFireAlert(aboveSince, now, lastAlert, sustained, cooldown) — pure-function alert decision (testable without wall-clock).
• pruneOldObservations(db, now?, retentionDays?) — TTL cleanup.

Storage

New schema-v36 table price_peer_observations:

Column	Type	Notes
peer_origin	TEXT	URL of the peer instance
asset	TEXT	which asset's price (BLURT today; BTC/XMR future)
denomination_fiat	TEXT	which fiat (USD today; EUR/XDR/XAU future per cp128)
observed_price	NUMERIC(38,18)	peer's reported derived_price
observed_at	TIMESTAMPTZ	when we recorded it
source_native	TEXT	'morphit_native' / 'unknown' — only morphit_native rows are used in the median

Indexed on (asset, denomination_fiat, observed_at DESC) for fast median-window queries. TTL'd to 7 days; cleanup runs every cycle.

Configuration

Two new env vars (both with sane defaults):

Env var	Default	Purpose
MORPHIT_INDEXER_PEER_PRICE_MONITOR_ENABLED	false	Opt-in master switch. Off for new instances with no peers.
MORPHIT_INDEXER_PEER_PRICE_SAMPLE_INTERVAL_MINUTES	30	How often to sample peers. ≥5 min recommended.

Numeric thresholds (built into the code, not env-tunable):

Constant	Default	Purpose
PEER_DISAGREEMENT_THRESHOLD	0.25	25% deviation triggers the over-threshold flag
PEER_DISAGREEMENT_WINDOW_HOURS	4	Time window for median computation
PEER_DISAGREEMENT_SUSTAINED_HOURS	4	Hours over-threshold before alert fires
PEER_ALERT_COOLDOWN_HOURS	24	Hours between alerts (anti-spam)
PEER_MIN_OBSERVATIONS	3	Below this, comparison is silent
PEER_OBSERVATION_RETENTION_DAYS	7	TTL for stored observations
PEER_FETCH_TIMEOUT_MS	10000	Per-peer HTTP timeout

These are constants to keep the trust model legible. An operator who wants to tune them needs to fork the code, which is a feature: peer-disagreement thresholds are a federation-level concern that shouldn't drift per-instance.

Wiring

• apps/indexer/src/main.ts starts the monitor on boot when enabled. Stop function registered for graceful shutdown.
• Federation discovery uses the existing known_instances table, filtered to last_probe_status IN ('good', 'quiet') — peers the federation prober already vetted.

Why median, not mean

A single malicious peer feeding a wildly wrong price (e.g. $1 BLURT/USD instead of $0.002) shouldn't be able to move the result. Mean is shifted by extreme values; median is not.

This means an attacker needs to compromise a majority of peers in the comparison window to manipulate the median — not just one or two. Combined with the federation prober's existing operator chain-registration checks (which require costly setup to get a peer into the directory at all), Sybil-ing the peer set becomes expensive enough to deter the attack class.

Why ≥3 peers minimum

Below 3 peers, the median is trivially moved by any single outlier (with 2 peers, median = average of the two; with 1, median = that value). At 3 peers, a single outlier is the min or max and gets filtered out by the median.

Operators with fewer than 3 reachable peers see the monitor degrade gracefully — no alert is ever fired. This is a feature: no signal is better than a misleading signal. An operator running on a brand-new federation should leave the monitor off until they have enough peers.

Same-denomination filter

Cp128 made denomination configurable per-operator. A USD- denominated indexer cannot meaningfully compare its BLURT/USD price to a EUR-denominated peer's BLURT/EUR price without a USD/EUR oracle, which would defeat the self-sovereign premise.

So the monitor filters peers to those reporting the SAME denomination_fiat. A USD-denominated indexer in a mostly-EUR federation will see few comparable peers and skip the comparison entirely (which is correct).

Same-source filter

The receipt endpoint can return prices from various sources (external feeds, native fetcher, static fallback). Comparing my native-derived price to a peer's external-feed-derived price is apples-to-oranges. So the median only includes peer observations where source = 'morphit_native' — apples to apples.

Peers running older versions that don't include a source field get tagged 'unknown' and excluded from the median.

Resilience scenarios

Single peer compromised, reporting wildly wrong price

• Their observation is one data point among ≥3.
• Median is unmoved.
• No alert. Defense works as designed (resistant to outliers).

Half the peers compromised, all reporting same wrong price

• The compromised group sets the median.
• I'd appear to be the outlier from MY perspective; my alert would fire on innocent me.
• This is the inherent limit of any majority-based defense. Same blind spot as cp127's "consensus from compromised sources." Cross-federation peer-Sybil is expensive but not impossible.
• Mitigation: the federation prober's chain-registration check (each peer must have a chain-broadcasted morphit_operator_register_v1 op) raises the cost.

My indexer compromised, reporting wildly wrong price

• Healthy peers' median is correct.
• I'm the outlier.
• Alert fires within 4 hours of sustained disagreement.
• This is the primary attack class Defense F catches.

My indexer + few peers compromised, but most peers healthy

• The median is mostly determined by the healthy majority.
• I'm flagged as the outlier (correct).
• Alert fires. Defense works.

Genuine market disagreement (e.g. flash crash)

• Different peers may have updated their native price at different cadences.
• Window is 4 hours — short-term volatility is averaged in.
• Sustained-disagreement window adds another 4 hours of dwell.
• For a true 8-hour disagreement to fire, the market must genuinely be reporting a divergent price. Reasonable.

Geographic isolation (peer-poor federation)

• <3 peers reachable → monitor degrades silently.
• No false alarms. Operator can investigate manually via /v1/instances and /v1/price/morphit-native/receipt.

All peers offline (network partition)

• 0 observations → silent.
• Operator sees peersQueried: N, observationsInWindow: 0 in debug logs.

What this design DOESN'T solve (honest limitations)

• All-federation collusion / shared poisoned source. If every operator is reporting the same wrong price (e.g. because they all rely on the same compromised external data), no cross-instance comparison can detect it. Same limitation as ADR-0039's Defense C documented.
• Geographic-isolation false negatives. An operator in a region where most peers are unreachable just sees fewer peer observations and may degrade to silent. Mitigation: monitor multiple federation peers across Tor + I2P + clearnet for reachability redundancy.
• Per-peer trust weighting. All peers count equally in the median. A future enhancement could weight peers by their age, trade volume, or federation-prober "goodness." Cp129 ships the simpler equal-weight approach; weighted-median is a REVISIT item.

Operator action required

• None mandatory. Default MORPHIT_INDEXER_PEER_PRICE_MONITOR_ENABLED=false is safe for any instance.

• Optional for operators with federation peers: set the env var to true after confirming you have ≥3 reachable peers via /v1/instances. No code change needed.

Privacy + decentralization posture

Per priorities #1 and #2:

• Peer queries are over normal HTTPS — same as the federation prober's existing queries. No new privacy surface.
• Observations live in this indexer's own DB — never federated, never on-chain, never logged externally.
• No new central authority. Each indexer makes its own comparison; alerts are local-only (operator logs + own /v1/health).
• No new mandatory peer. Disable the env var and the monitor doesn't run at all.

Smokes

apps/indexer/scripts/peer-price-monitor-smoke.ts — 28 structural scenarios covering: public surface area, sane numeric defaults, median pure-function correctness (including outlier-resistance), disagreementExceedsThreshold correctness (both directions, edge cases), shouldFireAlert correctness (sustained, cooldown, edge cases), and doc-comment defense manifest.

Future work

• Weighted peer median (REVISIT cp130+) — weight peers by federation-prober goodness score, age, or trade volume.
• /v1/health surface for the peer-disagreement state — Done, cp233. The latest peer-comparison cycle now surfaces on /v1/health?verbose=1 under price.peer (peers queried, peer median vs own price, deviation, above-threshold flag, alert), captured via an optional onResult callback on startPeerPriceMonitor so F's core logic was untouched. Surfaced alongside the cp233-wired defenses B (price.drift) and C (price.disagreement) — see ADR-0039's cp233 update. (The cp129 schema.sql comment claimed F already surfaced here; that was aspirational until cp233 — this future-work item was the accurate record.)
• Cross-asset extension — Done, cp130. The monitor is started per-asset for every configured (asset, denomination_fiat) pair (BLURT/BTC/XMR); cp233 captures each asset's latest result.

Related code/docs

• apps/indexer/src/indexer/price/peerPriceMonitor.ts — module
• apps/indexer/src/db/schema.sql — schema-v36 table
• apps/indexer/src/config/index.ts — env vars + Config fields
• apps/indexer/src/main.ts — startup + graceful shutdown wiring
• apps/indexer/src/api/health.ts — /v1/health price.peer surface (cp233)
• apps/indexer/scripts/peer-price-monitor-smoke.ts — 39 scenarios
• apps/indexer/scripts/price-source-hardening-smoke.ts — B/C/F wiring + surface scenarios (BW-*, CW-*, FS-*, cp233)
• ops/env/indexer.env.example — documented env vars
• scripts/run-smokes.sh — smoke registered in runner