morphit/docs/adr/0012-cross-post-flow.md

ADR-0012 — Post-first-trade cross-post flow to Blurt

Status: Accepted (implemented in apps/web/src/lib/syndication/publish.ts) Date: 2026-04-19 (proposed); 2026-05-06 (status updated) Deciders: project maintainer Related: ADR-0010 (key custody), ADR-0011 (dynamic fee model)

Originally a stub with three UNDECIDED design questions. All three resolved during Phase 5 implementation; the resolutions are recorded in the Design questions resolved section near the bottom of this document. The Decision section below is the resolved shape now in code.

Context

Phase 4c delivered the delayed welcome bonus: when a Morphit user completes their first trade (evidenced by counterparty morphit_feedback_v1 submission), the relay sends them 10 BLURT liquid + 10 BP as a welcome gift. The bonus is a concrete moment of delight for the user.

Phase 5 wants to convert that moment into ecosystem reach. The thesis: if Morphit's users post about their first completed trade on Blurt, those posts become organic discovery vectors for new users browsing blurt.blog, blurt.media, and the wider Blurt social layer. This is content marketing via user-generated authenticity rather than paid promotion.

The mechanism: right after the welcome bonus arrives, offer the user a pre-filled "I traded on Morphit" blog post they can review, edit, and publish to their own Blurt account. The user owns the posting key that would sign the post; Morphit never gets custody of content they didn't author.

Constraints from Morphit principles

• Consent-first. Users must opt in per-post, explicitly. No auto-posting. No "quiet default to on."
• Counterparty privacy. The post must not reveal the counterparty's account name, the trade amount, the asset traded, or timing precise enough to identify the trade from on-chain data. A trade-completion post that says "I just bought $500 of BTC from @alice using Zelle" is unacceptable — that's doxxing the counterparty.
• Non-custody stays non-custody. The post is signed by the user's posting key (JIT-decrypted). Morphit never sees or persists the post content server-side.
• Reversibility. If a user regrets the post, they can delete it via any Blurt frontend. No Morphit-side lock-in.

Technical state of play

• A feedback-submission UI does NOT exist in the Phase 4 frontend. The welcome bonus fires when the counterparty's feedback is indexed, but there's no UI for the original poster to submit THEIR feedback yet. Cross-post goes on the feedback-submit screen (the logical "trade complete" moment), so that UI is a hard prerequisite.
• The user's posting key is JIT-decrypted whenever they're composing an order or cancelling one. For cross-posting, we need a custom_json-like op (actually comment — the Blurt blog post op).
• The 10-locale i18n system (541 strings) needs ~5 new strings for the cross-post UI, plus the post-template body and title in each locale.

Decision

When: On the feedback-submit confirmation screen, offer (opt-in) to cross-post to Blurt. The offer shows once — if declined, don't re-prompt.

What: A short Blurt comment op (i.e., a blog post) with:

• A title in the user's locale (10 localized versions; UNDECIDED whether fully fixed or fill-in-blank — see Open Questions).
• A body crediting Morphit, mentioning the platform link, and tagged #morphit #p2p #privacy. No counterparty info. No concrete amounts. No asset specificity unless the user explicitly toggles "include asset" (default off).
• Posted into @{user}/morphit-first-trade-{random} — the user's own account namespace.

Key handling: Require an explicit password re-entry before signing the comment op, even if the posting key is already unlocked in the session. This makes the permanence of the post visible and deliberate. Rationale: unlike short-lived Morphit ops (orders, cancellations), a blog post is public and permanent — users should feel the weight of that choice.

Resolved 1 — Post template: Fixed template per locale. No in-line user editing; the post is fired in the same client turn as the feedback broadcast (Post A) or order broadcast (Post B). See "Design questions resolved" below.

Resolved 2 — Community posting: Both, by post type. Post A goes to the @morphit Blurt community (parent_permlink = "blurt-176570"). Post B goes to the user's personal feed with parent_permlink "morphit" (the project tag). See "Design questions resolved" below.

Resolved 3 — Schedule: Immediate. Fired in the same client turn as the triggering action. Replaced the originally-considered deferred-syndication-queue model that was scaffolded but never shipped. See "Design questions resolved" below.

Alternatives considered

• Auto-post (opt-out). Rejected outright on the consent- first principle. Any auto-posting under user accounts — even "silent" metadata ops — erodes the trust that Morphit never acts as the user.

