0. Changelog vs v1.0

Two-and-a-half weeks of delivery and discovery have shifted the picture. Headlines:

• NEW Portfolio Withdrawal History — leader-side history of every withdrawal, paginated, CSV-exportable. Backed by a dedicated portfolio_withdrawals table and a separate profit_history module (§4.3, §4.6, §4.10).
• NEW Margin Order Edit copying — when a leader edits TP/SL on an existing position (or batch-edits multiple orders), the change now propagates to every active follower mirror. Previously only order creation/cancellation/fill was copied (§3, §4.4).
• UPDATED Portfolio Catalog Search — was "filters and sorting", now a flexible multi-filter + multi-sort engine with pagination (§4.1).
• UPDATED Follower sizing-value bounds — explicit per-model input ranges enforced server-side (was a QA bug, now closed): progressive ∈ (0, 1], fixed > 0, adaptive_scaling ∈ [0, 3] (§4.4).
• NEW Event delivery resilience — Phase 1 — durable Bull-as-inbox with SETNX deduplication on the CT side, behind a setting flag. Closes the in-process loss window between RPC ACK and job enqueue. Producer-side outbox in margin_trading_service and vakotrade is DEFERRED — see §7.2 (§4.11).
• FIX Withdrawal precision — withdrawal amounts now respect V4's currency cent precision; previously a sub-cent rounding mismatch could push the leader wallet below the required balance during allocateFromWallet RPC. Resolved (§4.6).
• UPDATED Spot follower real-time P&L — moved from "explicitly OUT" to "partial in MVP": a spot holdings-P&L subscription bridge is now wired (§7.3.8).
• CATALOGUED Derivatives restrictions made explicit — three new subsections under §7.3 document what we've quietly restricted: (a) margin order modifications — only TP/SL edits propagate; (b) standalone Stop orders — not copied in MVP; (c) spot pair constraint — quote currency equals primary. See §7.3.4 / §7.3.5 / §7.3.6.
• IN FLIGHT Pre-launch hardening — codebase decomposition wave (DEC-013…DEC-029) and live work on Allocation Modes, Advanced Risk Settings, TP/SL Relative Scaling, mobile parity, Leader Dashboard 3-Tab Layout. Status table in §9.
• BE DONE / FE PENDING Close-portfolio lifecycle — backend wind-down fully shipped. FE integration NOT yet built. Scope decision needed — see §4.1, §9.3, §11.
• OPEN BUGS — position-flip duplicate orders, limit-price edit not propagating, mobile partial-close closing fully, etc. See §9.2.
• PRE-LAUNCH "To Think Later" lane covers Legal, GTM, Sales/Marketing/Support alignment, training, telemetry sign-off — captured in §10.

1. Executive Summary

What is this product at a high level?

Copy Trading Service is a SHIFT platform product that lets some users (leaders) share their trading strategy while others (followers) automatically replicate their trades proportionally to their own capital. The service closes the gap between "I have a strategy" and "I want to trade but lack the skill": a follower picks a leader, allocates an amount, and the system mirrors every leader action in real time.

Key value

• For leaders — monetize their skill without building their own fund or brand; the platform brings followers and splits the profit share.
• For followers — passive market exposure without watching charts 24/7; risk is bounded by fixed safety controls.
• For the platform — a new revenue stream (performance fee), increased trading volume, and stronger user retention.
• For marketing — a public leaderboard with statistics is ready-made content and social proof.

What is ALREADY working (production-ready or live)

• Margin Copy Trading — full lifecycle: subscription, trade copying (incl. TP/SL edits), risk control, fee accrual, statistics.
• Spot Copy Trading — spot copying with smart "intent-based" mirroring and currency conversion.
• Risk Watchdog — background protection against drawdowns and margin call (a unique product trait, not commodity in this space).
• Admin tooling — execution journals, error monitoring, manual support actions, CSV reports.
• Portfolio Withdrawals — leader can withdraw realized profit with full history and CSV export.

2. User roles

3. Product lines in MVP

The service supports two independent product lines, both included in MVP. The leader picks the portfolio mode; the follower decides what to copy.

4. What is included in MVP — functionality

4.1 Leader portfolios

