# Pacifica Delta-Neutral Scalping Implementation Plan

## Overview
This document consolidates the product requirements, technical architecture, and execution roadmap for the Pacifica delta-neutral market-making plus micro-scalping system. It targets a TypeScript/Node 22 stack and covers connector integration, risk controls, strategy logic, observability, and operational practices under a strict compliance posture.

> **Documentation contract**  
> 本计划与以下支持性文档配套使用：`docs/API_CONNECTOR_SPEC.md`, `docs/MODULE_INTERFACES.md`, `docs/SEQUENCE_FLOW.md`, `docs/CONFIG_REFERENCE.md`, `docs/TESTING_PLAN.md`, `docs/OPERATIONS_PLAYBOOK.md`。所有实现、配置或流程改动若偏离这些文档，需先修改文档再执行开发任务。

> **Micro grid control alignment**  
> 细粒度网格控制与闭环执行的细项安排，已拆分至 `docs/MICRO_GRID_CONTROL.md`（策略与指标规范）和 `docs/MICRO_GRID_ROADMAP.md`（Sprint 级排期）。本实施计划的里程碑需与上述文档保持一致；任何时间轴或范围调整，须同步更新三份文档。

## Objectives & Constraints
- Maintain net delta ≈ 0 while capturing spread and maker rebates across BTC/ETH/SOL perpetual markets.
- Enforce self-trade prevention, audit logging, and regulatory safeguards across all order flows.
- Prioritise risk: enforce notional/inventory/order caps, intraday drawdown kill-switch, latency and data-gap protection.
- Deliver production-grade observability (Prometheus metrics, alerting, traceable decisions) and hot-reloadable configuration with audit trails.

## Functional Scope
- **Exchange connectivity**: Pacifica REST (and optional WS) adapter, Ed25519 signing, rate-limit handling, structured error surfacing.
- **Market data**: shadow order book with mid/spread/OBI/short-term RV derivations; latency tracking.
- **Execution**: order router with limit/IOC modes, slippage guard, post-only support, deterministic `clientId`, and STP cross-checks.
- **Risk & compliance**: order pre-checks, inventory/notional/order-size constraints, realised PnL accumulation, kill-switch triggers, append-only audit logs.
- **Strategy layer**: passive market making (multi-layer reprice loop) and micro-scalping (spread expansion + flow imbalance triggers).
- **Hedging**: PI-controlled cross-venue/account hedger with throttle and funding-rate bias adjustments.
- **Trigger/OCO**: take-profit/stop-loss legs, timeout exits, shared STP/risk pipeline.
- **Telemetry**: Prometheus metrics（maker_ratio, delta_abs, latency_p99, pnl_intraday, hedge_cost_bps, ev_estimate, cancel_rate, stp_hits, risk_kill_switch_state 等）及报警规则。
- **Backtesting**: event replay (books+trades), fee/funding models, EV evaluation, parameter search, sharpe and bucketed reports.
- **Configuration**: `.env` secrets, `config.yaml` strategy parameters (symbols, mm, scalper, risk, hedge), zod validation, hot reload with audit entries.

## Non-Functional Targets (KPI / SLO)
- EV_p50 ≥ 1.5 bps; EV_p10 ≥ 0.
- |delta| P95 ≤ 0.5 × `max_base_abs`; taker_ratio ≤ 35%; hedge_cost_bps ≤ 0.4 × edge_bps.
- **对冲效率（新增）**：hedge_success_rate > 98%; hedge_latency_p50 < 500ms, p99 < 2s; hedge_slippage_bps < 0.5.
- **资金费率（新增）**：funding_rate_correlation > 0.8; funding_cost_net_bps < 1 per 8h; funding_same_sign_ratio < 20%.
- Latency_p99 within venue SLA; zero self-trade incidents; compliant audit log coverage.

