多租户 digital wallet 架构:VES 批量兑换 USDT 与内部 ledger
建议 MVP 使用统一托管账户(omnibus account),为每位用户设立独立子账。每天将符合条件的 VES 汇总成一个批次,完成一笔外部兑换后,按实际成交结果分配 USDT。采用这一方案的前提是开户机构和托管安排允许归集客户资金。
内部 ledger 应采用 double-entry bookkeeping,用来约束账内借贷平衡。用户资产是否足额,还需核对银行、兑换服务商和链上记录。
每天一笔兑换,如何保留用户资金归属?
将一次外部兑换与多笔内部账本记录关联。服务商处理汇总订单,应用记录每位用户投入的 VES、获得的 USDT 和承担的费用。
建议按以下步骤处理:
- 设定每日截止时间和时区,筛选已经到账、允许兑换且尚未进入其他批次的 VES 可用余额。
- 在数据库事务中冻结这些余额,创建
conversion_batch和逐用户的conversion_items。冻结后,用户不能再次提现或兑换这部分资金。 - 汇总冻结金额并获取报价,保存汇率方向、报价有效期、费用和预计到账数量。
- 使用固定的业务标识提交一笔兑换订单,保存服务商订单号。后续查询和重试继续关联该订单。
- 核实实际扣除的 VES、实际结算的 USDT 和费用,然后完成用户分配及入账。
每次汇总的是本批次符合条件的 VES。已经兑换为 USDT 的余额不能再次参加 VES 兑换,截止时间之后的入金进入后续批次。
业务状态可以设计为:
CREATED -> RESERVED -> SUBMITTED -> SETTLED -> ALLOCATED
只有确定兑换失败且资金未被扣除,才能解冻余额。请求超时或结果不明时,应保持冻结并查询原订单;直接创建新订单可能导致重复兑换。
还需要明确“一笔交易”的含义。兑换订单、银行转账和链上交易是不同事件。归集入金、兑换和链上提币可能分别发生,服务商也可能将一个订单拆成多个成交。若必须保证只有一次成交,应确认服务商是否支持相应的固定报价执行方式。
double-entry bookkeeping 应如何设计?
从平台角度看,银行和托管账户中的资金是资产,用户余额是平台对用户的负债。每个账户固定对应一种资产,每笔 journal 在同一种资产内满足:
sum(debits) = sum(credits)
VES 和 USDT 应分别检查平衡,不能直接将两个币种的数量相加。两边通过同一个 batch_id 关联,并保存实际汇率和成交记录。
以下以无手续费、资金已经结算的情况说明用户资金子账:
| 事件 | 借方 | 贷方 | 资产及金额 |
|---|---|---|---|
| 用户入金到账 | 银行资金资产账户 | 用户可用余额负债账户 | VES,用户入金金额 |
| 冻结兑换金额 | 用户可用余额负债账户 | 用户冻结余额负债账户 | VES,参与兑换金额 |
| 兑换完成,扣除 VES | 用户冻结余额负债账户 | VES 资金资产账户 | VES,实际消耗金额 |
| 兑换完成,分配 USDT | USDT 托管资产账户 | 用户 USDT 可用余额负债账户 | USDT,实际分配金额 |
最后两行分别在 VES 和 USDT 内平衡。本地确认入账时,应将对应的账本记录、分配结果和批次状态放在同一个数据库事务中。
若 VES 已经付出而 USDT 尚未到账,需要用在途或兑换清算账户反映中间状态。界面可以显示待结算金额,可提现余额应按照明确的结算条件释放。银行资金转入兑换服务商账户时,也应记录资产账户之间的转移。
这是一个运营子账的建模示例。手续费、平台收入以及本位币下的汇兑损益,还需要相应的会计科目。
TigerBeetle 的 Currency Exchange 文档使用不同币种独立 ledger、同币种 transfer 之间原子关联的方式处理兑换,可作为实现参考。这里的原子性只覆盖账本内部操作,无法让外部银行或兑换 API 与本地事务同时提交。
如何计算每位用户获得的 USDT?
若所有用户适用相同成交条件,且约定按投入 VES 的比例分配净到账 USDT,可以定义:
v_i = 用户 i 本批次实际消耗的 VES
V = sum(v_i)
Q = 本批次可分配的净 USDT
q_i = Q * v_i / V
Q 应来自核实后的结算结果。若费用已经从到账金额中扣除,计算净额时不要再次扣费;其他币种的费用则分别记录。
实际入账时必须处理最小单位和尾差。可以先将金额转换为整数单位,再用最大余数法分配,使各用户的分配之和精确等于 Q:
def allocate(net_units, weights):
# net_units: integer units of net USDT to allocate
# weights: {user_id: positive integer VES units}
if not weights or net_units < 0:
raise ValueError("Invalid allocation input")
if any(value <= 0 for value in weights.values()):
raise ValueError("Weights must be positive")
total = sum(weights.values())
result = {}
remainders = {}
for user_id, value in weights.items():
result[user_id], remainders[user_id] = divmod(
net_units * value, total
)
remaining = net_units - sum(result.values())
order = sorted(
weights,
key=lambda user_id: (-remainders[user_id], user_id),
)
for user_id in order[:remaining]:
result[user_id] += 1
assert sum(result.values()) == net_units
return result
示例假设输入已校验为整数,user_id 是可排序的稳定标识,且批次已经完整结算。资产精度、费用分摊方式和尾差排序规则应提前确定,并随批次保存。部分成交时,需要先确定各用户实际消耗的 VES,再分配对应收益并释放未成交部分。
金额可以使用整数最小单位,汇率使用精确十进制类型,避免二进制浮点数参与资金计算。PostgreSQL 的 numeric 是精确类型,real 和 double precision 是非精确类型,详见官方 Numeric Types 文档。数据库还需按业务范围设置精度、取值范围和舍入规则。
原问题中的 1$ 只是金额示意。实际兑换要记录真实 VES 数量和成交汇率,不能据此假定每位用户必然获得 1 USDT。
数据库怎样防止重复记账和并发超支?
MVP 可以先用 PostgreSQL 实现集中式 ledger。建议至少保存以下实体:
accounts:账户归属、资产、账户性质,以及可用或冻结等余额分类。journals、entries:业务事件及对应借贷分录。conversion_batches、conversion_items:每日汇总订单、用户投入金额与最终分配结果。external_events:服务商通知标识、原始记录和处理结果。
余额可以维护为实时更新的投影,但必须能由已入账分录重建。所有资金变更通过统一的记账入口执行;已入账分录使用冲正或补充分录更正。
实现时应落实以下约束:
- 记账入口在事务内检查账户归属、资产一致性、金额范围和逐资产借贷平衡。跨多行的借贷合计不能只靠普通行级
CHECK完成。 - 冻结、提现和转账通过行锁或带余额条件的原子更新执行,防止两个请求同时花掉同一笔可用资金。
- 业务请求与服务商事件分别设置幂等约束;同一业务标识携带不同金额时,应拒绝处理。
- 在冻结资金的事务中写入 outbox,由 worker 提交外部订单。网络调用放在事务之外。
worker 可能重复执行,因此仍需要服务商支持幂等提交,或能通过稳定的业务标识查询订单。如果服务商不具备这些能力,超时后的未知状态需要人工核实,不能承诺端到端 exactly-once。
如果不同 tenant 对应不同业务方,应让账户引用、批次、查询和幂等约束包含 tenant_id,并校验租户归属。不同法律主体能否共用资金账户,需要单独确认;技术上的多租户隔离不能代替资金隔离。
用户余额总和必须等于 master wallet 吗?
当一个 master wallet 只存放用户 USDT,且没有在途资金、平台自有资金或未处理费用时,可以要求:
master wallet USDT
= sum(用户 USDT 负债余额)
用户负债应覆盖互不重叠的可用、冻结和提现待结算金额。冻结只是状态转移,不应让同一笔用户权益重复计入总额。
实际系统可能同时在银行、服务商账户和链上地址持有资产,因此单个链上地址通常不足以代表全部资金。对账时应分别核对:
- 将银行流水、服务商余额和链上记录与内部对应的资产账户核对。
- 将用户子账汇总与用户负债控制账户核对。
- 通过订单和结算记录逐项解释在途款、手续费及其他差异。
链上资产还要核对网络和 token contract,仅凭 USDT 名称不能完成核验。即使 ledger 借贷完全平衡,也可能存在漏记外部扣款或错误确认到账的情况。
哪些 API、库或服务商值得评估?
外部服务商通常只需要接收汇总金额并返回可追踪的兑换结果。用户分账可以由应用完成,因此不一定需要专门的 batch exchange API。
Bitso Business可列入 LATAM 候选清单,其公开产品包括本地收付款、多币种账户、RFQ 和 OTC。可以用它来评估 LATAM 本地支付与兑换能力,但该产品页不能证明你的业务能够直接接入 VES→USDT,也不能证明允许归集多位用户的资金兑换。
针对 VES 场景,投入集成开发前应向候选服务商确认:
- 是否接受你的注册主体及目标用户,是否支持 VES 本地入金和 USDT 结算。
- 是否允许客户资金归集,以及需要什么账户结构和 KYC/KYB 安排。
- 是否能提交一笔汇总订单,是否支持固定报价、订单查询、幂等请求和结算报表。
- 最小兑换额、点差、固定费用、到账时间及支持的 USDT 网络。
若必须经过中间币种,应确认服务商能否把多段兑换封装为一笔对客订单。否则,这条路径可能无法满足每日只执行一笔兑换的硬约束。
ledger 可以从 PostgreSQL 起步;需要专门的账户、transfer 和 pending transfer 模型时,再评估 TigerBeetle。引入独立 ledger 后,还需要处理它与业务数据库之间的状态协调。账本工具与兑换通道应分别选型。
上线前至少要验证重复通知、并发提现、订单超时但实际成交、部分成交、到账延迟和尾差分配等情况。这些情况会直接影响用户能花多少钱,以及系统是否会重复兑换或重复入账。
备注:内容仅供参考。