A leader creates a portfolio — their "trading strategy packaged as a product".

4.2 Leader ranking and scoring

Every two hours the system recomputes the public-portfolio ranking automatically. This is KEY for marketing: natural selection happens — better leaders rise in the catalog.

• Win rate (25%) — share of profitable trades over the last 30 days.
• Profitability (20%) — total PnL as a percentage of portfolio.
• Follower health (25%) — how profitable the FOLLOWERS actually are (not just the leader).
• Consistency (20%) — stability of returns (Sharpe ratio).
• Activity (5%) — trade count.
• Popularity (5%) — follower count.

Only portfolios with real activity (≥1 trade in the last 30 days) enter the ranking — protects the catalog from "dead" or boosted portfolios.

4.3 Subscribing to a leader (copy flow)

4.4 How volumes are sized for the follower (3 models)

A follower never copies a leader 1:1 by volume — capital differs. The service supports three transparent sizing models:

Instrument constraints (min/max quantity, price step) are always applied — a follower never receives an impossible order.

4.5 Risk control — Risk Watchdog

Risk Watchdog is a background "guardian" running even while the follower sleeps. Competitive edge: on many CT platforms a follower can lose their full balance overnight — here the system intervenes.

4.6 Fees and profit sharing

4.7 Wallets

Every subscription creates a SEPARATE isolated copy wallet. This is foundational: the follower does not risk their main balance — only the amount they explicitly committed to a leader.

• Auto-creation of copy wallet on subscribe.
• Move funds MAIN → copy_wallet → MAIN — no intermediaries; instant.
• Single-API view of balances across all copy wallets — 2-min cache; fast dashboard render.

4.8 Notifications

Users receive push and email notifications in key scenarios:

• Leader — new subscription/unsubscribe, profit credited, follower hit daily loss.
• Follower — successful subscribe, trade copied (margin/spot), position closed in profit.
• Follower — daily loss limit triggered (pause + close).
• Follower — margin call protection triggered (pause).
• Follower — critical copy error (RPC reject, internal_error).
• v1.1 BE Leader — portfolio closing started (leader-initiated or admin-forced); closing finalized (archived); final profit credited to MAIN wallet.
• v1.1 BE Follower — portfolio being closed (auto-unsubscribe in progress); copy wallet returned with final balance summary; admin-forced close carries close_reason.

Email is sent only for important events (high/critical). Minor skips (e.g. "no holding to sell") are NOT emailed to avoid spam.

4.9 Statistics and analytics

4.10 Execution journal & support tooling

4.11 Reliability and operational guarantees

MVP already includes a serious reliability layer — this is not a proof of concept but a production-ready system with self-healing mechanisms:

• Checkpoint system — if a worker crashes mid-propagation across 1000 followers, we resume from where we stopped.
• Reconciliation — every 10 minutes we clean orphaned rows.
• Idempotent fee allocation — even if an event arrives twice, the follower is debited exactly once.
• Distributed locks — multiple workers will not run the same cron simultaneously (Postgres heartbeat).
• Concurrency pools — caps on concurrent calls; the platform doesn't fall over from one leader trade with 10 000 followers.
• Two-process architecture — gateway (API) and worker (queues) scale independently.
• v1.1 Bull-as-inbox + SETNX deduplication — every event the CT gateway receives from margin_trading_service / vakotrade is enqueued durably. Re-deliveries with the same event_id deduplicated against a 7-day Redis window. Gated by outbox_protocol_enabled setting flag (default off, backwards compatible). Producer-side outbox in margin/v4 is DEFERRED — see §7.2.

5. Admin capabilities (in MVP)

• Global settings (system settings) via UI: risk watchdog thresholds, min investment, max followers, spot quote currency. v1.1 outbox protocol toggle, enabled notification triggers.
• CRUD on fee groups and limit groups — commercial terms for leaders.
• View event logs — what happened in the system over a period.
• View and filter jobs errors by severity — reaction prioritization.
• Resolve stuck fee allocation — manual recovery.
• Toggle follower status — admin pause / unpause of a follower.
• v1.1 Reports endpoint — leader subscribers report + portfolio withdrawals report (both CSV).
• v1.1 BE Force-close portfolio via force_close_portfolio(portfolio_id, close_reason) — admin-only emergency variant. Reason recorded in audit trail and included in notification emails. Same wind-down pipeline as leader close. FE for admin force-close is also pending — see §9.3.