## Milestones & Deliverables
1. **M1 – Core Skeleton & Multi-Account Infrastructure (≈1–2 weeks)**
   - Type/domain definitions, Pacifica adapter with signing placeholder replaced by official implementation.
   - **Multi-account adapter registry**：支持 Account A (maker) / Account B (hedger) 独立配置与管理。
   - Shadow book pipeline, latency metrics, baseline Prometheus exporter.
   - **Symbol Registry & Allocator (新增)**：多标的生命周期管理与全局风险预算分配。
   - **Global Order Coordinator (新增)**：跨账户订单注册表与 STP 检查基础框架。
   - OrderRouter + SlippageGuard with post-only/STP checks.
   - RiskEngine v1 covering inventory/notional/order caps and **enhanced kill-switch**（跨账户聚合、多维度触发器）。
2. **M2 – Strategy Loop & Enhanced Hedging (≈1 week)**
   - **Strategy Coordinator (新增)**：信号聚合与冲突检测，MM 和 Scalper 提交 intent 而非直接下单。
   - MarketMaker v1 (mid±δ layers, periodic reprice) and MicroScalper v1 (spread + flow triggers, IOC exit fallback).
   - PositionManager & HedgeEngine (PI-controlled cross-account hedging, throttle, funding bias options).
   - **对冲延迟预算与重试机制（新增）**：P50/P99 追踪，超时强制市价，失败自动重试（最多 2 次）。
   - **资金费率监控（新增）**：双 venue funding rate 抓取、相关性计算、同向支付检测。
   - TriggerEngine for OCO tp/sl and timeout exits; funding rate ingestion.
   - **降级策略状态机（新增）**：实现降级矩阵中的核心场景（数据断流、对冲失败、Delta 失控）。
3. **M3 – Backtest & Parameterisation (≈1 week)**
   - Event replay harness reusing production interfaces; fee/funding/slippage modelling.
   - **延迟注入模块（新增）**：记录实盘延迟分布，回测时注入真实延迟，防止前瞻偏差。
   - EV/Sharpe/bucket reporting, parameter sweeps (grid/random) with config snapshots.
   - **配置热更新金丝雀流程（新增）**：zod 校验 → 回测烟囱测试 → 单标的试运行 10 分钟 → KPI 验证 → 全量发布或自动回滚。
   - Audit trail for parameter edits (who/when/what/result).
4. **M4 – Compliance Hardening & Multi-Venue (≈1–2 weeks)**
   - Second venue or sub-account integration; cross-venue STP; consistent snapshot+incremental recovery.
   - **完善 Global Order Coordinator**：跨账户经济 STP、冲突检测、降级策略触发全流程集成。
   - Append-only audit log store with trace IDs across signal→order→fill→hedge.
   - **流动性冲击成本监控（新增）**：top10_depth 追踪、clip 动态调整、实际滑点 vs 预期滑点告警。
   - **资金费率筛选器（新增）**：标的上线前评估双 venue funding rate 相关性，自动拒绝不合格 venue 对。
   - Adaptive parameter policy reacting to RV/OBI regimes; expanded symbol onboarding automation.
5. **M5 – Operations & Resilience (continuous)**
   - **完整降级策略矩阵实现**：覆盖所有 9 种故障场景（见 ARCHITECTURE_DESIGN.md 5.5 节）。
   - SRE playbooks (volatility shock, data gap, signing failure, hedge miss, funding rate anomaly) and regular drills.
   - **对冲效率指标监控面板**：hedge_success_rate, hedge_latency_p50/p95/p99, hedge_slippage_bps, cross_venue_basis 实时展示与报警。
   - Risk parameter auto-rollback and alert-driven mitigation; blue/green deploy + canary configs.
   - **手动干预接口**：`/api/override-degradation` (需认证)，允许运维人员强制退出降级模式。
   - Periodic KPI reviews (EV, hedge_cost, delta_abs, hedge efficiency, funding cost) feeding strategy tuning roadmap.

> **与微网格路线同步**  
> - `M1` 的监控建设需满足 `MICRO_GRID_ROADMAP` Sprint 1 的 T1 指标与报警验收。  
> - `M2` 上线前必须交付库存闭环（T2）与成交率 PI 控制（T3）。  
> - `M3` 的优化工作与 T4/T5 一致，要求深度跟随与费用拨盘在仿真/沙盒中验证通过。  
> - `M4` 与 T6/T7 共享同一稳定性演练与 kill-switch 验收标准。  
> 任一范围或时间调整，务必同步更新 `MICRO_GRID_CONTROL.md` 与 `MICRO_GRID_ROADMAP.md`。

