# Pacifica Delta-Neutral + Dual-Sided Scalping
**版本**: v0.1.0  
**类型**: 需求文档（PRD） + 技术方案（Tech Spec）  
**适用范围**: Pacifica DEX（主网/测试网）

## 1. 背景与目标
- 在 **Delta≈0** 约束下，使用“被动做市 + 双向微剥头皮”获取点差与成交周转，严格避免自成交/违规行为。
- 以主流合约（BTC/ETH/SOL）起步，自动评分筛选是否扩展更多标的。

## 2. 关键原则
- **合规**：启用 STP（自成交预防），对冲腿在另一账户/venue 完成；保留审计日志。
- **风险优先**：名义/库存/单笔上限、回撤熔断、延迟与数据断流保护。
- **可观测性**：Prometheus 指标与报警；全链路可追踪。

## 3. 指标/KPI（验收）
- EV_p50 ≥ 1.5 bps；EV_p10 ≥ 0
- |Delta| P95 ≤ max_base_abs 的 50%
- taker_ratio ≤ 35%；hedge_cost_bps ≤ edge_bps 的 40%
- 当日回撤不突破 kill_switch_dd_pct；latency_p99 达标

## 4. 策略设计
### 4.1 信号
- Spread 扩张：spread_bps = (ask1 - bid1)/mid * 1e4
- Order Book Imbalance (OBI)：k 档不平衡
- Trade Imbalance：T=0.5–2s 窗口的买卖量差
- 短时 RV：200–500ms 波动率，自适应 tp/sl/δ

### 4.2 交易模式
- **被动优先**：mid±δ 两侧 postOnly；一侧成交 → 对冲腿 IOC/紧限价；OCO(tp/sl) 管理退出。
- **微吃单**：spread_bps 放大 + 成交流向偏置时，小额吃入→在中点内侧被动挂出；超时 IOC 退出。

### 4.3 Delta 控制
- PI 控制：hedge_qty = clamp(kp*Δ + ki*∑Δ, ±Qmax)，含最小间隔防抖；资金费率不利时增加偏压。
- **对冲延迟风险预算（新增）**：
  - 目标延迟：P50 < 500ms, P99 < 2s（从成交信号到对冲完成）
  - 延迟窗口风险：在高波动期，10 秒单边敞口可能造成 10-50 bps 滑点损失
  - 超时处理：若对冲未在 3 秒内完成，触发强制市价平仓
  - 对冲失败重试：最多 2 次，每次增加滑点容忍度 +5bps
  - 预对冲机制（高级）：在 MM 挂单前，预先在对冲账户挂反向单，成交时立即对冲
- **资金费率套利风险（新增）**：
  - **关键风险**：双账户持有相反方向仓位时，若两 venue 资金费率同向，将双重支付而非互相抵消
  - 监控指标：
    - `funding_rate_correlation`：两 venue 资金费率的 30 天滚动相关性（目标 > 0.8）
    - `funding_cost_net_bps`：双账户净资金费支付/收入（目标每 8h < 1bps）
  - 风控动作：
    - 若相关性 < 0.8，告警并建议减仓至 50%
    - 若出现同向支付（如双方都支付 +0.01%），立即减仓至 30% 并人工审查
  - 标的筛选要求：仅选择资金费率相关性 > 0.8 的 venue 对进行双账户对冲

### 4.4 期望价值
EV ≈ edge_bps - taker_fee_bps*taker_ratio - real_slip_bps - cancel_cost_bps，需 EV_p50 > 1–2 bps 且 EV_p10 ≥ 0。

## 5. 标的筛选（自动评分任务）
- 从 `/info` 读取 tick/lot/min_order；
- 从 `/book` 计算 spread_bps、top10_depth_usd、queue_turnover；
- 从成交流估每分钟笔数；
- **流动性冲击成本评估（新增）**：
  - 要求：`base_clip_usd ≤ top10_depth_usd * 5%`（单笔订单不超过前 10 档深度的 5%）
  - 动态调整：若 depth 下降 >30%，自动降低 clip 至新的 5% 阈值
  - 监控指标：实际成交滑点 vs 预期滑点，若差异 >2bps 持续 5 分钟，暂停该标的
- **资金费率相关性评估（新增）**：
  - 从双 venue 抓取最近 30 天的 funding rate 历史
  - 计算 Pearson 相关系数，要求 > 0.8
  - 检查同向支付频率：若 >20% 的时间双方都支付正费率或都收取负费率，拒绝该 venue 对
- 依据费率/滑点回测 EV，满足阈值放行。

## 6. 系统架构（与仓库结构对齐）
- `packages/connectors/pacifica`：REST 客户端 + 签名；
- `packages/utils/shadowBook.ts`：影子订单簿；
- `packages/execution/orderRouter.ts`：滑点守卫、STP 检查、下单/撤单；
- `packages/strategies`：MarketMaker + MicroScalper；
- `packages/portfolio` & `packages/hedge`：持仓聚合与跨账户对冲；
- `packages/risk`：限额、回撤熔断；
- `packages/telemetry`：Prom 指标；
- `apps/runner`：参数加载、定时任务、主循环。