6. Non-functional requirements (MVP)

7. OUT OF SCOPE for MVP (post-launch / future)

This is not "never" — it's "explicitly NOT promised in v1.0" so we keep focus.

7.1 Not in MVP — product capabilities

• Bot mode for portfolios — algorithmic strategies without a live leader. Currently blocked with PORTFOLIO_MODE_UNDER_DEVELOPMENT. POST MVP.
• Trailing stop / take profit at the CT layer — followers inherit leader's TP/SL, but no separate dynamic SL.
• Per-instrument risk limits — risk is controlled at the portfolio level.
• Full real-time WS parity for spot follower positions — bridge exists (v1.1), full parity with margin's GraphQL subscription pending.
• Cross-pair PnL conversion — spot statistics stay in primary currency.
• Pre-warning notifications before risk watchdog triggers — explicitly NOT in MVP.
• Daily loss limit for spot integrated in propagation path — for spot we rely on the watchdog only.
• Spot-specific reconciliation of cost basis vs actual V4 balances.
• v1.1 Advanced margin order types copying (TWAP / Iceberg / Stop / Scaled / OCO / OTO / OSO) — POST MVP. See §7.3.3.
• v1.1 Back-office deep views on portfolios and their followers — NOT planned for MVP; deferred to post-launch.

7.2 Known constraints (acceptable in MVP)

• Margin call detection — reaction up to 30s (cron polling). Mitigation: faster cron (10s) post-launch.
• Fee allocation depends on V4 RPC: if V4 is down, accrual can be delayed (but not lost — buffer + retry).
• Adaptive scaling needs leader equity — if V4 RPC is down those copies are skipped; progressive/fixed continue.
• v1.1 Cross-service event delivery — DIRA #1 open until producer outbox ships in margin/vakotrade. CT inbox (§4.11) closes the consumer-side loss window, but the producer still emits via fire-and-forget Socket.IO. Mitigations: (a) reconciliation crons recover orphans, (b) support has manual resolve-stuck for fee allocation, (c) producer-side Bull outbox is scheduled cross-repo work.

7.3 Explicit MVP limitations — critical for FE, QA, and marketing

These limitations are imposed by the fact that neither margin-service nor copy-service in v1.0 covers the full feature set of a derivatives exchange. FE must hide the corresponding UI, QA must not test these scenarios, and marketing must not communicate them as "features".

7.3.1 Single-currency constraint on margin

Margin-service in MVP runs against ONE global primary currency (default USD/USDT, configured in settings.primary_currency). This means:

• All margin wallets in a single currency. Multi-currency margin accounts (cross-collateral) are NOT supported.
• Daily loss limit, max exposure, equity calculations — in a single currency.
• Withdraw profit, fee allocation, statistics — all in primary currency.
• A leader cannot run a margin portfolio with ETH-collateral while a follower uses USDT.

Why we are not adapting to multi-currency margin in this MVP, and why we don't intend to revisit:

• Multi-currency margin accounts and the corresponding multi-currency fee-group behaviour exist only on the Nexus platform. Our targets — Ouinex and CXM — run on the single-currency model.
• Multi-currency introduces operational risks we explicitly do not want in v1: excessive in-flight currency conversion on every propagation; inconsistent realized profit; per-follower flow divergence (different followers end up in different conversion paths) that is hard to debug; higher exposure to silent money LOSS or skipped propagation when one conversion fails.
• Net: for this MVP we explicitly do not plan to revisit multi-currency margin. If we later port to a Nexus-style deployment, that scope is opened as a separate workstream.

7.3.2 Multi TP / Multi SL — NOT supported

In MVP each position has AT MOST one Take Profit and one Stop Loss. If the leader places a multi-step TP at margin-service (e.g. 30% at +2%, 30% at +5%, 40% at +10%), the follower gets only ONE TP/SL level.