## Work Cadence & Governance
- Each milestone concludes with code, self-tests (simulation/backtest), and documentation updates.
- `apps/runner` exposes CLI for live, dry-run, and replay modes; CI runs lint/test/backtest smoke.
- PRs must attach KPI snapshots or logs; doc updates tracked under `docs/` with revision history.
- Maintain change log of strategy parameters and incidents; schedule monthly compliance review.

## Immediate Next Steps
1. Finalise Pacifica signing specification and implement `signRequest` in `packages/connectors/pacifica/src/signing.ts`.
2. Wire Runner / MarketData to pass API credentials for private WebSocket channels, then run live smoke tests against Pacifica orders/fills/account feeds以验证签名负载。
3. Stand up the shadow book + metrics pipeline, ensuring data feeds for MarketMaker/Scalper prototypes。
4. Define baseline Prometheus dashboard and risk parameter defaults to support M1 testing。

## Upcoming Iteration Focus
- **Incremental grid maintenance（替代“全撤全布”）**  
  - 在 `GridMaker` 中实现 `reconcileGrid()`，对比目标价位与 `grids` 状态，区分“轻微移动”“新增”“删除”三类操作。  
  - 优先尝试局部 `modify`（或 `cancel+place` 同 tick 内完成），仅在偏移超过阈值或局部更新失败次数过多时退回全量重布。  
  - 为 `GridLevel` 增加 `dirty/pending` 标记与超时回滚逻辑，避免重复提交；对齐 OrderRouter 接口，补充 `modifyLimitChild`/批量执行能力。  
- **Placement throttling & latency guard**  
  - 在 WS gateway 内引入令牌桶（`burst ≤ N`、`refillMs`）与可配置批处理，将 20+ 并行请求分批排队，缓解交易所限流。  
  - 记录每次 `create_order`/`cancel` 的 RTT，指标化 `placement_latency_{p50,p95,p99}`；超过阈值时自动降速或暂缓后续批次。  
  - 撤单同样按批次执行（例如每 50–100ms 处理 5–10 张），确保网格在更新阶段仍有大部分档位在线。  
- **Multi-account, multi-instance grid orchestration**  
  - 扩展 `config.yaml`，允许 `grid.instances[]` 指定多个 {symbol, account_id, 参数}，并记录审计 Trail。  
  - 引入 `GridFleetManager` 统一创建 ShadowBook、GridMaker、定时器，路由 fills/orders 到 `(accountId, symbol)` 维度；实例化过程需支持热加载与优雅停机。  
  - 更新 `GlobalOrderCoordinator` / `OrderRouter`，在跨实例间执行 STP/冲突检测、全局节流，避免不同账户或标的互踩。  
- **Observability & ops playbooks**  
  - 新增实例级指标：`grid_active_orders`, `grid_pending_levels`, `grid_incremental_rate`, `order_gateway_queue_depth`, `stp_conflicts`.  
  - 定义告警：连续多个 tick `pending_levels>0`、`placement_latency_p95>5s` 或实例重试超限时触发降级（回退全量模式或暂停实例）。  
  - 更新运维剧本，覆盖多实例启停、动态扩缩容、手动降级/恢复、以及在增量模式失败时的回滚步骤。
- **Ultra-tight micro-grid configuration**  
  - 研究低至 1–2 bps 的步长与 0–1 bps `post_only_cushion_bps` 组合对限流及 post-only 成功率的影响，配合多账户实例进行分层部署。  
  - 为极端贴盘口模式制定节流/批次下单策略（降低 burst、引入异步确认），并提供回滚配置模板（如 `micro_grid_extreme.yaml`）。  
  - 输出风控指引：如何在多账户环境下分配层级（内圈账号、外圈账号），以及极限模式下的 delta/对冲阈值调优建议。