## 7. 风控与合规
- 硬限：max_notional_abs、max_base_abs、max_order_sz、kill_switch_dd_pct
- **Kill-Switch（跨账户聚合，增强）**：
  - **聚合模式**：计算 Account A + Account B 的总权益与总 PnL，避免单账户误杀
  - **多维度熔断触发器**：
    1. 跨账户聚合 PnL 回撤 > -0.5%
    2. Delta 绝对值 > 2x max_base_abs（失控）
    3. 连续对冲失败 >3 次
    4. 行情数据断流 >3 秒
  - **时间窗口回撤**：基于 1 小时滑动窗口计算，而非从启动时刻
- 订单前置：tick/lot 对齐、滑点守卫、对手价 STP、本地影子簿自家挂单识别
- **跨账户 STP（新增）**：Global Order Coordinator 检查对手价是否来自关联账户，防止经济自成交
- 审计：信号→决策→下单→成交→对冲→OCO 全链路日志（append-only + trace id）

## 8. 可观测性
- **核心指标**：maker_ratio、avg_edge_bps、real_slip_bps、hedge_cost_bps、delta_abs、latency_p99、cancel_rate、pnl_intraday、ev_estimate
- **对冲效率指标（新增）**：
  - `hedge_success_rate`：对冲订单成交率（目标 >98%）
  - `hedge_latency_p50/p95/p99`：对冲延迟分位数（目标 P50<500ms, P99<2s）
  - `hedge_slippage_bps`：对冲实际成交价 vs 预期价偏差（目标 <0.5bps）
  - `hedge_retry_rate`：对冲重试率（目标 <5%）
  - `cross_venue_basis_bps`：双 venue 价差监控（发现套利或数据异常）
- **资金费率指标（新增）**：
  - `funding_rate_correlation`：双 venue 资金费率 30 天相关性
  - `funding_cost_net_bps`：双账户净资金费成本（每 8h）
  - `funding_same_sign_ratio`：同向支付频率（目标 <20%）
- **报警**：delta_abs>阈值、pnl_dd>阈值、latency_p99↑、data_gap、hedge_error、STP_hit、**funding_correlation<0.8**、**hedge_success_rate<95%**

## 9. 里程碑（M1–M4）
- **M1**：接入 `/info` `/book` `/orders/*` `/account/*`，签名链路跑通；影子簿/路由/指标基础。
- **M2**：策略闭环（MM + Scalper）、对冲引擎、OCO、资金费抓取与面板。
- **M3**：事件重放与费用/资金费模型、参数搜索、策略报告。
- **M4**：稳态化（限频、重连、审计）、自适应参数（随 RV/OBI）、多标的扩容。

## 10. 配置（示例）
```yaml
env: mainnet
api_base: https://api.pacifica.fi/api/v1
symbols: [BTC, ETH, SOL]

# 双账户配置
accounts:
  maker:
    address: ${MAKER_ADDRESS}
    private_key: ${MAKER_PRIVATE_KEY}
    subaccount: maker-01
  hedger:
    address: ${HEDGER_ADDRESS}
    private_key: ${HEDGER_PRIVATE_KEY}
    subaccount: hedger-01  # 或不同 venue

mm: { layers: 2, base_clip_usd: 1000, spread_bps: 1.6, reprice_ms: 300 }

scalper:
  trigger: { spread_bps: 1.8, min_cooldown_ms: 250 }
  tp_bps: 3
  sl_bps: 6

risk:
  max_notional_abs: 100000
  max_base_abs: 0.8
  kill_switch:
    mode: aggregated  # 跨账户聚合
    drawdown_pct: -0.5
    lookback_window_sec: 3600  # 1 小时滑动窗口
    triggers:
      - { type: pnl_drawdown, threshold: -0.5 }
      - { type: delta_abs, threshold: 1.6 }  # 2x max_base_abs
      - { type: hedge_failure_count, threshold: 3 }
      - { type: data_gap_sec, threshold: 3 }

hedge:
  kp: 0.6
  ki: 0.05
  qmax: 0.4
  min_interval_ms: 200
  # 对冲延迟预算
  latency_budget:
    target_p50_ms: 500
    target_p99_ms: 2000
    max_exposure_sec: 3  # 超过则强制市价
    retry_max: 2
    retry_slippage_increment_bps: 5

# 自适应降级（新增）
adaptive_mode:
  enabled: true
  rv_threshold_high: 0.5  # realized vol >0.5%/min
  actions_on_high_vol:
    - disable: scalper
    - mm.layers: 1
    - mm.spread_bps: 3.0
    - mm.clip_multiplier: 0.5

# 流动性监控（新增）
liquidity:
  min_top10_depth_usd: 50000  # 前 10 档最小深度
  max_clip_ratio: 0.05  # clip ≤ depth * 5%
  slippage_alert_bps: 2  # 实际滑点超过预期 2bps 告警

# 资金费率监控（新增）
funding:
  min_correlation: 0.8  # 双 venue 最低相关性
  max_same_sign_ratio: 0.2  # 最大同向支付频率
  alert_net_cost_bps_per_8h: 1  # 净成本告警阈值
```

## 11. 上线演练（Playbook）
- 金丝雀：低名义跑 30–60 分钟，观察指标与报警；
- 高波动：自动降层/降 clip，放宽 tp/sl；
- 数据断流：撤单→HALT；
- 对冲失败：冻结新增信号，仅处理存量；
- 资金费极端：降低持仓时长/名义，或只做有利方向的被动单。