• FE: hide additional TP/SL fields on the copy / follow form.
• FE: on the follower position page show a single TP/SL even if the leader sees several.
• QA: test only single-TP / single-SL scenarios.
• Marketing: do NOT communicate "advanced position management" — that is false advertising in v1.0.

Why: multi-tier TP/SL on margin-service is itself still under active development by the derivatives team. The feature has not yet been validated against real client traffic and has not been released to production. Wiring an in-development primitive into copy-trading — where one leader action fans out to thousands of follower mirrors — multiplies any unresolved edge case by the follower count. Once the derivatives team graduates multi-tier TP/SL to GA with confirmed production behaviour, copy-service will revisit propagation.

7.3.3 Advanced order types — NOT copied in MVP

Margin-service supports seven "advanced" order types (margin_order.advanced_type). In MVP NONE are propagated — only plain market and limit orders are copied.

An order with advanced_type !== null reaches the copy-service as an event but does not trigger propagation. QA must verify that such orders are NOT copied and that the execution log carries a clear reason_code.

7.3.4 Margin order modifications — only TP/SL edits propagate v1.1

Margin-service permits a leader to edit several fields on an existing order or open position. In MVP, copy-service propagates only a narrow subset of those edits.

Why: the v1.1 edit-propagation pipeline is scoped to risk-neutral mutations where size and exposure do NOT change on the follower side. Any edit that changes size, leverage, or open-order pricing requires a per-follower re-sizing pass (sizing model → instrument constraints → V4 price discovery → risk + balance checks) — that is a second propagation pipeline, not a small extension. Explicitly out of MVP scope.

7.3.5 Stop orders — explicitly restricted v1.1

"Stop Order" here means the standalone trigger-based order type from margin-service — NOT the position-level Stop Loss attached to an open position. The two are different primitives that often get conflated:

• Position-level Stop Loss: SUPPORTED. Set on an open position; closes it when price crosses the threshold. Single SL only (§7.3.2).
• Standalone Stop Order: NOT copied in MVP. A free-standing conditional order. Listed among the seven advanced types in §7.3.3, but called out separately here because:
  • From the leader's UX it looks like "just a regular order", not "advanced" — easy to misuse.
  • Propagating it would require N follower-side conditional orders, each with independent trigger and cancel race conditions across V4.
  • No mirror-of-trigger-state primitive exists in copy-service today; designing one is post-MVP.

BE: if a leader places one outside CT scope, execution log carries STOP_ORDER_NOT_SUPPORTED_FOR_COPY. Marketing: do NOT communicate "conditional order copying" — Stop Loss yes, Stop Order no.

7.3.6 Spot pair constraint — quote currency must equal CT spot primary currency v1.1

Setting settings.copy_trading_spot_primary_currency (default USDT). For spot copy-trading, the leader may only place orders on instruments where the quote currency equals this setting. Cross-pairs are out of scope.

Enforcement: copy-service rejects propagation with SPOT_PAIR_QUOTE_MISMATCH. The leader's own trade on V4 is not blocked — only the propagation to followers is skipped.

Why this restriction exists in MVP:

• Single accounting unit. All CT spot dashboards are denominated in spot primary; cross-pair would need live conversions that go stale.
• No conversion pipeline at all. Follower always trades in primary directly. Earlier auto_convert follower flag was removed in v1.1 once leader-side instrument restriction made cross-pair propagation unreachable.
• Cap math. Max exposure %, daily loss limit, max-position counts assume one denomination.
• Liquidity uniformity. Deepest spot liquidity on SHIFT's V4 sits on primary-currency pairs.
• Predictable reporting. Finance / tax / compliance want a single column "amount in spot primary currency".
• Double-slippage risk. A second conversion adds a second slippage exposure on top of the trade itself.

7.3.7 Frontend cleanup — derivative functionality hidden

Beyond multi TP/SL and advanced orders, the frontend must hide / disable the following for MVP:

