# 07｜从模拟撮合到链上二级交易

前一站：[可靠后端](06-backend-reliability.md) · 下一站：[源码阅读](08-code-reading.md)

## 1. 什么是订单簿和撮合

订单簿记着未完成的买卖意愿。买单愿意以不超过某个价格买，卖单愿意以不低于某个价格卖。买价达到卖价时，可以成交。maker 是先挂在簿上的订单，taker 是后来到达并吃到已有流动性的订单。

例如卖方先挂 1 MWETH @100 MUSDT，买方后来愿意买 1 @105。项目按 maker 价成交，因此实际是 100，不是 105。105 是买方上限，不能被错误理解成必须付 105。

相同价格按 FIFO，先到先处理。红黑树维护有序价格档，同档链表保存先后顺序，索引帮助快速定位撤单。单写者让修改顺序确定，日志允许重启时按同样顺序重演。

## 2. 先看模拟模式：资产由应用内部记账

模拟系统有账户可用和冻结余额。买方提交 3 ETH、限价 105，先冻结 315 USDT；若成交 2 ETH @100，实际付 200，剩余买单冻结 105，返还成交部分价差 10。撤掉余下 1 ETH 再释放 105。

```text
买方初始：可用 100000，冻结 0
下单后：可用 99685，冻结 315
成交 2 后：可用 99695，冻结 105
撤余单后：可用 99800，冻结 0
```

买方 ETH 加 2、卖方 ETH 减 2，双方 USDT 一减一加。除模拟 CREDIT 等明确增发行为，每种资产全账户总量应守恒。这些余额不进入本地链上的代币合约。

模拟模式允许 LIMIT GTC/IOC、MARKET IOC 和管理员等能力；不能据此认为钱包链模式全部支持。当前独立链模式只实现受限的 LIMIT GTC 签单与链上取消。

## 3. 为什么链模式不能照搬“撮合完就改余额”

链模式中，Go 不拥有钱包余额的最终写入权。即使本地撮合选出 A/B，也可能发现用户转走代币、撤销 allowance、订单到期或链上取消先执行。因此本地配对只能创建结算意图，不能直接宣称资产完成交换。

订单数量增加 Pending 状态，保持：

```text
Quantity = Remaining + Pending + Filled + Canceled
```

例如总量 3 lot，匹配 2 lot 后是 Remaining=1、Pending=2、Filled=0。链确认成功才将 2 从 Pending 移到 Filled。链上失败由持久化失败命令按当前引擎规则处理，不把失败当成交，也不绕过日志直接修内存。

## 4. 本项目的一次二级交易

A 首发买到 0.0001 MWETH，签卖单价格 10000、数量 0.0001；B 签同价同量买单。这两个订单各自包含 maker 钱包、方向、整数 price/quantity、订单 nonce、deadline 和签名。

这里 SignedOrder 字段名 `maker` 指“这份订单的签单人”，买方和卖方都有这个字段；撮合语境的 maker/taker 则区分谁先挂单、谁后来吃单。不要因为 B 是 taker，就把 B 的签单地址字段错误地填成 A。

Go 先验签、检查域和预算，将命令写入 SQLite FULL 日志，提交后交给单写者。撮合产生稳定结算 ID，查询投影与 outbox 保存后进入外围分发。前端收到 200/201 只代表本地受理，不是合约已经交币。

结算任务经 RabbitMQ 交接到 PG/SQLite 任务库。relayer 构造 `Settlement.settle` 交易，保存原始签名交易 raw、hash、发送 nonce，然后广播。保存早于广播，是崩溃后能查找和重发同一交易的关键。

## 5. relayer 是谁，为什么它付 Gas

relayer 是后端配置的交易发送账户。用户已经离线签署限价订单，relayer 将两份授权和成交数量提交合约，支付结算调用 Gas。

合约要求调用者为固定 relayer，但仍检查双方订单签名、方向、价格、期限、已成交数量、取消记录和 settlement ID。relayer 不是想让谁付多少钱都可以，它必须提交通过合约约束的材料。当前固定角色和密钥配置仍需要生产权限与运维演进。

## 6. Settlement 怎样原子交换

合约按 maker 价格确定实际支付，调用 base 的 transferFrom 将 MWETH 从卖方转给买方，再调用 quote 的 transferFrom 将 MUSDT 从买方转给卖方。两种转移属于同一交易：若后一笔失败，前面产生的状态也回滚。

这避免“卖方币已经转出，买方款却没交”的半完成结果。它不保证订单永远能成交：余额/授权不够、期限不符或取消竞争都可能导致整笔失败。

成功后实际币差是 A 的 MWETH−0.0001、MUSDT+1；B 的 MWETH+0.0001、MUSDT−1。结算 Gas 由 relayer 另付。首次发售的 Gas 则由买家自己付，两个路径不同。

## 7. 任务状态和订单状态不要混读

| 层 | 例子 | 含义 |
| --- | --- | --- |
| 订单 | OPEN / PENDING_SETTLEMENT / FILLED | 用户订单还有多少剩余、待结算和最终成交 |
| 结算意图 | READY / CONFIRMED / FAILED | 这组配对是否最终执行成功 |
| 发送任务 | BROADCAST / INCLUDED / CONFIRMED 等 | 对应 raw 交易发送、入块及确认进度 |
| 链事件索引 | Matched 及 blockHash | 已确认链事实的查询记录 |

一笔任务有 INCLUDED 并不代表所有层都已更新。系统需要确认策略、命令日志和投影逐步追上，不能让 UI 随便拿其中一个字段冒充完整结论。完整历史查询、事件索引和对账是 v0.5 引入的闭环能力。

## 8. 原始交易为何不能随意重建

设后端已广播交易 X，网络超时没拿到响应。X 可能已入块。若后端为同一业务重新分配发送 nonce 并生成交易 Y，两个发送对象就难以判断和恢复。

项目先保存 raw/hash/nonce；重启先查原 hash/receipt，必要时重发原 raw。同一 raw 仍对应同一 hash，不因重试制造另一个新业务。当前没有实现完整的同 nonce 加价替换和 nonce 窗口管理，不要把“支持重试”讲成完整交易管理平台。

## 9. 取消和成交可能竞争

链上 cancel 由订单 owner 发起，可能和已经广播的结算交易同时等待入块。最终由链上的执行顺序和合约检查决定谁先产生效果。不能把“用户点了撤单”立即视为已经不可成交；本地按钮操作无法撤回别处已广播的交易。

## 10. 日志、任务库、索引各有什么用

日志是订单状态恢复的权威输入；任务库保存发送交易的可靠记录；链决定资金事实；索引为查询和核对保存已确认事件。索引不是第二套资金写入路径，不能扫描到一笔 Matched 后又给钱包转一遍币。

后台只读对账重放指定水位的日志、比较投影、任务和事件，区分异步 lag 与稳定 difference。它不会自动修钱或补发交易，也不是钱包储备证明。

进一步阅读：[模拟架构](../02-architecture/architecture.md)、[既有链设计](../07-history/v0.5-design.md)、[Settlement](../../contracts/src/Settlement.sol)、[任务管理](../../chaintrade/tasks.go)。历史 v0.5 图中的 Kafka 是旧传输背景，当前中间件使用 RabbitMQ。

## 11. 自测

问：为什么允许合约代转，不等于资产已经被冻结？答：allowance 只是权限记录，用户余额和其他交易仍可能变化，所以结算要实时检查。

问：链索引里多看到一次相同事件，要再结算一次吗？答：不能。事件用于记录/核对已发生的事实，重放索引应幂等，不应产生第二笔资产转移。
