morphit/docs/PHASE-5-PLAN.md

# Phase 5 — Plan

**Status:** Draft for review, pre-implementation
**Date:** 2026-04-19
**Depends on:** Phase 4 deployed, PHASE-5-BACKLOG.md,
ADR-0012 (cross-post), ADR-0013 (operator incentives),
ADR-0014 (chat + reputation) — all currently stubs awaiting
resolution of open questions.

> **2026-05-11 forward note (Part 120 audit):** Sub-phases
> 5a, 5b, and 5d have all shipped, much faster than the
> "summer 2026 / fall 2026 / winter 2026→2027" timeline
> projected below.  Specifically:
>
> - **Sub-phase 5a (ecosystem reach)** → ✅ shipped.  Cross-post
>   flow lives at SYNDICATION-CHECKPOINT.md (Post A + Post B
>   + ADR-0017 preview).  Real price feed (Klingex composite)
>   shipped.  Morphit Blurt community at `blurt-176570` is
>   live.
> - **Sub-phase 5b (operator incentives)** → ✅ shipped as
>   **ADR-0013** (accepted + implemented 2026-05-02).
>   Operator registration, tag claim, payout pipeline all in
>   place; per-order operator payouts active.
> - **Sub-phase 5c (encrypted chat + reputation)** → realised
>   as **Phase 5d** under ADR-0015 (not ADR-0014; the original
>   ADR-0014 forward-secrecy plan was replaced by simpler
>   per-message ECIES per ADR-0015).  See CHAT-CRYPTO.md +
>   CHAT-UI-DESIGN.md.  Shipped through Phase 5d.
>
> The original timeline projections at the end of this doc are
> historical; the actual sequencing was faster and the chat
> design shifted from forward-secrecy session protocols
> (ADR-0014) to stateless ECIES (ADR-0015).  This file is
> preserved as the historical plan; current state is reflected
> in REVISIT-LIST.md and the ADRs.

## Goals

Phase 5 is the **ecosystem reach + decentralization** phase.
Phase 4 built the economics (fees, loyalty, welcome bonus).
Phase 5 uses those economic primitives to grow Morphit beyond
the three committed operators into a self-sustaining network.

Three independent-but-related bodies of work, each ship-able
on its own:

1. **5a — Ecosystem reach.** User-facing features that push
   Morphit's presence out onto the Blurt social layer and
   into the daily lives of current users. Cross-post flow
   (ADR-0012), Morphit Blurt community, real price feed,
   Phase 4 loose ends.

2. **5b — Operator incentives.** The economic mechanism that
   rewards third-party node operators with a share of listing
   fees (ADR-0013). This is the structural change that
   unlocks decentralization.

3. **5c — Encrypted chat + reputation.** End-to-end encrypted
   counterparty chat replacing the current in-memory bridge
   (ADR-0014). The biggest feature in Phase 5; probably its
   own release.

Each of these has its own design doc to come
(`PHASE-5a-DESIGN.md` etc.) once the relevant ADR(s) land in
Accepted state. This plan document is the phase-level index
and sequencing view.

## Non-goals (explicitly out of Phase 5)

Carried from PHASE-5-BACKLOG.md:

- **No blockchain beyond Blurt.** Not adding Ethereum, Solana,
  or any other chain.
- **No custody, no escrow.** P2P stays P2P.
- **No KYC.** Ever, per ADR-0001.
- **No mobile native apps.** SvelteKit frontend on mobile web
  is the mobile story.
- **No in-protocol dispute resolution.** Reputation is
  chain-tracked; Morphit does not arbitrate.

Additional non-goals specific to Phase 5:

