数值精度与类型约定
1. Decimal String（ADR-0026）
所有响应数值为规范化 decimal string。链内 i128，API 边界 format_decimal 转换。
| 语义 | 精度 | 示例 |
|---|---|---|
| 价格（price/mark/bid/ask/entry/liquidation_price/trigger_price/mark_price/last_price） | 市场 price_decimals | "97234.50" |
| 数量（size/qty/amount/remaining/volume） | 市场 size_decimals | "1.50000" |
| 余额/保证金/PnL/费用/名义价值/ROE/费率 | SCALE_6 | "1234.567890" |
写操作（envelope.action 内）同样使用 canonical decimal string，精度同上。链上解析超精度或非法格式 → DecimalPrecisionExceeded（kept-reject）。
2. 地址与哈希类型
| 类型 | 格式 | 示例 |
|---|---|---|
Address20 | 20 字节 hex，0x 前缀 | 0x1111222233334444555566667777888899990000 |
TxHash | 32 字节 hex，0x 前缀 | 0xa1b2c3... |
Hex32 | 32 字节 hex（state_root/digest/parent） | 0xabc...def |
MarketId | u32 | 1 |
OrderId | u64 | 1001 |
DepositSeq | u64 | 1 |
WithdrawRequestId | u64 | 1 |
TriggerOrderId | u64 | 1 |
PairId | u64 | 1 |
注意：WS
block推送中的digest/state_root无0x前缀（字符串），与 HTTP 端点返回的Hex32（0x前缀）不同。
3. 非 Hex 的二进制字段
| 字段 | 出现位置 | JSON 序列化 |
|---|---|---|
DepositResponse.tx_hash | getBridgeDeposit / listBridgeDeposits | [u8; 32] JSON 字节数组 |
WithdrawResponse.settle_tx_hash | getBridgeWithdrawal / listBridgeWithdrawals | [u8; 32] JSON 字节数组 |
credential.Secp256k1.signature | 写操作 envelope | Vec<u8> 65 字节 JSON 数组 |
这些字段不是 hex 字符串，而是 JSON 数组
[byte0, byte1, ...]。
4. DecimalStr 规范
canonical 格式：
- 整数部分不带前导零（
"0"除外） - 小数部分不带尾随零
- 整数部分 + 小数点 + 小数部分（始终含小数点）
- 例：
"100.5"、"0.000000"、"97234.50" - 不允许科学计数法
精度：不超过所属语义的位数（价格 ≤ price_decimals，数量 ≤ size_decimals，SCALE_6 字段 ≤ 6）。
5. Raw i128 注意
写操作 result.reason 中的数值字段是 raw i128（未做 decimal 投影），与 result.events[] 中的 decimal string 不同：
// result.reason —— raw i128
{ "InsufficientBalance": { "required": 5000000000, "have": 3000000000 } }
// result.events[0].kind —— decimal string
{ "Core": { "Rejected": { "reason": { "InsufficientBalance": { "required": "5000.000000", "have": "3000.000000" } } } } }
对接方解析 reason 时须自行按 SCALE_6 转换。
6. 分页约定
| 端点类型 | 默认 limit | 最大 limit | total |
|---|---|---|---|
| 事件扫描（getBlockEvents） | 500 | 2000 | Some(usize) |
| 成交 / 审计（getRecentTrades/getUserFills/getAdminAuditLog） | 100 | 1000 | null（journal 扫描不可知） |
| list 系列（listAccounts/listBridgeDeposits/listBridgeWithdrawals） | 100 | 500 | Some(usize) |
| K 线（getCandles） | 500 | 2000 | N/A（非分页） |
| 排行（getTopAccounts） | 50 | 50 | N/A（非分页） |
| 挂单列表（getAllOpenOrders） | 100 | 1000 | Some(usize) |
| 清算列表（getLiquidatablePositions） | 100 | 1000 | Some(usize) |