• Multi-currency margin account toggle (collateral selection) — keep only the primary currency.
• Advanced order builder controls (TWAP slicer, Iceberg display size, OCO pairing UI).
• "Bot mode" on portfolio creation — only margin / spot / all (under feature flag).
• Pre-warning toggles for daily loss limit.
• Trailing stop option at the CT layer.
• v1.1 Margin order edit controls for qty / leverage / limit price on portfolios with active subscribers — disable, or warn "edit will NOT propagate".
• v1.1 Standalone Stop order toggle on leader's copy-portfolio order form.
• v1.1 Spot instrument selector must filter to instruments where quote = CT spot primary.

7.3.8 Summary table — IN MVP / OUT OF MVP

8. Release readiness criteria

8.1 Product

• A leader can create a public portfolio, gain at least 1 follower, and see their fee.
• A follower can subscribe, see a copied trade, close it in profit/loss, and withdraw funds.
• Risk watchdog correctly pauses a follower on daily loss limit and margin call breach.
• The portfolio catalog ranks leaders by score with weights 25/20/25/20/5/5.
• Admin can see jobs errors, resolve stuck fee allocation, and pause a follower.
• v1.1 A leader can withdraw profit and inspect paginated withdrawal history; finance can export it as CSV.
• v1.1 A leader's TP/SL edit on an open position propagates to every active follower mirror.

8.2 QA scenarios (must pass before launch)

• Leader places a market BUY → 1000 followers receive copies sized per their model.
• Leader closes a position in profit → every winning follower is debited a fee, leader is credited.
• Worker crashes mid-propagation → after restart it resumes from checkpoint without duplicating orders.
• An event arrives twice (idempotency) → follower debited exactly once. v1.1 Verify both EventEmitter path (flag off) and Bull-inbox path (flag on) — same outcome.
• Margin call → follower paused, new leader trades skip them, open positions not touched.
• Daily loss → follower paused + all positions closed; auto-resumes at midnight UTC.
• Unfollow → all positions closed, funds returned to MAIN wallet, all tracking rows deleted.
• Spot: leader trades BTC/USDT, follower holds USDC → automatic conversion, copy in the right pair.
• v1.1 Leader edits TP/SL on existing open position (or batch-edits) → every follower with active mirror has the edit applied; followers without a mirror skipped without errors.
• v1.1 Leader withdraws amount that doesn't split evenly to cent precision (e.g. 9.9659 with 2% fee) → V4 wallet stays solvent, allocate RPC succeeds, withdrawal recorded correctly.
• v1.1 Sizing-value validation — copy_portfolio and update_follower reject progressive: 0, progressive: 1.01, fixed: -1, adaptive_scaling: 3.5; accept boundary values within range.
• v1.1 Advanced portfolio search — multi-filter (mode + min followers + min score) + multi-sort (score desc, follower count desc) returns correct paginated results.

8.3 Operational

• Dashboard metrics (eventsTotal, propagateExecuteMs, batchCancelMs) — for on-call.
• OpenTelemetry traces in production — we can diagnose individual copies end-to-end.
• QA and support documentation up to date (already in the Obsidian vault).
• Runbook for resolving stuck fee allocation and manual follower pause.
• v1.1 Runbook for outbox_protocol_enabled flag — how to flip it on/off, what to watch in metrics, when to roll back.
• v1.1 Re-regression pass on copy / fee / risk flows after the architectural decomposition wave (DEC-013…DEC-029, ~13 PRs merged 2-3 May). Behaviour-preserving, but warrants a focused regression sweep before public launch.

9. Work in flight (as of 2026-05-13)

Bridge between "scope" and "ship date". Backend MVP is largely feature-complete; the remaining work is integration, polish, mobile, and pre-launch QA.

9.1 Actively in progress

9.2 Open bugs — must be resolved before launch

9.3 Backlog — explicit scope decision needed

9.4 Post-MVP / Post-release (explicitly deferred)

• Introduce new margin order types copying — POST MVP (reinforces §7.3.3).
• Investigate opportunity for BOTS integration — POST MVP (reinforces §7.1).
• Add email triggers for all users by default — POST RELEASE.
• Add email triggers to global enabled_triggers setting — POST RELEASE.

10. Pre-launch obligations (non-engineering)

These items live in the "To Think Later" lane on the Asana board. They are NOT engineering blockers but ARE launch blockers. Without owners and dates, "ship date" is undefined regardless of the engineering status.

11. Risks & open business questions

12. Glossary