- **成交缺失驱动的自适应调节**  
  - 引入“连续 N 个 tick 无成交”与`average_fill_interval` 等指标，作为步长/范围动态压缩的触发条件。  
  - 设计压缩策略：在成交缺失时短暂降低 `min_grid_step_bps` / 增加 `min_layers`，成交恢复后渐进回调，避免频繁震荡。  
  - 在多账户/多实例场景下协调压缩动作，防止多个实例同时过度收紧导致限流；配套指标与运维回滚步骤。  

## M1.6 Detailed Development Plan

| # | Workstream | Deliverables | Dependencies | Notes / Owner Handoff |
|---|------------|--------------|--------------|-----------------------|
| 1 | Incremental Grid Engine | `GridMaker.reconcileGrid()`、`GridLevel` 状态机、并发安全检查；Router 支持 `modify`/批次撤单；Metrics：`grid_pending_levels`, `grid_incremental_rate`, `grid_modify_failures`；降级开关 `grid.incremental_mode` | 交易所不提供原生 `modify` 时，需要定义 `cancel+place` 原子操作；需先落地 Gateway 线程安全队列 | 完成后先灰度单实例，确保 fallback 正常 |
| 2 | Placement Throttling 2.0 | WS gateway 令牌桶、批次发送结构；全局节流配置（burst、refill、maxQueueDepth）；告警阈值：`placement_latency_p95`、`order_gateway_queue_depth` | 依赖 Workstream 1 的批次 API；需要针对 maker / hedger / 内外圈账号设置不同 burst | 产出运维 Playbook：burst 超限时如何调参或降级 |
| 3 | Fill-driven Tightening |  新增指标：`fill_count_tick`, `avg_fill_interval`, `no_fill_duration`; 策略：连续 N tick 无成交→临时压缩步长（因子 α）、提升 `min_layers`、或缩小 `grid_range_bps`；成交恢复 → 退回 | 依赖 Workstream 2 的稳定节流，防止压缩后爆限流；需要与风险/对冲协同调整阈值 | 同步更新 `config.yaml` schema (`adaptive.fill_starvation_threshold`, `fill_compression_factor`) 以及 config reference |
| 4 | Multi-instance Fleet Manager | `grid.instances[]` 配置；`GridFleetManager` 生命周期管理（启动、更新、停用）；跨实例 STP/限流整合；实例级指标 (per account/symbol) | Workstream 1–3 提供基础能力，否则多实例会放大问题；可能需要引入新的 config loader | 提供 CLI/REST 操作 (`fleet:list`, `fleet:scale`, `fleet:degrade`) 与审计记录 |
| 5 | Extreme Micro-grid Sandbox | 设立测试配置 `config/micro_grid_extreme.yaml`；实验 1–2 bps 步长 + 0–1 bps cushion 的限流曲线；自动回滚脚本 | 需完成 Workstream 2 的节流以及 Workstream 3 的成交压缩，以防实盘崩溃 | 第一阶段仅在测试网运行，收集 RPC RTT、post-only 成功率、成交分布 |
| 6 | Documentation & Runbook | 更新 `CONFIG_REFERENCE`, `OPERATIONS_PLAYBOOK`, `README` 示例；新增“增量模式调参”、“多实例扩缩容”、“无成交压缩”章节；Prometheus/Grafana dashboards | 需等以上工作流产出接口与指标后同步 | 标准化金丝雀流程，提供回滚 checklist |

### Implementation Notes
- **优先级建议**：先完成 Workstream 1 & 2 打牢基础（局部改单、节流），再处理 fill-driven & multi-instance 联动；最后做极限模式实验。  
- **风险控制**：任何自动压缩策略必须设置硬性下限（步长 ≥ 1 bps；累计压缩次数/幅度在窗体内受限），避免造成自激振荡。  
- **测试策略**：  
  1. 单实例回归测试：模拟不同波动与成交场景，验证 `reconcileGrid()` 不会错删订单。  
  2. 多实例压测：分别对内圈/外圈实例注入延迟、限流，观测节流与降级行为。  
  3. 极限模式灰度：只在测试环境或小资金账号运行，记录限流情况，验证回滚脚本。  
- **运维对接**：在 Playbook 中明确“如何判断增量模式失效”、“如何启用/关闭 fill-driven 压缩”、“多账户实例差异化策略（内圈挂更紧、外圈更宽）”等操作步骤。
