Core concepts基础约定
Fund safety资金安全
Failure scenarios and the safeguards on both sides.各类异常场景及双方的资金保障措施。
Money must never be lost, created or moved twice — in any failure. The protocol is built so that every money instruction ends in exactly one definite outcome on both sides. This section lists who guarantees what.
任何故障下，钱都不能丢、不能凭空多出、不能动两次。协议的设计目标是：每一条资金指令在双方最终都有且只有一个确定结果。本节写清双方各自保证什么。
What can go wrong, and what happens会出什么问题，结果如何
| Situation情况 | Risk风险 | How it is resolved怎么兜住 | End state最终结果 |
|---|---|---|---|
| Debit times out, you actually deducted扣款超时，商户其实扣了 | Player loses the stake玩家丢钱 | We never treat an unknown debit as placed; we roll it back结果未知的扣款平台一律不算下注成功，发冲正 | As if never bet等于没下注 |
| Debit times out, it is still in flight扣款超时，请求还在路上 | Late debit takes money after the rollback冲正之后扣款才到，把钱扣走 | Your TXN_NOT_FOUND + remembered rollback → late debit gets TXN_ROLLED_BACK商户返回 TXN_NOT_FOUND 并记下冲正 → 迟到的扣款返回 TXN_ROLLED_BACK | As if never bet等于没下注 |
Our process crashes right after your debit OK商户扣款 OK 后平台进程崩溃 | Money taken, bet not in the game钱扣了，注没进游戏 | We write every transaction to our database before sending it; on restart unresolved debits are rolled back平台每笔交易先落库再发送；重启后没有结果的扣款一律冲正 | As if never bet等于没下注 |
| Credit times out, you actually paid派彩超时，商户其实加了 | Double payout重复派彩 | We retry the same txnId; you return the original result平台用同一 txnId 重试，商户原样返回第一次结果 | Paid once只付一次 |
| Credit cannot reach you for hours派彩几个小时都发不到 | Player not paid玩家拿不到钱 | We keep retrying with no time limit (Retries) and alert; it stops only on a definite answer or when we close it manually — never dropped, never re-sent with a different amount平台不设期限地持续重试（重试）并告警，只有得到明确回复或人工关闭才停——绝不丢弃，绝不改金额重发 | Paid付到 |
| The game result arrives twice游戏结果重复到达 | Double settlement重复结算 | Our database allows exactly one closing transaction per wallet round平台数据库对每个钱包局只允许一笔关局交易 | Settled once只结算一次 |
| A payout above the table limits (very high multipliers, bug, bad data)派彩超过机台限额（极高倍数、程序错误、数据错误） | Overpayment多付 | Each bet's return is capped at the table's maximum win for that bet spot, and the player's round total at the table's maximum payout per round; the capped amount is paid and the uncapped figure is kept on our side for audit每注的返还以机台该投注点的最大赢钱封顶，玩家一局的合计以机台每人每局最大派彩封顶；按封顶后的金额派发，封顶前的数字留在平台备查 | Never above the table limits不超过机台限额 |
| A forged or replayed credit request reaches you伪造或重放的派彩请求打到商户 | Money created凭空加钱 | HMAC signature, ±300 s window, IP whitelist, idempotent txnId, and credits only for rounds with a successful debit (ROUND_NOT_FOUND)HMAC 签名、±300 秒时间窗、IP 白名单、txnId 幂等，且只给有成功扣款的钱包局派彩（ROUND_NOT_FOUND） | Refused被拒 |
| Player disabled while a round is open局还没结束玩家被禁用 | Winnings withheld赢的钱被扣住 | Credits and rollbacks are never refused for player status派彩和冲正从不因玩家状态拒绝 | Paid付到 |
| Platform cancels the round游戏平台取消这局 | Stakes kept注被吞 | Every debit of the round is rolled back; the last rollback closes it该局每笔扣款逐笔冲正，最后一笔关局 | All stakes returned全部退回 |
| Balance precision: payout has more decimals than the currency精度：派彩小数位多于币种精度 | Rounding up进位多付 | We truncate down to the currency precision before sending发送前向下截断到币种精度 | Never over不会多付 |
We guarantee平台保证
- Write-ahead: every transaction is stored before it is sent.
- One
txnIdper instruction; retries are byte-identical. - A bet counts only after your
OK; unknown debits are rolled back. - Credits and rollbacks are retried until definite; never dropped.
- Credits only after every debit of the round is definite; one round at a time.
- Exactly one closing transaction per wallet round.
- Amounts are derived from bet records and capped by the table limits (max win per bet spot, max payout per player per round).
- Money state lives only in our database, never in a cache.
- 先落库后发送：每笔交易发出之前已经存好。
- 一条指令一个
txnId；重试正文逐字节相同。 - 只有商户返回
OK的扣款才算下注成功；结果未知的扣款一律冲正。 - 派彩与冲正重试到有确定结果为止，绝不丢弃。
- 一局的扣款全部有结果后才发派彩；同一钱包局串行。
- 每个钱包局恰好一笔关局交易。
- 金额由注单推出，并受机台限额封顶（每个投注点最大赢钱、每人每局最大派彩）。
- 资金状态只存数据库，不放缓存。
You must商户必须
- Unique constraint on
(merchantCode, txnId); balance change and record in one DB transaction. - Repeats return the original result, including failures.
- Remember rollbacks of unknown debits and refuse the late debit.
- Never refuse a credit or rollback for player status.
- Credit only rounds that have a successful debit.
- Verify signature on raw bytes; enforce the time window and the IP whitelist on the TCP address.
- Reconcile daily (Reconciliation); never close or refund an open round on your own.
(merchantCode, txnId)唯一约束；改余额与写记录在同一个数据库事务。- 重发返回第一次的结果，包括失败。
- 冲正找不到扣款时记下冲正，迟到的扣款要拒绝。
- 派彩与冲正从不因玩家状态拒绝。
- 只给有成功扣款的钱包局派彩。
- 用原始字节验签；执行时间窗；白名单按 TCP 来源地址。
- 每日对账（对账）；不要自己关局或退款。
The conformance test (API conformance test) verifies every "You must" item, and ends by checking that the test player's balance is back to its starting value.
对接测试（接口对接测试）会逐条验证「商户必须」的每一项，最后核对测试玩家的余额回到初始值。