• Post from @morphit-relay on the user's behalf. Rejected because it would require custodial authority over content posted under the user's name (even if semantically attributed to Morphit, the chain record would show @morphit-relay posting about users' trades, which is creepy and off-brand for a non-custodial protocol).

• Off-chain announcement via Morphit-side database. We could maintain a "recent trades" page on the Morphit website that's populated server-side based on feedback events. Rejected because it doesn't use Blurt's network effect — the whole point is to push content INTO the Blurt social layer, not to host it ourselves.

• Share button that opens a pre-filled compose window on blurt.blog. A lower-effort version: instead of signing directly in Morphit, we redirect the user to a blurt.blog compose URL with the title/body pre-filled. Rejected because: (a) it breaks for users without a blurt.blog session (they'd have to log in again), and (b) it creates a UX seam right at the emotional-high moment after a successful trade.

Consequences

Positive

• Organic discovery: every cross-posted first trade is a Morphit mention on the Blurt social layer. If 30% of first-time users opt in, and Morphit gains 1000 first-time users in a year, that's 300 organic posts.
• Reinforces the non-custodial narrative: Morphit gives you something to share about your experience, signed under your own key, that you fully own.
• Closes the "what happened after the trade" loop: users currently complete their first trade and then don't interact with the site again until their next trade. The cross-post gives them a closing action that feels rewarding.

Negative

• Exposes a new vector for misinformation: if Morphit's template copy overclaims (e.g., "I made $1000 trading crypto!"), we're embedding it in user voices. Copy needs to be carefully neutral.
• 10-locale translation work for the template — adds to i18n maintenance burden.
• Prerequisite feedback-submit UI work (medium-sized frontend feature) must ship before this can land.
• Cross-posts from newly-minted accounts with low BP might get filtered as spam on Blurt frontends. We can't control Blurt's spam filters; some percentage of posts won't land.

Follow-up work

• Feedback-submit UI in the frontend (prerequisite).
• ADR-0013 must resolve whether a dedicated Morphit community exists before we can target posts there.
• 10-locale translation pass for the template.
• Analytics: track opt-in rate. If under 10%, the feature isn't earning its implementation cost.

Design questions resolved (2026-05-06)

Q1 — Post template: fully fixed

Decision: Fixed template per locale, generated programmatically from apps/web/src/lib/syndication/publish.ts. Hardcoded image URLs (IMAGE_FIRST_TRADE, IMAGE_ORDER_POST) point at images pre-uploaded to Blurt's image host. No in-line user editing; the post is fired in the same client turn as the triggering action.

Why: Removes a UX friction point (no "review before post" modal that users habitually dismiss without reading), removes the attack surface of user-controlled HTML/markdown landing under the @morphit-community feed, and keeps the "post Morphit talks about itself in a uniform way" branding consistent across operators.

User control: The opt-out is per-feature (Settings → "Auto- announce my first trade") rather than per-post. Per-order syndication (Post B) is already opt-in via a checkbox on /post.

Q2 — Community vs personal: both, by post type

Decision:

• Post A (first-trade announcement) → @morphit Blurt community (parent_permlink = "blurt-176570"). This is the discovery channel where Blurt users browsing the @morphit feed see new Morphit users' first-trade celebrations.
• Post B (per-order syndication) → user's personal blog with parent_permlink "morphit" (the project tag). This is the user's own marketing of their open trade, posted to their own followers, discoverable by anyone browsing the morphit tag.

Why: Post A is project-branded promotion; the community feed makes that explicit and gives the @morphit community account a reason to exist as a content hub. Post B is user-driven; their personal blog is the right venue for their own order.

Q3 — Schedule: immediate

Decision: Both posts fire in the same client turn as the triggering action (feedback broadcast for Post A, order broadcast for Post B). No deferred-syndication-queue, no indexer state, no "pending" banner.

Why: The originally-proposed 30-60s scheduled delay was scaffolded as a deferred-queue with cancel UI, but in practice nobody used the cancel and the indexer-state added attack surface for syndication-queue tampering. Replacing it with immediate firing eliminated ~200 lines of scaffolding code (publish.ts § "Replaces the old deferred-syndication-queue model"). Idempotency via deterministic permlink — a retry of the same trigger lands on the same Blurt post (edit, not duplicate).

References

• apps/web/src/lib/syndication/publish.ts — implementation
• apps/web/src/lib/utils/syndicationPrefs.ts — opt-out store
• PHASE-5-BACKLOG.md item 1
• ADR-0010 — key custody (constrains posting-key handling)
• ADR-0011 — dynamic fee model (defines the welcome bonus that this feature emotionally follows from)