- **No paid promotion.** Cross-post flow reaches users via
  organic content only. No ads, no sponsored slots outside
  the featured-slot auction (which is a backlog item
  deferred past Phase 5's initial scope).
- **No governance infrastructure.** Operator fee-split
  percentages, policy decisions, and tag-revocation rules
  remain Agorise-set in Phase 5. A governance token or
  DAO structure is out of scope.
- **No migration to a new indexer storage layer.** Postgres
  stays. No Redis, no ClickHouse, no distributed anything.

## Sub-phase 5a — Ecosystem reach

**Scope:** frontend + Blurt-side work that increases Morphit's
visibility and closes UX gaps from Phase 4.

**Dependencies:**
- ADR-0012 Accepted (open questions resolved)
- Morphit Blurt community created on the Blurt chain
  (one-time manual step, depends on ADR-0012 Q2 resolution)

### Milestones

**5a-M1: Feedback-submit UI.**
The precondition for the cross-post flow. Users currently see
counterparty feedback but have no way to submit their own
feedback from the Morphit UI. Add:
- A feedback-submit card on the completed-order detail page
- Form: 5-star rating + optional short comment (same shape as
  `morphit_feedback_v1`'s payload)
- Posting-key signing + broadcast path
- Success state that segues into cross-post UI (see 5a-M3)

*Done when:* a user can successfully submit feedback for a
trade they completed, and it lands indexed on the next block.

**5a-M2: Klingex/real price feed.**
Replace the `$0.002 BLURT` hardcoded fallback with a real
price source. Fetches from Klingex primarily, Coingecko
secondary, hardcoded floor as ultimate fallback.
- New `BlurtPriceSource` module in the indexer with fallback
  chain
- 5-minute in-memory cache with background refresh
- Existing `/v1/listing-fee` endpoint returns fresh prices

*Done when:* the indexer's quoted listing fee tracks BLURT's
actual USD price to within ~5% during a typical day.

**5a-M3: Cross-post flow.**
Implements ADR-0012. The frontend offers post-trade cross-
posting via the user's own posting key.
- Cross-post modal appearing after feedback submission
- Template in 10 locales
- Posting-key re-unlock prompt (even though the key is
  session-unlocked, per ADR-0012 rationale)
- Analytics: count opt-in rate (local storage only, no
  server reporting — privacy constraint)

*Done when:* a user completing their first trade can post a
localized "first trade on Morphit" entry to Blurt signed with
their own posting key, with Morphit never touching the post
content after submission.

**5a-M4: Morphit Blurt community creation + homepage
integration.**
One-time Blurt-side setup, plus small frontend integration.
- Create the community on Blurt with agreed name (currently
  proposed: `morphit`) via `create_community` op
- Moderator roster: Agorise + one-two community volunteers
- Homepage tile linking to the community's recent posts
  feed (fetched live from Blurt)

*Done when:* the community exists, has moderation rules
documented, and appears on the Morphit homepage.

**5a-M5: Phase 4 loose ends cluster.**
From PHASE-5-BACKLOG.md §8:
- Structured logging migration (handler `console.log` →
  `logger.info({handler, signer, reason}, msg)`)
- `/v1/health?verbose=1` integration tests
- XMR viewkey verification script for operators
- Persian and Chinese translation quality audit pass
- FAQ search scoring tweaks

*Done when:* each of these sub-items either lands or gets
explicitly deferred to Phase 6 with reason recorded.

### Size: MEDIUM

Rough fuzzy estimate: 5-8 weeks of engineering across the
five milestones. M1 and M3 are the largest; M4 is a one-day
task; M5 is cumulative small items.

### Risks

- **M1 blocks M3.** Cross-post flow can't ship without
  feedback-submit UI. If feedback-submit hits a design snag,
  M3 slips.
- **Klingex API stability.** If Klingex rate-limits us or
  goes down, the fallback chain protects the feature but
  operators see log noise. Mitigation: add circuit breaker
  from Phase 4 explorer work to the price source too (code
  reuse).
- **Translation fidelity.** Native-speaker review of Persian
  and Chinese could surface real errors that need locale-
  specific fixes, not just polish.

## Sub-phase 5b — Operator incentives

**Scope:** the economic mechanism that converts Morphit from
a single-operator project into a network of aligned operators.

**Dependencies:**
- ADR-0013 Accepted — this includes resolving all six of
  its open questions, which requires Agorise policy input
  alongside the technical decisions.
- At least one external-party operator identified as a
  pilot deploy partner (to prove the mechanism works end-
  to-end before general launch).

### Milestones

**5b-M1: Operator registration op.**
New `morphit_operator_register_v1` custom_json + its indexer
handler + the `operators` table. Depends on ADR-0013 Q1
(registration fee amount) being resolved.
- Payload shape: `{ tag, display_name, contact_url,
  registration_fee_transfer_permlink? }`
- Handler validates tag uniqueness, verifies fee transfer
  sibling, inserts into operators table
- Introduces an operator-registration schema migration (v7)

*Done when:* an operator can register via CLI and is
persistent + discoverable via a `/v1/operators` API.

**5b-M2: Referrer tracking in order op.**
The biggest interface decision, per ADR-0013 Q2. Assuming
we land on option (a) — a new payload field:
- `morphit_order_v2` with optional `operator_tag` field
- Indexer handler accepts both v1 and v2
- Frontend includes operator_tag when the instance config
  provides one
- Tag attribution recorded in `operator_earnings` table per
  order

*Done when:* an order posted through an operator-branded
frontend can be unambiguously attributed to that operator
at indexing time, and operator earnings accumulate.

**5b-M3: Monthly payout automation.**
The indexer runs a monthly pass that computes per-operator
earnings and queues payouts via the existing
`relay_pending_transfers` path.
- New `kind='operator_payout'` on the queue
- Idempotent — safe to re-run if a pass crashes mid-way
- Operator-initiated claim op for the "pull don't push"
  pattern (per ADR-0013 Q4 leaning)

*Done when:* an operator can claim their accumulated
earnings via a signed op and receive the payout in a
subsequent block.

**5b-M4: Operator directory + frontend integration.**
A public-facing `/operators` page with the list of
registered operators, their tags, contact info, and
optional stats (if operators opt in to showing trade
volume). Also a "run a Morphit node" landing page with
the one-time setup steps and CLI tools.

*Done when:* anyone curious about running Morphit themselves
has a single page with the economics, the setup instructions,
and links to join the existing operators.

**5b-M5: Three new FAQ entries + 10-locale translation.**
- "How do I run a Morphit node?"
- "How do operators earn?"
- "How do I find a good operator?"
(Last one is new — users seeing multiple operator instances
will ask.)

*Done when:* the three entries land in all 10 locales,
wired into `FAQ_KEYS` in the frontend-side index.

### Size: LARGE

Fuzzy estimate: 6-10 weeks of engineering, plus Agorise
policy input time that's not engineering but gates M1.

### Risks

- **ADR-0013 open questions.** Six open questions, some
  policy-heavy. ADR closure could itself take weeks.
- **First-operator bootstrap.** Who's the pilot partner?
  The mechanism is testable in isolation but genuine
  usefulness requires a real external operator trying it
  for a real deployment. Without that, we ship a feature
  no one verified end-to-end.
- **Spam registration risk.** If the registration fee
  lands low (e.g., free + probation per Q1), we could
  see spam registrations. Mitigation: add a rate limit
  on the handler, cap total registered operators per IP.
- **Fee-split economics.** If the split percentage is
  set wrong, either Morphit treasury drains too fast
  (too generous) or operators don't bother (too stingy).
  The fallback plan: treat the initial number as a
  governance parameter that Agorise can adjust in future
  phases without requiring new op versions.

## Sub-phase 5c — Encrypted chat + reputation

**Scope:** replace the in-memory/websocket chat with an
end-to-end encrypted protocol per ADR-0015 (per-message
ECIES via X25519 + ChaCha20-Poly1305). Add reputation
signals derived from chat and feedback data.

**Dependencies:**
- ADR-0014 Accepted
- ADR-0015 Accepted (resolves the cipher choice for ADR-0014
  Q1, replacing the original heavier-protocol proposal).
- A storage-model sub-ADR (ADR-0014 Q2) — big enough decision
  that squashing it into the parent ADR would make it
  unreadable.

### Milestones

**5c-M1: Crypto module.**
Implement `apps/web/src/lib/chat/crypto.ts` per ADR-0015:
- X25519 chat-identity derivation from Blurt posting key
- Per-message ephemeral keypair generation
- ECDH-derived per-message key with BLAKE2b domain separation
- ChaCha20-Poly1305-IETF AEAD on the ciphertext
- Wipe ephemerals after use for sender-side PFS

*Done when:* a pair of Morphit-browser clients can
exchange encrypted messages end-to-end in an integration
test, without any network round-trips to Morphit servers.

**5c-M2: Chat identity key management.**
Per the sub-ADR resolving ADR-0014 Q1. Leaning toward option
2 (published long-term chat identity via
`morphit_chat_identity_v1` op).
- New op + indexer handler
- Frontend "first-time chat setup" UI that generates the
  key, publishes the pubkey, and stores the privkey in
  the encrypted-envelope pattern from Phase 4a
- Key-rotation flow (user-initiated, e.g. if they suspect
  compromise)

*Done when:* every Morphit account that wants to use chat
has a chat identity published to chain; private key stored
encrypted on the user's device.

**5c-M3: `morphit_chat_v1` op + indexer handler.**
The transport for ciphertexts.
- Payload: `{ order_permlink, recipient, ciphertext, header }`
- Handler verifies sender is a counterparty in the
  referenced order
- `chat_messages` table with appropriate indexes
- HTTP API endpoint: `GET /v1/chat/:order_permlink` returns
  all ciphertexts for that order (clients decrypt locally)

*Done when:* messages flow through the Blurt chain and
land in the indexer, ciphertexts persisted and retrievable,
no plaintext ever in indexer logs.

**5c-M4: Chat UI replacement.**
Retire the in-memory chat. New chat UI that:
- Reads from the indexer's `/v1/chat/:permlink` endpoint
- Decrypts locally with the user's chat identity
- Queues outgoing messages, signs them, broadcasts
- Handles offline-recipient case (they see the messages
  when they come online and decrypt)

*Done when:* users can conduct a full counterparty
conversation, leave, come back a day later, see the
full history, continue the conversation.

**5c-M5: Reputation signals in UI.**
Display-only, no chain-inclusion (per ADR-0014 Q4 leaning).
- "N messages exchanged" displayed on completed-trade detail
- Response-time stat (average turnaround)
- Rendered in orderbook as an optional column for users
  who've been in chats with the counterparty before

*Done when:* a user browsing the orderbook sees at-a-glance
reputation signals from previous counterparty interactions.

**5c-M6: Key-loss onboarding + documentation.**
Losing the chat identity private key = losing all past chat
history. This is scary; users need to know upfront.
- Backup flow: on chat-identity creation, show the user
  their chat privkey encoded as a Blurt-style recovery
  phrase + offer to print it
- Clear warnings in the UI when a user imports a chat
  identity key
- FAQ entry: "What happens if I lose my chat key?"

*Done when:* the key-loss implications are documented
and the backup flow is working.

### Size: LARGE+

Fuzzy estimate: 12-16 weeks. This is genuinely a new crypto
protocol layered onto a new transport; the biggest feature
Morphit has shipped.

### Risks

- **libsignal JS port maturity.** The official JS port is
  less actively maintained than the Rust or mobile versions.
  Mitigation: assess at M1 start; if it's stale, consider
  libsignal's Rust+wasm path (more maintenance but more
  current).
- **On-chain storage load.** If chat volume is high, we
  contribute meaningful bytes to the Blurt chain. Need a
  community conversation with Blurt witnesses before
  launch. Mitigation: land the storage decision (ADR-0014
  Q2 sub-ADR) early and socialize it.
- **Key-loss UX is the single biggest UX risk.** If users
  routinely lose chat history due to key loss, the feature
  is worse than the current in-memory chat (which loses
  on reload but at least doesn't pretend to be durable).
  Mitigation: obsess over the backup + warning flow in M6.
- **Scope creep into "Morphit Messenger".** Chat could
  easily grow into a standalone messaging app. Phase 5c
  stays scoped to counterparty-per-order chat. General
  messaging stays out of scope explicitly.

## Cross-cutting sequencing

Three sub-phases, each independently ship-able:

```
Phase 4 ships (Q2 2026)
         │
         ├─────► 5a — Ecosystem reach (5-8 weeks)
         │         Start: immediately after Phase 4 ops-review
         │         Blocks: nothing; dependent: none
         │
         ├─────► 5b — Operator incentives (6-10 weeks + ADR time)
         │         Start: after ADR-0013 Accepted
         │         Blocks: decentralization goal
         │         Dependent: 5a's price feed (for accurate
         │                    fee attribution); not strict
         │
         └─────► 5c — Encrypted chat (12-16 weeks + sub-ADR time)
                   Start: after ADR-0014 + sub-ADRs Accepted
                   Blocks: the current chat weakness
                   Dependent: could use 5b's operator list for
                              key-discovery fallback, not strict
```

### Recommended order

**5a first** — small, user-visible, resolves Phase 4 gaps,
builds team momentum. ADR-0012 has only three open
questions; they resolve in normal design review, not
multi-party negotiation.

**5b second** — higher leverage (decentralization), but
gated by ADR-0013's open questions which have policy
content needing external input. While ADR-0013 is being
resolved in parallel, engineering proceeds on 5a.

**5c last** — biggest investment; worth starting only once
team has capacity. Might actually be Phase 6 depending on
team size.

### Parallel paths

Within a sub-phase, milestones can go in parallel:

- 5a: M1 (feedback UI) and M2 (price feed) are independent.
  M4 (community) is a one-day task that can fit anywhere.
  M3 (cross-post) depends on M1.
- 5b: M1 (registration) and M2 (referrer tracking) can
  develop in parallel once ADR-0013 is accepted.
- 5c: M1 (libsignal) and M2 (identity keys) are independent
  foundations; M3 builds on both; M4-6 build on M3.

## Open questions at the phase level

- **Parallelism vs. focus.** Can the team do 5a and 5b in
  parallel tracks? Depends on team size. Solo engineer
  should do them sequentially; two+ can split.
- **Sub-phase release cadence.** Do we ship 5a as its own
  release, then 5b, then 5c? Or bundle them? I lean toward
  separate releases — Phase 4 taught us that smaller
  releases catch issues earlier.
- **Do we do ADR-0013 before 5a ships, or concurrently?**
  If ADR-0013 work (which is partly policy, not engineering)
  runs in the background during 5a engineering, 5b can
  start immediately after 5a ends with no dead time.
- **Do we incorporate any 5c work into 5b?** Some chat
  infrastructure (e.g., the new custom_json op shape
  patterns, the indexer handler patterns) could be
  pre-built during 5b idle time. Low value, probably not
  worth optimizing.

## Timeline anchor

None committed. Rough ballpark assuming solo engineering:

- 5a: **summer 2026** realistic
- 5b: **fall 2026** realistic
- 5c: **winter 2026 into 2027** realistic

With two engineers these can overlap significantly.

## Design-doc changelog

- 2026-04-19 initial draft post-Phase-4 closeout