morphit/docs/adr/0014-chat-and-counterparty-reputation.md

# ADR-0014 — Chat and counterparty reputation

**Status:** Partially superseded. The cipher and key-exchange
decision (Component A below) was REPLACED by ADR-0015 — see
"Cipher decision superseded" call-out below.  Component B
(message transport via on-chain `morphit_chat_v1` ops) and the
chat-reputation framing in Component C remain in effect.
**Date:** 2026-04-19 (updated 2026-04-23 with ADR-0015 cross-ref)
**Deciders:** project maintainer
**Superseded by:** ADR-0015 (cipher + key derivation only)
**Related:** ADR-0010 (key custody), ADR-0009 (order posting),
ADR-0011 (dynamic fee model), ADR-0001 (custom_json replacement)

> **Cipher decision superseded.** ADR-0014 originally proposed
> a forward-secrecy protocol using a heavy WASM library.
> ADR-0015 (2026-04-23) reviewed that decision and chose
> simpler per-message ECIES instead: X25519 ECDH for key
> agreement + ChaCha20-Poly1305-IETF for the AEAD, with
> message keys derived per-message via BLAKE2b.  Rationale:
> the project's threat model didn't actually require forward
> secrecy or post-compromise security (a posting-key
> compromise already ends the account's security story), and
> the WASM library's ~2MB bundle weight was a real cost
> against the "fast first paint" requirement.  The
> implementation lives in `apps/web/src/lib/chat/crypto.ts`.
> Read ADR-0015 for the full derivation, security
> properties, and the four requirements that drove the
> choice.
>
> Everything below this call-out predates ADR-0015 and is kept
> for historical context.  All references to specific
> forward-secrecy protocols are obsolete — the implementation
> uses the ADR-0015 ECIES design.

## Context

Current state: counterparties in a trade communicate via an
in-memory chat in the Morphit frontend, routed through a
websocket bridge. This has three serious problems:

1. **No persistence.** If a user reloads the page, chat
   history is lost. Users report this as a major friction
   point ("I lost my counterparty's bank details because I
   refreshed").
2. **No authenticity.** The websocket bridge is operator-
   run. A compromised operator could impersonate either
   counterparty or man-in-the-middle the conversation. We
   don't rely on this for anything critical (addresses should
   be shared out-of-band), but the attack surface is real.
3. **No reputation carry-over.** A counterparty who has had
   many successful trades has feedback on-chain, but their
   chat style and responsiveness — real trust signals — don't
   inform future interactions.

Phase 5 proposes to fix all three with an on-chain message
protocol: ciphertexts stored as `custom_json` ops, keys
derived from Blurt keys, rendering via authenticated
encryption with key derivation per-message (see ADR-0015 for
the resolved cipher choice).

### Constraints from Morphit principles

- **No custody of plaintext messages.** Messages must be
  end-to-end encrypted between counterparties. No operator,
  not even Agorise, should be able to read them.
- **Forward secrecy.** Compromise of long-term keys (a user's
  posting key, say) must not reveal past messages.
- **Post-compromise security.** After a compromise event, future
  messages should recover to being private once keys rotate.
- **Counterparty verifiability.** Each message must be
  provably from the account it claims (via signature), so a
  malicious operator can't inject messages.
- **Non-custody stays non-custody.** Chat must be signed with
  the user's own keys, not a Morphit-held key.
- **No dispute resolution via chat.** Per PHASE-5-BACKLOG:
  Morphit does not arbitrate disputes. Chat is a
  communication tool; it is not evidence in a Morphit-run
  dispute process, because there is no Morphit-run dispute
  process.

### Technical state of play

- Each Morphit account has a Blurt posting key and active key.
  Posting keys are used on every Morphit op; active keys for
  transfers only. Both are long-term; neither is suitable
  for ephemeral chat session keys.
- `custom_json` ops are the transport for all Morphit activity.
  The chain enforces signature validity per op; our indexer
  enforces payload shape.
- An order has a permlink. This is a natural "channel
  identifier" — two users are in a chat scoped to an order.

## Decision

**Component A — Cipher and key exchange.**

**SUPERSEDED by ADR-0015.** The original ADR-0014 proposal
named a heavy WASM forward-secrecy library; ADR-0015
replaced this with per-message ECIES (X25519 ECDH +
ChaCha20-Poly1305-IETF, keys derived per-message via
BLAKE2b).  Read ADR-0015 for the chosen design.  The
implementation lives in `apps/web/src/lib/chat/crypto.ts`.

**Component B — Message transport.**

Encrypted messages flow as `morphit_chat_v1` custom_json
ops on the Blurt chain. The op payload contains:

- `order_permlink`: the order this chat is scoped to
- `recipient`: the counterparty account name
- `ciphertext`: base64-encoded encrypted message body
- `header`: a JSONB object carrying envelope fields the
  indexer / frontend may need to read without decrypting
  the body — including the ephemeral pubkey for the
  per-message ECDH (the part of the message not encrypted
  under the derived message key) and a `client_tag` for
  client-side replay deduplication.  Indexer treats the
  header as opaque JSONB (size-bounded), narrowing only
  defensively at read sites.

The indexer records these ops into a `chat_messages` table
indexed by `(order_permlink, recipient, block_num)`. Ciphertext
is stored; plaintext never lands in the indexer.

**UNDECIDED 1:** Per-account chat identity keys — how are
they generated, stored, rotated? See Open Q1.
**RESOLVED 2026-04-23 by ADR-0015:** derive from posting key
via HKDF-SHA256; no separate chat identity published.

**UNDECIDED 2:** On-chain vs. hybrid storage. See Open Q2.

**UNDECIDED 3:** Replay / relay logic. See Open Q3.
**RESOLVED 2026-04-23 by ADR-0015:** source_trx_id unique
constraint handles replay; no extra client state needed.

**Component C — Reputation integration (SEPARABLE).**

After a trade completes (feedback signed by both parties), the
following signals become available for display in the UI:

- Number of chat messages exchanged before trade close
- Response time statistics (first response, average turn-
  around)
- Whether the chat hit a lull > N hours before trade close
  (often an indicator of trouble)

Reputation signals are DISPLAYED in the UI (on an order-
detail page and a counterparty profile page) and optionally
included in the chain-visible feedback op as additional
context. Display-only use is cheap; chain-included signals
require an additive extension to `morphit_feedback_v1`.

**UNDECIDED 4:** Reputation chain-inclusion depth. See Open Q4.

**What Morphit does NOT provide:**

- Arbitration. Chat is communication, not evidence for a
  Morphit-run dispute process.
- Automated moderation. No content scanning, no auto-summarization,
  no auto-flagging. End-to-end encryption means even the operator
  can't read the messages.
- Analytics. No aggregated "average response time across
  all trades" metrics visible to anyone but the participants.
- Chat across multiple orders. Each chat is scoped to one
  order's permlink. Counterparties who trade repeatedly
  establish new chat sessions per order.

## Alternatives considered

- **Keep in-memory chat.** The current state. Rejected
  because the friction and security concerns above are
  real and increasing as user count grows.

- **Hosted chat server (Matrix, XMPP).** Morphit runs a
  Matrix homeserver; users authenticate via their Blurt
  keys. Rejected because it imports operational complexity
  (running a mature chat service), creates a single
  point-of-failure outside Morphit's control, and
  centralizes a component that the current architecture
  keeps distributed.

- **Roll our own crypto.** Write a forward-secrecy
  protocol from scratch for better library ergonomics and
  smaller bundle size. Rejected because rolling
  cryptographic protocols is how bugs land in production.
  Audited libraries are the only safe option for this layer.
  Note: ADR-0015 ultimately landed on a much simpler
  per-message ECIES design, which avoids both this
  alternative AND the heavy WASM library that the
  superseded Component A originally proposed.

- **Use Blurt's "private message" custom_json convention
  (if one exists).** Checked: it doesn't. No Blurt app uses
  a standard encrypted-messaging format we could adopt.

- **Peer-to-peer chat (libp2p, nostr).** Users' browsers
  establish direct connections and skip the Blurt chain
  entirely. Rejected because (a) browsers can't NAT-punch
  reliably; (b) users typically aren't online simultaneously
  during a trade window; (c) we'd lose the audit property
  that every message is chain-addressable.

## Consequences

### Positive

- End-to-end encrypted chat: operators can't read messages.
  Morphit can't read messages. Only the counterparties can.
- Cryptographically-authenticated senders: a hostile
  operator cannot impersonate a counterparty. (Protection
  that the current websocket-based chat lacks entirely.)
- Persistence: chat history survives page reloads and
  device swaps (if key material is preserved).
- Reputation signals from chat data: in-UI display makes
  response time and engagement visible to prospective
  counterparties.
- Defensible as privacy-preserving: a subpoena request
  for "the chat between alice and bob about order
  sell-btc-usd-xxxx" returns only ciphertexts; the
  operator can't decrypt them.

### Negative

- On-chain storage bloat. Every message is a Blurt op,
  and the chain grows forever. For chatty counterparties
  this could add up. (Quantify in Q2.)
- Blurt op throughput is finite. Can the chain support a
  trade that sends 50 messages in a minute? Probably yes
  (Blurt's fee_status allows many ops), but worth testing.
- Keystone for Blurt-network-dependent: if Blurt goes
  down or forks disruptively, chat goes down.
- Implementation complexity: cipher port, session
  management, key rotation, replay protection, message
  ordering. This is the largest feature in Phase 5.
- Key-loss consequences. If a user loses their chat
  identity key, all past chats on that account are
  permanently unreadable. Must be communicated clearly.

### Follow-up work

- Sub-ADR: chat identity-key management (Open Q1 is
  big enough to deserve its own ADR — RESOLVED by
  ADR-0015).
- Sub-ADR: message storage model (Open Q2 is the other
  big decision).
- `morphit_chat_v1` payload spec.
- Indexer handler for the new op.
- Frontend chat UI replacement.
- Key backup flow for users (posting key backup already
  exists; chat keys are new material).
- 10-locale copy for chat error states, key-loss warnings,
  "older messages may be unreadable" prompts.

## Open questions

**Q1 — Per-account chat identity keys.** Each account needs
a long-term keypair to seed encrypted-chat sessions. Two
options:

- **Derive from posting key.** A deterministic derivation
  (HKDF, domain-separated) gives every account a chat key
  without new user action. Pros: no new key material to
  lose. Cons: posting-key compromise compromises past chats;
  derivation exposes the chat key's address space to
  anyone who knows the posting pubkey.

- **Publish a chat identity as a custom_json.** User
  generates an ephemeral long-term chat keypair, publishes
  the pubkey via `morphit_chat_identity_v1`. Pros: chat
  compromise doesn't follow from posting-key compromise.
  Cons: new key material to lose; UI complexity around
  "publish your chat identity" (users who don't publish
  can't chat); key rotation needs a separate op.

- **Per-session ephemeral keys via dlog-signed handshake.**
  No persistent chat identity; each order's chat starts
  with a fresh handshake signed by posting keys. Pros:
  minimal additional infrastructure. Cons: handshake is
  a full round-trip (two messages) before content flows,
  costing latency and an extra on-chain op.

Leaning toward option 2 (published long-term chat identity)
but this deserves its own sub-ADR.

**Q2 — Storage model.** Three options, each with real
tradeoffs:

- **On-chain only.** Every message is a Blurt op. Storage
  is forever; retrieval is chain-scan. Works if message
  volume stays modest (~100 msgs/order avg). But a
  counterparty pair who trades actively for years could
  accumulate thousands of on-chain messages, contributing
  meaningfully to chain size. Blurt community reaction to
  this depends on scale.

- **Off-chain + on-chain integrity hash.** Ciphertext is
  stored on operator-run servers; a commitment hash goes
  on-chain. Retrieval is from any operator; integrity
  checked against on-chain hash. Pros: minimal chain load.
  Cons: operator-liveness-dependent for retrieval; new
  infrastructure to run.

- **Hybrid: recent on-chain, historic on cold storage.**
  Last N days on-chain (fast, always available), older
  messages archived to operator storage with on-chain
  pointers. Pros: best of both. Cons: implementation
  complexity, chat UX shows "archived — loading" delays.

Leaning toward on-chain-only for Phase 5 MVP, with explicit
plan to revisit if chain-load becomes problematic.

**Q3 — Replay protection.** Blurt ops are eventually-final;
an op submitted twice should be idempotent at the chat
layer. How do we detect replays?

- Per-message counter: each message embeds a counter
  derivable from session state. Replays are detected
  because the counter doesn't match current state.
- Timestamp window: reject messages with timestamps > N
  seconds in the past. Simple but crude.

**RESOLVED 2026-04-23 by ADR-0015.** ADR-0015's per-message
ECIES design uses the chain transaction id as a natural
nonce; replay detection is handled at the indexer layer by
the `(trx_id, op_index)` uniqueness already enforced by
Blurt + the indexer's own dedup on `source_trx_id`.

**Q4 — Reputation chain-inclusion.** The display-only
reputation signals (Component C) are cheap. If we want any
of them to be chain-visible (i.e., included in the
`morphit_feedback_v1` payload or a new companion op),
which should it be?

- Nothing: keep all reputation display-only based on
  client-side counting of on-chain messages.
- Message count: an integer field in feedback.
- Response time: aggregated metric in feedback.
- Boolean "was responsive": user-judged, bool in feedback.

The question is whether cross-client consistency matters
(i.e., does Alice see the same stats as Bob does?). If yes,
chain-include. If clients can compute independently from the
same on-chain data, don't chain-include.

Leaning toward nothing in chain — let clients compute from
ciphertext-counts (knowable without decryption) and the
feedback op itself.

## References

- PHASE-5-BACKLOG.md item 6
- ADR-0010 — key custody (constrains identity-key handling)
- ADR-0001 — custom_json replacement (transport foundation)
- ADR-0015 — chat crypto (resolved Component A)
- X3DH Key Agreement: https://signal.org/docs/specifications/x3dh/